diff options
Diffstat (limited to 'contrib/gdb/gdb/doc')
| -rw-r--r-- | contrib/gdb/gdb/doc/GDBvn.texi | 1 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/LRS | 197 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/a4rc.sed | 11 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/agentexpr.texi | 837 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/all-cfg.texi | 45 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/annotate.texinfo | 834 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/fdl.texi | 452 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/gdb.info-1 | 7636 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/gdb.info-2 | 9133 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/gdb.info-3 | 6665 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/gdb.texinfo | 21780 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/gdbint.texinfo | 6757 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/gpl.texi | 409 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/lpsrc.sed | 13 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/observer.texi | 70 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/psrc.sed | 13 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/refcard.tex | 647 | ||||
| -rw-r--r-- | contrib/gdb/gdb/doc/stabs.texinfo | 4046 |
18 files changed, 0 insertions, 59546 deletions
diff --git a/contrib/gdb/gdb/doc/GDBvn.texi b/contrib/gdb/gdb/doc/GDBvn.texi deleted file mode 100644 index 38987b5cff03..000000000000 --- a/contrib/gdb/gdb/doc/GDBvn.texi +++ /dev/null @@ -1 +0,0 @@ -@set GDBVN 6.1.1 diff --git a/contrib/gdb/gdb/doc/LRS b/contrib/gdb/gdb/doc/LRS deleted file mode 100644 index 7e25d432a3ee..000000000000 --- a/contrib/gdb/gdb/doc/LRS +++ /dev/null @@ -1,197 +0,0 @@ -What's LRS? -=========== - -LRS, or Live Range Splitting is an optimization technique which allows -a user variable to reside in different locations during different parts -of a function. - -For example, a variable might reside in the stack for part of a function -and in a register during a loop and in a different register during -another loop. - -Clearly, if a variable may reside in different locations, then the -compiler must describe to the debugger where the variable resides for -any given part of the function. - -This document describes the debug format for encoding these extensions -in stabs. - -Since these extensions are gcc specific, these additional symbols and -stabs can be disabled by the gcc command option -gstabs. - - -GNU extensions for LRS under stabs: -=================================== - - -range symbols: -------------- - - A range symbol will be used to mark the beginning or end of a - live range (the range which describes where a symbol is active, - or live). These symbols will later be referenced in the stabs for - debug purposes. For simplicity, we'll use the terms "range_start" - and "range_end" to identify the range symbols which mark the beginning - and end of a live range respectively. - - Any text symbol which would normally appear in the symbol table - (eg. a function name) can be used as range symbol. If an address - is needed to delimit a live range and does not match any of the - values of symbols which would normally appear in the symbol table, - a new symbol will be added to the table whose value is that address. - - The three new symbol types described below have been added for this - purpose. - - For efficiency, the compiler should use existing symbols as range - symbols whenever possible; this reduces the number of additional - symbols which need to be added to the symbol table. - - -New debug symbol type for defining ranges: ------------------------------------------- - - range_off - contains PC function offset for start/end of a live range. - Its location is relative to the function start and therefore - eliminates the need for additional relocation. - - This symbol has a values in the text section, and does not have a name. - - NOTE: the following may not be needed but are included here just - in case. - range - contains PC value of beginning or end of a live range - (relocs required). - - NOTE: the following will be required if we desire LRS debugging - to work with old style a.out stabs. - range_abs - contains absolute PC value of start/end of a live - range. The range_abs debug symbol is provided for - completeness, in case there is a need to describe addresses - in ROM, etc. - - -Live range: ------------ - - The compiler and debugger view a variable with multiple homes as - a primary symbol and aliases for that symbol. The primary symbol - describes the default home of the variable while aliases describe - alternate homes for the variable. - - A live range defines the interval of instructions beginning with - range_start and ending at range_end-1, and is used to specify a - range of instructions where an alias is active or "live". So, - the actual end of the range will be one less than the value of the - range_end symbol. - - Ranges do not have to be nested. Eg. Two ranges may intersect while - each range contains subranges which are not in the other range. - - There does not have to be a 1-1 mapping from range_start to - range_end symbols. Eg. Two range_starts can share the same - range_end, while one symbol's range_start can be another symbol's - range_end. - - When a variable's storage class changes (eg. from stack to register, - or from one register to another), a new symbol entry will be - added to the symbol table with stabs describing the new type, - and appropriate live ranges refering to the variable's initial - symbol index. - - For variables which are defined in the source but optimized away, - a symbol should be emitted with the live range l(0,0). - - Live ranges for aliases of a particular variable should always - be disjoint. Overlapping ranges for aliases of the same variable - will be treated as an error by the debugger, and the overlapping - range will be ignored. - - If no live range information is given, the live range will be assumed to - span the symbol's entire lexical scope. - - -New stabs string identifiers: ------------------------------ - - "id" in "#id" in the following section refers to a numeric value. - - New stab syntax for live range: l(<ref_from>,<ref_to>) - - <ref_from> - "#id" where #id identifies the text symbol (range symbol) to - use as the start of live range (range_start). The value for - the referenced text symbol is the starting address of the - live range. - - <ref_to> - "#id" where #id identifies the text symbol (range symbol) to - use as the end of live range (range_end). The value for - the referenced text symbol is ONE BYTE PAST the ending - address of the live range. - - - New stab syntax for identifying symbols. - - <def> - "#id=" - - Uses: - <def><name>:<typedef1>... - When used in front of a symbol name, "#id=" defines a - unique reference number for this symbol. The reference - number can be used later when defining aliases for this - symbol. - <def> - When used as the entire stab string, "#id=" identifies this - nameless symbol as being the symbol for which "#id" refers to. - - - <ref> - "#id" where "#id" refers to the symbol for which the string - "#id=" identifies. - Uses: - <ref>:<typedef2>;<liverange>;<liverange>... - Defines an alias for the symbol identified by the reference - number ID. - l(<ref1>,<ref2>) - When used within a live range, "#id" refers to the text - symbol identified by "#id=" to use as the range symbol. - - <liverange> - "l(<ref_from>,<ref_to>)" - specifies a live range for a - symbol. Multiple "l" specifiers can be combined to represent - mutiple live ranges, separated by semicolons. - - - - -Example: -======== - -Consider a program of the form: - - void foo(){ - int a = ...; - ... - while (b--) - c += a; - .. - d = a; - .. - } - -Assume that "a" lives in the stack at offset -8, except for inside the -loop where "a" resides in register "r5". - -The way to describe this is to create a stab for the variable "a" which -describes "a" as living in the stack and an alias for the variable "a" -which describes it as living in register "r5" in the loop. - -Let's assume that "#1" and "#2" are symbols which bound the area where -"a" lives in a register. - -The stabs to describe "a" and its alias would look like this: - - .stabs "#3=a:1",128,0,8,-8 - .stabs "#3:r1;l(#1,#2)",64,0,0,5 - - -This design implies that the debugger will keep a chain of aliases for -any given variable with aliases and that chain will be searched first -to find out if an alias is active. If no alias is active, then the -debugger will assume that the main variable is active. diff --git a/contrib/gdb/gdb/doc/a4rc.sed b/contrib/gdb/gdb/doc/a4rc.sed deleted file mode 100644 index 22922904efc9..000000000000 --- a/contrib/gdb/gdb/doc/a4rc.sed +++ /dev/null @@ -1,11 +0,0 @@ -/--- Papersize params:/,/--- end papersize params/c\ -%------- Papersize params:\ -%% A4 paper (297x210mm)\ -%%\ -\\totalwidth=297mm % total width of paper\ -\\totalheight=210mm % total height of paper\ -\\hmargin=5mm % horizontal margin width\ -\\vmargin=10mm % vertical margin width\ -\\secskip=.6pc % space between refcard secs\ -\\lskip=1pt % extra skip between \\sec entries\ -%------- end papersize params diff --git a/contrib/gdb/gdb/doc/agentexpr.texi b/contrib/gdb/gdb/doc/agentexpr.texi deleted file mode 100644 index 491ae2e0ec3d..000000000000 --- a/contrib/gdb/gdb/doc/agentexpr.texi +++ /dev/null @@ -1,837 +0,0 @@ -@c \input texinfo -@c %**start of header -@c @setfilename agentexpr.info -@c @settitle GDB Agent Expressions -@c @setchapternewpage off -@c %**end of header - -@c Revision: $Id: agentexpr.texi,v 1.2 1998/12/09 21:23:46 jimb Exp $ - -@node Agent Expressions -@appendix The GDB Agent Expression Mechanism - -In some applications, it is not feasable for the debugger to interrupt -the program's execution long enough for the developer to learn anything -helpful about its behavior. If the program's correctness depends on its -real-time behavior, delays introduced by a debugger might cause the -program to fail, even when the code itself is correct. It is useful to -be able to observe the program's behavior without interrupting it. - -Using GDB's @code{trace} and @code{collect} commands, the user can -specify locations in the program, and arbitrary expressions to evaluate -when those locations are reached. Later, using the @code{tfind} -command, she can examine the values those expressions had when the -program hit the trace points. The expressions may also denote objects -in memory --- structures or arrays, for example --- whose values GDB -should record; while visiting a particular tracepoint, the user may -inspect those objects as if they were in memory at that moment. -However, because GDB records these values without interacting with the -user, it can do so quickly and unobtrusively, hopefully not disturbing -the program's behavior. - -When GDB is debugging a remote target, the GDB @dfn{agent} code running -on the target computes the values of the expressions itself. To avoid -having a full symbolic expression evaluator on the agent, GDB translates -expressions in the source language into a simpler bytecode language, and -then sends the bytecode to the agent; the agent then executes the -bytecode, and records the values for GDB to retrieve later. - -The bytecode language is simple; there are forty-odd opcodes, the bulk -of which are the usual vocabulary of C operands (addition, subtraction, -shifts, and so on) and various sizes of literals and memory reference -operations. The bytecode interpreter operates strictly on machine-level -values --- various sizes of integers and floating point numbers --- and -requires no information about types or symbols; thus, the interpreter's -internal data structures are simple, and each bytecode requires only a -few native machine instructions to implement it. The interpreter is -small, and strict limits on the memory and time required to evaluate an -expression are easy to determine, making it suitable for use by the -debugging agent in real-time applications. - -@menu -* General Bytecode Design:: Overview of the interpreter. -* Bytecode Descriptions:: What each one does. -* Using Agent Expressions:: How agent expressions fit into the big picture. -* Varying Target Capabilities:: How to discover what the target can do. -* Tracing on Symmetrix:: Special info for implementation on EMC's - boxes. -* Rationale:: Why we did it this way. -@end menu - - -@c @node Rationale -@c @section Rationale - - -@node General Bytecode Design -@section General Bytecode Design - -The agent represents bytecode expressions as an array of bytes. Each -instruction is one byte long (thus the term @dfn{bytecode}). Some -instructions are followed by operand bytes; for example, the @code{goto} -instruction is followed by a destination for the jump. - -The bytecode interpreter is a stack-based machine; most instructions pop -their operands off the stack, perform some operation, and push the -result back on the stack for the next instruction to consume. Each -element of the stack may contain either a integer or a floating point -value; these values are as many bits wide as the largest integer that -can be directly manipulated in the source language. Stack elements -carry no record of their type; bytecode could push a value as an -integer, then pop it as a floating point value. However, GDB will not -generate code which does this. In C, one might define the type of a -stack element as follows: -@example -union agent_val @{ - LONGEST l; - DOUBLEST d; -@}; -@end example -@noindent -where @code{LONGEST} and @code{DOUBLEST} are @code{typedef} names for -the largest integer and floating point types on the machine. - -By the time the bytecode interpreter reaches the end of the expression, -the value of the expression should be the only value left on the stack. -For tracing applications, @code{trace} bytecodes in the expression will -have recorded the necessary data, and the value on the stack may be -discarded. For other applications, like conditional breakpoints, the -value may be useful. - -Separate from the stack, the interpreter has two registers: -@table @code -@item pc -The address of the next bytecode to execute. - -@item start -The address of the start of the bytecode expression, necessary for -interpreting the @code{goto} and @code{if_goto} instructions. - -@end table -@noindent -Neither of these registers is directly visible to the bytecode language -itself, but they are useful for defining the meanings of the bytecode -operations. - -There are no instructions to perform side effects on the running -program, or call the program's functions; we assume that these -expressions are only used for unobtrusive debugging, not for patching -the running code. - -Most bytecode instructions do not distinguish between the various sizes -of values, and operate on full-width values; the upper bits of the -values are simply ignored, since they do not usually make a difference -to the value computed. The exceptions to this rule are: -@table @asis - -@item memory reference instructions (@code{ref}@var{n}) -There are distinct instructions to fetch different word sizes from -memory. Once on the stack, however, the values are treated as full-size -integers. They may need to be sign-extended; the @code{ext} instruction -exists for this purpose. - -@item the sign-extension instruction (@code{ext} @var{n}) -These clearly need to know which portion of their operand is to be -extended to occupy the full length of the word. - -@end table - -If the interpreter is unable to evaluate an expression completely for -some reason (a memory location is inaccessible, or a divisor is zero, -for example), we say that interpretation ``terminates with an error''. -This means that the problem is reported back to the interpreter's caller -in some helpful way. In general, code using agent expressions should -assume that they may attempt to divide by zero, fetch arbitrary memory -locations, and misbehave in other ways. - -Even complicated C expressions compile to a few bytecode instructions; -for example, the expression @code{x + y * z} would typically produce -code like the following, assuming that @code{x} and @code{y} live in -registers, and @code{z} is a global variable holding a 32-bit -@code{int}: -@example -reg 1 -reg 2 -const32 @i{address of z} -ref32 -ext 32 -mul -add -end -@end example - -In detail, these mean: -@table @code - -@item reg 1 -Push the value of register 1 (presumably holding @code{x}) onto the -stack. - -@item reg 2 -Push the value of register 2 (holding @code{y}). - -@item const32 @i{address of z} -Push the address of @code{z} onto the stack. - -@item ref32 -Fetch a 32-bit word from the address at the top of the stack; replace -the address on the stack with the value. Thus, we replace the address -of @code{z} with @code{z}'s value. - -@item ext 32 -Sign-extend the value on the top of the stack from 32 bits to full -length. This is necessary because @code{z} is a signed integer. - -@item mul -Pop the top two numbers on the stack, multiply them, and push their -product. Now the top of the stack contains the value of the expression -@code{y * z}. - -@item add -Pop the top two numbers, add them, and push the sum. Now the top of the -stack contains the value of @code{x + y * z}. - -@item end -Stop executing; the value left on the stack top is the value to be -recorded. - -@end table - - -@node Bytecode Descriptions -@section Bytecode Descriptions - -Each bytecode description has the following form: - -@table @asis - -@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b} - -Pop the top two stack items, @var{a} and @var{b}, as integers; push -their sum, as an integer. - -@end table - -In this example, @code{add} is the name of the bytecode, and -@code{(0x02)} is the one-byte value used to encode the bytecode, in -hexidecimal. The phrase ``@var{a} @var{b} @result{} @var{a+b}'' shows -the stack before and after the bytecode executes. Beforehand, the stack -must contain at least two values, @var{a} and @var{b}; since the top of -the stack is to the right, @var{b} is on the top of the stack, and -@var{a} is underneath it. After execution, the bytecode will have -popped @var{a} and @var{b} from the stack, and replaced them with a -single value, @var{a+b}. There may be other values on the stack below -those shown, but the bytecode affects only those shown. - -Here is another example: - -@table @asis - -@item @code{const8} (0x22) @var{n}: @result{} @var{n} -Push the 8-bit integer constant @var{n} on the stack, without sign -extension. - -@end table - -In this example, the bytecode @code{const8} takes an operand @var{n} -directly from the bytecode stream; the operand follows the @code{const8} -bytecode itself. We write any such operands immediately after the name -of the bytecode, before the colon, and describe the exact encoding of -the operand in the bytecode stream in the body of the bytecode -description. - -For the @code{const8} bytecode, there are no stack items given before -the @result{}; this simply means that the bytecode consumes no values -from the stack. If a bytecode consumes no values, or produces no -values, the list on either side of the @result{} may be empty. - -If a value is written as @var{a}, @var{b}, or @var{n}, then the bytecode -treats it as an integer. If a value is written is @var{addr}, then the -bytecode treats it as an address. - -We do not fully describe the floating point operations here; although -this design can be extended in a clean way to handle floating point -values, they are not of immediate interest to the customer, so we avoid -describing them, to save time. - - -@table @asis - -@item @code{float} (0x01): @result{} - -Prefix for floating-point bytecodes. Not implemented yet. - -@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b} -Pop two integers from the stack, and push their sum, as an integer. - -@item @code{sub} (0x03): @var{a} @var{b} @result{} @var{a-b} -Pop two integers from the stack, subtract the top value from the -next-to-top value, and push the difference. - -@item @code{mul} (0x04): @var{a} @var{b} @result{} @var{a*b} -Pop two integers from the stack, multiply them, and push the product on -the stack. Note that, when one multiplies two @var{n}-bit numbers -yielding another @var{n}-bit number, it is irrelevant whether the -numbers are signed or not; the results are the same. - -@item @code{div_signed} (0x05): @var{a} @var{b} @result{} @var{a/b} -Pop two signed integers from the stack; divide the next-to-top value by -the top value, and push the quotient. If the divisor is zero, terminate -with an error. - -@item @code{div_unsigned} (0x06): @var{a} @var{b} @result{} @var{a/b} -Pop two unsigned integers from the stack; divide the next-to-top value -by the top value, and push the quotient. If the divisor is zero, -terminate with an error. - -@item @code{rem_signed} (0x07): @var{a} @var{b} @result{} @var{a modulo b} -Pop two signed integers from the stack; divide the next-to-top value by -the top value, and push the remainder. If the divisor is zero, -terminate with an error. - -@item @code{rem_unsigned} (0x08): @var{a} @var{b} @result{} @var{a modulo b} -Pop two unsigned integers from the stack; divide the next-to-top value -by the top value, and push the remainder. If the divisor is zero, -terminate with an error. - -@item @code{lsh} (0x09): @var{a} @var{b} @result{} @var{a<<b} -Pop two integers from the stack; let @var{a} be the next-to-top value, -and @var{b} be the top value. Shift @var{a} left by @var{b} bits, and -push the result. - -@item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @code{(signed)}@var{a>>b} -Pop two integers from the stack; let @var{a} be the next-to-top value, -and @var{b} be the top value. Shift @var{a} right by @var{b} bits, -inserting copies of the top bit at the high end, and push the result. - -@item @code{rsh_unsigned} (0x0b): @var{a} @var{b} @result{} @var{a>>b} -Pop two integers from the stack; let @var{a} be the next-to-top value, -and @var{b} be the top value. Shift @var{a} right by @var{b} bits, -inserting zero bits at the high end, and push the result. - -@item @code{log_not} (0x0e): @var{a} @result{} @var{!a} -Pop an integer from the stack; if it is zero, push the value one; -otherwise, push the value zero. - -@item @code{bit_and} (0x0f): @var{a} @var{b} @result{} @var{a&b} -Pop two integers from the stack, and push their bitwise @code{and}. - -@item @code{bit_or} (0x10): @var{a} @var{b} @result{} @var{a|b} -Pop two integers from the stack, and push their bitwise @code{or}. - -@item @code{bit_xor} (0x11): @var{a} @var{b} @result{} @var{a^b} -Pop two integers from the stack, and push their bitwise -exclusive-@code{or}. - -@item @code{bit_not} (0x12): @var{a} @result{} @var{~a} -Pop an integer from the stack, and push its bitwise complement. - -@item @code{equal} (0x13): @var{a} @var{b} @result{} @var{a=b} -Pop two integers from the stack; if they are equal, push the value one; -otherwise, push the value zero. - -@item @code{less_signed} (0x14): @var{a} @var{b} @result{} @var{a<b} -Pop two signed integers from the stack; if the next-to-top value is less -than the top value, push the value one; otherwise, push the value zero. - -@item @code{less_unsigned} (0x15): @var{a} @var{b} @result{} @var{a<b} -Pop two unsigned integers from the stack; if the next-to-top value is less -than the top value, push the value one; otherwise, push the value zero. - -@item @code{ext} (0x16) @var{n}: @var{a} @result{} @var{a}, sign-extended from @var{n} bits -Pop an unsigned value from the stack; treating it as an @var{n}-bit -twos-complement value, extend it to full length. This means that all -bits to the left of bit @var{n-1} (where the least significant bit is bit -0) are set to the value of bit @var{n-1}. Note that @var{n} may be -larger than or equal to the width of the stack elements of the bytecode -engine; in this case, the bytecode should have no effect. - -The number of source bits to preserve, @var{n}, is encoded as a single -byte unsigned integer following the @code{ext} bytecode. - -@item @code{zero_ext} (0x2a) @var{n}: @var{a} @result{} @var{a}, zero-extended from @var{n} bits -Pop an unsigned value from the stack; zero all but the bottom @var{n} -bits. This means that all bits to the left of bit @var{n-1} (where the -least significant bit is bit 0) are set to the value of bit @var{n-1}. - -The number of source bits to preserve, @var{n}, is encoded as a single -byte unsigned integer following the @code{zero_ext} bytecode. - -@item @code{ref8} (0x17): @var{addr} @result{} @var{a} -@itemx @code{ref16} (0x18): @var{addr} @result{} @var{a} -@itemx @code{ref32} (0x19): @var{addr} @result{} @var{a} -@itemx @code{ref64} (0x1a): @var{addr} @result{} @var{a} -Pop an address @var{addr} from the stack. For bytecode -@code{ref}@var{n}, fetch an @var{n}-bit value from @var{addr}, using the -natural target endianness. Push the fetched value as an unsigned -integer. - -Note that @var{addr} may not be aligned in any particular way; the -@code{ref@var{n}} bytecodes should operate correctly for any address. - -If attempting to access memory at @var{addr} would cause a processor -exception of some sort, terminate with an error. - -@item @code{ref_float} (0x1b): @var{addr} @result{} @var{d} -@itemx @code{ref_double} (0x1c): @var{addr} @result{} @var{d} -@itemx @code{ref_long_double} (0x1d): @var{addr} @result{} @var{d} -@itemx @code{l_to_d} (0x1e): @var{a} @result{} @var{d} -@itemx @code{d_to_l} (0x1f): @var{d} @result{} @var{a} -Not implemented yet. - -@item @code{dup} (0x28): @var{a} => @var{a} @var{a} -Push another copy of the stack's top element. - -@item @code{swap} (0x2b): @var{a} @var{b} => @var{b} @var{a} -Exchange the top two items on the stack. - -@item @code{pop} (0x29): @var{a} => -Discard the top value on the stack. - -@item @code{if_goto} (0x20) @var{offset}: @var{a} @result{} -Pop an integer off the stack; if it is non-zero, branch to the given -offset in the bytecode string. Otherwise, continue to the next -instruction in the bytecode stream. In other words, if @var{a} is -non-zero, set the @code{pc} register to @code{start} + @var{offset}. -Thus, an offset of zero denotes the beginning of the expression. - -The @var{offset} is stored as a sixteen-bit unsigned value, stored -immediately following the @code{if_goto} bytecode. It is always stored -most significant byte first, regardless of the target's normal -endianness. The offset is not guaranteed to fall at any particular -alignment within the bytecode stream; thus, on machines where fetching a -16-bit on an unaligned address raises an exception, you should fetch the -offset one byte at a time. - -@item @code{goto} (0x21) @var{offset}: @result{} -Branch unconditionally to @var{offset}; in other words, set the -@code{pc} register to @code{start} + @var{offset}. - -The offset is stored in the same way as for the @code{if_goto} bytecode. - -@item @code{const8} (0x22) @var{n}: @result{} @var{n} -@itemx @code{const16} (0x23) @var{n}: @result{} @var{n} -@itemx @code{const32} (0x24) @var{n}: @result{} @var{n} -@itemx @code{const64} (0x25) @var{n}: @result{} @var{n} -Push the integer constant @var{n} on the stack, without sign extension. -To produce a small negative value, push a small twos-complement value, -and then sign-extend it using the @code{ext} bytecode. - -The constant @var{n} is stored in the appropriate number of bytes -following the @code{const}@var{b} bytecode. The constant @var{n} is -always stored most significant byte first, regardless of the target's -normal endianness. The constant is not guaranteed to fall at any -particular alignment within the bytecode stream; thus, on machines where -fetching a 16-bit on an unaligned address raises an exception, you -should fetch @var{n} one byte at a time. - -@item @code{reg} (0x26) @var{n}: @result{} @var{a} -Push the value of register number @var{n}, without sign extension. The -registers are numbered following GDB's conventions. - -The register number @var{n} is encoded as a 16-bit unsigned integer -immediately following the @code{reg} bytecode. It is always stored most -significant byte first, regardless of the target's normal endianness. -The register number is not guaranteed to fall at any particular -alignment within the bytecode stream; thus, on machines where fetching a -16-bit on an unaligned address raises an exception, you should fetch the -register number one byte at a time. - -@item @code{trace} (0x0c): @var{addr} @var{size} @result{} -Record the contents of the @var{size} bytes at @var{addr} in a trace -buffer, for later retrieval by GDB. - -@item @code{trace_quick} (0x0d) @var{size}: @var{addr} @result{} @var{addr} -Record the contents of the @var{size} bytes at @var{addr} in a trace -buffer, for later retrieval by GDB. @var{size} is a single byte -unsigned integer following the @code{trace} opcode. - -This bytecode is equivalent to the sequence @code{dup const8 @var{size} -trace}, but we provide it anyway to save space in bytecode strings. - -@item @code{trace16} (0x30) @var{size}: @var{addr} @result{} @var{addr} -Identical to trace_quick, except that @var{size} is a 16-bit big-endian -unsigned integer, not a single byte. This should probably have been -named @code{trace_quick16}, for consistency. - -@item @code{end} (0x27): @result{} -Stop executing bytecode; the result should be the top element of the -stack. If the purpose of the expression was to compute an lvalue or a -range of memory, then the next-to-top of the stack is the lvalue's -address, and the top of the stack is the lvalue's size, in bytes. - -@end table - - -@node Using Agent Expressions -@section Using Agent Expressions - -Here is a sketch of a full non-stop debugging cycle, showing how agent -expressions fit into the process. - -@itemize @bullet - -@item -The user selects trace points in the program's code at which GDB should -collect data. - -@item -The user specifies expressions to evaluate at each trace point. These -expressions may denote objects in memory, in which case those objects' -contents are recorded as the program runs, or computed values, in which -case the values themselves are recorded. - -@item -GDB transmits the tracepoints and their associated expressions to the -GDB agent, running on the debugging target. - -@item -The agent arranges to be notified when a trace point is hit. Note that, -on some systems, the target operating system is completely responsible -for collecting the data; see @ref{Tracing on Symmetrix}. - -@item -When execution on the target reaches a trace point, the agent evaluates -the expressions associated with that trace point, and records the -resulting values and memory ranges. - -@item -Later, when the user selects a given trace event and inspects the -objects and expression values recorded, GDB talks to the agent to -retrieve recorded data as necessary to meet the user's requests. If the -user asks to see an object whose contents have not been recorded, GDB -reports an error. - -@end itemize - - -@node Varying Target Capabilities -@section Varying Target Capabilities - -Some targets don't support floating-point, and some would rather not -have to deal with @code{long long} operations. Also, different targets -will have different stack sizes, and different bytecode buffer lengths. - -Thus, GDB needs a way to ask the target about itself. We haven't worked -out the details yet, but in general, GDB should be able to send the -target a packet asking it to describe itself. The reply should be a -packet whose length is explicit, so we can add new information to the -packet in future revisions of the agent, without confusing old versions -of GDB, and it should contain a version number. It should contain at -least the following information: - -@itemize @bullet - -@item -whether floating point is supported - -@item -whether @code{long long} is supported - -@item -maximum acceptable size of bytecode stack - -@item -maximum acceptable length of bytecode expressions - -@item -which registers are actually available for collection - -@item -whether the target supports disabled tracepoints - -@end itemize - - - -@node Tracing on Symmetrix -@section Tracing on Symmetrix - -This section documents the API used by the GDB agent to collect data on -Symmetrix systems. - -Cygnus originally implemented these tracing features to help EMC -Corporation debug their Symmetrix high-availability disk drives. The -Symmetrix application code already includes substantial tracing -facilities; the GDB agent for the Symmetrix system uses those facilities -for its own data collection, via the API described here. - -@deftypefn Function DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *@var{frame}, char *@var{address}, char **@var{buffer}, unsigned int *@var{size}) -Search the trace frame @var{frame} for memory saved from @var{address}. -If the memory is available, provide the address of the buffer holding -it; otherwise, provide the address of the next saved area. - -@itemize @bullet - -@item -If the memory at @var{address} was saved in @var{frame}, set -@code{*@var{buffer}} to point to the buffer in which that memory was -saved, set @code{*@var{size}} to the number of bytes from @var{address} -that are saved at @code{*@var{buffer}}, and return -@code{OK_TARGET_RESPONSE}. (Clearly, in this case, the function will -always set @code{*@var{size}} to a value greater than zero.) - -@item -If @var{frame} does not record any memory at @var{address}, set -@code{*@var{size}} to the distance from @var{address} to the start of -the saved region with the lowest address higher than @var{address}. If -there is no memory saved from any higher address, set @code{*@var{size}} -to zero. Return @code{NOT_FOUND_TARGET_RESPONSE}. -@end itemize - -These two possibilities allow the caller to either retrieve the data, or -walk the address space to the next saved area. -@end deftypefn - -This function allows the GDB agent to map the regions of memory saved in -a particular frame, and retrieve their contents efficiently. - -This function also provides a clean interface between the GDB agent and -the Symmetrix tracing structures, making it easier to adapt the GDB -agent to future versions of the Symmetrix system, and vice versa. This -function searches all data saved in @var{frame}, whether the data is -there at the request of a bytecode expression, or because it falls in -one of the format's memory ranges, or because it was saved from the top -of the stack. EMC can arbitrarily change and enhance the tracing -mechanism, but as long as this function works properly, all collected -memory is visible to GDB. - -The function itself is straightforward to implement. A single pass over -the trace frame's stack area, memory ranges, and expression blocks can -yield the address of the buffer (if the requested address was saved), -and also note the address of the next higher range of memory, to be -returned when the search fails. - -As an example, suppose the trace frame @code{f} has saved sixteen bytes -from address @code{0x8000} in a buffer at @code{0x1000}, and thirty-two -bytes from address @code{0xc000} in a buffer at @code{0x1010}. Here are -some sample calls, and the effect each would have: - -@table @code - -@item adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size) -This would set @code{buffer} to @code{0x1000}, set @code{size} to -sixteen, and return @code{OK_TARGET_RESPONSE}, since @code{f} saves -sixteen bytes from @code{0x8000} at @code{0x1000}. - -@item adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size) -This would set @code{buffer} to @code{0x1004}, set @code{size} to -twelve, and return @code{OK_TARGET_RESPONSE}, since @file{f} saves the -twelve bytes from @code{0x8004} starting four bytes into the buffer at -@code{0x1000}. This shows that request addresses may fall in the middle -of saved areas; the function should return the address and size of the -remainder of the buffer. - -@item adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size) -This would set @code{size} to @code{0x3f00} and return -@code{NOT_FOUND_TARGET_RESPONSE}, since there is no memory saved in -@code{f} from the address @code{0x8100}, and the next memory available -is at @code{0x8100 + 0x3f00}, or @code{0xc000}. This shows that request -addresses may fall outside of all saved memory ranges; the function -should indicate the next saved area, if any. - -@item adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size) -This would set @code{size} to @code{0x1000} and return -@code{NOT_FOUND_TARGET_RESPONSE}, since the next saved memory is at -@code{0x7000 + 0x1000}, or @code{0x8000}. - -@item adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size) -This would set @code{size} to zero, and return -@code{NOT_FOUND_TARGET_RESPONSE}. This shows how the function tells the -caller that no further memory ranges have been saved. - -@end table - -As another example, here is a function which will print out the -addresses of all memory saved in the trace frame @code{frame} on the -Symmetrix INLINES console: -@example -void -print_frame_addresses (FRAME_DEF *frame) -@{ - char *addr; - char *buffer; - unsigned long size; - - addr = 0; - for (;;) - @{ - /* Either find out how much memory we have here, or discover - where the next saved region is. */ - if (adbg_find_memory_in_frame (frame, addr, &buffer, &size) - == OK_TARGET_RESPONSE) - printp ("saved %x to %x\n", addr, addr + size); - if (size == 0) - break; - addr += size; - @} -@} -@end example - -Note that there is not necessarily any connection between the order in -which the data is saved in the trace frame, and the order in which -@code{adbg_find_memory_in_frame} will return those memory ranges. The -code above will always print the saved memory regions in order of -increasing address, while the underlying frame structure might store the -data in a random order. - -[[This section should cover the rest of the Symmetrix functions the stub -relies upon, too.]] - -@node Rationale -@section Rationale - -Some of the design decisions apparent above are arguable. - -@table @b - -@item What about stack overflow/underflow? -GDB should be able to query the target to discover its stack size. -Given that information, GDB can determine at translation time whether a -given expression will overflow the stack. But this spec isn't about -what kinds of error-checking GDB ought to do. - -@item Why are you doing everything in LONGEST? - -Speed isn't important, but agent code size is; using LONGEST brings in a -bunch of support code to do things like division, etc. So this is a -serious concern. - -First, note that you don't need different bytecodes for different -operand sizes. You can generate code without @emph{knowing} how big the -stack elements actually are on the target. If the target only supports -32-bit ints, and you don't send any 64-bit bytecodes, everything just -works. The observation here is that the MIPS and the Alpha have only -fixed-size registers, and you can still get C's semantics even though -most instructions only operate on full-sized words. You just need to -make sure everything is properly sign-extended at the right times. So -there is no need for 32- and 64-bit variants of the bytecodes. Just -implement everything using the largest size you support. - -GDB should certainly check to see what sizes the target supports, so the -user can get an error earlier, rather than later. But this information -is not necessary for correctness. - - -@item Why don't you have @code{>} or @code{<=} operators? -I want to keep the interpreter small, and we don't need them. We can -combine the @code{less_} opcodes with @code{log_not}, and swap the order -of the operands, yielding all four asymmetrical comparison operators. -For example, @code{(x <= y)} is @code{! (x > y)}, which is @code{! (y < -x)}. - -@item Why do you have @code{log_not}? -@itemx Why do you have @code{ext}? -@itemx Why do you have @code{zero_ext}? -These are all easily synthesized from other instructions, but I expect -them to be used frequently, and they're simple, so I include them to -keep bytecode strings short. - -@code{log_not} is equivalent to @code{const8 0 equal}; it's used in half -the relational operators. - -@code{ext @var{n}} is equivalent to @code{const8 @var{s-n} lsh const8 -@var{s-n} rsh_signed}, where @var{s} is the size of the stack elements; -it follows @code{ref@var{m}} and @var{reg} bytecodes when the value -should be signed. See the next bulleted item. - -@code{zero_ext @var{n}} is equivalent to @code{const@var{m} @var{mask} -log_and}; it's used whenever we push the value of a register, because we -can't assume the upper bits of the register aren't garbage. - -@item Why not have sign-extending variants of the @code{ref} operators? -Because that would double the number of @code{ref} operators, and we -need the @code{ext} bytecode anyway for accessing bitfields. - -@item Why not have constant-address variants of the @code{ref} operators? -Because that would double the number of @code{ref} operators again, and -@code{const32 @var{address} ref32} is only one byte longer. - -@item Why do the @code{ref@var{n}} operators have to support unaligned fetches? -GDB will generate bytecode that fetches multi-byte values at unaligned -addresses whenever the executable's debugging information tells it to. -Furthermore, GDB does not know the value the pointer will have when GDB -generates the bytecode, so it cannot determine whether a particular -fetch will be aligned or not. - -In particular, structure bitfields may be several bytes long, but follow -no alignment rules; members of packed structures are not necessarily -aligned either. - -In general, there are many cases where unaligned references occur in -correct C code, either at the programmer's explicit request, or at the -compiler's discretion. Thus, it is simpler to make the GDB agent -bytecodes work correctly in all circumstances than to make GDB guess in -each case whether the compiler did the usual thing. - -@item Why are there no side-effecting operators? -Because our current client doesn't want them? That's a cheap answer. I -think the real answer is that I'm afraid of implementing function -calls. We should re-visit this issue after the present contract is -delivered. - -@item Why aren't the @code{goto} ops PC-relative? -The interpreter has the base address around anyway for PC bounds -checking, and it seemed simpler. - -@item Why is there only one offset size for the @code{goto} ops? -Offsets are currently sixteen bits. I'm not happy with this situation -either: - -Suppose we have multiple branch ops with different offset sizes. As I -generate code left-to-right, all my jumps are forward jumps (there are -no loops in expressions), so I never know the target when I emit the -jump opcode. Thus, I have to either always assume the largest offset -size, or do jump relaxation on the code after I generate it, which seems -like a big waste of time. - -I can imagine a reasonable expression being longer than 256 bytes. I -can't imagine one being longer than 64k. Thus, we need 16-bit offsets. -This kind of reasoning is so bogus, but relaxation is pathetic. - -The other approach would be to generate code right-to-left. Then I'd -always know my offset size. That might be fun. - -@item Where is the function call bytecode? - -When we add side-effects, we should add this. - -@item Why does the @code{reg} bytecode take a 16-bit register number? - -Intel's IA-64 architecture has 128 general-purpose registers, -and 128 floating-point registers, and I'm sure it has some random -control registers. - -@item Why do we need @code{trace} and @code{trace_quick}? -Because GDB needs to record all the memory contents and registers an -expression touches. If the user wants to evaluate an expression -@code{x->y->z}, the agent must record the values of @code{x} and -@code{x->y} as well as the value of @code{x->y->z}. - -@item Don't the @code{trace} bytecodes make the interpreter less general? -They do mean that the interpreter contains special-purpose code, but -that doesn't mean the interpreter can only be used for that purpose. If -an expression doesn't use the @code{trace} bytecodes, they don't get in -its way. - -@item Why doesn't @code{trace_quick} consume its arguments the way everything else does? -In general, you do want your operators to consume their arguments; it's -consistent, and generally reduces the amount of stack rearrangement -necessary. However, @code{trace_quick} is a kludge to save space; it -only exists so we needn't write @code{dup const8 @var{SIZE} trace} -before every memory reference. Therefore, it's okay for it not to -consume its arguments; it's meant for a specific context in which we -know exactly what it should do with the stack. If we're going to have a -kludge, it should be an effective kludge. - -@item Why does @code{trace16} exist? -That opcode was added by the customer that contracted Cygnus for the -data tracing work. I personally think it is unnecessary; objects that -large will be quite rare, so it is okay to use @code{dup const16 -@var{size} trace} in those cases. - -Whatever we decide to do with @code{trace16}, we should at least leave -opcode 0x30 reserved, to remain compatible with the customer who added -it. - -@end table diff --git a/contrib/gdb/gdb/doc/all-cfg.texi b/contrib/gdb/gdb/doc/all-cfg.texi deleted file mode 100644 index b680ea2b4925..000000000000 --- a/contrib/gdb/gdb/doc/all-cfg.texi +++ /dev/null @@ -1,45 +0,0 @@ -@c GDB MANUAL configuration file. -@c -@c Copyright 1993, 1995, 1999, 2002 Free Software Foundation, Inc. -@c -@c NOTE: While the GDB manual is configurable (by changing these -@c switches), its configuration is ***NOT*** automatically tied in to -@c source configuration---because the authors expect that, save in -@c unusual cases, the most inclusive form of the manual is appropriate -@c no matter how the program itself is configured. -@c -@c The only automatically-varying variable is the GDB version number, -@c which the Makefile rewrites based on the VERSION variable from -@c `../Makefile.in'. -@c -@c GDB version number is recorded in the variable GDBVN -@include GDBvn.texi -@c -@c ---------------------------------------------------------------------- -@c PLATFORM FLAGS: -@set GENERIC -@c -@c HP PA-RISC target ONLY: -@clear HPPA -@c -@c Refrain from discussing how to configure sw and format doc? -@clear PRECONFIGURED -@c -@c ---------------------------------------------------------------------- -@c STRINGS: -@c -@c Name of GDB program. Used also for (gdb) prompt string. -@set GDBP gdb -@c -@c Name of GDB product. Used in running text. -@set GDBN @sc{gdb} -@c -@c Name of host. Should not be used in generic configs, but generic -@c value may catch some flubs. -@set HOST machine specific -@c -@c Name of GCC product -@set NGCC @sc{gcc} -@c -@c Name of GCC program -@set GCC gcc diff --git a/contrib/gdb/gdb/doc/annotate.texinfo b/contrib/gdb/gdb/doc/annotate.texinfo deleted file mode 100644 index 2fb79d39d0e7..000000000000 --- a/contrib/gdb/gdb/doc/annotate.texinfo +++ /dev/null @@ -1,834 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename annotate.info - -@c This is a dir.info fragment to support semi-automated addition of -@c manuals to an info tree. -@dircategory Software development -@direntry -* Annotate: (annotate). The obsolete annotation interface. -@end direntry - -@c -@include gdb-cfg.texi -@c -@settitle @value{GDBN}'s Obsolete Annotations -@setchapternewpage off -@c %**end of header - -@set EDITION 1.0 -@set DATE July 2003 - -@c NOTE: cagney/2003-07-28: -@c Don't make this migration doccument an appendix of GDB's user guide. -@c By keeping this separate, the size of the user guide is contained. If -@c the user guide to get much bigger it would need to switch to a larger, -@c more expensive, form factor and would drive up the manuals publication -@c cost. Having a smaller cheaper manual helps the GNU Press with its sales. - -@ifinfo -This file documents @value{GDBN}'s obsolete annotations. - -Copyright 1994, 1995, 2000, 2001, 2003 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. - -@end ifinfo - -@titlepage -@title @value{GDBN}'s Obsolete Annotations -@subtitle Edition @value{EDITION} -@subtitle @value{DATE} -@author Free Software Foundation -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1994, 1995, 2000, 2001, 2003 Free Software -Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end titlepage - -@ifinfo -@node Top -@top GDB Annotations - -This document describes the obsolete level two annotation interface -implemented in older @value{GDBN} versions. - -@ignore -This is Edition @value{EDITION}, @value{DATE}. -@end ignore -@end ifinfo - -@menu -* Annotations Overview:: What annotations are; the general syntax. -* Limitations:: Limitations of the annotation interface. -* Migrating to GDB/MI:: Migrating to GDB/MI -* Server Prefix:: Issuing a command without affecting user state. -* Value Annotations:: Values are marked as such. -* Frame Annotations:: Stack frames are annotated. -* Displays:: @value{GDBN} can be told to display something periodically. -* Prompting:: Annotations marking @value{GDBN}'s need for input. -* Errors:: Annotations for error messages. -* Breakpoint Info:: Information on breakpoints. -* Invalidation:: Some annotations describe things now invalid. -* Annotations for Running:: - Whether the program is running, how it stopped, etc. -* Source Annotations:: Annotations describing source code. - -* GNU Free Documentation License:: -@end menu - -@contents - -@node Annotations Overview -@chapter What is an Annotation? -@cindex annotations - -To produce obsolete level two annotations, start @value{GDBN} with the -@code{--annotate=2} option. - -Annotations start with a newline character, two @samp{control-z} -characters, and the name of the annotation. If there is no additional -information associated with this annotation, the name of the annotation -is followed immediately by a newline. If there is additional -information, the name of the annotation is followed by a space, the -additional information, and a newline. The additional information -cannot contain newline characters. - -Any output not beginning with a newline and two @samp{control-z} -characters denotes literal output from @value{GDBN}. Currently there is -no need for @value{GDBN} to output a newline followed by two -@samp{control-z} characters, but if there was such a need, the -annotations could be extended with an @samp{escape} annotation which -means those three characters as output. - -A simple example of starting up @value{GDBN} with annotations is: - -@smallexample -$ gdb --annotate=2 -GNU GDB 5.0 -Copyright 2000 Free Software Foundation, Inc. -GDB is free software, covered by the GNU General Public License, -and you are welcome to change it and/or distribute copies of it -under certain conditions. -Type "show copying" to see the conditions. -There is absolutely no warranty for GDB. Type "show warranty" -for details. -This GDB was configured as "sparc-sun-sunos4.1.3" - -^Z^Zpre-prompt -(gdb) -^Z^Zprompt -quit - -^Z^Zpost-prompt -$ -@end smallexample - -Here @samp{quit} is input to @value{GDBN}; the rest is output from -@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} -denotes a @samp{control-z} character) are annotations; the rest is -output from @value{GDBN}. - -@node Limitations -@chapter Limitations of the Annotation Interface - -The level two annotations mechanism is known to have a number of -technical and architectural limitations. As a consequence, in 2001, -with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi}, -the annotation interface was marked as deprecated. - -This chapter discusses the known problems. - -@section Dependant on @sc{cli} output - -The annotation interface works by interspersing markups with -@value{GDBN} normal command-line interpreter output. Unfortunately, this -makes the annotation client dependant on not just the annotations, but -also the @sc{cli} output. This is because the client is forced to -assume that specific @value{GDBN} commands provide specific information. -Any change to @value{GDBN}'s @sc{cli} output modifies or removes that -information and, consequently, likely breaks the client. - -Since the @sc{gdb/mi} output is independant of the @sc{cli}, it does not -have this problem. - -@section Scalability - -The annotation interface relies on value annotations (@pxref{Value -Annotations}) and the display mechanism as a way of obtaining up-to-date -value information. These mechanisms are not scalable. - -In a graphical environment, where many values can be displayed -simultaneously, a serious performance problem occurs when the client -tries to first extract from @value{GDBN}, and then re-display, all those -values. The client should instead only request and update the values -that changed. - -The @sc{gdb/mi} Variable Objects provide just that mechanism. - -@section Correctness - -The annotation interface assumes that a variable's value can only be -changed when the target is running. This assumption is not correct. A -single assignment to a single variable can result in the entire target, -and all displayed values, needing an update. - -The @sc{gdb/mi} Variable Objects include a mechanism for efficiently -reporting such changes. - -@section Reliability - -The @sc{gdb/mi} interface includes a dedicated test directory -(@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include -testsuite changes. - -@section Maintainability - -The annotation mechanism was implemented by interspersing @sc{cli} print -statements with various annotations. As a consequence, any @sc{cli} -output change can alter the annotation output. - -Since the @sc{gdb/mi} output is independant of the @sc{cli}, and the -@sc{gdb/mi} is increasingly implemented independant of the @sc{cli} -code, its long term maintenance is much easier. - -@node Migrating to GDB/MI -@chapter Migrating to @sc{gdb/mi} - -By using the @samp{interp mi} command, it is possible for annotation -clients to invoke @sc{gdb/mi} commands, and hence access the -@sc{gdb/mi}. By doing this, existing annotation clients have a -migration path from this obsolete interface to @sc{gdb/mi}. - -@node Server Prefix -@chapter The Server Prefix -@cindex server prefix for annotations - -To issue a command to @value{GDBN} without affecting certain aspects of -the state which is seen by users, prefix it with @samp{server }. This -means that this command will not affect the command history, nor will it -affect @value{GDBN}'s notion of which command to repeat if @key{RET} is -pressed on a line by itself. - -The server prefix does not affect the recording of values into the value -history; to print a value without recording it into the value history, -use the @code{output} command instead of the @code{print} command. - -@node Value Annotations -@chapter Values - -@emph{Value Annotations have been removed. @sc{gdb/mi} instead provides -Variable Objects.} - -@cindex annotations for values -When a value is printed in various contexts, @value{GDBN} uses -annotations to delimit the value from the surrounding text. - -@findex value-history-begin -@findex value-history-value -@findex value-history-end -If a value is printed using @code{print} and added to the value history, -the annotation looks like - -@smallexample -^Z^Zvalue-history-begin @var{history-number} @var{value-flags} -@var{history-string} -^Z^Zvalue-history-value -@var{the-value} -^Z^Zvalue-history-end -@end smallexample - -@noindent -where @var{history-number} is the number it is getting in the value -history, @var{history-string} is a string, such as @samp{$5 = }, which -introduces the value to the user, @var{the-value} is the output -corresponding to the value itself, and @var{value-flags} is @samp{*} for -a value which can be dereferenced and @samp{-} for a value which cannot. - -@findex value-begin -@findex value-end -If the value is not added to the value history (it is an invalid float -or it is printed with the @code{output} command), the annotation is similar: - -@smallexample -^Z^Zvalue-begin @var{value-flags} -@var{the-value} -^Z^Zvalue-end -@end smallexample - -@findex arg-begin -@findex arg-name-end -@findex arg-value -@findex arg-end -When @value{GDBN} prints an argument to a function (for example, in the output -from the @code{backtrace} command), it annotates it as follows: - -@smallexample -^Z^Zarg-begin -@var{argument-name} -^Z^Zarg-name-end -@var{separator-string} -^Z^Zarg-value @var{value-flags} -@var{the-value} -^Z^Zarg-end -@end smallexample - -@noindent -where @var{argument-name} is the name of the argument, -@var{separator-string} is text which separates the name from the value -for the user's benefit (such as @samp{=}), and @var{value-flags} and -@var{the-value} have the same meanings as in a -@code{value-history-begin} annotation. - -@findex field-begin -@findex field-name-end -@findex field-value -@findex field-end -When printing a structure, @value{GDBN} annotates it as follows: - -@smallexample -^Z^Zfield-begin @var{value-flags} -@var{field-name} -^Z^Zfield-name-end -@var{separator-string} -^Z^Zfield-value -@var{the-value} -^Z^Zfield-end -@end smallexample - -@noindent -where @var{field-name} is the name of the field, @var{separator-string} -is text which separates the name from the value for the user's benefit -(such as @samp{=}), and @var{value-flags} and @var{the-value} have the -same meanings as in a @code{value-history-begin} annotation. - -When printing an array, @value{GDBN} annotates it as follows: - -@smallexample -^Z^Zarray-section-begin @var{array-index} @var{value-flags} -@end smallexample - -@noindent -where @var{array-index} is the index of the first element being -annotated and @var{value-flags} has the same meaning as in a -@code{value-history-begin} annotation. This is followed by any number -of elements, where is element can be either a single element: - -@findex elt -@smallexample -@samp{,} @var{whitespace} ; @r{omitted for the first element} -@var{the-value} -^Z^Zelt -@end smallexample - -or a repeated element - -@findex elt-rep -@findex elt-rep-end -@smallexample -@samp{,} @var{whitespace} ; @r{omitted for the first element} -@var{the-value} -^Z^Zelt-rep @var{number-of-repetitions} -@var{repetition-string} -^Z^Zelt-rep-end -@end smallexample - -In both cases, @var{the-value} is the output for the value of the -element and @var{whitespace} can contain spaces, tabs, and newlines. In -the repeated case, @var{number-of-repetitions} is the number of -consecutive array elements which contain that value, and -@var{repetition-string} is a string which is designed to convey to the -user that repetition is being depicted. - -@findex array-section-end -Once all the array elements have been output, the array annotation is -ended with - -@smallexample -^Z^Zarray-section-end -@end smallexample - -@node Frame Annotations -@chapter Frames - -@emph{Value Annotations have been removed. @sc{gdb/mi} instead provides -a number of frame commands.} - -@emph{Frame annotations are no longer available. The @sc{gdb/mi} -provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and -@samp{-stack-list-frames} commands.} - -@cindex annotations for frames -Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies -to frames printed when @value{GDBN} stops, output from commands such as -@code{backtrace} or @code{up}, etc. - -@findex frame-begin -The frame annotation begins with - -@smallexample -^Z^Zframe-begin @var{level} @var{address} -@var{level-string} -@end smallexample - -@noindent -where @var{level} is the number of the frame (0 is the innermost frame, -and other frames have positive numbers), @var{address} is the address of -the code executing in that frame, and @var{level-string} is a string -designed to convey the level to the user. @var{address} is in the form -@samp{0x} followed by one or more lowercase hex digits (note that this -does not depend on the language). The frame ends with - -@findex frame-end -@smallexample -^Z^Zframe-end -@end smallexample - -Between these annotations is the main body of the frame, which can -consist of - -@itemize @bullet -@item -@findex function-call -@smallexample -^Z^Zfunction-call -@var{function-call-string} -@end smallexample - -where @var{function-call-string} is text designed to convey to the user -that this frame is associated with a function call made by @value{GDBN} to a -function in the program being debugged. - -@item -@findex signal-handler-caller -@smallexample -^Z^Zsignal-handler-caller -@var{signal-handler-caller-string} -@end smallexample - -where @var{signal-handler-caller-string} is text designed to convey to -the user that this frame is associated with whatever mechanism is used -by this operating system to call a signal handler (it is the frame which -calls the signal handler, not the frame for the signal handler itself). - -@item -A normal frame. - -@findex frame-address -@findex frame-address-end -This can optionally (depending on whether this is thought of as -interesting information for the user to see) begin with - -@smallexample -^Z^Zframe-address -@var{address} -^Z^Zframe-address-end -@var{separator-string} -@end smallexample - -where @var{address} is the address executing in the frame (the same -address as in the @code{frame-begin} annotation, but printed in a form -which is intended for user consumption---in particular, the syntax varies -depending on the language), and @var{separator-string} is a string -intended to separate this address from what follows for the user's -benefit. - -@findex frame-function-name -@findex frame-args -Then comes - -@smallexample -^Z^Zframe-function-name -@var{function-name} -^Z^Zframe-args -@var{arguments} -@end smallexample - -where @var{function-name} is the name of the function executing in the -frame, or @samp{??} if not known, and @var{arguments} are the arguments -to the frame, with parentheses around them (each argument is annotated -individually as well, @pxref{Value Annotations}). - -@findex frame-source-begin -@findex frame-source-file -@findex frame-source-file-end -@findex frame-source-line -@findex frame-source-end -If source information is available, a reference to it is then printed: - -@smallexample -^Z^Zframe-source-begin -@var{source-intro-string} -^Z^Zframe-source-file -@var{filename} -^Z^Zframe-source-file-end -: -^Z^Zframe-source-line -@var{line-number} -^Z^Zframe-source-end -@end smallexample - -where @var{source-intro-string} separates for the user's benefit the -reference from the text which precedes it, @var{filename} is the name of -the source file, and @var{line-number} is the line number within that -file (the first line is line 1). - -@findex frame-where -If @value{GDBN} prints some information about where the frame is from (which -library, which load segment, etc.; currently only done on the RS/6000), -it is annotated with - -@smallexample -^Z^Zframe-where -@var{information} -@end smallexample - -Then, if source is to actually be displayed for this frame (for example, -this is not true for output from the @code{backtrace} command), then a -@code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike -most annotations, this is output instead of the normal text which would be -output, not in addition. -@end itemize - -@node Displays -@chapter Displays - -@emph{Display Annotations have been removed. @sc{gdb/mi} instead -provides Variable Objects.} - -@findex display-begin -@findex display-number-end -@findex display-format -@findex display-expression -@findex display-expression-end -@findex display-value -@findex display-end -@cindex annotations for display -When @value{GDBN} is told to display something using the @code{display} command, -the results of the display are annotated: - -@smallexample -^Z^Zdisplay-begin -@var{number} -^Z^Zdisplay-number-end -@var{number-separator} -^Z^Zdisplay-format -@var{format} -^Z^Zdisplay-expression -@var{expression} -^Z^Zdisplay-expression-end -@var{expression-separator} -^Z^Zdisplay-value -@var{value} -^Z^Zdisplay-end -@end smallexample - -@noindent -where @var{number} is the number of the display, @var{number-separator} -is intended to separate the number from what follows for the user, -@var{format} includes information such as the size, format, or other -information about how the value is being displayed, @var{expression} is -the expression being displayed, @var{expression-separator} is intended -to separate the expression from the text that follows for the user, -and @var{value} is the actual value being displayed. - -@node Prompting -@chapter Annotation for @value{GDBN} Input - -@cindex annotations for prompts -When @value{GDBN} prompts for input, it annotates this fact so it is possible -to know when to send output, when the output from a given command is -over, etc. - -Different kinds of input each have a different @dfn{input type}. Each -input type has three annotations: a @code{pre-} annotation, which -denotes the beginning of any prompt which is being output, a plain -annotation, which denotes the end of the prompt, and then a @code{post-} -annotation which denotes the end of any echo which may (or may not) be -associated with the input. For example, the @code{prompt} input type -features the following annotations: - -@smallexample -^Z^Zpre-prompt -^Z^Zprompt -^Z^Zpost-prompt -@end smallexample - -The input types are - -@table @code -@findex pre-prompt -@findex prompt -@findex post-prompt -@item prompt -When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). - -@findex pre-commands -@findex commands -@findex post-commands -@item commands -When @value{GDBN} prompts for a set of commands, like in the @code{commands} -command. The annotations are repeated for each command which is input. - -@findex pre-overload-choice -@findex overload-choice -@findex post-overload-choice -@item overload-choice -When @value{GDBN} wants the user to select between various overloaded functions. - -@findex pre-query -@findex query -@findex post-query -@item query -When @value{GDBN} wants the user to confirm a potentially dangerous operation. - -@findex pre-prompt-for-continue -@findex prompt-for-continue -@findex post-prompt-for-continue -@item prompt-for-continue -When @value{GDBN} is asking the user to press return to continue. Note: Don't -expect this to work well; instead use @code{set height 0} to disable -prompting. This is because the counting of lines is buggy in the -presence of annotations. -@end table - -@node Errors -@chapter Errors -@cindex annotations for errors, warnings and interrupts - -@findex quit -@smallexample -^Z^Zquit -@end smallexample - -This annotation occurs right before @value{GDBN} responds to an interrupt. - -@findex error -@smallexample -^Z^Zerror -@end smallexample - -This annotation occurs right before @value{GDBN} responds to an error. - -Quit and error annotations indicate that any annotations which @value{GDBN} was -in the middle of may end abruptly. For example, if a -@code{value-history-begin} annotation is followed by a @code{error}, one -cannot expect to receive the matching @code{value-history-end}. One -cannot expect not to receive it either, however; an error annotation -does not necessarily mean that @value{GDBN} is immediately returning all the way -to the top level. - -@findex error-begin -A quit or error annotation may be preceded by - -@smallexample -^Z^Zerror-begin -@end smallexample - -Any output between that and the quit or error annotation is the error -message. - -Warning messages are not yet annotated. -@c If we want to change that, need to fix warning(), type_error(), -@c range_error(), and possibly other places. - -@node Breakpoint Info -@chapter Information on Breakpoints - -@emph{Breakpoint Annotations have been removed. @sc{gdb/mi} instead -provides breakpoint commands.} - -@cindex annotations for breakpoints -The output from the @code{info breakpoints} command is annotated as follows: - -@findex breakpoints-headers -@findex breakpoints-table -@smallexample -^Z^Zbreakpoints-headers -@var{header-entry} -^Z^Zbreakpoints-table -@end smallexample - -@noindent -where @var{header-entry} has the same syntax as an entry (see below) but -instead of containing data, it contains strings which are intended to -convey the meaning of each field to the user. This is followed by any -number of entries. If a field does not apply for this entry, it is -omitted. Fields may contain trailing whitespace. Each entry consists -of: - -@findex record -@findex field -@smallexample -^Z^Zrecord -^Z^Zfield 0 -@var{number} -^Z^Zfield 1 -@var{type} -^Z^Zfield 2 -@var{disposition} -^Z^Zfield 3 -@var{enable} -^Z^Zfield 4 -@var{address} -^Z^Zfield 5 -@var{what} -^Z^Zfield 6 -@var{frame} -^Z^Zfield 7 -@var{condition} -^Z^Zfield 8 -@var{ignore-count} -^Z^Zfield 9 -@var{commands} -@end smallexample - -Note that @var{address} is intended for user consumption---the syntax -varies depending on the language. - -The output ends with - -@findex breakpoints-table-end -@smallexample -^Z^Zbreakpoints-table-end -@end smallexample - -@node Invalidation -@chapter Invalidation Notices - -@cindex annotations for invalidation messages -The following annotations say that certain pieces of state may have -changed. - -@table @code -@findex frames-invalid -@item ^Z^Zframes-invalid - -The frames (for example, output from the @code{backtrace} command) may -have changed. - -@findex breakpoints-invalid -@item ^Z^Zbreakpoints-invalid - -The breakpoints may have changed. For example, the user just added or -deleted a breakpoint. -@end table - -@node Annotations for Running -@chapter Running the Program -@cindex annotations for running programs - -@findex starting -@findex stopping -When the program starts executing due to a @value{GDBN} command such as -@code{step} or @code{continue}, - -@smallexample -^Z^Zstarting -@end smallexample - -is output. When the program stops, - -@smallexample -^Z^Zstopped -@end smallexample - -is output. Before the @code{stopped} annotation, a variety of -annotations describe how the program stopped. - -@table @code -@findex exited -@item ^Z^Zexited @var{exit-status} -The program exited, and @var{exit-status} is the exit status (zero for -successful exit, otherwise nonzero). - -@findex signalled -@findex signal-name -@findex signal-name-end -@findex signal-string -@findex signal-string-end -@item ^Z^Zsignalled -The program exited with a signal. After the @code{^Z^Zsignalled}, the -annotation continues: - -@smallexample -@var{intro-text} -^Z^Zsignal-name -@var{name} -^Z^Zsignal-name-end -@var{middle-text} -^Z^Zsignal-string -@var{string} -^Z^Zsignal-string-end -@var{end-text} -@end smallexample - -@noindent -where @var{name} is the name of the signal, such as @code{SIGILL} or -@code{SIGSEGV}, and @var{string} is the explanation of the signal, such -as @code{Illegal Instruction} or @code{Segmentation fault}. -@var{intro-text}, @var{middle-text}, and @var{end-text} are for the -user's benefit and have no particular format. - -@findex signal -@item ^Z^Zsignal -The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is -just saying that the program received the signal, not that it was -terminated with it. - -@findex breakpoint -@item ^Z^Zbreakpoint @var{number} -The program hit breakpoint number @var{number}. - -@findex watchpoint -@item ^Z^Zwatchpoint @var{number} -The program hit watchpoint number @var{number}. -@end table - -@node Source Annotations -@chapter Displaying Source -@cindex annotations for source display - -@findex source -The following annotation is used instead of displaying source code: - -@smallexample -^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} -@end smallexample - -where @var{filename} is an absolute file name indicating which source -file, @var{line} is the line number within that file (where 1 is the -first line in the file), @var{character} is the character position -within the file (where 0 is the first character in the file) (for most -debug formats this will necessarily point to the beginning of a line), -@var{middle} is @samp{middle} if @var{addr} is in the middle of the -line, or @samp{beg} if @var{addr} is at the beginning of the line, and -@var{addr} is the address in the target program associated with the -source which is being displayed. @var{addr} is in the form @samp{0x} -followed by one or more lowercase hex digits (note that this does not -depend on the language). - -@raisesections -@include fdl.texi -@lowersections - -@ignore -@node Index -@unnumbered Index - -@printindex fn -@end ignore - -@bye diff --git a/contrib/gdb/gdb/doc/fdl.texi b/contrib/gdb/gdb/doc/fdl.texi deleted file mode 100644 index 11737cc89bd1..000000000000 --- a/contrib/gdb/gdb/doc/fdl.texi +++ /dev/null @@ -1,452 +0,0 @@ - -@node GNU Free Documentation License -@appendixsec GNU Free Documentation License - -@cindex FDL, GNU Free Documentation License -@center Version 1.2, November 2002 - -@display -Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. -59 Temple Place, Suite 330, Boston, MA 02111-1307, USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. -@end enumerate - -@page -@appendixsubsec ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with...Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - diff --git a/contrib/gdb/gdb/doc/gdb.info-1 b/contrib/gdb/gdb/doc/gdb.info-1 deleted file mode 100644 index decf4543461a..000000000000 --- a/contrib/gdb/gdb/doc/gdb.info-1 +++ /dev/null @@ -1,7636 +0,0 @@ -This is gdb.info, produced by makeinfo version 4.6 from ./gdb.texinfo. - -INFO-DIR-SECTION Software development -START-INFO-DIR-ENTRY -* Gdb: (gdb). The GNU debugger. -END-INFO-DIR-ENTRY - - This file documents the GNU debugger GDB. - - This is the Ninth Edition, of `Debugging with GDB: the GNU -Source-Level Debugger' for GDB Version 6.1.1. - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1998, -1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "Free Software" and "Free Software Needs Free -Documentation", with the Front-Cover Texts being "A GNU Manual," and -with the Back-Cover Texts as in (a) below. - - (a) The Free Software Foundation's Back-Cover Text is: "You have -freedom to copy and modify this GNU Manual, like GNU software. Copies -published by the Free Software Foundation raise funds for GNU -development." - - -File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) - -Debugging with GDB -****************** - -This file describes GDB, the GNU symbolic debugger. - - This is the Ninth Edition, for GDB Version 6.1.1. - - Copyright (C) 1988-2004 Free Software Foundation, Inc. - -* Menu: - -* Summary:: Summary of GDB -* Sample Session:: A sample GDB session - -* Invocation:: Getting in and out of GDB -* Commands:: GDB commands -* Running:: Running programs under GDB -* Stopping:: Stopping and continuing -* Stack:: Examining the stack -* Source:: Examining source files -* Data:: Examining data -* Macros:: Preprocessor Macros -* Tracepoints:: Debugging remote targets non-intrusively -* Overlays:: Debugging programs that use overlays - -* Languages:: Using GDB with different languages - -* Symbols:: Examining the symbol table -* Altering:: Altering execution -* GDB Files:: GDB files -* Targets:: Specifying a debugging target -* Remote Debugging:: Debugging remote programs -* Configurations:: Configuration-specific information -* Controlling GDB:: Controlling GDB -* Sequences:: Canned sequences of commands -* TUI:: GDB Text User Interface -* Interpreters:: Command Interpreters -* Emacs:: Using GDB under GNU Emacs -* Annotations:: GDB's annotation interface. -* GDB/MI:: GDB's Machine Interface. - -* GDB Bugs:: Reporting bugs in GDB -* Formatting Documentation:: How to format and print GDB documentation - -* Command Line Editing:: Command Line Editing -* Using History Interactively:: Using History Interactively -* Installing GDB:: Installing GDB -* Maintenance Commands:: Maintenance Commands -* Remote Protocol:: GDB Remote Serial Protocol -* Agent Expressions:: The GDB Agent Expression Mechanism -* Copying:: GNU General Public License says - how you can copy and share GDB -* GNU Free Documentation License:: The license for this documentation -* Index:: Index - - -File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top - -Summary of GDB -************** - -The purpose of a debugger such as GDB is to allow you to see what is -going on "inside" another program while it executes--or what another -program was doing at the moment it crashed. - - GDB can do four main kinds of things (plus other things in support of -these) to help you catch bugs in the act: - - * Start your program, specifying anything that might affect its - behavior. - - * Make your program stop on specified conditions. - - * Examine what has happened, when your program has stopped. - - * Change things in your program, so you can experiment with - correcting the effects of one bug and go on to learn about another. - - You can use GDB to debug programs written in C and C++. For more -information, see *Note Supported languages: Support. For more -information, see *Note C and C++: C. - - Support for Modula-2 is partial. For information on Modula-2, see -*Note Modula-2: Modula-2. - - Debugging Pascal programs which use sets, subranges, file variables, -or nested functions does not currently work. GDB does not support -entering expressions, printing values, or similar features using Pascal -syntax. - - GDB can be used to debug programs written in Fortran, although it -may be necessary to refer to some variables with a trailing underscore. - - GDB can be used to debug programs written in Objective-C, using -either the Apple/NeXT or the GNU Objective-C runtime. - -* Menu: - -* Free Software:: Freely redistributable software -* Contributors:: Contributors to GDB - - -File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary - -Free software -============= - -GDB is "free software", protected by the GNU General Public License -(GPL). The GPL gives you the freedom to copy or adapt a licensed -program--but every person getting a copy also gets with it the freedom -to modify that copy (which means that they must get access to the -source code), and the freedom to distribute further copies. Typical -software companies use copyrights to limit your freedoms; the Free -Software Foundation uses the GPL to preserve these freedoms. - - Fundamentally, the General Public License is a license which says -that you have these freedoms and that you cannot take these freedoms -away from anyone else. - -Free Software Needs Free Documentation -====================================== - -The biggest deficiency in the free software community today is not in -the software--it is the lack of good free documentation that we can -include with the free software. Many of our most important programs do -not come with free reference manuals and free introductory texts. -Documentation is an essential part of any software package; when an -important free software package does not come with a free manual and a -free tutorial, that is a major gap. We have many such gaps today. - - Consider Perl, for instance. The tutorial manuals that people -normally use are non-free. How did this come about? Because the -authors of those manuals published them with restrictive terms--no -copying, no modification, source files not available--which exclude -them from the free software world. - - That wasn't the first time this sort of thing happened, and it was -far from the last. Many times we have heard a GNU user eagerly -describe a manual that he is writing, his intended contribution to the -community, only to learn that he had ruined everything by signing a -publication contract to make it non-free. - - Free documentation, like free software, is a matter of freedom, not -price. The problem with the non-free manual is not that publishers -charge a price for printed copies--that in itself is fine. (The Free -Software Foundation sells printed copies of manuals, too.) The problem -is the restrictions on the use of the manual. Free manuals are -available in source code form, and give you permission to copy and -modify. Non-free manuals do not allow this. - - The criteria of freedom for a free manual are roughly the same as for -free software. Redistribution (including the normal kinds of -commercial redistribution) must be permitted, so that the manual can -accompany every copy of the program, both on-line and on paper. - - Permission for modification of the technical content is crucial too. -When people modify the software, adding or changing features, if they -are conscientious they will change the manual too--so they can provide -accurate and clear documentation for the modified program. A manual -that leaves you no choice but to write a new manual to document a -changed version of the program is not really available to our community. - - Some kinds of limits on the way modification is handled are -acceptable. For example, requirements to preserve the original -author's copyright notice, the distribution terms, or the list of -authors, are ok. It is also no problem to require modified versions to -include notice that they were modified. Even entire sections that may -not be deleted or changed are acceptable, as long as they deal with -nontechnical topics (like this one). These kinds of restrictions are -acceptable because they don't obstruct the community's normal use of -the manual. - - However, it must be possible to modify all the _technical_ content -of the manual, and then distribute the result in all the usual media, -through all the usual channels. Otherwise, the restrictions obstruct -the use of the manual, it is not free, and we need another manual to -replace it. - - Please spread the word about this issue. Our community continues to -lose manuals to proprietary publishing. If we spread the word that -free software needs free reference manuals and free tutorials, perhaps -the next person who wants to contribute by writing documentation will -realize, before it is too late, that only free manuals contribute to -the free software community. - - If you are writing documentation, please insist on publishing it -under the GNU Free Documentation License or another free documentation -license. Remember that this decision requires your approval--you don't -have to let the publisher decide. Some commercial publishers will use -a free license if you insist, but they will not propose the option; it -is up to you to raise the issue and say firmly that this is what you -want. If the publisher you are dealing with refuses, please try other -publishers. If you're not sure whether a proposed license is free, -write to <licensing@gnu.org>. - - You can encourage commercial publishers to sell more free, copylefted -manuals and tutorials by buying them, and particularly by buying copies -from the publishers that paid for their writing or for major -improvements. Meanwhile, try to avoid buying non-free documentation at -all. Check the distribution terms of a manual before you buy it, and -insist that whoever seeks your business must respect your freedom. -Check the history of the book, and try to reward the publishers that -have paid or pay the authors to work on it. - - The Free Software Foundation maintains a list of free documentation -published by other publishers, at -<http://www.fsf.org/doc/other-free-books.html>. - - -File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary - -Contributors to GDB -=================== - -Richard Stallman was the original author of GDB, and of many other GNU -programs. Many others have contributed to its development. This -section attempts to credit major contributors. One of the virtues of -free software is that everyone is free to contribute to it; with -regret, we cannot actually acknowledge everyone here. The file -`ChangeLog' in the GDB distribution approximates a blow-by-blow account. - - Changes much prior to version 2.0 are lost in the mists of time. - - _Plea:_ Additions to this section are particularly welcome. If you - or your friends (or enemies, to be evenhanded) have been unfairly - omitted from this list, we would like to add your names! - - So that they may not regard their many labors as thankless, we -particularly thank those who shepherded GDB through major releases: -Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim Blandy -(release 4.18); Jason Molenda (release 4.17); Stan Shebs (release 4.14); -Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); Stu -Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); John -Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon (releases -3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1, and 3.0). - - Richard Stallman, assisted at various times by Peter TerMaat, Chris -Hanson, and Richard Mlynarik, handled releases through 2.8. - - Michael Tiemann is the author of most of the GNU C++ support in GDB, -with significant additional contributions from Per Bothner and Daniel -Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ -was by Peter TerMaat (who also did much general update work leading to -release 3.0). - - GDB uses the BFD subroutine library to examine multiple object-file -formats; BFD was a joint project of David V. Henkel-Wallace, Rich -Pixley, Steve Chamberlain, and John Gilmore. - - David Johnson wrote the original COFF support; Pace Willison did the -original support for encapsulated COFF. - - Brent Benson of Harris Computer Systems contributed DWARF 2 support. - - Adam de Boor and Bradley Davis contributed the ISI Optimum V support. -Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS -support. Jean-Daniel Fekete contributed Sun 386i support. Chris -Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki -Hasei contributed Sony/News OS 3 support. David Johnson contributed -Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. -Jeff Law contributed HP PA and SOM support. Keith Packard contributed -NS32K support. Doug Rabson contributed Acorn Risc Machine support. -Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith -contributed Convex support (and Fortran debugging). Jonathan Stone -contributed Pyramid support. Michael Tiemann contributed SPARC support. -Tim Tucker contributed support for the Gould NP1 and Gould Powernode. -Pace Willison contributed Intel 386 support. Jay Vosburgh contributed -Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. - - Andreas Schwab contributed M68K GNU/Linux support. - - Rich Schaefer and Peter Schauer helped with support of SunOS shared -libraries. - - Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about -several machine instruction sets. - - Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped -develop remote debugging. Intel Corporation, Wind River Systems, AMD, -and ARM contributed remote debugging modules for the i960, VxWorks, -A29K UDI, and RDI targets, respectively. - - Brian Fox is the author of the readline libraries providing -command-line editing and command history. - - Andrew Beers of SUNY Buffalo wrote the language-switching code, the -Modula-2 support, and contributed the Languages chapter of this manual. - - Fred Fish wrote most of the support for Unix System Vr4. He also -enhanced the command-completion support to cover C++ overloaded symbols. - - Hitachi America (now Renesas America), Ltd. sponsored the support for -H8/300, H8/500, and Super-H processors. - - NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx -processors. - - Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and -M32R/D processors. - - Toshiba sponsored the support for the TX39 Mips processor. - - Matsushita sponsored the support for the MN10200 and MN10300 -processors. - - Fujitsu sponsored the support for SPARClite and FR30 processors. - - Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware -watchpoints. - - Michael Snyder added support for tracepoints. - - Stu Grossman wrote gdbserver. - - Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly -innumerable bug fixes and cleanups throughout GDB. - - The following people at the Hewlett-Packard Company contributed -support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 -(narrow mode), HP's implementation of kernel threads, HP's aC++ -compiler, and the Text User Interface (nee Terminal User Interface): -Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, -Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase -provided HP-specific information in this manual. - - DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert -Hoehne made significant contributions to the DJGPP port. - - Cygnus Solutions has sponsored GDB maintenance and much of its -development since 1991. Cygnus engineers who have worked on GDB -fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin -Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim -Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, -Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek -Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In -addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, -JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug -Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff -Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, -Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin -Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela -Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David -Zuhn have made contributions both large and small. - - Jim Blandy added support for preprocessor macros, while working for -Red Hat. - - -File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top - -A Sample GDB Session -******************** - -You can use this manual at your leisure to read all about GDB. -However, a handful of commands are enough to get started using the -debugger. This chapter illustrates those commands. - - One of the preliminary versions of GNU `m4' (a generic macro -processor) exhibits the following bug: sometimes, when we change its -quote strings from the default, the commands used to capture one macro -definition within another stop working. In the following short `m4' -session, we define a macro `foo' which expands to `0000'; we then use -the `m4' built-in `defn' to define `bar' as the same thing. However, -when we change the open quote string to `<QUOTE>' and the close quote -string to `<UNQUOTE>', the same procedure fails to define a new synonym -`baz': - - $ cd gnu/m4 - $ ./m4 - define(foo,0000) - - foo - 0000 - define(bar,defn(`foo')) - - bar - 0000 - changequote(<QUOTE>,<UNQUOTE>) - - define(baz,defn(<QUOTE>foo<UNQUOTE>)) - baz - C-d - m4: End of input: 0: fatal error: EOF in string - -Let us use GDB to try to see what is going on. - - $ gdb m4 - GDB is free software and you are welcome to distribute copies - of it under certain conditions; type "show copying" to see - the conditions. - There is absolutely no warranty for GDB; type "show warranty" - for details. - - GDB 6.1.1, Copyright 1999 Free Software Foundation, Inc... - (gdb) - -GDB reads only enough symbol data to know where to find the rest when -needed; as a result, the first prompt comes up very quickly. We now -tell GDB to use a narrower display width than usual, so that examples -fit in this manual. - - (gdb) set width 70 - -We need to see how the `m4' built-in `changequote' works. Having -looked at the source, we know the relevant subroutine is -`m4_changequote', so we set a breakpoint there with the GDB `break' -command. - - (gdb) break m4_changequote - Breakpoint 1 at 0x62f4: file builtin.c, line 879. - -Using the `run' command, we start `m4' running under GDB control; as -long as control does not reach the `m4_changequote' subroutine, the -program runs as usual: - - (gdb) run - Starting program: /work/Editorial/gdb/gnu/m4/m4 - define(foo,0000) - - foo - 0000 - -To trigger the breakpoint, we call `changequote'. GDB suspends -execution of `m4', displaying information about the context where it -stops. - - changequote(<QUOTE>,<UNQUOTE>) - - Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) - at builtin.c:879 - 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) - -Now we use the command `n' (`next') to advance execution to the next -line of the current function. - - (gdb) n - 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ - : nil, - -`set_quotes' looks like a promising subroutine. We can go into it by -using the command `s' (`step') instead of `next'. `step' goes to the -next line to be executed in _any_ subroutine, so it steps into -`set_quotes'. - - (gdb) s - set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") - at input.c:530 - 530 if (lquote != def_lquote) - -The display that shows the subroutine where `m4' is now suspended (and -its arguments) is called a stack frame display. It shows a summary of -the stack. We can use the `backtrace' command (which can also be -spelled `bt'), to see where we are in the stack as a whole: the -`backtrace' command displays a stack frame for each active subroutine. - - (gdb) bt - #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") - at input.c:530 - #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) - at builtin.c:882 - #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 - #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) - at macro.c:71 - #4 0x79dc in expand_input () at macro.c:40 - #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 - -We step through a few more lines to see what happens. The first two -times, we can use `s'; the next two times we use `n' to avoid falling -into the `xstrdup' subroutine. - - (gdb) s - 0x3b5c 532 if (rquote != def_rquote) - (gdb) s - 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ - def_lquote : xstrdup(lq); - (gdb) n - 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ - : xstrdup(rq); - (gdb) n - 538 len_lquote = strlen(rquote); - -The last line displayed looks a little odd; we can examine the variables -`lquote' and `rquote' to see if they are in fact the new left and right -quotes we specified. We use the command `p' (`print') to see their -values. - - (gdb) p lquote - $1 = 0x35d40 "<QUOTE>" - (gdb) p rquote - $2 = 0x35d50 "<UNQUOTE>" - -`lquote' and `rquote' are indeed the new left and right quotes. To -look at some context, we can display ten lines of source surrounding -the current line with the `l' (`list') command. - - (gdb) l - 533 xfree(rquote); - 534 - 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ - : xstrdup (lq); - 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ - : xstrdup (rq); - 537 - 538 len_lquote = strlen(rquote); - 539 len_rquote = strlen(lquote); - 540 } - 541 - 542 void - -Let us step past the two lines that set `len_lquote' and `len_rquote', -and then examine the values of those variables. - - (gdb) n - 539 len_rquote = strlen(lquote); - (gdb) n - 540 } - (gdb) p len_lquote - $3 = 9 - (gdb) p len_rquote - $4 = 7 - -That certainly looks wrong, assuming `len_lquote' and `len_rquote' are -meant to be the lengths of `lquote' and `rquote' respectively. We can -set them to better values using the `p' command, since it can print the -value of any expression--and that expression can include subroutine -calls and assignments. - - (gdb) p len_lquote=strlen(lquote) - $5 = 7 - (gdb) p len_rquote=strlen(rquote) - $6 = 9 - -Is that enough to fix the problem of using the new quotes with the `m4' -built-in `defn'? We can allow `m4' to continue executing with the `c' -(`continue') command, and then try the example that caused trouble -initially: - - (gdb) c - Continuing. - - define(baz,defn(<QUOTE>foo<UNQUOTE>)) - - baz - 0000 - -Success! The new quotes now work just as well as the default ones. The -problem seems to have been just the two typos defining the wrong -lengths. We allow `m4' exit by giving it an EOF as input: - - C-d - Program exited normally. - -The message `Program exited normally.' is from GDB; it indicates `m4' -has finished executing. We can end our GDB session with the GDB `quit' -command. - - (gdb) quit - - -File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top - -Getting In and Out of GDB -************************* - -This chapter discusses how to start GDB, and how to get out of it. The -essentials are: - * type `gdb' to start GDB. - - * type `quit' or `C-d' to exit. - -* Menu: - -* Invoking GDB:: How to start GDB -* Quitting GDB:: How to quit GDB -* Shell Commands:: How to use shell commands inside GDB -* Logging output:: How to log GDB's output to a file - - -File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation - -Invoking GDB -============ - -Invoke GDB by running the program `gdb'. Once started, GDB reads -commands from the terminal until you tell it to exit. - - You can also run `gdb' with a variety of arguments and options, to -specify more of your debugging environment at the outset. - - The command-line options described here are designed to cover a -variety of situations; in some environments, some of these options may -effectively be unavailable. - - The most usual way to start GDB is with one argument, specifying an -executable program: - - gdb PROGRAM - -You can also start with both an executable program and a core file -specified: - - gdb PROGRAM CORE - - You can, instead, specify a process ID as a second argument, if you -want to debug a running process: - - gdb PROGRAM 1234 - -would attach GDB to process `1234' (unless you also have a file named -`1234'; GDB does check for a core file first). - - Taking advantage of the second command-line argument requires a -fairly complete operating system; when you use GDB as a remote debugger -attached to a bare board, there may not be any notion of "process", and -there is often no way to get a core dump. GDB will warn you if it is -unable to attach or to read core dumps. - - You can optionally have `gdb' pass any arguments after the -executable file to the inferior using `--args'. This option stops -option processing. - gdb --args gcc -O2 -c foo.c - This will cause `gdb' to debug `gcc', and to set `gcc''s -command-line arguments (*note Arguments::) to `-O2 -c foo.c'. - - You can run `gdb' without printing the front material, which -describes GDB's non-warranty, by specifying `-silent': - - gdb -silent - -You can further control how GDB starts up by using command-line -options. GDB itself can remind you of the options available. - -Type - - gdb -help - -to display all available options and briefly describe their use (`gdb --h' is a shorter equivalent). - - All options and command line arguments you give are processed in -sequential order. The order makes a difference when the `-x' option is -used. - -* Menu: - -* File Options:: Choosing files -* Mode Options:: Choosing modes - - -File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB - -Choosing files --------------- - -When GDB starts, it reads any arguments other than options as -specifying an executable file and core file (or process ID). This is -the same as if the arguments were specified by the `-se' and `-c' (or -`-p' options respectively. (GDB reads the first argument that does not -have an associated option flag as equivalent to the `-se' option -followed by that argument; and the second argument that does not have -an associated option flag, if any, as equivalent to the `-c'/`-p' -option followed by that argument.) If the second argument begins with -a decimal digit, GDB will first attempt to attach to it as a process, -and if that fails, attempt to open it as a corefile. If you have a -corefile whose name begins with a digit, you can prevent GDB from -treating it as a pid by prefixing it with `./', eg. `./12345'. - - If GDB has not been configured to included core file support, such -as for most embedded targets, then it will complain about a second -argument and ignore it. - - Many options have both long and short forms; both are shown in the -following list. GDB also recognizes the long forms if you truncate -them, so long as enough of the option is present to be unambiguous. -(If you prefer, you can flag option arguments with `--' rather than -`-', though we illustrate the more usual convention.) - -`-symbols FILE' -`-s FILE' - Read symbol table from file FILE. - -`-exec FILE' -`-e FILE' - Use file FILE as the executable file to execute when appropriate, - and for examining pure data in conjunction with a core dump. - -`-se FILE' - Read symbol table from file FILE and use it as the executable file. - -`-core FILE' -`-c FILE' - Use file FILE as a core dump to examine. - -`-c NUMBER' - -`-pid NUMBER' -`-p NUMBER' - Connect to process ID NUMBER, as with the `attach' command. If - there is no such process, GDB will attempt to open a core file - named NUMBER. - -`-command FILE' -`-x FILE' - Execute GDB commands from file FILE. *Note Command files: Command - Files. - -`-directory DIRECTORY' -`-d DIRECTORY' - Add DIRECTORY to the path to search for source files. - -`-m' -`-mapped' - _Warning: this option depends on operating system facilities that - are not supported on all systems._ - If memory-mapped files are available on your system through the - `mmap' system call, you can use this option to have GDB write the - symbols from your program into a reusable file in the current - directory. If the program you are debugging is called - `/tmp/fred', the mapped symbol file is `/tmp/fred.syms'. Future - GDB debugging sessions notice the presence of this file, and can - quickly map in symbol information from it, rather than reading the - symbol table from the executable program. - - The `.syms' file is specific to the host machine where GDB is run. - It holds an exact image of the internal GDB symbol table. It - cannot be shared across multiple host platforms. - -`-r' -`-readnow' - Read each symbol file's entire symbol table immediately, rather - than the default, which is to read it incrementally as it is - needed. This makes startup slower, but makes future operations - faster. - - - You typically combine the `-mapped' and `-readnow' options in order -to build a `.syms' file that contains complete symbol information. -(*Note Commands to specify files: Files, for information on `.syms' -files.) A simple GDB invocation to do nothing but build a `.syms' file -for future use is: - - gdb -batch -nx -mapped -readnow programname - - -File: gdb.info, Node: Mode Options, Prev: File Options, Up: Invoking GDB - -Choosing modes --------------- - -You can run GDB in various alternative modes--for example, in batch -mode or quiet mode. - -`-nx' -`-n' - Do not execute commands found in any initialization files. - Normally, GDB executes the commands in these files after all the - command options and arguments have been processed. *Note Command - files: Command Files. - -`-quiet' -`-silent' -`-q' - "Quiet". Do not print the introductory and copyright messages. - These messages are also suppressed in batch mode. - -`-batch' - Run in batch mode. Exit with status `0' after processing all the - command files specified with `-x' (and all commands from - initialization files, if not inhibited with `-n'). Exit with - nonzero status if an error occurs in executing the GDB commands in - the command files. - - Batch mode may be useful for running GDB as a filter, for example - to download and run a program on another computer; in order to - make this more useful, the message - - Program exited normally. - - (which is ordinarily issued whenever a program running under GDB - control terminates) is not issued when running in batch mode. - -`-nowindows' -`-nw' - "No windows". If GDB comes with a graphical user interface (GUI) - built in, then this option tells GDB to only use the command-line - interface. If no GUI is available, this option has no effect. - -`-windows' -`-w' - If GDB includes a GUI, then this option requires it to be used if - possible. - -`-cd DIRECTORY' - Run GDB using DIRECTORY as its working directory, instead of the - current directory. - -`-fullname' -`-f' - GNU Emacs sets this option when it runs GDB as a subprocess. It - tells GDB to output the full file name and line number in a - standard, recognizable fashion each time a stack frame is - displayed (which includes each time your program stops). This - recognizable format looks like two `\032' characters, followed by - the file name, line number and character position separated by - colons, and a newline. The Emacs-to-GDB interface program uses - the two `\032' characters as a signal to display the source code - for the frame. - -`-epoch' - The Epoch Emacs-GDB interface sets this option when it runs GDB as - a subprocess. It tells GDB to modify its print routines so as to - allow Epoch to display values of expressions in a separate window. - -`-annotate LEVEL' - This option sets the "annotation level" inside GDB. Its effect is - identical to using `set annotate LEVEL' (*note Annotations::). - The annotation LEVEL controls how much information GDB prints - together with its prompt, values of expressions, source lines, and - other types of output. Level 0 is the normal, level 1 is for use - when GDB is run as a subprocess of GNU Emacs, level 3 is the - maximum annotation suitable for programs that control GDB, and - level 2 has been deprecated. - - The annotation mechanism has largely been superseeded by GDB/MI - (*note GDB/MI::). - -`-async' - Use the asynchronous event loop for the command-line interface. - GDB processes all events, such as user keyboard input, via a - special event loop. This allows GDB to accept and process user - commands in parallel with the debugged process being run(1), so - you don't need to wait for control to return to GDB before you - type the next command. (_Note:_ as of version 5.1, the target - side of the asynchronous operation is not yet in place, so - `-async' does not work fully yet.) - - When the standard input is connected to a terminal device, GDB - uses the asynchronous event loop by default, unless disabled by the - `-noasync' option. - -`-noasync' - Disable the asynchronous event loop for the command-line interface. - -`--args' - Change interpretation of command line so that arguments following - the executable file are passed as command line arguments to the - inferior. This option stops option processing. - -`-baud BPS' -`-b BPS' - Set the line speed (baud rate or bits per second) of any serial - interface used by GDB for remote debugging. - -`-tty DEVICE' -`-t DEVICE' - Run using DEVICE for your program's standard input and output. - -`-tui' - Activate the "Text User Interface" when starting. The Text User - Interface manages several text windows on the terminal, showing - source, assembly, registers and GDB command outputs (*note GDB - Text User Interface: TUI.). Alternatively, the Text User - Interface can be enabled by invoking the program `gdbtui'. Do not - use this option if you run GDB from Emacs (*note Using GDB under - GNU Emacs: Emacs.). - -`-interpreter INTERP' - Use the interpreter INTERP for interface with the controlling - program or device. This option is meant to be set by programs - which communicate with GDB using it as a back end. *Note Command - Interpreters: Interpreters. - - `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the - "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included - since GDBN version 6.0. The previous GDB/MI interface, included - in GDB version 5.3 and selected with `--interpreter=mi1', is - deprecated. Earlier GDB/MI interfaces are no longer supported. - -`-write' - Open the executable and core files for both reading and writing. - This is equivalent to the `set write on' command inside GDB (*note - Patching::). - -`-statistics' - This option causes GDB to print statistics about time and memory - usage after it completes each command and returns to the prompt. - -`-version' - This option causes GDB to print its version number and no-warranty - blurb, and exit. - - - ---------- Footnotes ---------- - - (1) GDB built with DJGPP tools for MS-DOS/MS-Windows supports this -mode of operation, but the event loop is suspended when the debuggee -runs. - - -File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation - -Quitting GDB -============ - -`quit [EXPRESSION]' -`q' - To exit GDB, use the `quit' command (abbreviated `q'), or type an - end-of-file character (usually `C-d'). If you do not supply - EXPRESSION, GDB will terminate normally; otherwise it will - terminate using the result of EXPRESSION as the error code. - - An interrupt (often `C-c') does not exit from GDB, but rather -terminates the action of any GDB command that is in progress and -returns to GDB command level. It is safe to type the interrupt -character at any time because GDB does not allow it to take effect -until a time when it is safe. - - If you have been using GDB to control an attached process or device, -you can release it with the `detach' command (*note Debugging an -already-running process: Attach.). - - -File: gdb.info, Node: Shell Commands, Next: Logging output, Prev: Quitting GDB, Up: Invocation - -Shell commands -============== - -If you need to execute occasional shell commands during your debugging -session, there is no need to leave or suspend GDB; you can just use the -`shell' command. - -`shell COMMAND STRING' - Invoke a standard shell to execute COMMAND STRING. If it exists, - the environment variable `SHELL' determines which shell to run. - Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, - `COMMAND.COM' on MS-DOS, etc.). - - The utility `make' is often needed in development environments. You -do not have to use the `shell' command for this purpose in GDB: - -`make MAKE-ARGS' - Execute the `make' program with the specified arguments. This is - equivalent to `shell make MAKE-ARGS'. - - -File: gdb.info, Node: Logging output, Prev: Shell Commands, Up: Invocation - -Logging output -============== - -You may want to save the output of GDB commands to a file. There are -several commands to control GDB's logging. - -`set logging on' - Enable logging. - -`set logging off' - Disable logging. - -`set logging file FILE' - Change the name of the current logfile. The default logfile is - `gdb.txt'. - -`set logging overwrite [on|off]' - By default, GDB will append to the logfile. Set `overwrite' if - you want `set logging on' to overwrite the logfile instead. - -`set logging redirect [on|off]' - By default, GDB output will go to both the terminal and the - logfile. Set `redirect' if you want output to go only to the log - file. - -`show logging' - Show the current values of the logging settings. - - -File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top - -GDB Commands -************ - -You can abbreviate a GDB command to the first few letters of the command -name, if that abbreviation is unambiguous; and you can repeat certain -GDB commands by typing just <RET>. You can also use the <TAB> key to -get GDB to fill out the rest of a word in a command (or to show you the -alternatives available, if there is more than one possibility). - -* Menu: - -* Command Syntax:: How to give commands to GDB -* Completion:: Command completion -* Help:: How to ask GDB for help - - -File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands - -Command syntax -============== - -A GDB command is a single line of input. There is no limit on how long -it can be. It starts with a command name, which is followed by -arguments whose meaning depends on the command name. For example, the -command `step' accepts an argument which is the number of times to -step, as in `step 5'. You can also use the `step' command with no -arguments. Some commands do not allow any arguments. - - GDB command names may always be truncated if that abbreviation is -unambiguous. Other possible command abbreviations are listed in the -documentation for individual commands. In some cases, even ambiguous -abbreviations are allowed; for example, `s' is specially defined as -equivalent to `step' even though there are other commands whose names -start with `s'. You can test abbreviations by using them as arguments -to the `help' command. - - A blank line as input to GDB (typing just <RET>) means to repeat the -previous command. Certain commands (for example, `run') will not -repeat this way; these are commands whose unintentional repetition -might cause trouble and which you are unlikely to want to repeat. - - The `list' and `x' commands, when you repeat them with <RET>, -construct new arguments rather than repeating exactly as typed. This -permits easy scanning of source or memory. - - GDB can also use <RET> in another way: to partition lengthy output, -in a way similar to the common utility `more' (*note Screen size: -Screen Size.). Since it is easy to press one <RET> too many in this -situation, GDB disables command repetition after any command that -generates this sort of display. - - Any text from a `#' to the end of the line is a comment; it does -nothing. This is useful mainly in command files (*note Command files: -Command Files.). - - The `C-o' binding is useful for repeating a complex sequence of -commands. This command accepts the current line, like `RET', and then -fetches the next line relative to the current line from the history for -editing. - - -File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands - -Command completion -================== - -GDB can fill in the rest of a word in a command for you, if there is -only one possibility; it can also show you what the valid possibilities -are for the next word in a command, at any time. This works for GDB -commands, GDB subcommands, and the names of symbols in your program. - - Press the <TAB> key whenever you want GDB to fill out the rest of a -word. If there is only one possibility, GDB fills in the word, and -waits for you to finish the command (or press <RET> to enter it). For -example, if you type - - (gdb) info bre <TAB> - -GDB fills in the rest of the word `breakpoints', since that is the only -`info' subcommand beginning with `bre': - - (gdb) info breakpoints - -You can either press <RET> at this point, to run the `info breakpoints' -command, or backspace and enter something else, if `breakpoints' does -not look like the command you expected. (If you were sure you wanted -`info breakpoints' in the first place, you might as well just type -<RET> immediately after `info bre', to exploit command abbreviations -rather than command completion). - - If there is more than one possibility for the next word when you -press <TAB>, GDB sounds a bell. You can either supply more characters -and try again, or just press <TAB> a second time; GDB displays all the -possible completions for that word. For example, you might want to set -a breakpoint on a subroutine whose name begins with `make_', but when -you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again -displays all the function names in your program that begin with those -characters, for example: - - (gdb) b make_ <TAB> -GDB sounds bell; press <TAB> again, to see: - make_a_section_from_file make_environ - make_abs_section make_function_type - make_blockvector make_pointer_type - make_cleanup make_reference_type - make_command make_symbol_completion_list - (gdb) b make_ - -After displaying the available possibilities, GDB copies your partial -input (`b make_' in the example) so you can finish the command. - - If you just want to see the list of alternatives in the first place, -you can press `M-?' rather than pressing <TAB> twice. `M-?' means -`<META> ?'. You can type this either by holding down a key designated -as the <META> shift on your keyboard (if there is one) while typing -`?', or as <ESC> followed by `?'. - - Sometimes the string you need, while logically a "word", may contain -parentheses or other characters that GDB normally excludes from its -notion of a word. To permit word completion to work in this situation, -you may enclose words in `'' (single quote marks) in GDB commands. - - The most likely situation where you might need this is in typing the -name of a C++ function. This is because C++ allows function -overloading (multiple definitions of the same function, distinguished -by argument type). For example, when you want to set a breakpoint you -may need to distinguish whether you mean the version of `name' that -takes an `int' parameter, `name(int)', or the version that takes a -`float' parameter, `name(float)'. To use the word-completion -facilities in this situation, type a single quote `'' at the beginning -of the function name. This alerts GDB that it may need to consider -more information than usual when you press <TAB> or `M-?' to request -word completion: - - (gdb) b 'bubble( M-? - bubble(double,double) bubble(int,int) - (gdb) b 'bubble( - - In some cases, GDB can tell that completing a name requires using -quotes. When this happens, GDB inserts the quote for you (while -completing as much as it can) if you do not type the quote in the first -place: - - (gdb) b bub <TAB> -GDB alters your input line to the following, and rings a bell: - (gdb) b 'bubble( - -In general, GDB can tell that a quote is needed (and inserts it) if you -have not yet started typing the argument list when you ask for -completion on an overloaded symbol. - - For more information about overloaded functions, see *Note C++ -expressions: C plus plus expressions. You can use the command `set -overload-resolution off' to disable overload resolution; see *Note GDB -features for C++: Debugging C plus plus. - - -File: gdb.info, Node: Help, Prev: Completion, Up: Commands - -Getting help -============ - -You can always ask GDB itself for information on its commands, using -the command `help'. - -`help' -`h' - You can use `help' (abbreviated `h') with no arguments to display - a short list of named classes of commands: - - (gdb) help - List of classes of commands: - - aliases -- Aliases of other commands - breakpoints -- Making program stop at certain points - data -- Examining data - files -- Specifying and examining files - internals -- Maintenance commands - obscure -- Obscure features - running -- Running the program - stack -- Examining the stack - status -- Status inquiries - support -- Support facilities - tracepoints -- Tracing of program execution without - - stopping the program - user-defined -- User-defined commands - - Type "help" followed by a class name for a list of - commands in that class. - Type "help" followed by command name for full - documentation. - Command name abbreviations are allowed if unambiguous. - (gdb) - -`help CLASS' - Using one of the general help classes as an argument, you can get a - list of the individual commands in that class. For example, here - is the help display for the class `status': - - (gdb) help status - Status inquiries. - - List of commands: - - info -- Generic command for showing things - about the program being debugged - show -- Generic command for showing things - about the debugger - - Type "help" followed by command name for full - documentation. - Command name abbreviations are allowed if unambiguous. - (gdb) - -`help COMMAND' - With a command name as `help' argument, GDB displays a short - paragraph on how to use that command. - -`apropos ARGS' - The `apropos ARGS' command searches through all of the GDB - commands, and their documentation, for the regular expression - specified in ARGS. It prints out all matches found. For example: - - apropos reload - - results in: - - set symbol-reloading -- Set dynamic symbol table reloading - multiple times in one run - show symbol-reloading -- Show dynamic symbol table reloading - multiple times in one run - -`complete ARGS' - The `complete ARGS' command lists all the possible completions for - the beginning of a command. Use ARGS to specify the beginning of - the command you want completed. For example: - - complete i - - results in: - - if - ignore - info - inspect - - This is intended for use by GNU Emacs. - - In addition to `help', you can use the GDB commands `info' and -`show' to inquire about the state of your program, or the state of GDB -itself. Each command supports many topics of inquiry; this manual -introduces each of them in the appropriate context. The listings under -`info' and under `show' in the Index point to all the sub-commands. -*Note Index::. - -`info' - This command (abbreviated `i') is for describing the state of your - program. For example, you can list the arguments given to your - program with `info args', list the registers currently in use with - `info registers', or list the breakpoints you have set with `info - breakpoints'. You can get a complete list of the `info' - sub-commands with `help info'. - -`set' - You can assign the result of an expression to an environment - variable with `set'. For example, you can set the GDB prompt to a - $-sign with `set prompt $'. - -`show' - In contrast to `info', `show' is for describing the state of GDB - itself. You can change most of the things you can `show', by - using the related command `set'; for example, you can control what - number system is used for displays with `set radix', or simply - inquire which is currently in use with `show radix'. - - To display all the settable parameters and their current values, - you can use `show' with no arguments; you may also use `info set'. - Both commands produce the same display. - - Here are three miscellaneous `show' subcommands, all of which are -exceptional in lacking corresponding `set' commands: - -`show version' - Show what version of GDB is running. You should include this - information in GDB bug-reports. If multiple versions of GDB are - in use at your site, you may need to determine which version of - GDB you are running; as GDB evolves, new commands are introduced, - and old ones may wither away. Also, many system vendors ship - variant versions of GDB, and there are variant versions of GDB in - GNU/Linux distributions as well. The version number is the same - as the one announced when you start GDB. - -`show copying' - Display information about permission for copying GDB. - -`show warranty' - Display the GNU "NO WARRANTY" statement, or a warranty, if your - version of GDB comes with one. - - - -File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top - -Running Programs Under GDB -************************** - -When you run a program under GDB, you must first generate debugging -information when you compile it. - - You may start GDB with its arguments, if any, in an environment of -your choice. If you are doing native debugging, you may redirect your -program's input and output, debug an already running process, or kill a -child process. - -* Menu: - -* Compilation:: Compiling for debugging -* Starting:: Starting your program -* Arguments:: Your program's arguments -* Environment:: Your program's environment - -* Working Directory:: Your program's working directory -* Input/Output:: Your program's input and output -* Attach:: Debugging an already-running process -* Kill Process:: Killing the child process - -* Threads:: Debugging programs with multiple threads -* Processes:: Debugging programs with multiple processes - - -File: gdb.info, Node: Compilation, Next: Starting, Up: Running - -Compiling for debugging -======================= - -In order to debug a program effectively, you need to generate debugging -information when you compile it. This debugging information is stored -in the object file; it describes the data type of each variable or -function and the correspondence between source line numbers and -addresses in the executable code. - - To request debugging information, specify the `-g' option when you -run the compiler. - - Most compilers do not include information about preprocessor macros -in the debugging information if you specify the `-g' flag alone, -because this information is rather large. Version 3.1 of GCC, the GNU -C compiler, provides macro information if you specify the options -`-gdwarf-2' and `-g3'; the former option requests debugging information -in the Dwarf 2 format, and the latter requests "extra information". In -the future, we hope to find more compact ways to represent macro -information, so that it can be included with `-g' alone. - - Many C compilers are unable to handle the `-g' and `-O' options -together. Using those compilers, you cannot generate optimized -executables containing debugging information. - - GCC, the GNU C compiler, supports `-g' with or without `-O', making -it possible to debug optimized code. We recommend that you _always_ -use `-g' whenever you compile a program. You may think your program is -correct, but there is no sense in pushing your luck. - - When you debug a program compiled with `-g -O', remember that the -optimizer is rearranging your code; the debugger shows you what is -really there. Do not be too surprised when the execution path does not -exactly match your source file! An extreme example: if you define a -variable, but never use it, GDB never sees that variable--because the -compiler optimizes it out of existence. - - Some things do not work as well with `-g -O' as with just `-g', -particularly on machines with instruction scheduling. If in doubt, -recompile with `-g' alone, and if this fixes the problem, please report -it to us as a bug (including a test case!). - - Older versions of the GNU C compiler permitted a variant option -`-gg' for debugging information. GDB no longer supports this format; -if your GNU C compiler has this option, do not use it. - - -File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running - -Starting your program -===================== - -`run' -`r' - Use the `run' command to start your program under GDB. You must - first specify the program name (except on VxWorks) with an - argument to GDB (*note Getting In and Out of GDB: Invocation.), or - by using the `file' or `exec-file' command (*note Commands to - specify files: Files.). - - - If you are running your program in an execution environment that -supports processes, `run' creates an inferior process and makes that -process run your program. (In environments without processes, `run' -jumps to the start of your program.) - - The execution of a program is affected by certain information it -receives from its superior. GDB provides ways to specify this -information, which you must do _before_ starting your program. (You -can change it after starting your program, but such changes only affect -your program the next time you start it.) This information may be -divided into four categories: - -The _arguments._ - Specify the arguments to give your program as the arguments of the - `run' command. If a shell is available on your target, the shell - is used to pass the arguments, so that you may use normal - conventions (such as wildcard expansion or variable substitution) - in describing the arguments. In Unix systems, you can control - which shell is used with the `SHELL' environment variable. *Note - Your program's arguments: Arguments. - -The _environment._ - Your program normally inherits its environment from GDB, but you - can use the GDB commands `set environment' and `unset environment' - to change parts of the environment that affect your program. - *Note Your program's environment: Environment. - -The _working directory._ - Your program inherits its working directory from GDB. You can set - the GDB working directory with the `cd' command in GDB. *Note - Your program's working directory: Working Directory. - -The _standard input and output._ - Your program normally uses the same device for standard input and - standard output as GDB is using. You can redirect input and output - in the `run' command line, or you can use the `tty' command to set - a different device for your program. *Note Your program's input - and output: Input/Output. - - _Warning:_ While input and output redirection work, you cannot use - pipes to pass the output of the program you are debugging to - another program; if you attempt this, GDB is likely to wind up - debugging the wrong program. - - When you issue the `run' command, your program begins to execute -immediately. *Note Stopping and continuing: Stopping, for discussion -of how to arrange for your program to stop. Once your program has -stopped, you may call functions in your program, using the `print' or -`call' commands. *Note Examining Data: Data. - - If the modification time of your symbol file has changed since the -last time GDB read its symbols, GDB discards its symbol table, and -reads it again. When it does this, GDB tries to retain your current -breakpoints. - - -File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running - -Your program's arguments -======================== - -The arguments to your program can be specified by the arguments of the -`run' command. They are passed to a shell, which expands wildcard -characters and performs redirection of I/O, and thence to your program. -Your `SHELL' environment variable (if it exists) specifies what shell -GDB uses. If you do not define `SHELL', GDB uses the default shell -(`/bin/sh' on Unix). - - On non-Unix systems, the program is usually invoked directly by GDB, -which emulates I/O redirection via the appropriate system calls, and -the wildcard characters are expanded by the startup code of the -program, not by the shell. - - `run' with no arguments uses the same arguments used by the previous -`run', or those set by the `set args' command. - -`set args' - Specify the arguments to be used the next time your program is - run. If `set args' has no arguments, `run' executes your program - with no arguments. Once you have run your program with arguments, - using `set args' before the next `run' is the only way to run it - again without arguments. - -`show args' - Show the arguments to give your program when it is started. - - -File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running - -Your program's environment -========================== - -The "environment" consists of a set of environment variables and their -values. Environment variables conventionally record such things as -your user name, your home directory, your terminal type, and your search -path for programs to run. Usually you set up environment variables with -the shell and they are inherited by all the other programs you run. -When debugging, it can be useful to try running your program with a -modified environment without having to start GDB over again. - -`path DIRECTORY' - Add DIRECTORY to the front of the `PATH' environment variable (the - search path for executables) that will be passed to your program. - The value of `PATH' used by GDB does not change. You may specify - several directory names, separated by whitespace or by a - system-dependent separator character (`:' on Unix, `;' on MS-DOS - and MS-Windows). If DIRECTORY is already in the path, it is moved - to the front, so it is searched sooner. - - You can use the string `$cwd' to refer to whatever is the current - working directory at the time GDB searches the path. If you use - `.' instead, it refers to the directory where you executed the - `path' command. GDB replaces `.' in the DIRECTORY argument (with - the current path) before adding DIRECTORY to the search path. - -`show paths' - Display the list of search paths for executables (the `PATH' - environment variable). - -`show environment [VARNAME]' - Print the value of environment variable VARNAME to be given to - your program when it starts. If you do not supply VARNAME, print - the names and values of all environment variables to be given to - your program. You can abbreviate `environment' as `env'. - -`set environment VARNAME [=VALUE]' - Set environment variable VARNAME to VALUE. The value changes for - your program only, not for GDB itself. VALUE may be any string; - the values of environment variables are just strings, and any - interpretation is supplied by your program itself. The VALUE - parameter is optional; if it is eliminated, the variable is set to - a null value. - - For example, this command: - - set env USER = foo - - tells the debugged program, when subsequently run, that its user - is named `foo'. (The spaces around `=' are used for clarity here; - they are not actually required.) - -`unset environment VARNAME' - Remove variable VARNAME from the environment to be passed to your - program. This is different from `set env VARNAME ='; `unset - environment' removes the variable from the environment, rather - than assigning it an empty value. - - _Warning:_ On Unix systems, GDB runs your program using the shell -indicated by your `SHELL' environment variable if it exists (or -`/bin/sh' if not). If your `SHELL' variable names a shell that runs an -initialization file--such as `.cshrc' for C-shell, or `.bashrc' for -BASH--any variables you set in that file affect your program. You may -wish to move setting of environment variables to files that are only -run when you sign on, such as `.login' or `.profile'. - - -File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running - -Your program's working directory -================================ - -Each time you start your program with `run', it inherits its working -directory from the current working directory of GDB. The GDB working -directory is initially whatever it inherited from its parent process -(typically the shell), but you can specify a new working directory in -GDB with the `cd' command. - - The GDB working directory also serves as a default for the commands -that specify files for GDB to operate on. *Note Commands to specify -files: Files. - -`cd DIRECTORY' - Set the GDB working directory to DIRECTORY. - -`pwd' - Print the GDB working directory. - - -File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running - -Your program's input and output -=============================== - -By default, the program you run under GDB does input and output to the -same terminal that GDB uses. GDB switches the terminal to its own -terminal modes to interact with you, but it records the terminal modes -your program was using and switches back to them when you continue -running your program. - -`info terminal' - Displays information recorded by GDB about the terminal modes your - program is using. - - You can redirect your program's input and/or output using shell -redirection with the `run' command. For example, - - run > outfile - -starts your program, diverting its output to the file `outfile'. - - Another way to specify where your program should do input and output -is with the `tty' command. This command accepts a file name as -argument, and causes this file to be the default for future `run' -commands. It also resets the controlling terminal for the child -process, for future `run' commands. For example, - - tty /dev/ttyb - -directs that processes started with subsequent `run' commands default -to do input and output on the terminal `/dev/ttyb' and have that as -their controlling terminal. - - An explicit redirection in `run' overrides the `tty' command's -effect on the input/output device, but not its effect on the controlling -terminal. - - When you use the `tty' command or redirect input in the `run' -command, only the input _for your program_ is affected. The input for -GDB still comes from your terminal. - - -File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running - -Debugging an already-running process -==================================== - -`attach PROCESS-ID' - This command attaches to a running process--one that was started - outside GDB. (`info files' shows your active targets.) The - command takes as argument a process ID. The usual way to find out - the process-id of a Unix process is with the `ps' utility, or with - the `jobs -l' shell command. - - `attach' does not repeat if you press <RET> a second time after - executing the command. - - To use `attach', your program must be running in an environment -which supports processes; for example, `attach' does not work for -programs on bare-board targets that lack an operating system. You must -also have permission to send the process a signal. - - When you use `attach', the debugger finds the program running in the -process first by looking in the current working directory, then (if the -program is not found) by using the source file search path (*note -Specifying source directories: Source Path.). You can also use the -`file' command to load the program. *Note Commands to Specify Files: -Files. - - The first thing GDB does after arranging to debug the specified -process is to stop it. You can examine and modify an attached process -with all the GDB commands that are ordinarily available when you start -processes with `run'. You can insert breakpoints; you can step and -continue; you can modify storage. If you would rather the process -continue running, you may use the `continue' command after attaching -GDB to the process. - -`detach' - When you have finished debugging the attached process, you can use - the `detach' command to release it from GDB control. Detaching - the process continues its execution. After the `detach' command, - that process and GDB become completely independent once more, and - you are ready to `attach' another process or start one with `run'. - `detach' does not repeat if you press <RET> again after executing - the command. - - If you exit GDB or use the `run' command while you have an attached -process, you kill that process. By default, GDB asks for confirmation -if you try to do either of these things; you can control whether or not -you need to confirm by using the `set confirm' command (*note Optional -warnings and messages: Messages/Warnings.). - - -File: gdb.info, Node: Kill Process, Next: Threads, Prev: Attach, Up: Running - -Killing the child process -========================= - -`kill' - Kill the child process in which your program is running under GDB. - - This command is useful if you wish to debug a core dump instead of a -running process. GDB ignores any core dump file while your program is -running. - - On some operating systems, a program cannot be executed outside GDB -while you have breakpoints set on it inside GDB. You can use the -`kill' command in this situation to permit running your program outside -the debugger. - - The `kill' command is also useful if you wish to recompile and -relink your program, since on many systems it is impossible to modify an -executable file while it is running in a process. In this case, when -you next type `run', GDB notices that the file has changed, and reads -the symbol table again (while trying to preserve your current -breakpoint settings). - - -File: gdb.info, Node: Threads, Next: Processes, Prev: Kill Process, Up: Running - -Debugging programs with multiple threads -======================================== - -In some operating systems, such as HP-UX and Solaris, a single program -may have more than one "thread" of execution. The precise semantics of -threads differ from one operating system to another, but in general the -threads of a single program are akin to multiple processes--except that -they share one address space (that is, they can all examine and modify -the same variables). On the other hand, each thread has its own -registers and execution stack, and perhaps private memory. - - GDB provides these facilities for debugging multi-thread programs: - - * automatic notification of new threads - - * `thread THREADNO', a command to switch among threads - - * `info threads', a command to inquire about existing threads - - * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command - to a list of threads - - * thread-specific breakpoints - - _Warning:_ These facilities are not yet available on every GDB - configuration where the operating system supports threads. If - your GDB does not support threads, these commands have no effect. - For example, a system without thread support shows no output from - `info threads', and always rejects the `thread' command, like this: - - (gdb) info threads - (gdb) thread 1 - Thread ID 1 not known. Use the "info threads" command to - see the IDs of currently known threads. - - The GDB thread debugging facility allows you to observe all threads -while your program runs--but whenever GDB takes control, one thread in -particular is always the focus of debugging. This thread is called the -"current thread". Debugging commands show program information from the -perspective of the current thread. - - Whenever GDB detects a new thread in your program, it displays the -target system's identification for the thread with a message in the -form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies -depending on the particular system. For example, on LynxOS, you might -see - - [New process 35 thread 27] - -when GDB notices a new thread. In contrast, on an SGI system, the -SYSTAG is simply something like `process 368', with no further -qualifier. - - For debugging purposes, GDB associates its own thread number--always -a single integer--with each thread in your program. - -`info threads' - Display a summary of all threads currently in your program. GDB - displays for each thread (in this order): - - 1. the thread number assigned by GDB - - 2. the target system's thread identifier (SYSTAG) - - 3. the current stack frame summary for that thread - - An asterisk `*' to the left of the GDB thread number indicates the - current thread. - - For example, - - (gdb) info threads - 3 process 35 thread 27 0x34e5 in sigpause () - 2 process 35 thread 23 0x34e5 in sigpause () - * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) - at threadtest.c:68 - - On HP-UX systems: - - For debugging purposes, GDB associates its own thread number--a -small integer assigned in thread-creation order--with each thread in -your program. - - Whenever GDB detects a new thread in your program, it displays both -GDB's thread number and the target system's identification for the -thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread -identifier whose form varies depending on the particular system. For -example, on HP-UX, you see - - [New thread 2 (system thread 26594)] - -when GDB notices a new thread. - -`info threads' - Display a summary of all threads currently in your program. GDB - displays for each thread (in this order): - - 1. the thread number assigned by GDB - - 2. the target system's thread identifier (SYSTAG) - - 3. the current stack frame summary for that thread - - An asterisk `*' to the left of the GDB thread number indicates the - current thread. - - For example, - - (gdb) info threads - * 3 system thread 26607 worker (wptr=0x7b09c318 "@") \ - - at quicksort.c:137 - 2 system thread 26606 0x7b0030d8 in __ksleep () \ - - from /usr/lib/libc.2 - 1 system thread 27905 0x7b003498 in _brk () \ - - from /usr/lib/libc.2 - -`thread THREADNO' - Make thread number THREADNO the current thread. The command - argument THREADNO is the internal GDB thread number, as shown in - the first field of the `info threads' display. GDB responds by - displaying the system identifier of the thread you selected, and - its current stack frame summary: - - (gdb) thread 2 - [Switching to process 35 thread 23] - 0x34e5 in sigpause () - - As with the `[New ...]' message, the form of the text after - `Switching to' depends on your system's conventions for identifying - threads. - -`thread apply [THREADNO] [ALL] ARGS' - The `thread apply' command allows you to apply a command to one or - more threads. Specify the numbers of the threads that you want - affected with the command argument THREADNO. THREADNO is the - internal GDB thread number, as shown in the first field of the - `info threads' display. To apply a command to all threads, use - `thread apply all' ARGS. - - Whenever GDB stops your program, due to a breakpoint or a signal, it -automatically selects the thread where that breakpoint or signal -happened. GDB alerts you to the context switch with a message of the -form `[Switching to SYSTAG]' to identify the thread. - - *Note Stopping and starting multi-thread programs: Thread Stops, for -more information about how GDB behaves when you stop and start programs -with multiple threads. - - *Note Setting watchpoints: Set Watchpoints, for information about -watchpoints in programs with multiple threads. - - -File: gdb.info, Node: Processes, Prev: Threads, Up: Running - -Debugging programs with multiple processes -========================================== - -On most systems, GDB has no special support for debugging programs -which create additional processes using the `fork' function. When a -program forks, GDB will continue to debug the parent process and the -child process will run unimpeded. If you have set a breakpoint in any -code which the child then executes, the child will get a `SIGTRAP' -signal which (unless it catches the signal) will cause it to terminate. - - However, if you want to debug the child process there is a workaround -which isn't too painful. Put a call to `sleep' in the code which the -child process executes after the fork. It may be useful to sleep only -if a certain environment variable is set, or a certain file exists, so -that the delay need not occur when you don't want to run GDB on the -child. While the child is sleeping, use the `ps' program to get its -process ID. Then tell GDB (a new invocation of GDB if you are also -debugging the parent process) to attach to the child process (*note -Attach::). From that point on you can debug the child process just -like any other process which you attached to. - - On some systems, GDB provides support for debugging programs that -create additional processes using the `fork' or `vfork' functions. -Currently, the only platforms with this feature are HP-UX (11.x and -later only?) and GNU/Linux (kernel version 2.5.60 and later). - - By default, when a program forks, GDB will continue to debug the -parent process and the child process will run unimpeded. - - If you want to follow the child process instead of the parent -process, use the command `set follow-fork-mode'. - -`set follow-fork-mode MODE' - Set the debugger response to a program call of `fork' or `vfork'. - A call to `fork' or `vfork' creates a new process. The MODE can - be: - - `parent' - The original process is debugged after a fork. The child - process runs unimpeded. This is the default. - - `child' - The new process is debugged after a fork. The parent process - runs unimpeded. - - -`show follow-fork-mode' - Display the current debugger response to a `fork' or `vfork' call. - - If you ask to debug a child process and a `vfork' is followed by an -`exec', GDB executes the new target up to the first breakpoint in the -new target. If you have a breakpoint set on `main' in your original -program, the breakpoint will also be set on the child process's `main'. - - When a child process is spawned by `vfork', you cannot debug the -child or parent until an `exec' call completes. - - If you issue a `run' command to GDB after an `exec' call executes, -the new target restarts. To restart the parent process, use the `file' -command with the parent executable name as its argument. - - You can use the `catch' command to make GDB stop whenever a `fork', -`vfork', or `exec' call is made. *Note Setting catchpoints: Set -Catchpoints. - - -File: gdb.info, Node: Stopping, Next: Stack, Prev: Running, Up: Top - -Stopping and Continuing -*********************** - -The principal purposes of using a debugger are so that you can stop your -program before it terminates; or so that, if your program runs into -trouble, you can investigate and find out why. - - Inside GDB, your program may stop for any of several reasons, such -as a signal, a breakpoint, or reaching a new line after a GDB command -such as `step'. You may then examine and change variables, set new -breakpoints or remove old ones, and then continue execution. Usually, -the messages shown by GDB provide ample explanation of the status of -your program--but you can also explicitly request this information at -any time. - -`info program' - Display information about the status of your program: whether it is - running or not, what process it is, and why it stopped. - -* Menu: - -* Breakpoints:: Breakpoints, watchpoints, and catchpoints -* Continuing and Stepping:: Resuming execution -* Signals:: Signals -* Thread Stops:: Stopping and starting multi-thread programs - - -File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping - -Breakpoints, watchpoints, and catchpoints -========================================= - -A "breakpoint" makes your program stop whenever a certain point in the -program is reached. For each breakpoint, you can add conditions to -control in finer detail whether your program stops. You can set -breakpoints with the `break' command and its variants (*note Setting -breakpoints: Set Breaks.), to specify the place where your program -should stop by line number, function name or exact address in the -program. - - In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can -set breakpoints in shared libraries before the executable is run. -There is a minor limitation on HP-UX systems: you must wait until the -executable is run in order to set breakpoints in shared library -routines that are not called directly by the program (for example, -routines that are arguments in a `pthread_create' call). - - A "watchpoint" is a special breakpoint that stops your program when -the value of an expression changes. You must use a different command -to set watchpoints (*note Setting watchpoints: Set Watchpoints.), but -aside from that, you can manage a watchpoint like any other breakpoint: -you enable, disable, and delete both breakpoints and watchpoints using -the same commands. - - You can arrange to have values from your program displayed -automatically whenever GDB stops at a breakpoint. *Note Automatic -display: Auto Display. - - A "catchpoint" is another special breakpoint that stops your program -when a certain kind of event occurs, such as the throwing of a C++ -exception or the loading of a library. As with watchpoints, you use a -different command to set a catchpoint (*note Setting catchpoints: Set -Catchpoints.), but aside from that, you can manage a catchpoint like any -other breakpoint. (To stop when your program receives a signal, use the -`handle' command; see *Note Signals: Signals.) - - GDB assigns a number to each breakpoint, watchpoint, or catchpoint -when you create it; these numbers are successive integers starting with -one. In many of the commands for controlling various features of -breakpoints you use the breakpoint number to say which breakpoint you -want to change. Each breakpoint may be "enabled" or "disabled"; if -disabled, it has no effect on your program until you enable it again. - - Some GDB commands accept a range of breakpoints on which to operate. -A breakpoint range is either a single breakpoint number, like `5', or -two such numbers, in increasing order, separated by a hyphen, like -`5-7'. When a breakpoint range is given to a command, all breakpoint -in that range are operated on. - -* Menu: - -* Set Breaks:: Setting breakpoints -* Set Watchpoints:: Setting watchpoints -* Set Catchpoints:: Setting catchpoints -* Delete Breaks:: Deleting breakpoints -* Disabling:: Disabling breakpoints -* Conditions:: Break conditions -* Break Commands:: Breakpoint command lists -* Breakpoint Menus:: Breakpoint menus -* Error in Breakpoints:: ``Cannot insert breakpoints'' -* Breakpoint related warnings:: ``Breakpoint address adjusted...'' - - -File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints - -Setting breakpoints -------------------- - -Breakpoints are set with the `break' command (abbreviated `b'). The -debugger convenience variable `$bpnum' records the number of the -breakpoint you've set most recently; see *Note Convenience variables: -Convenience Vars, for a discussion of what you can do with convenience -variables. - - You have several ways to say where the breakpoint should go. - -`break FUNCTION' - Set a breakpoint at entry to function FUNCTION. When using source - languages that permit overloading of symbols, such as C++, - FUNCTION may refer to more than one possible place to break. - *Note Breakpoint menus: Breakpoint Menus, for a discussion of that - situation. - -`break +OFFSET' -`break -OFFSET' - Set a breakpoint some number of lines forward or back from the - position at which execution stopped in the currently selected - "stack frame". (*Note Frames: Frames, for a description of stack - frames.) - -`break LINENUM' - Set a breakpoint at line LINENUM in the current source file. The - current source file is the last file whose source text was printed. - The breakpoint will stop your program just before it executes any - of the code on that line. - -`break FILENAME:LINENUM' - Set a breakpoint at line LINENUM in source file FILENAME. - -`break FILENAME:FUNCTION' - Set a breakpoint at entry to function FUNCTION found in file - FILENAME. Specifying a file name as well as a function name is - superfluous except when multiple files contain similarly named - functions. - -`break *ADDRESS' - Set a breakpoint at address ADDRESS. You can use this to set - breakpoints in parts of your program which do not have debugging - information or source files. - -`break' - When called without any arguments, `break' sets a breakpoint at - the next instruction to be executed in the selected stack frame - (*note Examining the Stack: Stack.). In any selected frame but the - innermost, this makes your program stop as soon as control returns - to that frame. This is similar to the effect of a `finish' - command in the frame inside the selected frame--except that - `finish' does not leave an active breakpoint. If you use `break' - without an argument in the innermost frame, GDB stops the next - time it reaches the current location; this may be useful inside - loops. - - GDB normally ignores breakpoints when it resumes execution, until - at least one instruction has been executed. If it did not do - this, you would be unable to proceed past a breakpoint without - first disabling the breakpoint. This rule applies whether or not - the breakpoint already existed when your program stopped. - -`break ... if COND' - Set a breakpoint with condition COND; evaluate the expression COND - each time the breakpoint is reached, and stop only if the value is - nonzero--that is, if COND evaluates as true. `...' stands for one - of the possible arguments described above (or no argument) - specifying where to break. *Note Break conditions: Conditions, - for more information on breakpoint conditions. - -`tbreak ARGS' - Set a breakpoint enabled only for one stop. ARGS are the same as - for the `break' command, and the breakpoint is set in the same - way, but the breakpoint is automatically deleted after the first - time your program stops there. *Note Disabling breakpoints: - Disabling. - -`hbreak ARGS' - Set a hardware-assisted breakpoint. ARGS are the same as for the - `break' command and the breakpoint is set in the same way, but the - breakpoint requires hardware support and some target hardware may - not have this support. The main purpose of this is EPROM/ROM code - debugging, so you can set a breakpoint at an instruction without - changing the instruction. This can be used with the new - trap-generation provided by SPARClite DSU and some x86-based - targets. These targets will generate traps when a program - accesses some data or instruction address that is assigned to the - debug registers. However the hardware breakpoint registers can - take a limited number of breakpoints. For example, on the DSU, - only two data breakpoints can be set at a time, and GDB will - reject this command if more than two are used. Delete or disable - unused hardware breakpoints before setting new ones (*note - Disabling: Disabling.). *Note Break conditions: Conditions. - *Note set remote hardware-breakpoint-limit::. - -`thbreak ARGS' - Set a hardware-assisted breakpoint enabled only for one stop. ARGS - are the same as for the `hbreak' command and the breakpoint is set - in the same way. However, like the `tbreak' command, the - breakpoint is automatically deleted after the first time your - program stops there. Also, like the `hbreak' command, the - breakpoint requires hardware support and some target hardware may - not have this support. *Note Disabling breakpoints: Disabling. - See also *Note Break conditions: Conditions. - -`rbreak REGEX' - Set breakpoints on all functions matching the regular expression - REGEX. This command sets an unconditional breakpoint on all - matches, printing a list of all breakpoints it set. Once these - breakpoints are set, they are treated just like the breakpoints - set with the `break' command. You can delete them, disable them, - or make them conditional the same way as any other breakpoint. - - The syntax of the regular expression is the standard one used with - tools like `grep'. Note that this is different from the syntax - used by shells, so for instance `foo*' matches all functions that - include an `fo' followed by zero or more `o's. There is an - implicit `.*' leading and trailing the regular expression you - supply, so to match only functions that begin with `foo', use - `^foo'. - - When debugging C++ programs, `rbreak' is useful for setting - breakpoints on overloaded functions that are not members of any - special classes. - -`info breakpoints [N]' -`info break [N]' -`info watchpoints [N]' - Print a table of all breakpoints, watchpoints, and catchpoints set - and not deleted, with the following columns for each breakpoint: - - _Breakpoint Numbers_ - - _Type_ - Breakpoint, watchpoint, or catchpoint. - - _Disposition_ - Whether the breakpoint is marked to be disabled or deleted - when hit. - - _Enabled or Disabled_ - Enabled breakpoints are marked with `y'. `n' marks - breakpoints that are not enabled. - - _Address_ - Where the breakpoint is in your program, as a memory address. - If the breakpoint is pending (see below for details) on a - future load of a shared library, the address will be listed - as `<PENDING>'. - - _What_ - Where the breakpoint is in the source for your program, as a - file and line number. For a pending breakpoint, the original - string passed to the breakpoint command will be listed as it - cannot be resolved until the appropriate shared library is - loaded in the future. - - If a breakpoint is conditional, `info break' shows the condition on - the line following the affected breakpoint; breakpoint commands, - if any, are listed after that. A pending breakpoint is allowed to - have a condition specified for it. The condition is not parsed - for validity until a shared library is loaded that allows the - pending breakpoint to resolve to a valid location. - - `info break' with a breakpoint number N as argument lists only - that breakpoint. The convenience variable `$_' and the default - examining-address for the `x' command are set to the address of - the last breakpoint listed (*note Examining memory: Memory.). - - `info break' displays a count of the number of times the breakpoint - has been hit. This is especially useful in conjunction with the - `ignore' command. You can ignore a large number of breakpoint - hits, look at the breakpoint info to see how many times the - breakpoint was hit, and then run again, ignoring one less than - that number. This will get you quickly to the last hit of that - breakpoint. - - GDB allows you to set any number of breakpoints at the same place in -your program. There is nothing silly or meaningless about this. When -the breakpoints are conditional, this is even useful (*note Break -conditions: Conditions.). - - If a specified breakpoint location cannot be found, it may be due to -the fact that the location is in a shared library that is yet to be -loaded. In such a case, you may want GDB to create a special -breakpoint (known as a "pending breakpoint") that attempts to resolve -itself in the future when an appropriate shared library gets loaded. - - Pending breakpoints are useful to set at the start of your GDB -session for locations that you know will be dynamically loaded later by -the program being debugged. When shared libraries are loaded, a check -is made to see if the load resolves any pending breakpoint locations. -If a pending breakpoint location gets resolved, a regular breakpoint is -created and the original pending breakpoint is removed. - - GDB provides some additional commands for controlling pending -breakpoint support: - -`set breakpoint pending auto' - This is the default behavior. When GDB cannot find the breakpoint - location, it queries you whether a pending breakpoint should be - created. - -`set breakpoint pending on' - This indicates that an unrecognized breakpoint location should - automatically result in a pending breakpoint being created. - -`set breakpoint pending off' - This indicates that pending breakpoints are not to be created. Any - unrecognized breakpoint location results in an error. This - setting does not affect any pending breakpoints previously created. - -`show breakpoint pending' - Show the current behavior setting for creating pending breakpoints. - - Normal breakpoint operations apply to pending breakpoints as well. -You may specify a condition for a pending breakpoint and/or commands to -run when the breakpoint is reached. You can also enable or disable the -pending breakpoint. When you specify a condition for a pending -breakpoint, the parsing of the condition will be deferred until the -point where the pending breakpoint location is resolved. Disabling a -pending breakpoint tells GDB to not attempt to resolve the breakpoint -on any subsequent shared library load. When a pending breakpoint is -re-enabled, GDB checks to see if the location is already resolved. -This is done because any number of shared library loads could have -occurred since the time the breakpoint was disabled and one or more of -these loads could resolve the location. - - GDB itself sometimes sets breakpoints in your program for special -purposes, such as proper handling of `longjmp' (in C programs). These -internal breakpoints are assigned negative numbers, starting with `-1'; -`info breakpoints' does not display them. You can see these -breakpoints with the GDB maintenance command `maint info breakpoints' -(*note maint info breakpoints::). - - -File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints - -Setting watchpoints -------------------- - -You can use a watchpoint to stop execution whenever the value of an -expression changes, without having to predict a particular place where -this may happen. - - Depending on your system, watchpoints may be implemented in software -or hardware. GDB does software watchpointing by single-stepping your -program and testing the variable's value each time, which is hundreds of -times slower than normal execution. (But this may still be worth it, to -catch errors where you have no clue what part of your program is the -culprit.) - - On some systems, such as HP-UX, GNU/Linux and some other x86-based -targets, GDB includes support for hardware watchpoints, which do not -slow down the running of your program. - -`watch EXPR' - Set a watchpoint for an expression. GDB will break when EXPR is - written into by the program and its value changes. - -`rwatch EXPR' - Set a watchpoint that will break when watch EXPR is read by the - program. - -`awatch EXPR' - Set a watchpoint that will break when EXPR is either read or - written into by the program. - -`info watchpoints' - This command prints a list of watchpoints, breakpoints, and - catchpoints; it is the same as `info break'. - - GDB sets a "hardware watchpoint" if possible. Hardware watchpoints -execute very quickly, and the debugger reports a change in value at the -exact instruction where the change occurs. If GDB cannot set a -hardware watchpoint, it sets a software watchpoint, which executes more -slowly and reports the change in value at the next statement, not the -instruction, after the change occurs. - - When you issue the `watch' command, GDB reports - - Hardware watchpoint NUM: EXPR - -if it was able to set a hardware watchpoint. - - Currently, the `awatch' and `rwatch' commands can only set hardware -watchpoints, because accesses to data that don't change the value of -the watched expression cannot be detected without examining every -instruction as it is being executed, and GDB does not do that -currently. If GDB finds that it is unable to set a hardware breakpoint -with the `awatch' or `rwatch' command, it will print a message like -this: - - Expression cannot be implemented with read/access watchpoint. - - Sometimes, GDB cannot set a hardware watchpoint because the data -type of the watched expression is wider than what a hardware watchpoint -on the target machine can handle. For example, some systems can only -watch regions that are up to 4 bytes wide; on such systems you cannot -set hardware watchpoints for an expression that yields a -double-precision floating-point number (which is typically 8 bytes -wide). As a work-around, it might be possible to break the large region -into a series of smaller ones and watch them with separate watchpoints. - - If you set too many hardware watchpoints, GDB might be unable to -insert all of them when you resume the execution of your program. -Since the precise number of active watchpoints is unknown until such -time as the program is about to be resumed, GDB might not be able to -warn you about this when you set the watchpoints, and the warning will -be printed only when the program is resumed: - - Hardware watchpoint NUM: Could not insert watchpoint - -If this happens, delete or disable some of the watchpoints. - - The SPARClite DSU will generate traps when a program accesses some -data or instruction address that is assigned to the debug registers. -For the data addresses, DSU facilitates the `watch' command. However -the hardware breakpoint registers can only take two data watchpoints, -and both watchpoints must be the same kind. For example, you can set -two watchpoints with `watch' commands, two with `rwatch' commands, *or* -two with `awatch' commands, but you cannot set one watchpoint with one -command and the other with a different command. GDB will reject the -command if you try to mix watchpoints. Delete or disable unused -watchpoint commands before setting new ones. - - If you call a function interactively using `print' or `call', any -watchpoints you have set will be inactive until GDB reaches another -kind of breakpoint or the call completes. - - GDB automatically deletes watchpoints that watch local (automatic) -variables, or expressions that involve such variables, when they go out -of scope, that is, when the execution leaves the block in which these -variables were defined. In particular, when the program being debugged -terminates, _all_ local variables go out of scope, and so only -watchpoints that watch global variables remain set. If you rerun the -program, you will need to set all such watchpoints again. One way of -doing that would be to set a code breakpoint at the entry to the `main' -function and when it breaks, set all the watchpoints. - - _Warning:_ In multi-thread programs, watchpoints have only limited - usefulness. With the current watchpoint implementation, GDB can - only watch the value of an expression _in a single thread_. If - you are confident that the expression can only change due to the - current thread's activity (and if you are also confident that no - other thread can become current), then you can use watchpoints as - usual. However, GDB may not notice when a non-current thread's - activity changes the expression. - - _HP-UX Warning:_ In multi-thread programs, software watchpoints - have only limited usefulness. If GDB creates a software - watchpoint, it can only watch the value of an expression _in a - single thread_. If you are confident that the expression can only - change due to the current thread's activity (and if you are also - confident that no other thread can become current), then you can - use software watchpoints as usual. However, GDB may not notice - when a non-current thread's activity changes the expression. - (Hardware watchpoints, in contrast, watch an expression in all - threads.) - - *Note set remote hardware-watchpoint-limit::. - - -File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints - -Setting catchpoints -------------------- - -You can use "catchpoints" to cause the debugger to stop for certain -kinds of program events, such as C++ exceptions or the loading of a -shared library. Use the `catch' command to set a catchpoint. - -`catch EVENT' - Stop when EVENT occurs. EVENT can be any of the following: - `throw' - The throwing of a C++ exception. - - `catch' - The catching of a C++ exception. - - `exec' - A call to `exec'. This is currently only available for HP-UX. - - `fork' - A call to `fork'. This is currently only available for HP-UX. - - `vfork' - A call to `vfork'. This is currently only available for - HP-UX. - - `load' - `load LIBNAME' - The dynamic loading of any shared library, or the loading of - the library LIBNAME. This is currently only available for - HP-UX. - - `unload' - `unload LIBNAME' - The unloading of any dynamically loaded shared library, or - the unloading of the library LIBNAME. This is currently only - available for HP-UX. - -`tcatch EVENT' - Set a catchpoint that is enabled only for one stop. The - catchpoint is automatically deleted after the first time the event - is caught. - - - Use the `info break' command to list the current catchpoints. - - There are currently some limitations to C++ exception handling -(`catch throw' and `catch catch') in GDB: - - * If you call a function interactively, GDB normally returns control - to you when the function has finished executing. If the call - raises an exception, however, the call may bypass the mechanism - that returns control to you and cause your program either to abort - or to simply continue running until it hits a breakpoint, catches - a signal that GDB is listening for, or exits. This is the case - even if you set a catchpoint for the exception; catchpoints on - exceptions are disabled within interactive calls. - - * You cannot raise an exception interactively. - - * You cannot install an exception handler interactively. - - Sometimes `catch' is not the best way to debug exception handling: -if you need to know exactly where an exception is raised, it is better -to stop _before_ the exception handler is called, since that way you -can see the stack before any unwinding takes place. If you set a -breakpoint in an exception handler instead, it may not be easy to find -out where the exception was raised. - - To stop just before an exception handler is called, you need some -knowledge of the implementation. In the case of GNU C++, exceptions are -raised by calling a library function named `__raise_exception' which -has the following ANSI C interface: - - /* ADDR is where the exception identifier is stored. - ID is the exception identifier. */ - void __raise_exception (void **addr, void *id); - -To make the debugger catch all exceptions before any stack unwinding -takes place, set a breakpoint on `__raise_exception' (*note -Breakpoints; watchpoints; and exceptions: Breakpoints.). - - With a conditional breakpoint (*note Break conditions: Conditions.) -that depends on the value of ID, you can stop your program when a -specific exception is raised. You can use multiple conditional -breakpoints to stop your program when any of a number of exceptions are -raised. - - -File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints - -Deleting breakpoints --------------------- - -It is often necessary to eliminate a breakpoint, watchpoint, or -catchpoint once it has done its job and you no longer want your program -to stop there. This is called "deleting" the breakpoint. A breakpoint -that has been deleted no longer exists; it is forgotten. - - With the `clear' command you can delete breakpoints according to -where they are in your program. With the `delete' command you can -delete individual breakpoints, watchpoints, or catchpoints by specifying -their breakpoint numbers. - - It is not necessary to delete a breakpoint to proceed past it. GDB -automatically ignores breakpoints on the first instruction to be -executed when you continue execution without changing the execution -address. - -`clear' - Delete any breakpoints at the next instruction to be executed in - the selected stack frame (*note Selecting a frame: Selection.). - When the innermost frame is selected, this is a good way to delete - a breakpoint where your program just stopped. - -`clear FUNCTION' -`clear FILENAME:FUNCTION' - Delete any breakpoints set at entry to the function FUNCTION. - -`clear LINENUM' -`clear FILENAME:LINENUM' - Delete any breakpoints set at or within the code of the specified - line. - -`delete [breakpoints] [RANGE...]' - Delete the breakpoints, watchpoints, or catchpoints of the - breakpoint ranges specified as arguments. If no argument is - specified, delete all breakpoints (GDB asks confirmation, unless - you have `set confirm off'). You can abbreviate this command as - `d'. - - -File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints - -Disabling breakpoints ---------------------- - -Rather than deleting a breakpoint, watchpoint, or catchpoint, you might -prefer to "disable" it. This makes the breakpoint inoperative as if it -had been deleted, but remembers the information on the breakpoint so -that you can "enable" it again later. - - You disable and enable breakpoints, watchpoints, and catchpoints with -the `enable' and `disable' commands, optionally specifying one or more -breakpoint numbers as arguments. Use `info break' or `info watch' to -print a list of breakpoints, watchpoints, and catchpoints if you do not -know which numbers to use. - - A breakpoint, watchpoint, or catchpoint can have any of four -different states of enablement: - - * Enabled. The breakpoint stops your program. A breakpoint set - with the `break' command starts out in this state. - - * Disabled. The breakpoint has no effect on your program. - - * Enabled once. The breakpoint stops your program, but then becomes - disabled. - - * Enabled for deletion. The breakpoint stops your program, but - immediately after it does so it is deleted permanently. A - breakpoint set with the `tbreak' command starts out in this state. - - You can use the following commands to enable or disable breakpoints, -watchpoints, and catchpoints: - -`disable [breakpoints] [RANGE...]' - Disable the specified breakpoints--or all breakpoints, if none are - listed. A disabled breakpoint has no effect but is not forgotten. - All options such as ignore-counts, conditions and commands are - remembered in case the breakpoint is enabled again later. You may - abbreviate `disable' as `dis'. - -`enable [breakpoints] [RANGE...]' - Enable the specified breakpoints (or all defined breakpoints). - They become effective once again in stopping your program. - -`enable [breakpoints] once RANGE...' - Enable the specified breakpoints temporarily. GDB disables any of - these breakpoints immediately after stopping your program. - -`enable [breakpoints] delete RANGE...' - Enable the specified breakpoints to work once, then die. GDB - deletes any of these breakpoints as soon as your program stops - there. - - Except for a breakpoint set with `tbreak' (*note Setting -breakpoints: Set Breaks.), breakpoints that you set are initially -enabled; subsequently, they become disabled or enabled only when you -use one of the commands above. (The command `until' can set and delete -a breakpoint of its own, but it does not change the state of your other -breakpoints; see *Note Continuing and stepping: Continuing and -Stepping.) - - -File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints - -Break conditions ----------------- - -The simplest sort of breakpoint breaks every time your program reaches a -specified place. You can also specify a "condition" for a breakpoint. -A condition is just a Boolean expression in your programming language -(*note Expressions: Expressions.). A breakpoint with a condition -evaluates the expression each time your program reaches it, and your -program stops only if the condition is _true_. - - This is the converse of using assertions for program validation; in -that situation, you want to stop when the assertion is violated--that -is, when the condition is false. In C, if you want to test an -assertion expressed by the condition ASSERT, you should set the -condition `! ASSERT' on the appropriate breakpoint. - - Conditions are also accepted for watchpoints; you may not need them, -since a watchpoint is inspecting the value of an expression anyhow--but -it might be simpler, say, to just set a watchpoint on a variable name, -and specify a condition that tests whether the new value is an -interesting one. - - Break conditions can have side effects, and may even call functions -in your program. This can be useful, for example, to activate functions -that log program progress, or to use your own print functions to format -special data structures. The effects are completely predictable unless -there is another enabled breakpoint at the same address. (In that -case, GDB might see the other breakpoint first and stop your program -without checking the condition of this one.) Note that breakpoint -commands are usually more convenient and flexible than break conditions -for the purpose of performing side effects when a breakpoint is reached -(*note Breakpoint command lists: Break Commands.). - - Break conditions can be specified when a breakpoint is set, by using -`if' in the arguments to the `break' command. *Note Setting -breakpoints: Set Breaks. They can also be changed at any time with the -`condition' command. - - You can also use the `if' keyword with the `watch' command. The -`catch' command does not recognize the `if' keyword; `condition' is the -only way to impose a further condition on a catchpoint. - -`condition BNUM EXPRESSION' - Specify EXPRESSION as the break condition for breakpoint, - watchpoint, or catchpoint number BNUM. After you set a condition, - breakpoint BNUM stops your program only if the value of EXPRESSION - is true (nonzero, in C). When you use `condition', GDB checks - EXPRESSION immediately for syntactic correctness, and to determine - whether symbols in it have referents in the context of your - breakpoint. If EXPRESSION uses symbols not referenced in the - context of the breakpoint, GDB prints an error message: - - No symbol "foo" in current context. - - GDB does not actually evaluate EXPRESSION at the time the - `condition' command (or a command that sets a breakpoint with a - condition, like `break if ...') is given, however. *Note - Expressions: Expressions. - -`condition BNUM' - Remove the condition from breakpoint number BNUM. It becomes an - ordinary unconditional breakpoint. - - A special case of a breakpoint condition is to stop only when the -breakpoint has been reached a certain number of times. This is so -useful that there is a special way to do it, using the "ignore count" -of the breakpoint. Every breakpoint has an ignore count, which is an -integer. Most of the time, the ignore count is zero, and therefore has -no effect. But if your program reaches a breakpoint whose ignore count -is positive, then instead of stopping, it just decrements the ignore -count by one and continues. As a result, if the ignore count value is -N, the breakpoint does not stop the next N times your program reaches -it. - -`ignore BNUM COUNT' - Set the ignore count of breakpoint number BNUM to COUNT. The next - COUNT times the breakpoint is reached, your program's execution - does not stop; other than to decrement the ignore count, GDB takes - no action. - - To make the breakpoint stop the next time it is reached, specify a - count of zero. - - When you use `continue' to resume execution of your program from a - breakpoint, you can specify an ignore count directly as an - argument to `continue', rather than using `ignore'. *Note - Continuing and stepping: Continuing and Stepping. - - If a breakpoint has a positive ignore count and a condition, the - condition is not checked. Once the ignore count reaches zero, GDB - resumes checking the condition. - - You could achieve the effect of the ignore count with a condition - such as `$foo-- <= 0' using a debugger convenience variable that - is decremented each time. *Note Convenience variables: - Convenience Vars. - - Ignore counts apply to breakpoints, watchpoints, and catchpoints. - - -File: gdb.info, Node: Break Commands, Next: Breakpoint Menus, Prev: Conditions, Up: Breakpoints - -Breakpoint command lists ------------------------- - -You can give any breakpoint (or watchpoint or catchpoint) a series of -commands to execute when your program stops due to that breakpoint. For -example, you might want to print the values of certain expressions, or -enable other breakpoints. - -`commands [BNUM]' -`... COMMAND-LIST ...' -`end' - Specify a list of commands for breakpoint number BNUM. The - commands themselves appear on the following lines. Type a line - containing just `end' to terminate the commands. - - To remove all commands from a breakpoint, type `commands' and - follow it immediately with `end'; that is, give no commands. - - With no BNUM argument, `commands' refers to the last breakpoint, - watchpoint, or catchpoint set (not to the breakpoint most recently - encountered). - - Pressing <RET> as a means of repeating the last GDB command is -disabled within a COMMAND-LIST. - - You can use breakpoint commands to start your program up again. -Simply use the `continue' command, or `step', or any other command that -resumes execution. - - Any other commands in the command list, after a command that resumes -execution, are ignored. This is because any time you resume execution -(even with a simple `next' or `step'), you may encounter another -breakpoint--which could have its own command list, leading to -ambiguities about which list to execute. - - If the first command you specify in a command list is `silent', the -usual message about stopping at a breakpoint is not printed. This may -be desirable for breakpoints that are to print a specific message and -then continue. If none of the remaining commands print anything, you -see no sign that the breakpoint was reached. `silent' is meaningful -only at the beginning of a breakpoint command list. - - The commands `echo', `output', and `printf' allow you to print -precisely controlled output, and are often useful in silent -breakpoints. *Note Commands for controlled output: Output. - - For example, here is how you could use breakpoint commands to print -the value of `x' at entry to `foo' whenever `x' is positive. - - break foo if x>0 - commands - silent - printf "x is %d\n",x - cont - end - - One application for breakpoint commands is to compensate for one bug -so you can test for another. Put a breakpoint just after the erroneous -line of code, give it a condition to detect the case in which something -erroneous has been done, and give it commands to assign correct values -to any variables that need them. End with the `continue' command so -that your program does not stop, and start with the `silent' command so -that no output is produced. Here is an example: - - break 403 - commands - silent - set x = y + 4 - cont - end - - -File: gdb.info, Node: Breakpoint Menus, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints - -Breakpoint menus ----------------- - -Some programming languages (notably C++ and Objective-C) permit a -single function name to be defined several times, for application in -different contexts. This is called "overloading". When a function -name is overloaded, `break FUNCTION' is not enough to tell GDB where -you want a breakpoint. If you realize this is a problem, you can use -something like `break FUNCTION(TYPES)' to specify which particular -version of the function you want. Otherwise, GDB offers you a menu of -numbered choices for different possible breakpoints, and waits for your -selection with the prompt `>'. The first two options are always `[0] -cancel' and `[1] all'. Typing `1' sets a breakpoint at each definition -of FUNCTION, and typing `0' aborts the `break' command without setting -any new breakpoints. - - For example, the following session excerpt shows an attempt to set a -breakpoint at the overloaded symbol `String::after'. We choose three -particular definitions of that function name: - - (gdb) b String::after - [0] cancel - [1] all - [2] file:String.cc; line number:867 - [3] file:String.cc; line number:860 - [4] file:String.cc; line number:875 - [5] file:String.cc; line number:853 - [6] file:String.cc; line number:846 - [7] file:String.cc; line number:735 - > 2 4 6 - Breakpoint 1 at 0xb26c: file String.cc, line 867. - Breakpoint 2 at 0xb344: file String.cc, line 875. - Breakpoint 3 at 0xafcc: file String.cc, line 846. - Multiple breakpoints were set. - Use the "delete" command to delete unwanted - breakpoints. - (gdb) - - -File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint related warnings, Prev: Breakpoint Menus, Up: Breakpoints - -"Cannot insert breakpoints" ---------------------------- - -Under some operating systems, breakpoints cannot be used in a program if -any other process is running that program. In this situation, -attempting to run or continue a program with a breakpoint causes GDB to -print an error message: - - Cannot insert breakpoints. - The same program may be running in another process. - - When this happens, you have three ways to proceed: - - 1. Remove or disable the breakpoints, then continue. - - 2. Suspend GDB, and copy the file containing your program to a new - name. Resume GDB and use the `exec-file' command to specify that - GDB should run your program under that name. Then start your - program again. - - 3. Relink your program so that the text segment is nonsharable, using - the linker option `-N'. The operating system limitation may not - apply to nonsharable executables. - - A similar message can be printed if you request too many active -hardware-assisted breakpoints and watchpoints: - - Stopped; cannot insert breakpoints. - You may have requested too many hardware breakpoints and watchpoints. - -This message is printed when you attempt to resume the program, since -only then GDB knows exactly how many hardware breakpoints and -watchpoints it needs to insert. - - When this message is printed, you need to disable or remove some of -the hardware-assisted breakpoints and watchpoints, and then continue. - - -File: gdb.info, Node: Breakpoint related warnings, Prev: Error in Breakpoints, Up: Breakpoints - -"Breakpoint address adjusted..." --------------------------------- - -Some processor architectures place constraints on the addresses at -which breakpoints may be placed. For architectures thus constrained, -GDB will attempt to adjust the breakpoint's address to comply with the -constraints dictated by the architecture. - - One example of such an architecture is the Fujitsu FR-V. The FR-V is -a VLIW architecture in which a number of RISC-like instructions may be -bundled together for parallel execution. The FR-V architecture -constrains the location of a breakpoint instruction within such a -bundle to the instruction with the lowest address. GDB honors this -constraint by adjusting a breakpoint's address to the first in the -bundle. - - It is not uncommon for optimized code to have bundles which contain -instructions from different source statements, thus it may happen that -a breakpoint's address will be adjusted from one source statement to -another. Since this adjustment may significantly alter GDB's -breakpoint related behavior from what the user expects, a warning is -printed when the breakpoint is first set and also when the breakpoint -is hit. - - A warning like the one below is printed when setting a breakpoint -that's been subject to address adjustment: - - warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. - - Such warnings are printed both for user settable and GDB's internal -breakpoints. If you see one of these warnings, you should verify that -a breakpoint set at the adjusted address will have the desired affect. -If not, the breakpoint in question may be removed and other breakpoints -may be set which will have the desired behavior. E.g., it may be -sufficient to place the breakpoint at a later instruction. A -conditional breakpoint may also be useful in some cases to prevent the -breakpoint from triggering too often. - - GDB will also issue a warning when stopping at one of these adjusted -breakpoints: - - warning: Breakpoint 1 address previously adjusted from 0x00010414 - to 0x00010410. - - When this warning is encountered, it may be too late to take remedial -action except in cases where the breakpoint is hit earlier or more -frequently than expected. - - -File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping - -Continuing and stepping -======================= - -"Continuing" means resuming program execution until your program -completes normally. In contrast, "stepping" means executing just one -more "step" of your program, where "step" may mean either one line of -source code, or one machine instruction (depending on what particular -command you use). Either when continuing or when stepping, your -program may stop even sooner, due to a breakpoint or a signal. (If it -stops due to a signal, you may want to use `handle', or use `signal 0' -to resume execution. *Note Signals: Signals.) - -`continue [IGNORE-COUNT]' -`c [IGNORE-COUNT]' -`fg [IGNORE-COUNT]' - Resume program execution, at the address where your program last - stopped; any breakpoints set at that address are bypassed. The - optional argument IGNORE-COUNT allows you to specify a further - number of times to ignore a breakpoint at this location; its - effect is like that of `ignore' (*note Break conditions: - Conditions.). - - The argument IGNORE-COUNT is meaningful only when your program - stopped due to a breakpoint. At other times, the argument to - `continue' is ignored. - - The synonyms `c' and `fg' (for "foreground", as the debugged - program is deemed to be the foreground program) are provided - purely for convenience, and have exactly the same behavior as - `continue'. - - To resume execution at a different place, you can use `return' -(*note Returning from a function: Returning.) to go back to the calling -function; or `jump' (*note Continuing at a different address: Jumping.) -to go to an arbitrary location in your program. - - A typical technique for using stepping is to set a breakpoint (*note -Breakpoints; watchpoints; and catchpoints: Breakpoints.) at the -beginning of the function or the section of your program where a problem -is believed to lie, run your program until it stops at that breakpoint, -and then step through the suspect area, examining the variables that are -interesting, until you see the problem happen. - -`step' - Continue running your program until control reaches a different - source line, then stop it and return control to GDB. This command - is abbreviated `s'. - - _Warning:_ If you use the `step' command while control is - within a function that was compiled without debugging - information, execution proceeds until control reaches a - function that does have debugging information. Likewise, it - will not step into a function which is compiled without - debugging information. To step through functions without - debugging information, use the `stepi' command, described - below. - - The `step' command only stops at the first instruction of a source - line. This prevents the multiple stops that could otherwise occur - in `switch' statements, `for' loops, etc. `step' continues to - stop if a function that has debugging information is called within - the line. In other words, `step' _steps inside_ any functions - called within the line. - - Also, the `step' command only enters a function if there is line - number information for the function. Otherwise it acts like the - `next' command. This avoids problems when using `cc -gl' on MIPS - machines. Previously, `step' entered subroutines if there was any - debugging information about the routine. - -`step COUNT' - Continue running as in `step', but do so COUNT times. If a - breakpoint is reached, or a signal not related to stepping occurs - before COUNT steps, stepping stops right away. - -`next [COUNT]' - Continue to the next source line in the current (innermost) stack - frame. This is similar to `step', but function calls that appear - within the line of code are executed without stopping. Execution - stops when control reaches a different line of code at the - original stack level that was executing when you gave the `next' - command. This command is abbreviated `n'. - - An argument COUNT is a repeat count, as for `step'. - - The `next' command only stops at the first instruction of a source - line. This prevents multiple stops that could otherwise occur in - `switch' statements, `for' loops, etc. - -`set step-mode' -`set step-mode on' - The `set step-mode on' command causes the `step' command to stop - at the first instruction of a function which contains no debug line - information rather than stepping over it. - - This is useful in cases where you may be interested in inspecting - the machine instructions of a function which has no symbolic info - and do not want GDB to automatically skip over this function. - -`set step-mode off' - Causes the `step' command to step over any functions which - contains no debug information. This is the default. - -`finish' - Continue running until just after function in the selected stack - frame returns. Print the returned value (if any). - - Contrast this with the `return' command (*note Returning from a - function: Returning.). - -`until' -`u' - Continue running until a source line past the current line, in the - current stack frame, is reached. This command is used to avoid - single stepping through a loop more than once. It is like the - `next' command, except that when `until' encounters a jump, it - automatically continues execution until the program counter is - greater than the address of the jump. - - This means that when you reach the end of a loop after single - stepping though it, `until' makes your program continue execution - until it exits the loop. In contrast, a `next' command at the end - of a loop simply steps back to the beginning of the loop, which - forces you to step through the next iteration. - - `until' always stops your program if it attempts to exit the - current stack frame. - - `until' may produce somewhat counterintuitive results if the order - of machine code does not match the order of the source lines. For - example, in the following excerpt from a debugging session, the `f' - (`frame') command shows that execution is stopped at line `206'; - yet when we use `until', we get to line `195': - - (gdb) f - #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 - 206 expand_input(); - (gdb) until - 195 for ( ; argc > 0; NEXTARG) { - - This happened because, for execution efficiency, the compiler had - generated code for the loop closure test at the end, rather than - the start, of the loop--even though the test in a C `for'-loop is - written before the body of the loop. The `until' command appeared - to step back to the beginning of the loop when it advanced to this - expression; however, it has not really gone to an earlier - statement--not in terms of the actual machine code. - - `until' with no argument works by means of single instruction - stepping, and hence is slower than `until' with an argument. - -`until LOCATION' -`u LOCATION' - Continue running your program until either the specified location - is reached, or the current stack frame returns. LOCATION is any of - the forms of argument acceptable to `break' (*note Setting - breakpoints: Set Breaks.). This form of the command uses - breakpoints, and hence is quicker than `until' without an - argument. The specified location is actually reached only if it - is in the current frame. This implies that `until' can be used to - skip over recursive function invocations. For instance in the - code below, if the current location is line `96', issuing `until - 99' will execute the program up to line `99' in the same - invocation of factorial, i.e. after the inner invocations have - returned. - - 94 int factorial (int value) - 95 { - 96 if (value > 1) { - 97 value *= factorial (value - 1); - 98 } - 99 return (value); - 100 } - -`advance LOCATION' - Continue running the program up to the given location. An - argument is required, anything of the same form as arguments for - the `break' command. Execution will also stop upon exit from the - current stack frame. This command is similar to `until', but - `advance' will not skip over recursive function calls, and the - target location doesn't have to be in the same frame as the - current one. - -`stepi' -`stepi ARG' -`si' - Execute one machine instruction, then stop and return to the - debugger. - - It is often useful to do `display/i $pc' when stepping by machine - instructions. This makes GDB automatically display the next - instruction to be executed, each time your program stops. *Note - Automatic display: Auto Display. - - An argument is a repeat count, as in `step'. - -`nexti' -`nexti ARG' -`ni' - Execute one machine instruction, but if it is a function call, - proceed until the function returns. - - An argument is a repeat count, as in `next'. - - -File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping - -Signals -======= - -A signal is an asynchronous event that can happen in a program. The -operating system defines the possible kinds of signals, and gives each -kind a name and a number. For example, in Unix `SIGINT' is the signal -a program gets when you type an interrupt character (often `C-c'); -`SIGSEGV' is the signal a program gets from referencing a place in -memory far away from all the areas in use; `SIGALRM' occurs when the -alarm clock timer goes off (which happens only if your program has -requested an alarm). - - Some signals, including `SIGALRM', are a normal part of the -functioning of your program. Others, such as `SIGSEGV', indicate -errors; these signals are "fatal" (they kill your program immediately) -if the program has not specified in advance some other way to handle -the signal. `SIGINT' does not indicate an error in your program, but -it is normally fatal so it can carry out the purpose of the interrupt: -to kill the program. - - GDB has the ability to detect any occurrence of a signal in your -program. You can tell GDB in advance what to do for each kind of -signal. - - Normally, GDB is set up to let the non-erroneous signals like -`SIGALRM' be silently passed to your program (so as not to interfere -with their role in the program's functioning) but to stop your program -immediately whenever an error signal happens. You can change these -settings with the `handle' command. - -`info signals' -`info handle' - Print a table of all the kinds of signals and how GDB has been - told to handle each one. You can use this to see the signal - numbers of all the defined types of signals. - - `info handle' is an alias for `info signals'. - -`handle SIGNAL KEYWORDS...' - Change the way GDB handles signal SIGNAL. SIGNAL can be the - number of a signal or its name (with or without the `SIG' at the - beginning); a list of signal numbers of the form `LOW-HIGH'; or - the word `all', meaning all the known signals. The KEYWORDS say - what change to make. - - The keywords allowed by the `handle' command can be abbreviated. -Their full names are: - -`nostop' - GDB should not stop your program when this signal happens. It may - still print a message telling you that the signal has come in. - -`stop' - GDB should stop your program when this signal happens. This - implies the `print' keyword as well. - -`print' - GDB should print a message when this signal happens. - -`noprint' - GDB should not mention the occurrence of the signal at all. This - implies the `nostop' keyword as well. - -`pass' -`noignore' - GDB should allow your program to see this signal; your program can - handle the signal, or else it may terminate if the signal is fatal - and not handled. `pass' and `noignore' are synonyms. - -`nopass' -`ignore' - GDB should not allow your program to see this signal. `nopass' - and `ignore' are synonyms. - - When a signal stops your program, the signal is not visible to the -program until you continue. Your program sees the signal then, if -`pass' is in effect for the signal in question _at that time_. In -other words, after GDB reports a signal, you can use the `handle' -command with `pass' or `nopass' to control whether your program sees -that signal when you continue. - - The default is set to `nostop', `noprint', `pass' for non-erroneous -signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop', -`print', `pass' for the erroneous signals. - - You can also use the `signal' command to prevent your program from -seeing a signal, or cause it to see a signal it normally would not see, -or to give it any signal at any time. For example, if your program -stopped due to some sort of memory reference error, you might store -correct values into the erroneous variables and continue, hoping to see -more execution; but your program would probably terminate immediately as -a result of the fatal signal once it saw the signal. To prevent this, -you can continue with `signal 0'. *Note Giving your program a signal: -Signaling. - - -File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping - -Stopping and starting multi-thread programs -=========================================== - -When your program has multiple threads (*note Debugging programs with -multiple threads: Threads.), you can choose whether to set breakpoints -on all threads, or on a particular thread. - -`break LINESPEC thread THREADNO' -`break LINESPEC thread THREADNO if ...' - LINESPEC specifies source lines; there are several ways of writing - them, but the effect is always to specify some source line. - - Use the qualifier `thread THREADNO' with a breakpoint command to - specify that you only want GDB to stop the program when a - particular thread reaches this breakpoint. THREADNO is one of the - numeric thread identifiers assigned by GDB, shown in the first - column of the `info threads' display. - - If you do not specify `thread THREADNO' when you set a breakpoint, - the breakpoint applies to _all_ threads of your program. - - You can use the `thread' qualifier on conditional breakpoints as - well; in this case, place `thread THREADNO' before the breakpoint - condition, like this: - - (gdb) break frik.c:13 thread 28 if bartab > lim - - - Whenever your program stops under GDB for any reason, _all_ threads -of execution stop, not just the current thread. This allows you to -examine the overall state of the program, including switching between -threads, without worrying that things may change underfoot. - - There is an unfortunate side effect. If one thread stops for a -breakpoint, or for some other reason, and another thread is blocked in a -system call, then the system call may return prematurely. This is a -consequence of the interaction between multiple threads and the signals -that GDB uses to implement breakpoints and other events that stop -execution. - - To handle this problem, your program should check the return value of -each system call and react appropriately. This is good programming -style anyways. - - For example, do not write code like this: - - sleep (10); - - The call to `sleep' will return early if a different thread stops at -a breakpoint or for some other reason. - - Instead, write this: - - int unslept = 10; - while (unslept > 0) - unslept = sleep (unslept); - - A system call is allowed to return early, so the system is still -conforming to its specification. But GDB does cause your -multi-threaded program to behave differently than it would without GDB. - - Also, GDB uses internal breakpoints in the thread library to monitor -certain events such as thread creation and thread destruction. When -such an event happens, a system call in another thread may return -prematurely, even though your program does not appear to stop. - - Conversely, whenever you restart the program, _all_ threads start -executing. _This is true even when single-stepping_ with commands like -`step' or `next'. - - In particular, GDB cannot single-step all threads in lockstep. -Since thread scheduling is up to your debugging target's operating -system (not controlled by GDB), other threads may execute more than one -statement while the current thread completes a single step. Moreover, -in general other threads stop in the middle of a statement, rather than -at a clean statement boundary, when the program stops. - - You might even find your program stopped in another thread after -continuing or even single-stepping. This happens whenever some other -thread runs into a breakpoint, a signal, or an exception before the -first thread completes whatever you requested. - - On some OSes, you can lock the OS scheduler and thus allow only a -single thread to run. - -`set scheduler-locking MODE' - Set the scheduler locking mode. If it is `off', then there is no - locking and any thread may run at any time. If `on', then only the - current thread may run when the inferior is resumed. The `step' - mode optimizes for single-stepping. It stops other threads from - "seizing the prompt" by preempting the current thread while you are - stepping. Other threads will only rarely (or never) get a chance - to run when you step. They are more likely to run when you `next' - over a function call, and they are completely free to run when you - use commands like `continue', `until', or `finish'. However, - unless another thread hits a breakpoint during its timeslice, they - will never steal the GDB prompt away from the thread that you are - debugging. - -`show scheduler-locking' - Display the current scheduler locking mode. - - -File: gdb.info, Node: Stack, Next: Source, Prev: Stopping, Up: Top - -Examining the Stack -******************* - -When your program has stopped, the first thing you need to know is -where it stopped and how it got there. - - Each time your program performs a function call, information about -the call is generated. That information includes the location of the -call in your program, the arguments of the call, and the local -variables of the function being called. The information is saved in a -block of data called a "stack frame". The stack frames are allocated -in a region of memory called the "call stack". - - When your program stops, the GDB commands for examining the stack -allow you to see all of this information. - - One of the stack frames is "selected" by GDB and many GDB commands -refer implicitly to the selected frame. In particular, whenever you -ask GDB for the value of a variable in your program, the value is found -in the selected frame. There are special GDB commands to select -whichever frame you are interested in. *Note Selecting a frame: -Selection. - - When your program stops, GDB automatically selects the currently -executing frame and describes it briefly, similar to the `frame' -command (*note Information about a frame: Frame Info.). - -* Menu: - -* Frames:: Stack frames -* Backtrace:: Backtraces -* Selection:: Selecting a frame -* Frame Info:: Information on a frame - - -File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack - -Stack frames -============ - -The call stack is divided up into contiguous pieces called "stack -frames", or "frames" for short; each frame is the data associated with -one call to one function. The frame contains the arguments given to -the function, the function's local variables, and the address at which -the function is executing. - - When your program is started, the stack has only one frame, that of -the function `main'. This is called the "initial" frame or the -"outermost" frame. Each time a function is called, a new frame is -made. Each time a function returns, the frame for that function -invocation is eliminated. If a function is recursive, there can be -many frames for the same function. The frame for the function in which -execution is actually occurring is called the "innermost" frame. This -is the most recently created of all the stack frames that still exist. - - Inside your program, stack frames are identified by their addresses. -A stack frame consists of many bytes, each of which has its own -address; each kind of computer has a convention for choosing one byte -whose address serves as the address of the frame. Usually this address -is kept in a register called the "frame pointer register" while -execution is going on in that frame. - - GDB assigns numbers to all existing stack frames, starting with zero -for the innermost frame, one for the frame that called it, and so on -upward. These numbers do not really exist in your program; they are -assigned by GDB to give you a way of designating stack frames in GDB -commands. - - Some compilers provide a way to compile functions so that they -operate without stack frames. (For example, the gcc option - `-fomit-frame-pointer' - generates functions without a frame.) This is occasionally done -with heavily used library functions to save the frame setup time. GDB -has limited facilities for dealing with these function invocations. If -the innermost function invocation has no stack frame, GDB nevertheless -regards it as though it had a separate frame, which is numbered zero as -usual, allowing correct tracing of the function call chain. However, -GDB has no provision for frameless functions elsewhere in the stack. - -`frame ARGS' - The `frame' command allows you to move from one stack frame to - another, and to print the stack frame you select. ARGS may be - either the address of the frame or the stack frame number. - Without an argument, `frame' prints the current stack frame. - -`select-frame' - The `select-frame' command allows you to move from one stack frame - to another without printing the frame. This is the silent version - of `frame'. - - -File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack - -Backtraces -========== - -A backtrace is a summary of how your program got where it is. It shows -one line per frame, for many frames, starting with the currently -executing frame (frame zero), followed by its caller (frame one), and -on up the stack. - -`backtrace' -`bt' - Print a backtrace of the entire stack: one line per frame for all - frames in the stack. - - You can stop the backtrace at any time by typing the system - interrupt character, normally `C-c'. - -`backtrace N' -`bt N' - Similar, but print only the innermost N frames. - -`backtrace -N' -`bt -N' - Similar, but print only the outermost N frames. - - The names `where' and `info stack' (abbreviated `info s') are -additional aliases for `backtrace'. - - Each line in the backtrace shows the frame number and the function -name. The program counter value is also shown--unless you use `set -print address off'. The backtrace also shows the source file name and -line number, as well as the arguments to the function. The program -counter value is omitted if it is at the beginning of the code for that -line number. - - Here is an example of a backtrace. It was made with the command `bt -3', so it shows the innermost three frames. - - #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) - at builtin.c:993 - #1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 - #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) - at macro.c:71 - (More stack frames follow...) - -The display for frame zero does not begin with a program counter value, -indicating that your program has stopped at the beginning of the code -for line `993' of `builtin.c'. - - Most programs have a standard user entry point--a place where system -libraries and startup code transition into user code. For C this is -`main'. When GDB finds the entry function in a backtrace it will -terminate the backtrace, to avoid tracing into highly system-specific -(and generally uninteresting) code. - - If you need to examine the startup code, or limit the number of -levels in a backtrace, you can change this behavior: - -`set backtrace past-main' -`set backtrace past-main on' - Backtraces will continue past the user entry point. - -`set backtrace past-main off' - Backtraces will stop when they encounter the user entry point. - This is the default. - -`show backtrace past-main' - Display the current user entry point backtrace policy. - -`set backtrace limit N' -`set backtrace limit 0' - Limit the backtrace to N levels. A value of zero means unlimited. - -`show backtrace limit' - Display the current limit on backtrace levels. - - -File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack - -Selecting a frame -================= - -Most commands for examining the stack and other data in your program -work on whichever stack frame is selected at the moment. Here are the -commands for selecting a stack frame; all of them finish by printing a -brief description of the stack frame just selected. - -`frame N' -`f N' - Select frame number N. Recall that frame zero is the innermost - (currently executing) frame, frame one is the frame that called the - innermost one, and so on. The highest-numbered frame is the one - for `main'. - -`frame ADDR' -`f ADDR' - Select the frame at address ADDR. This is useful mainly if the - chaining of stack frames has been damaged by a bug, making it - impossible for GDB to assign numbers properly to all frames. In - addition, this can be useful when your program has multiple stacks - and switches between them. - - On the SPARC architecture, `frame' needs two addresses to select - an arbitrary frame: a frame pointer and a stack pointer. - - On the MIPS and Alpha architecture, it needs two addresses: a stack - pointer and a program counter. - - On the 29k architecture, it needs three addresses: a register stack - pointer, a program counter, and a memory stack pointer. - -`up N' - Move N frames up the stack. For positive numbers N, this advances - toward the outermost frame, to higher frame numbers, to frames - that have existed longer. N defaults to one. - -`down N' - Move N frames down the stack. For positive numbers N, this - advances toward the innermost frame, to lower frame numbers, to - frames that were created more recently. N defaults to one. You - may abbreviate `down' as `do'. - - All of these commands end by printing two lines of output describing -the frame. The first line shows the frame number, the function name, -the arguments, and the source file and line number of execution in that -frame. The second line shows the text of that source line. - - For example: - - (gdb) up - #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) - at env.c:10 - 10 read_input_file (argv[i]); - - After such a printout, the `list' command with no arguments prints -ten lines centered on the point of execution in the frame. You can -also edit the program at the point of execution with your favorite -editing program by typing `edit'. *Note Printing source lines: List, -for details. - -`up-silently N' -`down-silently N' - These two commands are variants of `up' and `down', respectively; - they differ in that they do their work silently, without causing - display of the new frame. They are intended primarily for use in - GDB command scripts, where the output might be unnecessary and - distracting. - - -File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack - -Information about a frame -========================= - -There are several other commands to print information about the selected -stack frame. - -`frame' -`f' - When used without any argument, this command does not change which - frame is selected, but prints a brief description of the currently - selected stack frame. It can be abbreviated `f'. With an - argument, this command is used to select a stack frame. *Note - Selecting a frame: Selection. - -`info frame' -`info f' - This command prints a verbose description of the selected stack - frame, including: - - * the address of the frame - - * the address of the next frame down (called by this frame) - - * the address of the next frame up (caller of this frame) - - * the language in which the source code corresponding to this - frame is written - - * the address of the frame's arguments - - * the address of the frame's local variables - - * the program counter saved in it (the address of execution in - the caller frame) - - * which registers were saved in the frame - - The verbose description is useful when something has gone wrong - that has made the stack format fail to fit the usual conventions. - -`info frame ADDR' -`info f ADDR' - Print a verbose description of the frame at address ADDR, without - selecting that frame. The selected frame remains unchanged by this - command. This requires the same kind of address (more than one - for some architectures) that you specify in the `frame' command. - *Note Selecting a frame: Selection. - -`info args' - Print the arguments of the selected frame, each on a separate line. - -`info locals' - Print the local variables of the selected frame, each on a separate - line. These are all variables (declared either static or - automatic) accessible at the point of execution of the selected - frame. - -`info catch' - Print a list of all the exception handlers that are active in the - current stack frame at the current point of execution. To see - other exception handlers, visit the associated frame (using the - `up', `down', or `frame' commands); then type `info catch'. *Note - Setting catchpoints: Set Catchpoints. - - - -File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top - -Examining Source Files -********************** - -GDB can print parts of your program's source, since the debugging -information recorded in the program tells GDB what source files were -used to build it. When your program stops, GDB spontaneously prints -the line where it stopped. Likewise, when you select a stack frame -(*note Selecting a frame: Selection.), GDB prints the line where -execution in that frame has stopped. You can print other portions of -source files by explicit command. - - If you use GDB through its GNU Emacs interface, you may prefer to -use Emacs facilities to view source; see *Note Using GDB under GNU -Emacs: Emacs. - -* Menu: - -* List:: Printing source lines -* Edit:: Editing source files -* Search:: Searching source files -* Source Path:: Specifying source directories -* Machine Code:: Source and machine code - - -File: gdb.info, Node: List, Next: Edit, Up: Source - -Printing source lines -===================== - -To print lines from a source file, use the `list' command (abbreviated -`l'). By default, ten lines are printed. There are several ways to -specify what part of the file you want to print. - - Here are the forms of the `list' command most commonly used: - -`list LINENUM' - Print lines centered around line number LINENUM in the current - source file. - -`list FUNCTION' - Print lines centered around the beginning of function FUNCTION. - -`list' - Print more lines. If the last lines printed were printed with a - `list' command, this prints lines following the last lines - printed; however, if the last line printed was a solitary line - printed as part of displaying a stack frame (*note Examining the - Stack: Stack.), this prints lines centered around that line. - -`list -' - Print lines just before the lines last printed. - - By default, GDB prints ten source lines with any of these forms of -the `list' command. You can change this using `set listsize': - -`set listsize COUNT' - Make the `list' command display COUNT source lines (unless the - `list' argument explicitly specifies some other number). - -`show listsize' - Display the number of lines that `list' prints. - - Repeating a `list' command with <RET> discards the argument, so it -is equivalent to typing just `list'. This is more useful than listing -the same lines again. An exception is made for an argument of `-'; -that argument is preserved in repetition so that each repetition moves -up in the source file. - - In general, the `list' command expects you to supply zero, one or two -"linespecs". Linespecs specify source lines; there are several ways of -writing them, but the effect is always to specify some source line. -Here is a complete description of the possible arguments for `list': - -`list LINESPEC' - Print lines centered around the line specified by LINESPEC. - -`list FIRST,LAST' - Print lines from FIRST to LAST. Both arguments are linespecs. - -`list ,LAST' - Print lines ending with LAST. - -`list FIRST,' - Print lines starting with FIRST. - -`list +' - Print lines just after the lines last printed. - -`list -' - Print lines just before the lines last printed. - -`list' - As described in the preceding table. - - Here are the ways of specifying a single source line--all the kinds -of linespec. - -`NUMBER' - Specifies line NUMBER of the current source file. When a `list' - command has two linespecs, this refers to the same source file as - the first linespec. - -`+OFFSET' - Specifies the line OFFSET lines after the last line printed. When - used as the second linespec in a `list' command that has two, this - specifies the line OFFSET lines down from the first linespec. - -`-OFFSET' - Specifies the line OFFSET lines before the last line printed. - -`FILENAME:NUMBER' - Specifies line NUMBER in the source file FILENAME. - -`FUNCTION' - Specifies the line that begins the body of the function FUNCTION. - For example: in C, this is the line with the open brace. - -`FILENAME:FUNCTION' - Specifies the line of the open-brace that begins the body of the - function FUNCTION in the file FILENAME. You only need the file - name with a function name to avoid ambiguity when there are - identically named functions in different source files. - -`*ADDRESS' - Specifies the line containing the program address ADDRESS. - ADDRESS may be any expression. - - -File: gdb.info, Node: Edit, Next: Search, Prev: List, Up: Source - -Editing source files -==================== - -To edit the lines in a source file, use the `edit' command. The -editing program of your choice is invoked with the current line set to -the active line in the program. Alternatively, there are several ways -to specify what part of the file you want to print if you want to see -other parts of the program. - - Here are the forms of the `edit' command most commonly used: - -`edit' - Edit the current source file at the active line number in the - program. - -`edit NUMBER' - Edit the current source file with NUMBER as the active line number. - -`edit FUNCTION' - Edit the file containing FUNCTION at the beginning of its - definition. - -`edit FILENAME:NUMBER' - Specifies line NUMBER in the source file FILENAME. - -`edit FILENAME:FUNCTION' - Specifies the line that begins the body of the function FUNCTION - in the file FILENAME. You only need the file name with a function - name to avoid ambiguity when there are identically named functions - in different source files. - -`edit *ADDRESS' - Specifies the line containing the program address ADDRESS. - ADDRESS may be any expression. - -Choosing your editor --------------------- - -You can customize GDB to use any editor you want (1). By default, it -is /bin/ex, but you can change this by setting the environment variable -`EDITOR' before using GDB. For example, to configure GDB to use the -`vi' editor, you could use these commands with the `sh' shell: - EDITOR=/usr/bin/vi - export EDITOR - gdb ... - or in the `csh' shell, - setenv EDITOR /usr/bin/vi - gdb ... - - ---------- Footnotes ---------- - - (1) The only restriction is that your editor (say `ex'), recognizes -the following command-line syntax: - ex +NUMBER file - The optional numeric value +NUMBER designates the active line in the -file. - - -File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source - -Searching source files -====================== - -There are two commands for searching through the current source file -for a regular expression. - -`forward-search REGEXP' -`search REGEXP' - The command `forward-search REGEXP' checks each line, starting - with the one following the last line listed, for a match for - REGEXP. It lists the line that is found. You can use the synonym - `search REGEXP' or abbreviate the command name as `fo'. - -`reverse-search REGEXP' - The command `reverse-search REGEXP' checks each line, starting - with the one before the last line listed and going backward, for a - match for REGEXP. It lists the line that is found. You can - abbreviate this command as `rev'. - - -File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source - -Specifying source directories -============================= - -Executable programs sometimes do not record the directories of the -source files from which they were compiled, just the names. Even when -they do, the directories could be moved between the compilation and -your debugging session. GDB has a list of directories to search for -source files; this is called the "source path". Each time GDB wants a -source file, it tries all the directories in the list, in the order -they are present in the list, until it finds a file with the desired -name. Note that the executable search path is _not_ used for this -purpose. Neither is the current working directory, unless it happens -to be in the source path. - - If GDB cannot find a source file in the source path, and the object -program records a directory, GDB tries that directory too. If the -source path is empty, and there is no record of the compilation -directory, GDB looks in the current directory as a last resort. - - Whenever you reset or rearrange the source path, GDB clears out any -information it has cached about where source files are found and where -each line is in the file. - - When you start GDB, its source path includes only `cdir' and `cwd', -in that order. To add other directories, use the `directory' command. - -`directory DIRNAME ...' - -`dir DIRNAME ...' - Add directory DIRNAME to the front of the source path. Several - directory names may be given to this command, separated by `:' - (`;' on MS-DOS and MS-Windows, where `:' usually appears as part - of absolute file names) or whitespace. You may specify a - directory that is already in the source path; this moves it - forward, so GDB searches it sooner. - - You can use the string `$cdir' to refer to the compilation - directory (if one is recorded), and `$cwd' to refer to the current - working directory. `$cwd' is not the same as `.'--the former - tracks the current working directory as it changes during your GDB - session, while the latter is immediately expanded to the current - directory at the time you add an entry to the source path. - -`directory' - Reset the source path to empty again. This requires confirmation. - -`show directories' - Print the source path: show which directories it contains. - - If your source path is cluttered with directories that are no longer -of interest, GDB may sometimes cause confusion by finding the wrong -versions of source. You can correct the situation as follows: - - 1. Use `directory' with no argument to reset the source path to empty. - - 2. Use `directory' with suitable arguments to reinstall the - directories you want in the source path. You can add all the - directories in one command. - - -File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source - -Source and machine code -======================= - -You can use the command `info line' to map source lines to program -addresses (and vice versa), and the command `disassemble' to display a -range of addresses as machine instructions. When run under GNU Emacs -mode, the `info line' command causes the arrow to point to the line -specified. Also, `info line' prints addresses in symbolic form as well -as hex. - -`info line LINESPEC' - Print the starting and ending addresses of the compiled code for - source line LINESPEC. You can specify source lines in any of the - ways understood by the `list' command (*note Printing source - lines: List.). - - For example, we can use `info line' to discover the location of the -object code for the first line of function `m4_changequote': - - (gdb) info line m4_changequote - Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. - -We can also inquire (using `*ADDR' as the form for LINESPEC) what -source line covers a particular address: - (gdb) info line *0x63ff - Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. - - After `info line', the default address for the `x' command is -changed to the starting address of the line, so that `x/i' is -sufficient to begin examining the machine code (*note Examining memory: -Memory.). Also, this address is saved as the value of the convenience -variable `$_' (*note Convenience variables: Convenience Vars.). - -`disassemble' - This specialized command dumps a range of memory as machine - instructions. The default memory range is the function - surrounding the program counter of the selected frame. A single - argument to this command is a program counter value; GDB dumps the - function surrounding this value. Two arguments specify a range of - addresses (first inclusive, second exclusive) to dump. - - The following example shows the disassembly of a range of addresses -of HP PA-RISC 2.0 code: - - (gdb) disas 0x32c4 0x32e4 - Dump of assembler code from 0x32c4 to 0x32e4: - 0x32c4 <main+204>: addil 0,dp - 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 - 0x32cc <main+212>: ldil 0x3000,r31 - 0x32d0 <main+216>: ble 0x3f8(sr4,r31) - 0x32d4 <main+220>: ldo 0(r31),rp - 0x32d8 <main+224>: addil -0x800,dp - 0x32dc <main+228>: ldo 0x588(r1),r26 - 0x32e0 <main+232>: ldil 0x3000,r31 - End of assembler dump. - - Some architectures have more than one commonly-used set of -instruction mnemonics or other syntax. - -`set disassembly-flavor INSTRUCTION-SET' - Select the instruction set to use when disassembling the program - via the `disassemble' or `x/i' commands. - - Currently this command is only defined for the Intel x86 family. - You can set INSTRUCTION-SET to either `intel' or `att'. The - default is `att', the AT&T flavor used by default by Unix - assemblers for x86-based targets. - - -File: gdb.info, Node: Data, Next: Macros, Prev: Source, Up: Top - -Examining Data -************** - -The usual way to examine data in your program is with the `print' -command (abbreviated `p'), or its synonym `inspect'. It evaluates and -prints the value of an expression of the language your program is -written in (*note Using GDB with Different Languages: Languages.). - -`print EXPR' -`print /F EXPR' - EXPR is an expression (in the source language). By default the - value of EXPR is printed in a format appropriate to its data type; - you can choose a different format by specifying `/F', where F is a - letter specifying the format; see *Note Output formats: Output - Formats. - -`print' -`print /F' - If you omit EXPR, GDB displays the last value again (from the - "value history"; *note Value history: Value History.). This - allows you to conveniently inspect the same value in an - alternative format. - - A more low-level way of examining data is with the `x' command. It -examines data in memory at a specified address and prints it in a -specified format. *Note Examining memory: Memory. - - If you are interested in information about types, or about how the -fields of a struct or a class are declared, use the `ptype EXP' command -rather than `print'. *Note Examining the Symbol Table: Symbols. - -* Menu: - -* Expressions:: Expressions -* Variables:: Program variables -* Arrays:: Artificial arrays -* Output Formats:: Output formats -* Memory:: Examining memory -* Auto Display:: Automatic display -* Print Settings:: Print settings -* Value History:: Value history -* Convenience Vars:: Convenience variables -* Registers:: Registers -* Floating Point Hardware:: Floating point hardware -* Vector Unit:: Vector Unit -* Auxiliary Vector:: Auxiliary data provided by operating system -* Memory Region Attributes:: Memory region attributes -* Dump/Restore Files:: Copy between memory and a file -* Character Sets:: Debugging programs that use a different - character set than GDB does - - -File: gdb.info, Node: Expressions, Next: Variables, Up: Data - -Expressions -=========== - -`print' and many other GDB commands accept an expression and compute -its value. Any kind of constant, variable or operator defined by the -programming language you are using is valid in an expression in GDB. -This includes conditional expressions, function calls, casts, and -string constants. It also includes preprocessor macros, if you -compiled your program to include this information; see *Note -Compilation::. - - GDB supports array constants in expressions input by the user. The -syntax is {ELEMENT, ELEMENT...}. For example, you can use the command -`print {1, 2, 3}' to build up an array in memory that is `malloc'ed in -the target program. - - Because C is so widespread, most of the expressions shown in -examples in this manual are in C. *Note Using GDB with Different -Languages: Languages, for information on how to use expressions in other -languages. - - In this section, we discuss operators that you can use in GDB -expressions regardless of your programming language. - - Casts are supported in all languages, not just in C, because it is so -useful to cast a number into a pointer in order to examine a structure -at that address in memory. - - GDB supports these operators, in addition to those common to -programming languages: - -`@' - `@' is a binary operator for treating parts of memory as arrays. - *Note Artificial arrays: Arrays, for more information. - -`::' - `::' allows you to specify a variable in terms of the file or - function where it is defined. *Note Program variables: Variables. - -`{TYPE} ADDR' - Refers to an object of type TYPE stored at address ADDR in memory. - ADDR may be any expression whose value is an integer or pointer - (but parentheses are required around binary operators, just as in - a cast). This construct is allowed regardless of what kind of - data is normally supposed to reside at ADDR. - - -File: gdb.info, Node: Variables, Next: Arrays, Prev: Expressions, Up: Data - -Program variables -================= - -The most common kind of expression to use is the name of a variable in -your program. - - Variables in expressions are understood in the selected stack frame -(*note Selecting a frame: Selection.); they must be either: - - * global (or file-static) - -or - - * visible according to the scope rules of the programming language - from the point of execution in that frame - -This means that in the function - - foo (a) - int a; - { - bar (a); - { - int b = test (); - bar (b); - } - } - -you can examine and use the variable `a' whenever your program is -executing within the function `foo', but you can only use or examine -the variable `b' while your program is executing inside the block where -`b' is declared. - - There is an exception: you can refer to a variable or function whose -scope is a single source file even if the current execution point is not -in this file. But it is possible to have more than one such variable or -function with the same name (in different source files). If that -happens, referring to that name has unpredictable effects. If you wish, -you can specify a static variable in a particular function or file, -using the colon-colon notation: - - FILE::VARIABLE - FUNCTION::VARIABLE - -Here FILE or FUNCTION is the name of the context for the static -VARIABLE. In the case of file names, you can use quotes to make sure -GDB parses the file name as a single word--for example, to print a -global value of `x' defined in `f2.c': - - (gdb) p 'f2.c'::x - - This use of `::' is very rarely in conflict with the very similar -use of the same notation in C++. GDB also supports use of the C++ -scope resolution operator in GDB expressions. - - _Warning:_ Occasionally, a local variable may appear to have the - wrong value at certain points in a function--just after entry to a - new scope, and just before exit. - You may see this problem when you are stepping by machine -instructions. This is because, on most machines, it takes more than -one instruction to set up a stack frame (including local variable -definitions); if you are stepping by machine instructions, variables -may appear to have the wrong values until the stack frame is completely -built. On exit, it usually also takes more than one machine -instruction to destroy a stack frame; after you begin stepping through -that group of instructions, local variable definitions may be gone. - - This may also happen when the compiler does significant -optimizations. To be sure of always seeing accurate values, turn off -all optimization when compiling. - - Another possible effect of compiler optimizations is to optimize -unused variables out of existence, or assign variables to registers (as -opposed to memory addresses). Depending on the support for such cases -offered by the debug info format used by the compiler, GDB might not be -able to display values for such local variables. If that happens, GDB -will print a message like this: - - No symbol "foo" in current context. - - To solve such problems, either recompile without optimizations, or -use a different debug info format, if the compiler supports several such -formats. For example, GCC, the GNU C/C++ compiler usually supports the -`-gstabs+' option. `-gstabs+' produces debug info in a format that is -superior to formats such as COFF. You may be able to use DWARF 2 -(`-gdwarf-2'), which is also an effective form for debug info. *Note -Options for Debugging Your Program or GNU CC: (gcc.info)Debugging -Options. - - -File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data - -Artificial arrays -================= - -It is often useful to print out several successive objects of the same -type in memory; a section of an array, or an array of dynamically -determined size for which only a pointer exists in the program. - - You can do this by referring to a contiguous span of memory as an -"artificial array", using the binary operator `@'. The left operand of -`@' should be the first element of the desired array and be an -individual object. The right operand should be the desired length of -the array. The result is an array value whose elements are all of the -type of the left argument. The first element is actually the left -argument; the second element comes from bytes of memory immediately -following those that hold the first element, and so on. Here is an -example. If a program says - - int *array = (int *) malloc (len * sizeof (int)); - -you can print the contents of `array' with - - p *array@len - - The left operand of `@' must reside in memory. Array values made -with `@' in this way behave just like other arrays in terms of -subscripting, and are coerced to pointers when used in expressions. -Artificial arrays most often appear in expressions via the value history -(*note Value history: Value History.), after printing one out. - - Another way to create an artificial array is to use a cast. This -re-interprets a value as if it were an array. The value need not be in -memory: - (gdb) p/x (short[2])0x12345678 - $1 = {0x1234, 0x5678} - - As a convenience, if you leave the array length out (as in -`(TYPE[])VALUE') GDB calculates the size to fill the value (as -`sizeof(VALUE)/sizeof(TYPE)': - (gdb) p/x (short[])0x12345678 - $2 = {0x1234, 0x5678} - - Sometimes the artificial array mechanism is not quite enough; in -moderately complex data structures, the elements of interest may not -actually be adjacent--for example, if you are interested in the values -of pointers in an array. One useful work-around in this situation is -to use a convenience variable (*note Convenience variables: Convenience -Vars.) as a counter in an expression that prints the first interesting -value, and then repeat that expression via <RET>. For instance, -suppose you have an array `dtab' of pointers to structures, and you are -interested in the values of a field `fv' in each structure. Here is an -example of what you might type: - - set $i = 0 - p dtab[$i++]->fv - <RET> - <RET> - ... - - -File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data - -Output formats -============== - -By default, GDB prints a value according to its data type. Sometimes -this is not what you want. For example, you might want to print a -number in hex, or a pointer in decimal. Or you might want to view data -in memory at a certain address as a character string or as an -instruction. To do these things, specify an "output format" when you -print a value. - - The simplest use of output formats is to say how to print a value -already computed. This is done by starting the arguments of the -`print' command with a slash and a format letter. The format letters -supported are: - -`x' - Regard the bits of the value as an integer, and print the integer - in hexadecimal. - -`d' - Print as integer in signed decimal. - -`u' - Print as integer in unsigned decimal. - -`o' - Print as integer in octal. - -`t' - Print as integer in binary. The letter `t' stands for "two". (1) - -`a' - Print as an address, both absolute in hexadecimal and as an offset - from the nearest preceding symbol. You can use this format used - to discover where (in what function) an unknown address is located: - - (gdb) p/a 0x54320 - $3 = 0x54320 <_initialize_vx+396> - - The command `info symbol 0x54320' yields similar results. *Note - info symbol: Symbols. - -`c' - Regard as an integer and print it as a character constant. - -`f' - Regard the bits of the value as a floating point number and print - using typical floating point syntax. - - For example, to print the program counter in hex (*note -Registers::), type - - p/x $pc - -Note that no space is required before the slash; this is because command -names in GDB cannot contain a slash. - - To reprint the last value in the value history with a different -format, you can use the `print' command with just a format and no -expression. For example, `p/x' reprints the last value in hex. - - ---------- Footnotes ---------- - - (1) `b' cannot be used because these format letters are also used -with the `x' command, where `b' stands for "byte"; see *Note Examining -memory: Memory. - - -File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data - -Examining memory -================ - -You can use the command `x' (for "examine") to examine memory in any of -several formats, independently of your program's data types. - -`x/NFU ADDR' -`x ADDR' -`x' - Use the `x' command to examine memory. - - N, F, and U are all optional parameters that specify how much memory -to display and how to format it; ADDR is an expression giving the -address where you want to start displaying memory. If you use defaults -for NFU, you need not type the slash `/'. Several commands set -convenient defaults for ADDR. - -N, the repeat count - The repeat count is a decimal integer; the default is 1. It - specifies how much memory (counting by units U) to display. - -F, the display format - The display format is one of the formats used by `print', `s' - (null-terminated string), or `i' (machine instruction). The - default is `x' (hexadecimal) initially. The default changes each - time you use either `x' or `print'. - -U, the unit size - The unit size is any of - - `b' - Bytes. - - `h' - Halfwords (two bytes). - - `w' - Words (four bytes). This is the initial default. - - `g' - Giant words (eight bytes). - - Each time you specify a unit size with `x', that size becomes the - default unit the next time you use `x'. (For the `s' and `i' - formats, the unit size is ignored and is normally not written.) - -ADDR, starting display address - ADDR is the address where you want GDB to begin displaying memory. - The expression need not have a pointer value (though it may); it - is always interpreted as an integer address of a byte of memory. - *Note Expressions: Expressions, for more information on - expressions. The default for ADDR is usually just after the last - address examined--but several other commands also set the default - address: `info breakpoints' (to the address of the last breakpoint - listed), `info line' (to the starting address of a line), and - `print' (if you use it to display a value from memory). - - For example, `x/3uh 0x54320' is a request to display three halfwords -(`h') of memory, formatted as unsigned decimal integers (`u'), starting -at address `0x54320'. `x/4xw $sp' prints the four words (`w') of -memory above the stack pointer (here, `$sp'; *note Registers: -Registers.) in hexadecimal (`x'). - - Since the letters indicating unit sizes are all distinct from the -letters specifying output formats, you do not have to remember whether -unit size or format comes first; either order works. The output -specifications `4xw' and `4wx' mean exactly the same thing. (However, -the count N must come first; `wx4' does not work.) - - Even though the unit size U is ignored for the formats `s' and `i', -you might still want to use a count N; for example, `3i' specifies that -you want to see three machine instructions, including any operands. -The command `disassemble' gives an alternative way of inspecting -machine instructions; see *Note Source and machine code: Machine Code. - - All the defaults for the arguments to `x' are designed to make it -easy to continue scanning memory with minimal specifications each time -you use `x'. For example, after you have inspected three machine -instructions with `x/3i ADDR', you can inspect the next seven with just -`x/7'. If you use <RET> to repeat the `x' command, the repeat count N -is used again; the other arguments default as for successive uses of -`x'. - - The addresses and contents printed by the `x' command are not saved -in the value history because there is often too much of them and they -would get in the way. Instead, GDB makes these values available for -subsequent use in expressions as values of the convenience variables -`$_' and `$__'. After an `x' command, the last address examined is -available for use in expressions in the convenience variable `$_'. The -contents of that address, as examined, are available in the convenience -variable `$__'. - - If the `x' command has a repeat count, the address and contents saved -are from the last memory unit printed; this is not the same as the last -address printed if several units were printed on the last line of -output. - - -File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data - -Automatic display -================= - -If you find that you want to print the value of an expression frequently -(to see how it changes), you might want to add it to the "automatic -display list" so that GDB prints its value each time your program stops. -Each expression added to the list is given a number to identify it; to -remove an expression from the list, you specify that number. The -automatic display looks like this: - - 2: foo = 38 - 3: bar[5] = (struct hack *) 0x3804 - -This display shows item numbers, expressions and their current values. -As with displays you request manually using `x' or `print', you can -specify the output format you prefer; in fact, `display' decides -whether to use `print' or `x' depending on how elaborate your format -specification is--it uses `x' if you specify a unit size, or one of the -two formats (`i' and `s') that are only supported by `x'; otherwise it -uses `print'. - -`display EXPR' - Add the expression EXPR to the list of expressions to display each - time your program stops. *Note Expressions: Expressions. - - `display' does not repeat if you press <RET> again after using it. - -`display/FMT EXPR' - For FMT specifying only a display format and not a size or count, - add the expression EXPR to the auto-display list but arrange to - display it each time in the specified format FMT. *Note Output - formats: Output Formats. - -`display/FMT ADDR' - For FMT `i' or `s', or including a unit-size or a number of units, - add the expression ADDR as a memory address to be examined each - time your program stops. Examining means in effect doing `x/FMT - ADDR'. *Note Examining memory: Memory. - - For example, `display/i $pc' can be helpful, to see the machine -instruction about to be executed each time execution stops (`$pc' is a -common name for the program counter; *note Registers: Registers.). - -`undisplay DNUMS...' -`delete display DNUMS...' - Remove item numbers DNUMS from the list of expressions to display. - - `undisplay' does not repeat if you press <RET> after using it. - (Otherwise you would just get the error `No display number ...'.) - -`disable display DNUMS...' - Disable the display of item numbers DNUMS. A disabled display - item is not printed automatically, but is not forgotten. It may be - enabled again later. - -`enable display DNUMS...' - Enable display of item numbers DNUMS. It becomes effective once - again in auto display of its expression, until you specify - otherwise. - -`display' - Display the current values of the expressions on the list, just as - is done when your program stops. - -`info display' - Print the list of expressions previously set up to display - automatically, each one with its item number, but without showing - the values. This includes disabled expressions, which are marked - as such. It also includes expressions which would not be - displayed right now because they refer to automatic variables not - currently available. - - If a display expression refers to local variables, then it does not -make sense outside the lexical context for which it was set up. Such an -expression is disabled when execution enters a context where one of its -variables is not defined. For example, if you give the command -`display last_char' while inside a function with an argument -`last_char', GDB displays this argument while your program continues to -stop inside that function. When it stops elsewhere--where there is no -variable `last_char'--the display is disabled automatically. The next -time your program stops where `last_char' is meaningful, you can enable -the display expression once again. - - -File: gdb.info, Node: Print Settings, Next: Value History, Prev: Auto Display, Up: Data - -Print settings -============== - -GDB provides the following ways to control how arrays, structures, and -symbols are printed. - -These settings are useful for debugging programs in any language: - -`set print address' -`set print address on' - GDB prints memory addresses showing the location of stack traces, - structure values, pointer values, breakpoints, and so forth, even - when it also displays the contents of those addresses. The default - is `on'. For example, this is what a stack frame display looks - like with `set print address on': - - (gdb) f - #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") - at input.c:530 - 530 if (lquote != def_lquote) - -`set print address off' - Do not print addresses when displaying their contents. For - example, this is the same stack frame displayed with `set print - address off': - - (gdb) set print addr off - (gdb) f - #0 set_quotes (lq="<<", rq=">>") at input.c:530 - 530 if (lquote != def_lquote) - - You can use `set print address off' to eliminate all machine - dependent displays from the GDB interface. For example, with - `print address off', you should get the same text for backtraces on - all machines--whether or not they involve pointer arguments. - -`show print address' - Show whether or not addresses are to be printed. - - When GDB prints a symbolic address, it normally prints the closest -earlier symbol plus an offset. If that symbol does not uniquely -identify the address (for example, it is a name whose scope is a single -source file), you may need to clarify. One way to do this is with -`info line', for example `info line *0x4537'. Alternately, you can set -GDB to print the source file and line number when it prints a symbolic -address: - -`set print symbol-filename on' - Tell GDB to print the source file name and line number of a symbol - in the symbolic form of an address. - -`set print symbol-filename off' - Do not print source file name and line number of a symbol. This - is the default. - -`show print symbol-filename' - Show whether or not GDB will print the source file name and line - number of a symbol in the symbolic form of an address. - - Another situation where it is helpful to show symbol filenames and -line numbers is when disassembling code; GDB shows you the line number -and source file that corresponds to each instruction. - - Also, you may wish to see the symbolic form only if the address being -printed is reasonably close to the closest earlier symbol: - -`set print max-symbolic-offset MAX-OFFSET' - Tell GDB to only display the symbolic form of an address if the - offset between the closest earlier symbol and the address is less - than MAX-OFFSET. The default is 0, which tells GDB to always - print the symbolic form of an address if any symbol precedes it. - -`show print max-symbolic-offset' - Ask how large the maximum offset is that GDB prints in a symbolic - address. - - If you have a pointer and you are not sure where it points, try `set -print symbol-filename on'. Then you can determine the name and source -file location of the variable where it points, using `p/a POINTER'. -This interprets the address in symbolic form. For example, here GDB -shows that a variable `ptt' points at another variable `t', defined in -`hi2.c': - - (gdb) set print symbol-filename on - (gdb) p/a ptt - $4 = 0xe008 <t in hi2.c> - - _Warning:_ For pointers that point to a local variable, `p/a' does - not show the symbol name and filename of the referent, even with - the appropriate `set print' options turned on. - - Other settings control how different kinds of objects are printed: - -`set print array' -`set print array on' - Pretty print arrays. This format is more convenient to read, but - uses more space. The default is off. - -`set print array off' - Return to compressed format for arrays. - -`show print array' - Show whether compressed or pretty format is selected for displaying - arrays. - -`set print elements NUMBER-OF-ELEMENTS' - Set a limit on how many elements of an array GDB will print. If - GDB is printing a large array, it stops printing after it has - printed the number of elements set by the `set print elements' - command. This limit also applies to the display of strings. When - GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS - to zero means that the printing is unlimited. - -`show print elements' - Display the number of elements of a large array that GDB will - print. If the number is 0, then the printing is unlimited. - -`set print null-stop' - Cause GDB to stop printing the characters of an array when the - first NULL is encountered. This is useful when large arrays - actually contain only short strings. The default is off. - -`set print pretty on' - Cause GDB to print structures in an indented format with one member - per line, like this: - - $1 = { - next = 0x0, - flags = { - sweet = 1, - sour = 1 - }, - meat = 0x54 "Pork" - } - -`set print pretty off' - Cause GDB to print structures in a compact format, like this: - - $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ - meat = 0x54 "Pork"} - - This is the default format. - -`show print pretty' - Show which format GDB is using to print structures. - -`set print sevenbit-strings on' - Print using only seven-bit characters; if this option is set, GDB - displays any eight-bit characters (in strings or character values) - using the notation `\'NNN. This setting is best if you are - working in English (ASCII) and you use the high-order bit of - characters as a marker or "meta" bit. - -`set print sevenbit-strings off' - Print full eight-bit characters. This allows the use of more - international character sets, and is the default. - -`show print sevenbit-strings' - Show whether or not GDB is printing only seven-bit characters. - -`set print union on' - Tell GDB to print unions which are contained in structures. This - is the default setting. - -`set print union off' - Tell GDB not to print unions which are contained in structures. - -`show print union' - Ask GDB whether or not it will print unions which are contained in - structures. - - For example, given the declarations - - typedef enum {Tree, Bug} Species; - typedef enum {Big_tree, Acorn, Seedling} Tree_forms; - typedef enum {Caterpillar, Cocoon, Butterfly} - Bug_forms; - - struct thing { - Species it; - union { - Tree_forms tree; - Bug_forms bug; - } form; - }; - - struct thing foo = {Tree, {Acorn}}; - - with `set print union on' in effect `p foo' would print - - $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} - - and with `set print union off' in effect it would print - - $1 = {it = Tree, form = {...}} - -These settings are of interest when debugging C++ programs: - -`set print demangle' -`set print demangle on' - Print C++ names in their source form rather than in the encoded - ("mangled") form passed to the assembler and linker for type-safe - linkage. The default is on. - -`show print demangle' - Show whether C++ names are printed in mangled or demangled form. - -`set print asm-demangle' -`set print asm-demangle on' - Print C++ names in their source form rather than their mangled - form, even in assembler code printouts such as instruction - disassemblies. The default is off. - -`show print asm-demangle' - Show whether C++ names in assembly listings are printed in mangled - or demangled form. - -`set demangle-style STYLE' - Choose among several encoding schemes used by different compilers - to represent C++ names. The choices for STYLE are currently: - - `auto' - Allow GDB to choose a decoding style by inspecting your - program. - - `gnu' - Decode based on the GNU C++ compiler (`g++') encoding - algorithm. This is the default. - - `hp' - Decode based on the HP ANSI C++ (`aCC') encoding algorithm. - - `lucid' - Decode based on the Lucid C++ compiler (`lcc') encoding - algorithm. - - `arm' - Decode using the algorithm in the `C++ Annotated Reference - Manual'. *Warning:* this setting alone is not sufficient to - allow debugging `cfront'-generated executables. GDB would - require further enhancement to permit that. - - If you omit STYLE, you will see a list of possible formats. - -`show demangle-style' - Display the encoding style currently in use for decoding C++ - symbols. - -`set print object' -`set print object on' - When displaying a pointer to an object, identify the _actual_ - (derived) type of the object rather than the _declared_ type, using - the virtual function table. - -`set print object off' - Display only the declared type of objects, without reference to the - virtual function table. This is the default setting. - -`show print object' - Show whether actual, or declared, object types are displayed. - -`set print static-members' -`set print static-members on' - Print static members when displaying a C++ object. The default is - on. - -`set print static-members off' - Do not print static members when displaying a C++ object. - -`show print static-members' - Show whether C++ static members are printed, or not. - -`set print vtbl' -`set print vtbl on' - Pretty print C++ virtual function tables. The default is off. - (The `vtbl' commands do not work on programs compiled with the HP - ANSI C++ compiler (`aCC').) - -`set print vtbl off' - Do not pretty print C++ virtual function tables. - -`show print vtbl' - Show whether C++ virtual function tables are pretty printed, or - not. - - -File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Print Settings, Up: Data - -Value history -============= - -Values printed by the `print' command are saved in the GDB "value -history". This allows you to refer to them in other expressions. -Values are kept until the symbol table is re-read or discarded (for -example with the `file' or `symbol-file' commands). When the symbol -table changes, the value history is discarded, since the values may -contain pointers back to the types defined in the symbol table. - - The values printed are given "history numbers" by which you can -refer to them. These are successive integers starting with one. -`print' shows you the history number assigned to a value by printing -`$NUM = ' before the value; here NUM is the history number. - - To refer to any previous value, use `$' followed by the value's -history number. The way `print' labels its output is designed to -remind you of this. Just `$' refers to the most recent value in the -history, and `$$' refers to the value before that. `$$N' refers to the -Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is -equivalent to `$$', and `$$0' is equivalent to `$'. - - For example, suppose you have just printed a pointer to a structure -and want to see the contents of the structure. It suffices to type - - p *$ - - If you have a chain of structures where the component `next' points -to the next one, you can print the contents of the next one with this: - - p *$.next - -You can print successive links in the chain by repeating this -command--which you can do by just typing <RET>. - - Note that the history records values, not expressions. If the value -of `x' is 4 and you type these commands: - - print x - set x=5 - -then the value recorded in the value history by the `print' command -remains 4 even though the value of `x' has changed. - -`show values' - Print the last ten values in the value history, with their item - numbers. This is like `p $$9' repeated ten times, except that - `show values' does not change the history. - -`show values N' - Print ten history values centered on history item number N. - -`show values +' - Print ten history values just after the values last printed. If - no more values are available, `show values +' produces no display. - - Pressing <RET> to repeat `show values N' has exactly the same effect -as `show values +'. - - -File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data - -Convenience variables -===================== - -GDB provides "convenience variables" that you can use within GDB to -hold on to a value and refer to it later. These variables exist -entirely within GDB; they are not part of your program, and setting a -convenience variable has no direct effect on further execution of your -program. That is why you can use them freely. - - Convenience variables are prefixed with `$'. Any name preceded by -`$' can be used for a convenience variable, unless it is one of the -predefined machine-specific register names (*note Registers: -Registers.). (Value history references, in contrast, are _numbers_ -preceded by `$'. *Note Value history: Value History.) - - You can save a value in a convenience variable with an assignment -expression, just as you would set a variable in your program. For -example: - - set $foo = *object_ptr - -would save in `$foo' the value contained in the object pointed to by -`object_ptr'. - - Using a convenience variable for the first time creates it, but its -value is `void' until you assign a new value. You can alter the value -with another assignment at any time. - - Convenience variables have no fixed types. You can assign a -convenience variable any type of value, including structures and -arrays, even if that variable already has a value of a different type. -The convenience variable, when used as an expression, has the type of -its current value. - -`show convenience' - Print a list of convenience variables used so far, and their - values. Abbreviated `show conv'. - - One of the ways to use a convenience variable is as a counter to be -incremented or a pointer to be advanced. For example, to print a field -from successive elements of an array of structures: - - set $i = 0 - print bar[$i++]->contents - -Repeat that command by typing <RET>. - - Some convenience variables are created automatically by GDB and given -values likely to be useful. - -`$_' - The variable `$_' is automatically set by the `x' command to the - last address examined (*note Examining memory: Memory.). Other - commands which provide a default address for `x' to examine also - set `$_' to that address; these commands include `info line' and - `info breakpoint'. The type of `$_' is `void *' except when set - by the `x' command, in which case it is a pointer to the type of - `$__'. - -`$__' - The variable `$__' is automatically set by the `x' command to the - value found in the last address examined. Its type is chosen to - match the format in which the data was printed. - -`$_exitcode' - The variable `$_exitcode' is automatically set to the exit code - when the program being debugged terminates. - - On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, GDB searches for a user or system name -first, before it searches for a convenience variable. - - -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 - and vector registers (in the selected stack frame). - -`info all-registers' - Print the names and values of all registers, including - floating-point and vector registers (in the selected stack frame). - -`info registers REGNAME ...' - Print the "relativized" value of each specified register REGNAME. - As discussed in detail below, register values are normally - relative to the selected stack frame. 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'; and on x86-based machines `$ps' is an alias -for the EFLAGS register. - - 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 -makes no difference. - - ---------- 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'; see -*Note Returning from a function: Returning. - - -File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data - -Floating point hardware -======================= - -Depending on the configuration, 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. Currently, `info float' is supported on the - ARM and x86 machines. - - -File: gdb.info, Node: Vector Unit, Next: Auxiliary Vector, Prev: Floating Point Hardware, Up: Data - -Vector Unit -=========== - -Depending on the configuration, GDB may be able to give you more -information about the status of the vector unit. - -`info vector' - Display information about the vector unit. The exact contents and - layout vary depending on the hardware. - - -File: gdb.info, Node: Auxiliary Vector, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data - -Operating system auxiliary vector -================================= - -Some operating systems supply an "auxiliary vector" to programs at -startup. This is akin to the arguments and environment that you -specify for a program, but contains a system-dependent variety of -binary values that tell system libraries important details about the -hardware, operating system, and process. Each value's purpose is -identified by an integer tag; the meanings are well-known but -system-specific. Depending on the configuration and operating system -facilities, GDB may be able to show you this information. - -`info auxv' - Display the auxiliary vector of the inferior, which can be either a - live process or a core dump file. GDB prints each tag value - numerically, and also shows names and text descriptions for - recognized tags. Some values in the vector are numbers, some bit - masks, and some pointers to strings or other data. GDB displays - each value in the most appropriate form for a recognized tag, and - in hexadecimal for an unrecognized tag. - - -File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: Auxiliary Vector, Up: Data - -Memory region attributes -======================== - -"Memory region attributes" allow you to describe special handling -required by regions of your target's memory. GDB uses attributes to -determine whether to allow certain types of memory accesses; whether to -use specific width accesses; and whether to cache target memory. - - Defined memory regions can be individually enabled and disabled. -When a memory region is disabled, GDB uses the default attributes when -accessing memory in that region. Similarly, if no memory regions have -been defined, GDB uses the default attributes when accessing all memory. - - When a memory region is defined, it is given a number to identify it; -to enable, disable, or remove a memory region, you specify that number. - -`mem LOWER UPPER ATTRIBUTES...' - Define memory region bounded by LOWER and UPPER with attributes - ATTRIBUTES.... Note that UPPER == 0 is a special case: it is - treated as the the target's maximum memory address. (0xffff on 16 - bit targets, 0xffffffff on 32 bit targets, etc.) - -`delete mem NUMS...' - Remove memory regions NUMS.... - -`disable mem NUMS...' - Disable memory regions NUMS.... A disabled memory region is not - forgotten. It may be enabled again later. - -`enable mem NUMS...' - Enable memory regions NUMS.... - -`info mem' - Print a table of all defined memory regions, with the following - columns for each region. - - _Memory Region Number_ - - _Enabled or Disabled._ - Enabled memory regions are marked with `y'. Disabled memory - regions are marked with `n'. - - _Lo Address_ - The address defining the inclusive lower bound of the memory - region. - - _Hi Address_ - The address defining the exclusive upper bound of the memory - region. - - _Attributes_ - The list of attributes set for this memory region. - -Attributes ----------- - -Memory Access Mode -.................. - -The access mode attributes set whether GDB may make read or write -accesses to a memory region. - - While these attributes prevent GDB from performing invalid memory -accesses, they do nothing to prevent the target system, I/O DMA, etc. -from accessing memory. - -`ro' - Memory is read only. - -`wo' - Memory is write only. - -`rw' - Memory is read/write. This is the default. - -Memory Access Size -.................. - -The acccess size attributes tells GDB to use specific sized accesses in -the memory region. Often memory mapped device registers require -specific sized accesses. If no access size attribute is specified, GDB -may use accesses of any size. - -`8' - Use 8 bit memory accesses. - -`16' - Use 16 bit memory accesses. - -`32' - Use 32 bit memory accesses. - -`64' - Use 64 bit memory accesses. - -Data Cache -.......... - -The data cache attributes set whether GDB will cache target memory. -While this generally improves performance by reducing debug protocol -overhead, it can lead to incorrect results because GDB does not know -about volatile variables or memory mapped device registers. - -`cache' - Enable GDB to cache target memory. - -`nocache' - Disable GDB from caching target memory. This is the default. - - -File: gdb.info, Node: Dump/Restore Files, Next: Character Sets, Prev: Memory Region Attributes, Up: Data - -Copy between memory and a file -============================== - -You can use the commands `dump', `append', and `restore' to copy data -between target memory and a file. The `dump' and `append' commands -write data to a file, and the `restore' command reads data from a file -back into the inferior's memory. Files may be in binary, Motorola -S-record, Intel hex, or Tektronix Hex format; however, GDB can only -append to binary files. - -`dump [FORMAT] memory FILENAME START_ADDR END_ADDR' -`dump [FORMAT] value FILENAME EXPR' - Dump the contents of memory from START_ADDR to END_ADDR, or the - value of EXPR, to FILENAME in the given format. - - The FORMAT parameter may be any one of: - `binary' - Raw binary form. - - `ihex' - Intel hex format. - - `srec' - Motorola S-record format. - - `tekhex' - Tektronix Hex format. - - GDB uses the same definitions of these formats as the GNU binary - utilities, like `objdump' and `objcopy'. If FORMAT is omitted, - GDB dumps the data in raw binary form. - -`append [binary] memory FILENAME START_ADDR END_ADDR' -`append [binary] value FILENAME EXPR' - Append the contents of memory from START_ADDR to END_ADDR, or the - value of EXPR, to FILENAME, in raw binary form. (GDB can only - append data to files in raw binary form.) - -`restore FILENAME [binary] BIAS START END' - Restore the contents of file FILENAME into memory. The `restore' - command can automatically recognize any known BFD file format, - except for raw binary. To restore a raw binary file you must - specify the optional keyword `binary' after the filename. - - If BIAS is non-zero, its value will be added to the addresses - contained in the file. Binary files always start at address zero, - so they will be restored at address BIAS. Other bfd files have a - built-in location; they will be restored at offset BIAS from that - location. - - If START and/or END are non-zero, then only data between file - offset START and file offset END will be restored. These offsets - are relative to the addresses in the file, before the BIAS - argument is applied. - - - -File: gdb.info, Node: Character Sets, Prev: Dump/Restore Files, Up: Data - -Character Sets -============== - -If the program you are debugging uses a different character set to -represent characters and strings than the one GDB uses itself, GDB can -automatically translate between the character sets for you. The -character set GDB uses we call the "host character set"; the one the -inferior program uses we call the "target character set". - - For example, if you are running GDB on a GNU/Linux system, which -uses the ISO Latin 1 character set, but you are using GDB's remote -protocol (*note Remote Debugging: Remote.) to debug a program running -on an IBM mainframe, which uses the EBCDIC character set, then the host -character set is Latin-1, and the target character set is EBCDIC. If -you give GDB the command `set target-charset EBCDIC-US', then GDB -translates between EBCDIC and Latin 1 as you print character or string -values, or use character and string literals in expressions. - - GDB has no way to automatically recognize which character set the -inferior program uses; you must tell it, using the `set target-charset' -command, described below. - - Here are the commands for controlling GDB's character set support: - -`set target-charset CHARSET' - Set the current target character set to CHARSET. We list the - character set names GDB recognizes below, but if you type `set - target-charset' followed by <TAB><TAB>, GDB will list the target - character sets it supports. - -`set host-charset CHARSET' - Set the current host character set to CHARSET. - - By default, GDB uses a host character set appropriate to the - system it is running on; you can override that default using the - `set host-charset' command. - - GDB can only use certain character sets as its host character set. - We list the character set names GDB recognizes below, and - indicate which can be host character sets, but if you type `set - target-charset' followed by <TAB><TAB>, GDB will list the host - character sets it supports. - -`set charset CHARSET' - Set the current host and target character sets to CHARSET. As - above, if you type `set charset' followed by <TAB><TAB>, GDB will - list the name of the character sets that can be used for both host - and target. - -`show charset' - Show the names of the current host and target charsets. - -`show host-charset' - Show the name of the current host charset. - -`show target-charset' - Show the name of the current target charset. - - - GDB currently includes support for the following character sets: - -`ASCII' - Seven-bit U.S. ASCII. GDB can use this as its host character set. - -`ISO-8859-1' - The ISO Latin 1 character set. This extends ASCII with accented - characters needed for French, German, and Spanish. GDB can use - this as its host character set. - -`EBCDIC-US' -`IBM1047' - Variants of the EBCDIC character set, used on some of IBM's - mainframe operating systems. (GNU/Linux on the S/390 uses U.S. - ASCII.) GDB cannot use these as its host character set. - - - Note that these are all single-byte character sets. More work inside -GDB is needed to support multi-byte or variable-width character -encodings, like the UTF-8 and UCS-2 encodings of Unicode. - - Here is an example of GDB's character set support in action. Assume -that the following source code has been placed in the file -`charset-test.c': - - #include <stdio.h> - - char ascii_hello[] - = {72, 101, 108, 108, 111, 44, 32, 119, - 111, 114, 108, 100, 33, 10, 0}; - char ibm1047_hello[] - = {200, 133, 147, 147, 150, 107, 64, 166, - 150, 153, 147, 132, 90, 37, 0}; - - main () - { - printf ("Hello, world!\n"); - } - - In this program, `ascii_hello' and `ibm1047_hello' are arrays -containing the string `Hello, world!' followed by a newline, encoded in -the ASCII and IBM1047 character sets. - - We compile the program, and invoke the debugger on it: - - $ gcc -g charset-test.c -o charset-test - $ gdb -nw charset-test - GNU gdb 2001-12-19-cvs - Copyright 2001 Free Software Foundation, Inc. - ... - (gdb) - - We can use the `show charset' command to see what character sets GDB -is currently using to interpret and display characters and strings: - - (gdb) show charset - The current host and target character set is `ISO-8859-1'. - (gdb) - - For the sake of printing this manual, let's use ASCII as our initial -character set: - (gdb) set charset ASCII - (gdb) show charset - The current host and target character set is `ASCII'. - (gdb) - - Let's assume that ASCII is indeed the correct character set for our -host system -- in other words, let's assume that if GDB prints -characters using the ASCII character set, our terminal will display -them properly. Since our current target character set is also ASCII, -the contents of `ascii_hello' print legibly: - - (gdb) print ascii_hello - $1 = 0x401698 "Hello, world!\n" - (gdb) print ascii_hello[0] - $2 = 72 'H' - (gdb) - - GDB uses the target character set for character and string literals -you use in expressions: - - (gdb) print '+' - $3 = 43 '+' - (gdb) - - The ASCII character set uses the number 43 to encode the `+' -character. - - GDB relies on the user to tell it which character set the target -program uses. If we print `ibm1047_hello' while our target character -set is still ASCII, we get jibberish: - - (gdb) print ibm1047_hello - $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" - (gdb) print ibm1047_hello[0] - $5 = 200 '\310' - (gdb) - - If we invoke the `set target-charset' followed by <TAB><TAB>, GDB -tells us the character sets it supports: - - (gdb) set target-charset - ASCII EBCDIC-US IBM1047 ISO-8859-1 - (gdb) set target-charset - - We can select IBM1047 as our target character set, and examine the -program's strings again. Now the ASCII string is wrong, but GDB -translates the contents of `ibm1047_hello' from the target character -set, IBM1047, to the host character set, ASCII, and they display -correctly: - - (gdb) set target-charset IBM1047 - (gdb) show charset - The current host character set is `ASCII'. - The current target character set is `IBM1047'. - (gdb) print ascii_hello - $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" - (gdb) print ascii_hello[0] - $7 = 72 '\110' - (gdb) print ibm1047_hello - $8 = 0x4016a8 "Hello, world!\n" - (gdb) print ibm1047_hello[0] - $9 = 200 'H' - (gdb) - - As above, GDB uses the target character set for character and string -literals you use in expressions: - - (gdb) print '+' - $10 = 78 '+' - (gdb) - - The IBM1047 character set uses the number 78 to encode the `+' -character. - - -File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Data, Up: Top - -C Preprocessor Macros -********************* - -Some languages, such as C and C++, provide a way to define and invoke -"preprocessor macros" which expand into strings of tokens. GDB can -evaluate expressions containing macro invocations, show the result of -macro expansion, and show a macro's definition, including where it was -defined. - - You may need to compile your program specially to provide GDB with -information about preprocessor macros. Most compilers do not include -macros in their debugging information, even when you compile with the -`-g' flag. *Note Compilation::. - - A program may define a macro at one point, remove that definition -later, and then provide a different definition after that. Thus, at -different points in the program, a macro may have different -definitions, or have no definition at all. If there is a current stack -frame, GDB uses the macros in scope at that frame's source code line. -Otherwise, GDB uses the macros in scope at the current listing location; -see *Note List::. - - At the moment, GDB does not support the `##' token-splicing -operator, the `#' stringification operator, or variable-arity macros. - - Whenever GDB evaluates an expression, it always expands any macro -invocations present in the expression. GDB also provides the following -commands for working with macros explicitly. - -`macro expand EXPRESSION' -`macro exp EXPRESSION' - Show the results of expanding all preprocessor macro invocations in - EXPRESSION. Since GDB simply expands macros, but does not parse - the result, EXPRESSION need not be a valid expression; it can be - any string of tokens. - -`macro expand-once EXPRESSION' -`macro exp1 EXPRESSION' - (This command is not yet implemented.) Show the results of - expanding those preprocessor macro invocations that appear - explicitly in EXPRESSION. Macro invocations appearing in that - expansion are left unchanged. This command allows you to see the - effect of a particular macro more clearly, without being confused - by further expansions. Since GDB simply expands macros, but does - not parse the result, EXPRESSION need not be a valid expression; it - can be any string of tokens. - -`info macro MACRO' - Show the definition of the macro named MACRO, and describe the - source location where that definition was established. - -`macro define MACRO REPLACEMENT-LIST' -`macro define MACRO(ARGLIST) REPLACEMENT-LIST' - (This command is not yet implemented.) Introduce a definition for - a preprocessor macro named MACRO, invocations of which are replaced - by the tokens given in REPLACEMENT-LIST. The first form of this - command defines an "object-like" macro, which takes no arguments; - the second form defines a "function-like" macro, which takes the - arguments given in ARGLIST. - - A definition introduced by this command is in scope in every - expression evaluated in GDB, until it is removed with the `macro - undef' command, described below. The definition overrides all - definitions for MACRO present in the program being debugged, as - well as any previous user-supplied definition. - -`macro undef MACRO' - (This command is not yet implemented.) Remove any user-supplied - definition for the macro named MACRO. This command only affects - definitions provided with the `macro define' command, described - above; it cannot remove definitions present in the program being - debugged. - - - Here is a transcript showing the above commands in action. First, we -show our source files: - - $ cat sample.c - #include <stdio.h> - #include "sample.h" - - #define M 42 - #define ADD(x) (M + x) - - main () - { - #define N 28 - printf ("Hello, world!\n"); - #undef N - printf ("We're so creative.\n"); - #define N 1729 - printf ("Goodbye, world!\n"); - } - $ cat sample.h - #define Q < - $ - - Now, we compile the program using the GNU C compiler, GCC. We pass -the `-gdwarf-2' and `-g3' flags to ensure the compiler includes -information about preprocessor macros in the debugging information. - - $ gcc -gdwarf-2 -g3 sample.c -o sample - $ - - Now, we start GDB on our sample program: - - $ gdb -nw sample - GNU gdb 2002-05-06-cvs - Copyright 2002 Free Software Foundation, Inc. - GDB is free software, ... - (gdb) - - We can expand macros and examine their definitions, even when the -program is not running. GDB uses the current listing position to -decide which macro definitions are in scope: - - (gdb) list main - 3 - 4 #define M 42 - 5 #define ADD(x) (M + x) - 6 - 7 main () - 8 { - 9 #define N 28 - 10 printf ("Hello, world!\n"); - 11 #undef N - 12 printf ("We're so creative.\n"); - (gdb) info macro ADD - Defined at /home/jimb/gdb/macros/play/sample.c:5 - #define ADD(x) (M + x) - (gdb) info macro Q - Defined at /home/jimb/gdb/macros/play/sample.h:1 - included at /home/jimb/gdb/macros/play/sample.c:2 - #define Q < - (gdb) macro expand ADD(1) - expands to: (42 + 1) - (gdb) macro expand-once ADD(1) - expands to: once (M + 1) - (gdb) - - In the example above, note that `macro expand-once' expands only the -macro invocation explicit in the original text -- the invocation of -`ADD' -- but does not expand the invocation of the macro `M', which was -introduced by `ADD'. - - Once the program is running, GDB uses the macro definitions in force -at the source line of the current stack frame: - - (gdb) break main - Breakpoint 1 at 0x8048370: file sample.c, line 10. - (gdb) run - Starting program: /home/jimb/gdb/macros/play/sample - - Breakpoint 1, main () at sample.c:10 - 10 printf ("Hello, world!\n"); - (gdb) - - At line 10, the definition of the macro `N' at line 9 is in force: - - (gdb) info macro N - Defined at /home/jimb/gdb/macros/play/sample.c:9 - #define N 28 - (gdb) macro expand N Q M - expands to: 28 < 42 - (gdb) print N Q M - $1 = 1 - (gdb) - - As we step over directives that remove `N''s definition, and then -give it a new definition, GDB finds the definition (or lack thereof) in -force at each point: - - (gdb) next - Hello, world! - 12 printf ("We're so creative.\n"); - (gdb) info macro N - The symbol `N' has no definition as a C/C++ preprocessor macro - at /home/jimb/gdb/macros/play/sample.c:12 - (gdb) next - We're so creative. - 14 printf ("Goodbye, world!\n"); - (gdb) info macro N - Defined at /home/jimb/gdb/macros/play/sample.c:13 - #define N 1729 - (gdb) macro expand N Q M - expands to: 1729 < 42 - (gdb) print N Q M - $2 = 0 - (gdb) - - -File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top - -Tracepoints -*********** - -In some applications, it is not feasible for the debugger to interrupt -the program's execution long enough for the developer to learn anything -helpful about its behavior. If the program's correctness depends on -its real-time behavior, delays introduced by a debugger might cause the -program to change its behavior drastically, or perhaps fail, even when -the code itself is correct. It is useful to be able to observe the -program's behavior without interrupting it. - - Using GDB's `trace' and `collect' commands, you can specify -locations in the program, called "tracepoints", and arbitrary -expressions to evaluate when those tracepoints are reached. Later, -using the `tfind' command, you can examine the values those expressions -had when the program hit the tracepoints. The expressions may also -denote objects in memory--structures or arrays, for example--whose -values GDB should record; while visiting a particular tracepoint, you -may inspect those objects as if they were in memory at that moment. -However, because GDB records these values without interacting with you, -it can do so quickly and unobtrusively, hopefully not disturbing the -program's behavior. - - The tracepoint facility is currently available only for remote -targets. *Note Targets::. In addition, your remote target must know -how to collect trace data. This functionality is implemented in the -remote stub; however, none of the stubs distributed with GDB support -tracepoints as of this writing. - - This chapter describes the tracepoint commands and features. - -* Menu: - -* Set Tracepoints:: -* Analyze Collected Data:: -* Tracepoint Variables:: - - -File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints - -Commands to Set Tracepoints -=========================== - -Before running such a "trace experiment", an arbitrary number of -tracepoints can be set. Like a breakpoint (*note Set Breaks::), a -tracepoint has a number assigned to it by GDB. Like with breakpoints, -tracepoint numbers are successive integers starting from one. Many of -the commands associated with tracepoints take the tracepoint number as -their argument, to identify which tracepoint to work on. - - For each tracepoint, you can specify, in advance, some arbitrary set -of data that you want the target to collect in the trace buffer when it -hits that tracepoint. The collected data can include registers, local -variables, or global data. Later, you can use GDB commands to examine -the values these data had at the time the tracepoint was hit. - - This section describes commands to set tracepoints and associated -conditions and actions. - -* Menu: - -* Create and Delete Tracepoints:: -* Enable and Disable Tracepoints:: -* Tracepoint Passcounts:: -* Tracepoint Actions:: -* Listing Tracepoints:: -* Starting and Stopping Trace Experiment:: - - -File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints - -Create and Delete Tracepoints ------------------------------ - -`trace' - The `trace' command is very similar to the `break' command. Its - argument can be a source line, a function name, or an address in - the target program. *Note Set Breaks::. The `trace' command - defines a tracepoint, which is a point in the target program where - the debugger will briefly stop, collect some data, and then allow - the program to continue. Setting a tracepoint or changing its - commands doesn't take effect until the next `tstart' command; - thus, you cannot change the tracepoint attributes once a trace - experiment is running. - - Here are some examples of using the `trace' command: - - (gdb) trace foo.c:121 // a source file and line number - - (gdb) trace +2 // 2 lines forward - - (gdb) trace my_function // first source line of function - - (gdb) trace *my_function // EXACT start address of function - - (gdb) trace *0x2117c4 // an address - - You can abbreviate `trace' as `tr'. - - The convenience variable `$tpnum' records the tracepoint number of - the most recently set tracepoint. - -`delete tracepoint [NUM]' - Permanently delete one or more tracepoints. With no argument, the - default is to delete all tracepoints. - - Examples: - - (gdb) delete trace 1 2 3 // remove three tracepoints - - (gdb) delete trace // remove all tracepoints - - You can abbreviate this command as `del tr'. - - -File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints - -Enable and Disable Tracepoints ------------------------------- - -`disable tracepoint [NUM]' - Disable tracepoint NUM, or all tracepoints if no argument NUM is - given. A disabled tracepoint will have no effect during the next - trace experiment, but it is not forgotten. You can re-enable a - disabled tracepoint using the `enable tracepoint' command. - -`enable tracepoint [NUM]' - Enable tracepoint NUM, or all tracepoints. The enabled - tracepoints will become effective the next time a trace experiment - is run. - - -File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Actions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints - -Tracepoint Passcounts ---------------------- - -`passcount [N [NUM]]' - Set the "passcount" of a tracepoint. The passcount is a way to - automatically stop a trace experiment. If a tracepoint's - passcount is N, then the trace experiment will be automatically - stopped on the N'th time that tracepoint is hit. If the - tracepoint number NUM is not specified, the `passcount' command - sets the passcount of the most recently defined tracepoint. If no - passcount is given, the trace experiment will run until stopped - explicitly by the user. - - Examples: - - (gdb) passcount 5 2 // Stop on the 5th execution of - `// tracepoint 2' - - (gdb) passcount 12 // Stop on the 12th execution of the - `// most recently defined tracepoint.' - (gdb) trace foo - (gdb) pass 3 - (gdb) trace bar - (gdb) pass 2 - (gdb) trace baz - (gdb) pass 1 // Stop tracing when foo has been - `// executed 3 times OR when bar has' - `// been executed 2 times' - `// OR when baz has been executed 1 time.' - - - -File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Tracepoint Passcounts, Up: Set Tracepoints - -Tracepoint Action Lists ------------------------ - -`actions [NUM]' - This command will prompt for a list of actions to be taken when the - tracepoint is hit. If the tracepoint number NUM is not specified, - this command sets the actions for the one that was most recently - defined (so that you can define a tracepoint and then say - `actions' without bothering about its number). You specify the - actions themselves on the following lines, one action at a time, - and terminate the actions list with a line containing just `end'. - So far, the only defined actions are `collect' and - `while-stepping'. - - To remove all actions from a tracepoint, type `actions NUM' and - follow it immediately with `end'. - - (gdb) collect DATA // collect some data - - (gdb) while-stepping 5 // single-step 5 times, collect data - - (gdb) end // signals the end of actions. - - In the following example, the action list begins with `collect' - commands indicating the things to be collected when the tracepoint - is hit. Then, in order to single-step and collect additional data - following the tracepoint, a `while-stepping' command is used, - followed by the list of things to be collected while stepping. The - `while-stepping' command is terminated by its own separate `end' - command. Lastly, the action list is terminated by an `end' - command. - - (gdb) trace foo - (gdb) actions - Enter actions for tracepoint 1, one per line: - > collect bar,baz - > collect $regs - > while-stepping 12 - > collect $fp, $sp - > end - end - -`collect EXPR1, EXPR2, ...' - Collect values of the given expressions when the tracepoint is hit. - This command accepts a comma-separated list of any valid - expressions. In addition to global, static, or local variables, - the following special arguments are supported: - - `$regs' - collect all registers - - `$args' - collect all function arguments - - `$locals' - collect all local variables. - - You can give several consecutive `collect' commands, each one with - a single argument, or one `collect' command with several arguments - separated by commas: the effect is the same. - - The command `info scope' (*note info scope: Symbols.) is - particularly useful for figuring out what data to collect. - -`while-stepping N' - Perform N single-step traces after the tracepoint, collecting new - data at each step. The `while-stepping' command is followed by - the list of what to collect while stepping (followed by its own - `end' command): - - > while-stepping 12 - > collect $regs, myglobal - > end - > - - You may abbreviate `while-stepping' as `ws' or `stepping'. - - -File: gdb.info, Node: Listing Tracepoints, Next: Starting and Stopping Trace Experiment, Prev: Tracepoint Actions, Up: Set Tracepoints - -Listing Tracepoints -------------------- - -`info tracepoints [NUM]' - Display information about the tracepoint NUM. If you don't specify - a tracepoint number, displays information about all the tracepoints - defined so far. For each tracepoint, the following information is - shown: - - * its number - - * whether it is enabled or disabled - - * its address - - * its passcount as given by the `passcount N' command - - * its step count as given by the `while-stepping N' command - - * where in the source files is the tracepoint set - - * its action list as given by the `actions' command - - (gdb) info trace - Num Enb Address PassC StepC What - 1 y 0x002117c4 0 0 <gdb_asm> - 2 y 0x0020dc64 0 0 in g_test at g_test.c:1375 - 3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41 - (gdb) - - This command can be abbreviated `info tp'. - - -File: gdb.info, Node: Starting and Stopping Trace Experiment, Prev: Listing Tracepoints, Up: Set Tracepoints - -Starting and Stopping Trace Experiment --------------------------------------- - -`tstart' - This command takes no arguments. It starts the trace experiment, - and begins collecting data. This has the side effect of - discarding all the data collected in the trace buffer during the - previous trace experiment. - -`tstop' - This command takes no arguments. It ends the trace experiment, and - stops collecting data. - - *Note:* a trace experiment and data collection may stop - automatically if any tracepoint's passcount is reached (*note - Tracepoint Passcounts::), or if the trace buffer becomes full. - -`tstatus' - This command displays the status of the current trace data - collection. - - Here is an example of the commands we described so far: - - (gdb) trace gdb_c_test - (gdb) actions - Enter actions for tracepoint #1, one per line. - > collect $regs,$locals,$args - > while-stepping 11 - > collect $regs - > end - > end - (gdb) tstart - [time passes ...] - (gdb) tstop - - -File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints - -Using the collected data -======================== - -After the tracepoint experiment ends, you use GDB commands for -examining the trace data. The basic idea is that each tracepoint -collects a trace "snapshot" every time it is hit and another snapshot -every time it single-steps. All these snapshots are consecutively -numbered from zero and go into a buffer, and you can examine them -later. The way you examine them is to "focus" on a specific trace -snapshot. When the remote stub is focused on a trace snapshot, it will -respond to all GDB requests for memory and registers by reading from -the buffer which belongs to that snapshot, rather than from _real_ -memory or registers of the program being debugged. This means that -*all* GDB commands (`print', `info registers', `backtrace', etc.) will -behave as if we were currently debugging the program state as it was -when the tracepoint occurred. Any requests for data that are not in -the buffer will fail. - -* Menu: - -* tfind:: How to select a trace snapshot -* tdump:: How to display all data for a snapshot -* save-tracepoints:: How to save tracepoints for a future run - - -File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data - -`tfind N' ---------- - -The basic command for selecting a trace snapshot from the buffer is -`tfind N', which finds trace snapshot number N, counting from zero. If -no argument N is given, the next snapshot is selected. - - Here are the various forms of using the `tfind' command. - -`tfind start' - Find the first snapshot in the buffer. This is a synonym for - `tfind 0' (since 0 is the number of the first snapshot). - -`tfind none' - Stop debugging trace snapshots, resume _live_ debugging. - -`tfind end' - Same as `tfind none'. - -`tfind' - No argument means find the next trace snapshot. - -`tfind -' - Find the previous trace snapshot before the current one. This - permits retracing earlier steps. - -`tfind tracepoint NUM' - Find the next snapshot associated with tracepoint NUM. Search - proceeds forward from the last examined trace snapshot. If no - argument NUM is given, it means find the next snapshot collected - for the same tracepoint as the current snapshot. - -`tfind pc ADDR' - Find the next snapshot associated with the value ADDR of the - program counter. Search proceeds forward from the last examined - trace snapshot. If no argument ADDR is given, it means find the - next snapshot with the same value of PC as the current snapshot. - -`tfind outside ADDR1, ADDR2' - Find the next snapshot whose PC is outside the given range of - addresses. - -`tfind range ADDR1, ADDR2' - Find the next snapshot whose PC is between ADDR1 and ADDR2. - -`tfind line [FILE:]N' - Find the next snapshot associated with the source line N. If the - optional argument FILE is given, refer to line N in that source - file. Search proceeds forward from the last examined trace - snapshot. If no argument N is given, it means find the next line - other than the one currently being examined; thus saying `tfind - line' repeatedly can appear to have the same effect as stepping - from line to line in a _live_ debugging session. - - The default arguments for the `tfind' commands are specifically -designed to make it easy to scan through the trace buffer. For -instance, `tfind' with no argument selects the next trace snapshot, and -`tfind -' with no argument selects the previous trace snapshot. So, by -giving one `tfind' command, and then simply hitting <RET> repeatedly -you can examine all the trace snapshots in order. Or, by saying `tfind --' and then hitting <RET> repeatedly you can examine the snapshots in -reverse order. The `tfind line' command with no argument selects the -snapshot for the next source line executed. The `tfind pc' command with -no argument selects the next snapshot with the same program counter -(PC) as the current frame. The `tfind tracepoint' command with no -argument selects the next trace snapshot collected by the same -tracepoint as the current one. - - In addition to letting you scan through the trace buffer manually, -these commands make it easy to construct GDB scripts that scan through -the trace buffer and print out whatever collected data you are -interested in. Thus, if we want to examine the PC, FP, and SP -registers from each trace frame in the buffer, we can say this: - - (gdb) tfind start - (gdb) while ($trace_frame != -1) - > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ - $trace_frame, $pc, $sp, $fp - > tfind - > end - - Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 - Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 - Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 - Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 - Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 - Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 - Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 - Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 - Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 - Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 - Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 - - Or, if we want to examine the variable `X' at each source line in -the buffer: - - (gdb) tfind start - (gdb) while ($trace_frame != -1) - > printf "Frame %d, X == %d\n", $trace_frame, X - > tfind line - > end - - Frame 0, X = 1 - Frame 7, X = 2 - Frame 13, X = 255 - - -File: gdb.info, Node: tdump, Next: save-tracepoints, Prev: tfind, Up: Analyze Collected Data - -`tdump' -------- - -This command takes no arguments. It prints all the data collected at -the current trace snapshot. - - (gdb) trace 444 - (gdb) actions - Enter actions for tracepoint #2, one per line: - > collect $regs, $locals, $args, gdb_long_test - > end - - (gdb) tstart - - (gdb) tfind line 444 - #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) - at gdb_test.c:444 - 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) - - (gdb) tdump - Data collected at tracepoint 2, trace frame 1: - d0 0xc4aa0085 -995491707 - d1 0x18 24 - d2 0x80 128 - d3 0x33 51 - d4 0x71aea3d 119204413 - d5 0x22 34 - d6 0xe0 224 - d7 0x380035 3670069 - a0 0x19e24a 1696330 - a1 0x3000668 50333288 - a2 0x100 256 - a3 0x322000 3284992 - a4 0x3000698 50333336 - a5 0x1ad3cc 1758156 - fp 0x30bf3c 0x30bf3c - sp 0x30bf34 0x30bf34 - ps 0x0 0 - pc 0x20b2c8 0x20b2c8 - fpcontrol 0x0 0 - fpstatus 0x0 0 - fpiaddr 0x0 0 - p = 0x20e5b4 "gdb-test" - p1 = (void *) 0x11 - p2 = (void *) 0x22 - p3 = (void *) 0x33 - p4 = (void *) 0x44 - p5 = (void *) 0x55 - p6 = (void *) 0x66 - gdb_long_test = 17 '\021' - - (gdb) - - -File: gdb.info, Node: save-tracepoints, Prev: tdump, Up: Analyze Collected Data - -`save-tracepoints FILENAME' ---------------------------- - -This command saves all current tracepoint definitions together with -their actions and passcounts, into a file `FILENAME' suitable for use -in a later debugging session. To read the saved tracepoint -definitions, use the `source' command (*note Command Files::). - - -File: gdb.info, Node: Tracepoint Variables, Prev: Analyze Collected Data, Up: Tracepoints - -Convenience Variables for Tracepoints -===================================== - -`(int) $trace_frame' - The current trace snapshot (a.k.a. "frame") number, or -1 if no - snapshot is selected. - -`(int) $tracepoint' - The tracepoint for the current trace snapshot. - -`(int) $trace_line' - The line number for the current trace snapshot. - -`(char []) $trace_file' - The source file for the current trace snapshot. - -`(char []) $trace_func' - The name of the function containing `$tracepoint'. - - Note: `$trace_file' is not suitable for use in `printf', use -`output' instead. - - Here's a simple example of using these convenience variables for -stepping through all the trace snapshots and printing some of their -data. - - (gdb) tfind start - - (gdb) while $trace_frame != -1 - > output $trace_file - > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint - > tfind - > end - - -File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top - -Debugging Programs That Use Overlays -************************************ - -If your program is too large to fit completely in your target system's -memory, you can sometimes use "overlays" to work around this problem. -GDB provides some support for debugging programs that use overlays. - -* Menu: - -* How Overlays Work:: A general explanation of overlays. -* Overlay Commands:: Managing overlays in GDB. -* Automatic Overlay Debugging:: GDB can find out which overlays are - mapped by asking the inferior. -* Overlay Sample Program:: A sample program using overlays. - - -File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays - -How Overlays Work -================= - -Suppose you have a computer whose instruction address space is only 64 -kilobytes long, but which has much more memory which can be accessed by -other means: special instructions, segment registers, or memory -management hardware, for example. Suppose further that you want to -adapt a program which is larger than 64 kilobytes to run on this system. - - One solution is to identify modules of your program which are -relatively independent, and need not call each other directly; call -these modules "overlays". Separate the overlays from the main program, -and place their machine code in the larger memory. Place your main -program in instruction memory, but leave at least enough space there to -hold the largest overlay as well. - - Now, to call a function located in an overlay, you must first copy -that overlay's machine code from the large memory into the space set -aside for it in the instruction memory, and then jump to its entry point -there. - - Data Instruction Larger - Address Space Address Space Address Space - +-----------+ +-----------+ +-----------+ - | | | | | | - +-----------+ +-----------+ +-----------+<-- overlay 1 - | program | | main | .----| overlay 1 | load address - | variables | | program | | +-----------+ - | and heap | | | | | | - +-----------+ | | | +-----------+<-- overlay 2 - | | +-----------+ | | | load address - +-----------+ | | | .-| overlay 2 | - | | | | | | - mapped --->+-----------+ | | +-----------+ - address | | | | | | - | overlay | <-' | | | - | area | <---' +-----------+<-- overlay 3 - | | <---. | | load address - +-----------+ `--| overlay 3 | - | | | | - +-----------+ | | - +-----------+ - | | - +-----------+ - - A code overlay - - The diagram (*note A code overlay::) shows a system with separate -data and instruction address spaces. To map an overlay, the program -copies its code from the larger address space to the instruction -address space. Since the overlays shown here all use the same mapped -address, only one may be mapped at a time. For a system with a single -address space for data and instructions, the diagram would be similar, -except that the program variables and heap would share an address space -with the main program and the overlay area. - - An overlay loaded into instruction memory and ready for use is -called a "mapped" overlay; its "mapped address" is its address in the -instruction memory. An overlay not present (or only partially present) -in instruction memory is called "unmapped"; its "load address" is its -address in the larger memory. The mapped address is also called the -"virtual memory address", or "VMA"; the load address is also called the -"load memory address", or "LMA". - - Unfortunately, overlays are not a completely transparent way to -adapt a program to limited instruction memory. They introduce a new -set of global constraints you must keep in mind as you design your -program: - - * Before calling or returning to a function in an overlay, your - program must make sure that overlay is actually mapped. - Otherwise, the call or return will transfer control to the right - address, but in the wrong overlay, and your program will probably - crash. - - * If the process of mapping an overlay is expensive on your system, - you will need to choose your overlays carefully to minimize their - effect on your program's performance. - - * The executable file you load onto your system must contain each - overlay's instructions, appearing at the overlay's load address, - not its mapped address. However, each overlay's instructions must - be relocated and its symbols defined as if the overlay were at its - mapped address. You can use GNU linker scripts to specify - different load and relocation addresses for pieces of your - program; see *Note Overlay Description: (ld.info)Overlay - Description. - - * The procedure for loading executable files onto your system must - be able to load their contents into the larger address space as - well as the instruction and data spaces. - - - The overlay system described above is rather simple, and could be -improved in many ways: - - * If your system has suitable bank switch registers or memory - management hardware, you could use those facilities to make an - overlay's load area contents simply appear at their mapped address - in instruction space. This would probably be faster than copying - the overlay to its mapped area in the usual way. - - * If your overlays are small enough, you could set aside more than - one overlay area, and have more than one overlay mapped at a time. - - * You can use overlays to manage data, as well as instructions. In - general, data overlays are even less transparent to your design - than code overlays: whereas code overlays only require care when - you call or return to functions, data overlays require care every - time you access the data. Also, if you change the contents of a - data overlay, you must copy its contents back out to its load - address before you can copy a different data overlay into the same - mapped area. - - - -File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays - -Overlay Commands -================ - -To use GDB's overlay support, each overlay in your program must -correspond to a separate section of the executable file. The section's -virtual memory address and load memory address must be the overlay's -mapped and load addresses. Identifying overlays with sections allows -GDB to determine the appropriate address of a function or variable, -depending on whether the overlay is mapped or not. - - GDB's overlay commands all start with the word `overlay'; you can -abbreviate this as `ov' or `ovly'. The commands are: - -`overlay off' - Disable GDB's overlay support. When overlay support is disabled, - GDB assumes that all functions and variables are always present at - their mapped addresses. By default, GDB's overlay support is - disabled. - -`overlay manual' - Enable "manual" overlay debugging. In this mode, GDB relies on - you to tell it which overlays are mapped, and which are not, using - the `overlay map-overlay' and `overlay unmap-overlay' commands - described below. - -`overlay map-overlay OVERLAY' -`overlay map OVERLAY' - Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of - the object file section containing the overlay. When an overlay - is mapped, GDB assumes it can find the overlay's functions and - variables at their mapped addresses. GDB assumes that any other - overlays whose mapped ranges overlap that of OVERLAY are now - unmapped. - -`overlay unmap-overlay OVERLAY' -`overlay unmap OVERLAY' - Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the - name of the object file section containing the overlay. When an - overlay is unmapped, GDB assumes it can find the overlay's - functions and variables at their load addresses. - -`overlay auto' - Enable "automatic" overlay debugging. In this mode, GDB consults - a data structure the overlay manager maintains in the inferior to - see which overlays are mapped. For details, see *Note Automatic - Overlay Debugging::. - -`overlay load-target' -`overlay load' - Re-read the overlay table from the inferior. Normally, GDB - re-reads the table GDB automatically each time the inferior stops, - so this command should only be necessary if you have changed the - overlay mapping yourself using GDB. This command is only useful - when using automatic overlay debugging. - -`overlay list-overlays' -`overlay list' - Display a list of the overlays currently mapped, along with their - mapped addresses, load addresses, and sizes. - - - Normally, when GDB prints a code address, it includes the name of -the function the address falls in: - - (gdb) print main - $3 = {int ()} 0x11a0 <main> - -When overlay debugging is enabled, GDB recognizes code in unmapped -overlays, and prints the names of unmapped functions with asterisks -around them. For example, if `foo' is a function in an unmapped -overlay, GDB prints it this way: - - (gdb) overlay list - No sections are mapped. - (gdb) print foo - $5 = {int (int)} 0x100000 <*foo*> - -When `foo''s overlay is mapped, GDB prints the function's name normally: - - (gdb) overlay list - Section .ov.foo.text, loaded at 0x100000 - 0x100034, - mapped at 0x1016 - 0x104a - (gdb) print foo - $6 = {int (int)} 0x1016 <foo> - - When overlay debugging is enabled, GDB can find the correct address -for functions and variables in an overlay, whether or not the overlay -is mapped. This allows most GDB commands, like `break' and -`disassemble', to work normally, even on unmapped code. However, GDB's -breakpoint support has some limitations: - - * You can set breakpoints in functions in unmapped overlays, as long - as GDB can write to the overlay at its load address. - - * GDB can not set hardware or simulator-based breakpoints in - unmapped overlays. However, if you set a breakpoint at the end of - your overlay manager (and tell GDB which overlays are now mapped, - if you are using manual overlay management), GDB will re-set its - breakpoints properly. - - -File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays - -Automatic Overlay Debugging -=========================== - -GDB can automatically track which overlays are mapped and which are -not, given some simple co-operation from the overlay manager in the -inferior. If you enable automatic overlay debugging with the `overlay -auto' command (*note Overlay Commands::), GDB looks in the inferior's -memory for certain variables describing the current state of the -overlays. - - Here are the variables your overlay manager must define to support -GDB's automatic overlay debugging: - -`_ovly_table': - This variable must be an array of the following structures: - - struct - { - /* The overlay's mapped address. */ - unsigned long vma; - - /* The size of the overlay, in bytes. */ - unsigned long size; - - /* The overlay's load address. */ - unsigned long lma; - - /* Non-zero if the overlay is currently mapped; - zero otherwise. */ - unsigned long mapped; - } - -`_novlys': - This variable must be a four-byte signed integer, holding the total - number of elements in `_ovly_table'. - - - To decide whether a particular overlay is mapped or not, GDB looks -for an entry in `_ovly_table' whose `vma' and `lma' members equal the -VMA and LMA of the overlay's section in the executable file. When GDB -finds a matching entry, it consults the entry's `mapped' member to -determine whether the overlay is currently mapped. - - In addition, your overlay manager may define a function called -`_ovly_debug_event'. If this function is defined, GDB will silently -set a breakpoint there. If the overlay manager then calls this -function whenever it has changed the overlay table, this will enable -GDB to accurately keep track of which overlays are in program memory, -and update any breakpoints that may be set in overlays. This will -allow breakpoints to work even if the overlays are kept in ROM or other -non-writable memory while they are not being executed. - - -File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays - -Overlay Sample Program -====================== - -When linking a program which uses overlays, you must place the overlays -at their load addresses, while relocating them to run at their mapped -addresses. To do this, you must write a linker script (*note Overlay -Description: (ld.info)Overlay Description.). Unfortunately, since -linker scripts are specific to a particular host system, target -architecture, and target memory layout, this manual cannot provide -portable sample code demonstrating GDB's overlay support. - - However, the GDB source distribution does contain an overlaid -program, with linker scripts for a few systems, as part of its test -suite. The program consists of the following files from -`gdb/testsuite/gdb.base': - -`overlays.c' - The main program file. - -`ovlymgr.c' - A simple overlay manager, used by `overlays.c'. - -`foo.c' -`bar.c' -`baz.c' -`grbx.c' - Overlay modules, loaded and used by `overlays.c'. - -`d10v.ld' -`m32r.ld' - Linker scripts for linking the test program on the `d10v-elf' and - `m32r-elf' targets. - - You can build the test program using the `d10v-elf' GCC -cross-compiler like this: - - $ d10v-elf-gcc -g -c overlays.c - $ d10v-elf-gcc -g -c ovlymgr.c - $ d10v-elf-gcc -g -c foo.c - $ d10v-elf-gcc -g -c bar.c - $ d10v-elf-gcc -g -c baz.c - $ d10v-elf-gcc -g -c grbx.c - $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ - baz.o grbx.o -Wl,-Td10v.ld -o overlays - - The build process is identical for any other architecture, except -that you must substitute the appropriate compiler and linker script for -the target system for `d10v-elf-gcc' and `d10v.ld'. - - -File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, 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 appear as `0x1ae', while in -Modula-2 they appear as `1AEH'. - - Language-specific information is built into GDB for some languages, -allowing you to express operations like the above in your program's -native language, and allowing GDB to output values in a manner -consistent with the syntax of your program's native language. The -language you use to build expressions is called the "working language". - -* Menu: - -* Setting:: Switching between source languages -* Show:: Displaying the language -* Checks:: Type and range checks -* Support:: Supported languages -* Unsupported languages:: Unsupported 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. The working language is used to -determine how expressions you type are interpreted, how values are -printed, etc. - - In addition to the working language, every source file that GDB -knows about has its own working language. For some object file -formats, the compiler might indicate which language a particular source -file is in. However, most of the time GDB infers the language from the -name of the file. The language of a source file controls whether C++ -names are demangled--this way `backtrace' can show each frame -appropriately for its own language. There is no way to set the -language of a source file from within GDB, but you can set the language -associated with a filename extension. *Note Displaying the language: -Show. - - This is most commonly a problem when you use a program, such as -`cfront' or `f2c', that generates C but is written in another language. -In that case, make the program use `#line' directives in its C output; -that way GDB will know the correct language of the source code of the -original program, and will display that source code, not the generated -C code. - -* Menu: - -* Filenames:: Filename extensions and languages. -* Manually:: Setting the working language manually -* Automatically:: Having GDB infer the source language - - -File: gdb.info, Node: Filenames, Next: Manually, Up: Setting - -List of filename extensions and languages ------------------------------------------ - -If a source file name ends in one of the following extensions, then GDB -infers that its language is the one indicated. - -`.c' - C source file - -`.C' -`.cc' -`.cp' -`.cpp' -`.cxx' -`.c++' - C++ source file - -`.m' - Objective-C source file - -`.f' -`.F' - Fortran source file - -`.mod' - Modula-2 source file - -`.s' -`.S' - Assembler source file. This actually behaves almost like C, but - GDB does not skip over function prologues when stepping. - - In addition, you may set the language associated with a filename -extension. *Note Displaying the language: Show. - - -File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, 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 working language. -That is, when your program stops in a frame (usually by encountering a -breakpoint), GDB sets the working language to the language recorded for -the function in that frame. If the language for a frame is unknown -(that is, if the function or block corresponding to the frame was -defined in a source file that does not have a recognized extension), -the current working language is not changed, and GDB issues a warning. - - This may not seem necessary for most programs, which are written -entirely in one source language. However, program modules and libraries -written in one source language can be used by a main program written in -a different source language. Using `set language auto' in this case -frees you from having to set the working language manually. - - -File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages - -Displaying the language -======================= - -The following commands help you find out which language is the working -language, and also what language source files were written in. - -`show language' - Display the current working language. This is the language you - can use with commands such as `print' to build and compute - expressions that may involve variables in your program. - -`info frame' - Display the source language for this frame. This language becomes - the working language if you use an identifier from this frame. - *Note Information about a frame: Frame Info, to identify the other - information listed here. - -`info source' - Display the source language of this source file. *Note Examining - the Symbol Table: Symbols, to identify the other information - listed here. - - In unusual circumstances, you may have source files with extensions -not in the standard list. You can then set the extension associated -with a language explicitly: - -`set extension-language .EXT LANGUAGE' - Set source files with extension .EXT to be assumed to be in the - source language LANGUAGE. - -`info extensions' - List all the filename extensions and the associated languages. - - -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 does 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 the 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 to 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 if you turn type checking off, there may be other reasons -related to type that prevent GDB from evaluating an expression. For -instance, GDB does not know how to add an `int' and a `struct foo'. -These particular type errors have nothing to do with the language in -use, and usually arise from expressions, 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 type checking 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 and - range checking is on, then a message is printed and evaluation of - the expression is aborted. - -`set check range warn' - Output messages when the GDB range checker detects a range error, - but attempt to evaluate the expression anyway. Evaluating the - expression may still be impossible for other reasons, such as - accessing memory that the process does not own (a typical example - from many Unix systems). - -`show range' - Show the current setting of the range checker, and whether or not - it is being set automatically by GDB. - - -File: gdb.info, Node: Support, Next: Unsupported languages, Prev: Checks, Up: Languages - -Supported languages -=================== - -GDB supports C, C++, Objective-C, Fortran, Java, assembly, and Modula-2. -Some GDB features may be used in expressions regardless of the language -you use: the GDB `@' and `::' operators, and the `{type}addr' construct -(*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 accepts, and what input and output formats should -look like for different languages. There are many good books written -on each of these languages; please look to these for a language -reference or tutorial. - -* Menu: - -* C:: C and C++ -* Objective-C:: Objective-C -* Modula-2:: Modula-2 - - -File: gdb.info, Node: C, Next: Objective-C, 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 those languages -together. - - The C++ debugging facilities are jointly implemented by the C++ -compiler and GDB. Therefore, to debug your C++ code effectively, you -must compile your C++ programs with a supported C++ compiler, such as -GNU `g++', or the HP ANSI C++ compiler (`aCC'). - - For best results when using GNU C++, use the DWARF 2 debugging -format; if it doesn't work on your system, try the stabs+ debugging -format. You can select those formats explicitly with the `g++' -command-line options `-gdwarf-2' and `-gstabs+'. *Note Options for -Debugging Your Program or GNU CC: (gcc.info)Debugging Options. - -* Menu: - -* C Operators:: C and C++ operators -* C Constants:: C and C++ constants -* C plus plus 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:: GDB 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'; `enum'; and, for C++, `bool'. - - * _Floating-point types_ include `float', `double', and `long - double' (if supported by the target platform). - - * _Pointer types_ include all types defined as `(TYPE *)'. - - * _Scalar types_ include all of the above. - - -The following operators are supported. They are listed here in order -of increasing precedence: - -`,' - The comma or sequencing operator. Expressions in a - comma-separated list are evaluated from left to right, with the - result of the entire expression being the last expression - evaluated. - -`=' - Assignment. The value of an assignment expression is the value - assigned. Defined on scalar types. - -`OP=' - Used in an expression of the form `A OP= B', and translated to - `A = A OP B'. `OP=' and `=' have the same precedence. OP is any - one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', - `/', `%'. - -`?:' - The ternary operator. `A ? B : C' can be thought of as: if A - then B else C. A should be of an integral type. - -`||' - Logical OR. Defined on integral types. - -`&&' - Logical AND. Defined on integral types. - -`|' - Bitwise OR. Defined on integral types. - -`^' - Bitwise exclusive-OR. Defined on integral types. - -`&' - Bitwise AND. Defined on integral types. - -`==, !=' - Equality and inequality. Defined on scalar types. The value of - these expressions is 0 for false and non-zero for true. - -`<, >, <=, >=' - Less than, greater than, less than or equal, greater than or equal. - Defined on scalar types. The value of these expressions is 0 for - false and non-zero for true. - -`<<, >>' - left shift, and right shift. Defined on integral types. - -`@' - The GDB "artificial array" operator (*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. - -`.*, ->*' - Dereferences of pointers to members. - -`[]' - Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence - as `->'. - -`()' - Function parameter list. Same precedence as `->'. - -`::' - C++ scope resolution operator. Defined on `struct', `union', and - `class' types. - -`::' - Doubled colons also represent the GDB scope operator (*note - Expressions: Expressions.). Same precedence as `::', above. - - If an operator is redefined in the user code, GDB usually attempts -to invoke the redefined version instead of using the operator's -predefined meaning. - -* Menu: - -* C Constants:: - - -File: gdb.info, Node: C Constants, Next: C plus plus 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. A floating-point constant may - also end with a letter `f' or `F', specifying that the constant - should be treated as being of the `float' (as opposed to the - default `double') type; or with a letter `l' or `L', which - specifies a `long double' constant. - - * Enumerated constants consist of enumerated identifiers, or their - integral equivalents. - - * Character constants are a single character surrounded by single - quotes (`''), or a number--the ordinal value of the corresponding - character (usually its ASCII value). Within quotes, the single - character may be represented by a letter or by "escape sequences", - which are of the form `\NNN', where NNN is the octal representation - of the character's ordinal value; or of the form `\X', where `X' - is a predefined special character--for example, `\n' for newline. - - * String constants are a sequence of character constants surrounded - by double quotes (`"'). Any valid character constant (as described - above) may appear. Double quotes within the string must be - preceded by a backslash, so for instance `"a\"b'c"' is a string of - five characters. - - * Pointer constants are an integral value. You can also write - pointers to constants using the C operator `&'. - - * Array constants are comma-separated lists surrounded by braces `{' - and `}'; for example, `{1,2,3}' is a three-element array of - integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and - `{&"hi", &"there", &"fred"}' is a three-element array of pointers. - -* Menu: - -* C plus plus expressions:: -* C Defaults:: -* C Checks:: - -* Debugging C:: - - -File: gdb.info, Node: C plus plus 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 and the proper debug format. Currently, GDB works best - when debugging C++ code that is compiled with GCC 2.95.3 or with - GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'. - DWARF 2 is preferred over stabs+. Most configurations of GCC emit - either DWARF 2 or stabs+ as their default debug format, so you - usually don't need to specify a debug format explicitly. Other - compilers and/or debug formats are likely to work badly or not at - all when using GDB to debug C++ code. - - 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 some restrictions. GDB does not - perform overload resolution involving user-defined type - conversions, calls to constructors, or instantiations of templates - that do not exist in the program. It also cannot handle ellipsis - argument lists or default arguments. - - It does perform integral conversions and promotions, floating-point - promotions, arithmetic conversions, pointer conversions, - conversions of class objects to base classes, and standard - conversions such as those of functions or arrays to pointers; it - requires an exact match on the number of function arguments. - - Overload resolution is always performed, unless you have specified - `set overload-resolution off'. *Note GDB features for C++: - Debugging C plus plus. - - You must specify `set overload-resolution off' in order to use an - explicit function signature to call an overloaded function, as in - p 'foo(char,int)'('x', 13) - - The GDB command-completion facility can simplify this; see *Note - Command completion: Completion. - - 4. GDB understands variables declared as C++ references; you can use - them in expressions just as you do in C++ source--they are - automatically dereferenced. - - In the parameter list shown when GDB displays a frame, the values - of reference variables are not displayed (unlike other variables); - this avoids clutter, since references are often used for large - structures. The _address_ of a reference variable is always - shown, unless you have specified `set print address off'. - - 5. GDB supports the C++ name resolution operator `::'--your - expressions can use it just as expressions in your program do. - Since one scope may be defined in another, you can use `::' - repeatedly if necessary, for example in an expression like - `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by - reference to source files, in both C and C++ debugging (*note - Program variables: Variables.). - - In addition, when used with HP's C++ compiler, GDB supports calling -virtual functions correctly, printing out virtual bases of objects, -calling functions in a base subobject, casting objects, and invoking -user-defined operators. - - -File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C plus plus 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 - -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. (The `vtbl' commands do not work - on programs compiled with the HP ANSI C++ compiler (`aCC').) - -`set overload-resolution on' - Enable overload resolution for C++ expression evaluation. The - default is on. For overloaded functions, GDB evaluates the - arguments and searches for a function whose signature matches the - argument types, using the standard C++ conversion rules (see *Note - C++ expressions: C plus plus expressions, for details). If it - cannot find a match, it emits a message. - -`set overload-resolution off' - Disable overload resolution for C++ expression evaluation. For - overloaded functions that are not class member functions, GDB - chooses the first function of the specified name that it finds in - the symbol table, whether or not its arguments are of the correct - type. For overloaded functions that are class member functions, - GDB searches for a function whose signature _exactly_ matches the - argument types. - -`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: Objective-C, Next: Modula-2, Prev: C, Up: Support - -Objective-C ------------ - -This section provides information about some commands and command -options that are useful for debugging Objective-C code. - -* Menu: - -* Method Names in Commands:: -* The Print Command with Objective-C:: - - -File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Prev: Objective-C, Up: Objective-C - -Method Names in Commands -........................ - -The following commands have been extended to accept Objective-C method -names as line specifications: - - * `clear' - - * `break' - - * `info line' - - * `jump' - - * `list' - - A fully qualified Objective-C method name is specified as - - -[CLASS METHODNAME] - - where the minus sign is used to indicate an instance method and a -plus sign (not shown) is used to indicate a class method. The class -name CLASS and method name METHODNAME are enclosed in brackets, similar -to the way messages are specified in Objective-C source code. For -example, to set a breakpoint at the `create' instance method of class -`Fruit' in the program currently being debugged, enter: - - break -[Fruit create] - - To list ten program lines around the `initialize' class method, -enter: - - list +[NSText initialize] - - In the current version of GDB, the plus or minus sign is required. -In future versions of GDB, the plus or minus sign will be optional, but -you can use it to narrow the search. It is also possible to specify -just a method name: - - break create - - You must specify the complete method name, including any colons. If -your program's source files contain more than one `create' method, -you'll be presented with a numbered list of classes that implement that -method. Indicate your choice by number, or type `0' to exit if none -apply. - - As another example, to clear a breakpoint established at the -`makeKeyAndOrderFront:' method of the `NSWindow' class, enter: - - clear -[NSWindow makeKeyAndOrderFront:] - - -File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C - -The Print Command With Objective-C -.................................. - -The print command has also been extended to accept methods. For -example: - - print -[OBJECT hash] - -will tell GDB to send the `hash' message to OBJECT and print the -result. Also, an additional command has been added, `print-object' or -`po' for short, which is meant to print the description of an object. -However, this command may only work with certain Objective-C libraries -that have a particular hook function, `_NSPrintForDebugger', defined. - - -File: gdb.info, Node: Modula-2, Prev: Objective-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, 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 or equal to, greater than or equal to on integral, - floating-point and enumerated types, or set inclusion on set - types. Same precedence as `<'. - -`=, <>, #' - Equality and two ways of expressing inequality, valid on scalar - types. Same precedence as `<'. In GDB scripts, only `<>' is - available for inequality, since `#' conflicts with the script - comment character. - -`IN' - Set membership. Defined on set types and the types of their - members. Same precedence as `<'. - -`OR' - Boolean disjunction. Defined on boolean types. - -`AND, &' - Boolean conjunction. Defined on boolean types. - -`@' - The GDB "artificial array" operator (*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 by one. Returns the new - value. - -`DEC(V,I)' - Decrements the value in the variable V by I. Returns the new - value. - -`EXCL(M,S)' - Removes the element M from the set S. Returns the new set. - -`FLOAT(I)' - Returns the floating point equivalent of the integer I. - -`HIGH(A)' - Returns the index of the last member of A. - -`INC(V)' - Increments the value in the variable V by one. Returns the new - value. - -`INC(V,I)' - Increments the value in the variable V by I. Returns the new - value. - -`INCL(M,S)' - Adds the element M to the set S if it is not already there. - Returns the new set. - -`MAX(T)' - Returns the maximum value of the type T. - -`MIN(T)' - Returns the minimum value of the type T. - -`ODD(I)' - Returns boolean TRUE if I is an odd number. - -`ORD(X)' - Returns the ordinal value of its argument. For example, the - ordinal value of a character is its ASCII value (on machines - supporting the ASCII character set). X must be of an ordered - type, which include integral, character and enumerated types. - -`SIZE(X)' - Returns the size of its argument. X can be a variable or a type. - -`TRUNC(R)' - Returns the integral part of R. - -`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. - diff --git a/contrib/gdb/gdb/doc/gdb.info-2 b/contrib/gdb/gdb/doc/gdb.info-2 deleted file mode 100644 index 4dcf4353b5b2..000000000000 --- a/contrib/gdb/gdb/doc/gdb.info-2 +++ /dev/null @@ -1,9133 +0,0 @@ -This is gdb.info, produced by makeinfo version 4.6 from ./gdb.texinfo. - -INFO-DIR-SECTION Software development -START-INFO-DIR-ENTRY -* Gdb: (gdb). The GNU debugger. -END-INFO-DIR-ENTRY - - This file documents the GNU debugger GDB. - - This is the Ninth Edition, of `Debugging with GDB: the GNU -Source-Level Debugger' for GDB Version 6.1.1. - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1998, -1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "Free Software" and "Free Software Needs Free -Documentation", with the Front-Cover Texts being "A GNU Manual," and -with the Back-Cover Texts as in (a) below. - - (a) The Free Software Foundation's Back-Cover Text is: "You have -freedom to copy and modify this GNU Manual, like GNU software. Copies -published by the Free Software Foundation raise funds for GNU -development." - - -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 -with any language, is not useful with Modula-2. Its intent is to aid -the debugging of "dynamic arrays", which cannot be created in Modula-2 -as they can in C or C++. However, because an address can be specified -by an integral constant, the construct `{TYPE}ADREXP' is still useful. - - In GDB scripts, the Modula-2 inequality operator `#' is interpreted -as the beginning of a comment. Use `<>' instead. - - -File: gdb.info, Node: Unsupported languages, Prev: Support, Up: Languages - -Unsupported languages -===================== - -In addition to the other fully-supported programming languages, GDB -also provides a pseudo-language, called `minimal'. It does not -represent a real programming language, but provides a set of -capabilities close to what the C or assembly languages provide. This -should allow most simple operations to be performed while debugging an -application that uses a language currently not supported by GDB. - - If the language is set to `auto', GDB will automatically select this -language if the current frame corresponds to an unsupported language. - - -File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top - -Examining the Symbol Table -************************** - -The commands described in this chapter 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. - -`info symbol ADDR' - Print the name of a symbol which is stored at the address ADDR. - If no symbol is stored exactly at ADDR, GDB prints the nearest - symbol and an offset from it: - - (gdb) info symbol 0x54320 - _initialize_vx + 396 in section .text - - This is the opposite of the `info address' command. You can use - it to find out the name of a variable or a function given its - address. - -`whatis EXPR' - Print the data type of expression EXPR. EXPR 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 EXPR' -`ptype' - Print a description of the type of expression EXPR. `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 names match 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 names include 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 scope ADDR' - List all the variables local to a particular scope. This command - accepts a location--a function name, a source line, or an address - preceded by a `*', and prints all the variables local to the scope - defined by that location. For example: - - (gdb) info scope command_line_handler - Scope for command_line_handler: - Symbol rl is an argument at stack/frame offset 8, length 4. - Symbol linebuffer is in static storage at address 0x150a18, length 4. - Symbol linelength is in static storage at address 0x150a1c, length 4. - Symbol p is a local variable in register $esi, length 4. - Symbol p1 is a local variable in register $ebx, length 4. - Symbol nline is a local variable in register $edx, length 4. - Symbol repeat is a local variable at frame offset -8, length 4. - - This command is especially useful for determining what data to - collect during a "trace experiment", see *Note collect: Tracepoint - Actions. - -`info source' - Show information about the current source file--that is, the - source file for the function containing the current point of - execution: - * the name of the source file, and the directory containing it, - - * the directory it was compiled in, - - * its length, in lines, - - * which programming language it is written in, - - * whether the executable includes debugging information for - that file, and if so, what format the information is in - (e.g., STABS, Dwarf 2, etc.), and - - * whether the debugging information includes information about - preprocessor macros. - -`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'. If a - function name contains characters that conflict with the regular - expression language (eg. `operator*()'), they may be quoted with - a backslash. - -`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. - -`info classes' -`info classes REGEXP' - Display all Objective-C classes in your program, or (with the - REGEXP argument) all those matching a particular regular - expression. - -`info selectors' -`info selectors REGEXP' - Display all Objective-C selectors in your program, or (with the - REGEXP argument) all those matching a particular regular - expression. - - 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 encountering object - files of the same name more than once. This is the default - state; if you are not running on a system that permits - automatic relinking of 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. - -`set opaque-type-resolution on' - Tell GDB to resolve opaque types. An opaque type is a type - declared as a pointer to a `struct', `class', or `union'--for - example, `struct MyType *'--that is used in one source file - although the full declaration of `struct MyType' is in another - source file. The default is on. - - A change in the setting of this subcommand will not take effect - until the next time symbols for a file are loaded. - -`set opaque-type-resolution off' - Tell GDB not to resolve opaque types. In this case, the type is - printed as follows: - {<no data fields>} - -`show opaque-type-resolution' - Show whether opaque types are resolved or not. - -`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'). - -`maint info symtabs [ REGEXP ]' -`maint info psymtabs [ REGEXP ]' - List the `struct symtab' or `struct partial_symtab' structures - whose names match REGEXP. If REGEXP is not given, list them all. - The output includes expressions which you can copy into a GDB - debugging this one to examine a particular structure in more - detail. For example: - - (gdb) maint info psymtabs dwarf2read - { objfile /home/gnu/build/gdb/gdb - ((struct objfile *) 0x82e69d0) - { psymtab /home/gnu/src/gdb/dwarf2read.c - ((struct partial_symtab *) 0x8474b10) - readin no - fullname (null) - text addresses 0x814d3c8 -- 0x8158074 - globals (* (struct partial_symbol **) 0x8507a08 @ 9) - statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) - dependencies (none) - } - } - (gdb) maint info symtabs - (gdb) - - We see that there is one partial symbol table whose filename - contains the string `dwarf2read', belonging to the `gdb' - executable; and we see that GDB has not read in any symtabs yet at - all. If we set a breakpoint on a function, that will cause GDB to - read the symtab for the compilation unit containing that function: - - (gdb) break dwarf2_psymtab_to_symtab - Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, - line 1574. - (gdb) maint info symtabs - { objfile /home/gnu/build/gdb/gdb - ((struct objfile *) 0x82e69d0) - { symtab /home/gnu/src/gdb/dwarf2read.c - ((struct symtab *) 0x86c1f38) - dirname (null) - fullname (null) - blockvector ((struct blockvector *) 0x86c1bd0) (primary) - debugformat DWARF 2 - } - } - (gdb) - - -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, 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 - - Because the `set' command has many subcommands that can conflict -with the names of program variables, it is a good idea to use the `set -variable' command instead of just `set'. For example, if your program -has a variable `g', you run into problems if you try to set a new value -with just `set g=4', because GDB has the command `set gnutarget', -abbreviated `set g': - - (gdb) whatis g - type = double - (gdb) p g - $1 = 1 - (gdb) set g=4 - (gdb) p g - $2 = 1 - (gdb) r - The program being debugged has been started already. - Start it from the beginning? (y or n) y - Starting program: /home/smith/cc_progs/a.out - "/home/smith/cc_progs/a.out": can't open to read symbols: - Invalid bfd target. - (gdb) show g - The current BFD target is "=4". - -The program variable `g' did not change, and you silently set the -`gnutarget' to an invalid value. In order to set the variable `g', use - - (gdb) set var g=4 - - 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. - - On many systems, 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. - - -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 -* Separate Debug Files:: Debugging information in separate files -* Symbol Errors:: Errors reading symbol files - - -File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files - -Commands to specify files -========================= - -You may want to specify executable and core dump file names. The usual -way to do this is at start-up time, using the arguments to GDB's -start-up commands (*note Getting In and Out of GDB: Invocation.). - - Occasionally it is necessary to change to a different file during a -GDB session. Or you may run GDB and forget to specify a file you want -to use. In these situations the GDB commands to specify new files are -useful. - -`file FILENAME' - Use FILENAME as the program to be debugged. It is read for its - symbols and for the contents of pure memory. It is also the - program executed when you use the `run' command. If you do not - specify a directory and the file is not found in the GDB working - directory, GDB uses the environment variable `PATH' as a list of - directories to search, just as the shell does when looking for a - program to run. You can change the value of this variable, for - both GDB and your program, using the `path' command. - - On systems with memory-mapped files, an auxiliary file named - `FILENAME.syms' may hold symbol table information for FILENAME. - If so, GDB maps in the symbol table from `FILENAME.syms', starting - up more quickly. See the descriptions of the file options - `-mapped' and `-readnow' (available on the command line, and with - the commands `file', `symbol-file', or `add-symbol-file', - described below), for more information. - -`file' - `file' with no argument makes GDB discard any information it has - on both executable file and the symbol table. - -`exec-file [ FILENAME ]' - Specify that the program to be run (but not the symbol table) is - found in FILENAME. GDB searches the environment variable `PATH' - if necessary to locate your program. Omitting FILENAME means to - discard information on the executable file. - -`symbol-file [ FILENAME ]' - Read symbol table information from file FILENAME. `PATH' is - searched when necessary. Use the `file' command to get both symbol - table and program to run from the same file. - - `symbol-file' with no argument clears out GDB information on your - program's symbol table. - - The `symbol-file' command causes GDB to forget the contents of its - convenience variables, the value history, and all breakpoints and - auto-display expressions. This is because they may contain - pointers to the internal data recording symbols and data types, - which are part of the old symbol table data being discarded inside - GDB. - - `symbol-file' does not repeat if you press <RET> again after - executing it once. - - When GDB is configured for a particular environment, it - understands debugging information in whatever format is the - standard generated for that environment; you may use either a GNU - compiler, or other compilers that adhere to the local conventions. - Best results are usually obtained from GNU compilers; for example, - using `gcc' you can generate debugging information for optimized - code. - - For most kinds of object files, with the exception of old SVR3 - systems using COFF, the `symbol-file' command does not normally - read the symbol table in full right away. Instead, it scans the - symbol table quickly to find which source files and which symbols - are present. The details are read later, one source file at a - time, as they are needed. - - The purpose of this two-stage reading strategy is to make GDB - start up faster. For the most part, it is invisible except for - occasional pauses while the symbol table details for a particular - source file are being read. (The `set verbose' command can turn - these pauses into messages if desired. *Note Optional warnings - and messages: Messages/Warnings.) - - We have not implemented the two-stage strategy for COFF yet. When - the symbol table is stored in COFF format, `symbol-file' reads the - symbol table data in full right away. Note that "stabs-in-COFF" - still does the two-stage strategy, since the debug info is actually - in stabs format. - -`symbol-file FILENAME [ -readnow ] [ -mapped ]' -`file FILENAME [ -readnow ] [ -mapped ]' - You can override the GDB two-stage strategy for reading symbol - tables by using the `-readnow' option with any of the commands that - load symbol table information, if you want to be sure GDB has the - entire symbol table available. - - If memory-mapped files are available on your system through the - `mmap' system call, you can use another option, `-mapped', to - cause GDB to write the symbols for your program into a reusable - file. Future GDB debugging sessions map in symbol information - from this auxiliary symbol file (if the program has not changed), - rather than spending time reading the symbol table from the - executable program. Using the `-mapped' option has the same - effect as starting GDB with the `-mapped' command-line option. - - You can use both options together, to make sure the auxiliary - symbol file has all the symbol information for your program. - - The auxiliary symbol file for a program called MYPROG is called - `MYPROG.syms'. Once this file exists (so long as it is newer than - the corresponding executable), GDB always attempts to use it when - you debug MYPROG; no special options or commands are needed. - - The `.syms' file is specific to the host machine where you run - GDB. It holds an exact image of the internal GDB symbol table. - It cannot be shared across multiple host platforms. - -`core-file [ FILENAME ]' - Specify the whereabouts of a core dump file to be used as the - "contents of memory". Traditionally, core files contain only some - parts of the address space of the process that generated them; GDB - can access the executable file itself for other parts. - - `core-file' with no argument specifies that no core file is to be - used. - - Note that the core file is ignored when your program is actually - running under GDB. So, if you have been running your program and - you wish to debug a core file instead, you must kill the - subprocess in which the program is running. To do this, use the - `kill' command (*note Killing the child process: Kill Process.). - -`add-symbol-file FILENAME ADDRESS' -`add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]' -`add-symbol-file FILENAME -sSECTION ADDRESS ...' - The `add-symbol-file' command reads additional symbol table - information from the file FILENAME. You would use this command - when FILENAME has been dynamically loaded (by some other means) - into the program that is running. ADDRESS should be the memory - address at which the file has been loaded; GDB cannot figure this - out for itself. You can additionally specify an arbitrary number - of `-sSECTION ADDRESS' pairs, to give an explicit section name and - base address for that section. You can specify any ADDRESS as an - expression. - - The symbol table of the file FILENAME is added to the symbol table - originally read with the `symbol-file' command. You can use the - `add-symbol-file' command any number of times; the new symbol data - thus read keeps adding to the old. To discard all old symbol data - instead, use the `symbol-file' command without any arguments. - - Although FILENAME is typically a shared library file, an - executable file, or some other object file which has been fully - relocated for loading into a process, you can also load symbolic - information from relocatable `.o' files, as long as: - - * the file's symbolic information refers only to linker symbols - defined in that file, not to symbols defined by other object - files, - - * every section the file's symbolic information refers to has - actually been loaded into the inferior, as it appears in the - file, and - - * you can determine the address at which every section was - loaded, and provide these to the `add-symbol-file' command. - - Some embedded operating systems, like Sun Chorus and VxWorks, can - load relocatable files into an already running program; such - systems typically make the requirements above easy to meet. - However, it's important to recognize that many native systems use - complex link procedures (`.linkonce' section factoring and C++ - constructor table assembly, for example) that make the - requirements difficult to meet. In general, one cannot assume - that using `add-symbol-file' to read a relocatable object file's - symbolic information will have the same effect as linking the - relocatable object file into the program in the normal way. - - `add-symbol-file' does not repeat if you press <RET> after using - it. - - You can use the `-mapped' and `-readnow' options just as with the - `symbol-file' command, to change how GDB manages the symbol table - information for FILENAME. - -`add-shared-symbol-file' - The `add-shared-symbol-file' command can be used only under - Harris' CXUX operating system for the Motorola 88k. GDB - automatically looks for shared libraries, however if GDB does not - find yours, you can run `add-shared-symbol-file'. It takes no - arguments. - -`section' - The `section' command changes the base address of section SECTION - of the exec file to ADDR. This can be used if the exec file does - not contain section addresses, (such as in the a.out format), or - when the addresses specified in the file itself are wrong. Each - section must be changed separately. The `info files' command, - described below, lists all the sections and their addresses. - -`info files' -`info target' - `info files' and `info target' are synonymous; both print the - current target (*note Specifying a Debugging Target: Targets.), - including the names of the executable and core dump files - currently in use by GDB, and the files from which symbols were - loaded. The command `help target' lists all possible targets - rather than current ones. - -`maint info sections' - Another command that can give you extra information about program - sections is `maint info sections'. In addition to the section - information displayed by `info files', this command displays the - flags and file offset of each section in the executable and core - dump files. In addition, `maint info sections' provides the - following command options (which may be arbitrarily combined): - - `ALLOBJ' - Display sections for all loaded object files, including - shared libraries. - - `SECTIONS' - Display info only for named SECTIONS. - - `SECTION-FLAGS' - Display info only for sections for which SECTION-FLAGS are - true. The section flags that GDB currently knows about are: - `ALLOC' - Section will have space allocated in the process when - loaded. Set for all sections except those containing - debug information. - - `LOAD' - Section will be loaded from the file into the child - process memory. Set for pre-initialized code and data, - clear for `.bss' sections. - - `RELOC' - Section needs to be relocated before loading. - - `READONLY' - Section cannot be modified by the child process. - - `CODE' - Section contains executable code only. - - `DATA' - Section contains data only (no executable code). - - `ROM' - Section will reside in ROM. - - `CONSTRUCTOR' - Section contains data for constructor/destructor lists. - - `HAS_CONTENTS' - Section is not empty. - - `NEVER_LOAD' - An instruction to the linker to not output the section. - - `COFF_SHARED_LIBRARY' - A notification to the linker that the section contains - COFF shared library information. - - `IS_COMMON' - Section contains common symbols. - -`set trust-readonly-sections on' - Tell GDB that readonly sections in your object file really are - read-only (i.e. that their contents will not change). In that - case, GDB can fetch values from these sections out of the object - file, rather than from the target program. For some targets - (notably embedded ones), this can be a significant enhancement to - debugging performance. - - The default is off. - -`set trust-readonly-sections off' - Tell GDB not to trust readonly sections. This means that the - contents of the section might change while the program is running, - and must therefore be fetched from the target when needed. - - All file-specifying commands allow both absolute and relative file -names as arguments. GDB always converts the file name to an absolute -file name and remembers it that way. - - GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared -libraries. - - GDB automatically loads symbol definitions from shared libraries -when you use the `run' command, or when you examine a core file. -(Before you issue the `run' command, GDB does not understand references -to a function in a shared library, however--unless you are debugging a -core file). - - On HP-UX, if the program loads a library explicitly, GDB -automatically loads the symbols at the time of the `shl_load' call. - - There are times, however, when you may wish to not automatically load -symbol definitions from shared libraries, such as when they are -particularly large or there are many of them. - - To control the automatic loading of shared library symbols, use the -commands: - -`set auto-solib-add MODE' - If MODE is `on', symbols from all shared object libraries will be - loaded automatically when the inferior begins execution, you - attach to an independently started inferior, or when the dynamic - linker informs GDB that a new library has been loaded. If MODE is - `off', symbols must be loaded manually, using the `sharedlibrary' - command. The default value is `on'. - -`show auto-solib-add' - Display the current autoloading mode. - - To explicitly load shared library symbols, use the `sharedlibrary' -command: - -`info share' -`info sharedlibrary' - Print the names of the shared libraries which are currently loaded. - -`sharedlibrary REGEX' -`share REGEX' - Load shared object library symbols for files matching a Unix - regular expression. As with files loaded automatically, it only - loads shared libraries required by your program for a core file or - after typing `run'. If REGEX is omitted all shared libraries - required by your program are loaded. - - On some systems, such as HP-UX systems, GDB supports autoloading -shared library symbols until a limiting threshold size is reached. -This provides the benefit of allowing autoloading to remain on by -default, but avoids autoloading excessively large shared libraries, up -to a threshold that is initially set, but which you can modify if you -wish. - - Beyond that threshold, symbols from shared libraries must be -explicitly loaded. To load these symbols, use the command -`sharedlibrary FILENAME'. The base address of the shared library is -determined automatically by GDB and need not be specified. - - To display or set the threshold, use the commands: - -`set auto-solib-limit THRESHOLD' - Set the autoloading size threshold, in an integral number of - megabytes. If THRESHOLD is nonzero and shared library autoloading - is enabled, symbols from all shared object libraries will be - loaded until the total size of the loaded shared library symbols - exceeds this threshold. Otherwise, symbols must be loaded - manually, using the `sharedlibrary' command. The default - threshold is 100 (i.e. 100 Mb). - -`show auto-solib-limit' - Display the current autoloading size threshold, in megabytes. - - Shared libraries are also supported in many cross or remote debugging -configurations. A copy of the target's libraries need to be present on -the host system; they need to be the same as the target libraries, -although the copies on the target can be stripped as long as the copies -on the host are not. - - You need to tell GDB where the target libraries are, so that it can -load the correct copies--otherwise, it may try to load the host's -libraries. GDB has two variables to specify the search directories for -target libraries. - -`set solib-absolute-prefix PATH' - If this variable is set, PATH will be used as a prefix for any - absolute shared library paths; many runtime loaders store the - absolute paths to the shared library in the target program's - memory. If you use `solib-absolute-prefix' to find shared - libraries, they need to be laid out in the same way that they are - on the target, with e.g. a `/usr/lib' hierarchy under PATH. - - You can set the default value of `solib-absolute-prefix' by using - the configure-time `--with-sysroot' option. - -`show solib-absolute-prefix' - Display the current shared library prefix. - -`set solib-search-path PATH' - If this variable is set, PATH is a colon-separated list of - directories to search for shared libraries. `solib-search-path' - is used after `solib-absolute-prefix' fails to locate the library, - or if the path to the library is relative instead of absolute. If - you want to use `solib-search-path' instead of - `solib-absolute-prefix', be sure to set `solib-absolute-prefix' to - a nonexistant directory to prevent GDB from finding your host's - libraries. - -`show solib-search-path' - Display the current shared library search path. - - -File: gdb.info, Node: Separate Debug Files, Next: Symbol Errors, Prev: Files, Up: GDB Files - -Debugging Information in Separate Files -======================================= - -GDB allows you to put a program's debugging information in a file -separate from the executable itself, in a way that allows GDB to find -and load the debugging information automatically. Since debugging -information can be very large -- sometimes larger than the executable -code itself -- some systems distribute debugging information for their -executables in separate files, which users can install only when they -need to debug a problem. - - If an executable's debugging information has been extracted to a -separate file, the executable should contain a "debug link" giving the -name of the debugging information file (with no directory components), -and a checksum of its contents. (The exact form of a debug link is -described below.) If the full name of the directory containing the -executable is EXECDIR, and the executable has a debug link that -specifies the name DEBUGFILE, then GDB will automatically search for -the debugging information file in three places: - - * the directory containing the executable file (that is, it will look - for a file named `EXECDIR/DEBUGFILE', - - * a subdirectory of that directory named `.debug' (that is, the file - `EXECDIR/.debug/DEBUGFILE', and - - * a subdirectory of the global debug file directory that includes the - executable's full path, and the name from the link (that is, the - file `GLOBALDEBUGDIR/EXECDIR/DEBUGFILE', where GLOBALDEBUGDIR is - the global debug file directory, and EXECDIR has been turned into - a relative path). - -GDB checks under each of these names for a debugging information file -whose checksum matches that given in the link, and reads the debugging -information from the first one it finds. - - So, for example, if you ask GDB to debug `/usr/bin/ls', which has a -link containing the name `ls.debug', and the global debug directory is -`/usr/lib/debug', then GDB will look for debug information in -`/usr/bin/ls.debug', `/usr/bin/.debug/ls.debug', and -`/usr/lib/debug/usr/bin/ls.debug'. - - You can set the global debugging info directory's name, and view the -name GDB is currently using. - -`set debug-file-directory DIRECTORY' - Set the directory which GDB searches for separate debugging - information files to DIRECTORY. - -`show debug-file-directory' - Show the directory GDB searches for separate debugging information - files. - - - A debug link is a special section of the executable file named -`.gnu_debuglink'. The section must contain: - - * A filename, with any leading directory components removed, - followed by a zero byte, - - * zero to three bytes of padding, as needed to reach the next - four-byte boundary within the section, and - - * a four-byte CRC checksum, stored in the same endianness used for - the executable file itself. The checksum is computed on the - debugging information file's full contents by the function given - below, passing zero as the CRC argument. - - Any executable file format can carry a debug link, as long as it can -contain a section named `.gnu_debuglink' with the contents described -above. - - The debugging information file itself should be an ordinary -executable, containing a full set of linker symbols, sections, and -debugging information. The sections of the debugging information file -should have the same names, addresses and sizes as the original file, -but they need not contain any data -- much like a `.bss' section in an -ordinary executable. - - As of December 2002, there is no standard GNU utility to produce -separated executable / debugging information file pairs. Ulrich -Drepper's `elfutils' package, starting with version 0.53, contains a -version of the `strip' command such that the command `strip foo -f -foo.debug' removes the debugging information from the executable file -`foo', places it in the file `foo.debug', and leaves behind a debug -link in `foo'. - - Since there are many different ways to compute CRC's (different -polynomials, reversals, byte ordering, etc.), the simplest way to -describe the CRC used in `.gnu_debuglink' sections is to give the -complete code for a function that computes it: - - unsigned long - gnu_debuglink_crc32 (unsigned long crc, - unsigned char *buf, size_t len) - { - static const unsigned long crc32_table[256] = - { - 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, - 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, - 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, - 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, - 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, - 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, - 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, - 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, - 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, - 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, - 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, - 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, - 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, - 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, - 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, - 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, - 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, - 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, - 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, - 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, - 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, - 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, - 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, - 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, - 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, - 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, - 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, - 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, - 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, - 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, - 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, - 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, - 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, - 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, - 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, - 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, - 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, - 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, - 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, - 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, - 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, - 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, - 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, - 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, - 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, - 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, - 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, - 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, - 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, - 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, - 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, - 0x2d02ef8d - }; - unsigned char *end; - - crc = ~crc & 0xffffffff; - for (end = buf + len; buf < end; ++buf) - crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); - return ~crc & 0xffffffff; - } - - -File: gdb.info, Node: Symbol Errors, Prev: Separate Debug Files, Up: GDB Files - -Errors reading symbol files -=========================== - -While reading a symbol file, GDB occasionally encounters problems, such -as symbol types it does not recognize, or known bugs in compiler -output. By default, GDB does not notify you of such problems, since -they are relatively common and primarily of interest to people -debugging compilers. If you are interested in seeing information about -ill-constructed symbol tables, you can either ask GDB to print only one -message about each such type of problem, no matter how many times the -problem occurs; or you can ask GDB to print more messages, to see how -many times the problems occur, with the `set complaints' command (*note -Optional warnings and messages: Messages/Warnings.). - - The messages currently printed, and their meanings, include: - -`inner block not inside outer block in SYMBOL' - The symbol information shows where symbol scopes begin and end - (such as at the start of a function or a block of statements). - This error indicates that an inner scope block is not fully - contained in its outer scope blocks. - - GDB circumvents the problem by treating the inner block as if it - had the same scope as the outer block. In the error message, - SYMBOL may be shown as "`(don't know)'" if the outer block is not a - function. - -`block at ADDRESS out of order' - The symbol information for symbol scope blocks should occur in - order of increasing addresses. This error indicates that it does - not do so. - - GDB does not circumvent this problem, and has trouble locating - symbols in the source file whose symbols it is reading. (You can - often determine what source file is affected by specifying `set - verbose on'. *Note Optional warnings and messages: - Messages/Warnings.) - -`bad block start address patched' - The symbol information for a symbol scope block has a start address - smaller than the address of the preceding source line. This is - known to occur in the SunOS 4.1.1 (and earlier) C compiler. - - GDB circumvents the problem by treating the symbol scope block as - starting on the previous source line. - -`bad string table offset in symbol N' - Symbol number N contains a pointer into the string table which is - larger than the size of the string table. - - GDB circumvents the problem by considering the symbol to have the - name `foo', which may cause other problems if many symbols end up - with this name. - -`unknown symbol type `0xNN'' - The symbol information contains new data types that GDB does not - yet know how to read. `0xNN' is the symbol type of the - uncomprehended information, in hexadecimal. - - GDB circumvents the error by ignoring this symbol information. - This usually allows you to debug your program, though certain - symbols are not accessible. If you encounter such a problem and - feel like debugging it, you can debug `gdb' with itself, breakpoint - on `complain', then go up to the function `read_dbx_symtab' and - examine `*bufp' to see the symbol. - -`stub type has NULL name' - GDB could not find the full definition for a struct or class. - -`const/volatile indicator missing (ok if using g++ v1.x), got...' - The symbol information for a C++ member function is missing some - information that recent versions of the compiler should have - output for it. - -`info mismatch between compiler and debugger' - GDB could not parse a type specification output by the compiler. - - - -File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top - -Specifying a Debugging Target -***************************** - -A "target" is the execution environment occupied by your program. - - Often, GDB runs in the same host environment as your program; in -that case, the debugging target is specified as a side effect when you -use the `file' or `core' commands. When you need more flexibility--for -example, running GDB on a physically separate host, or controlling a -standalone system over a serial port or a realtime system over a TCP/IP -connection--you can use the `target' command to specify one of the -target types configured for GDB (*note Commands for managing targets: -Target Commands.). - -* Menu: - -* Active Targets:: Active targets -* Target Commands:: Commands for managing targets -* Byte Order:: Choosing target byte order -* Remote:: Remote debugging -* KOD:: Kernel Object Display - - -File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets - -Active targets -============== - -There are three classes of targets: processes, core files, and -executable files. GDB can work concurrently on up to three active -targets, one in each class. This allows you to (for example) start a -process and inspect its activity without abandoning your work on a core -file. - - For example, if you execute `gdb a.out', then the executable file -`a.out' is the only active target. If you designate a core file as -well--presumably from a prior run that crashed and coredumped--then GDB -has two active targets and uses them in tandem, looking first in the -corefile target, then in the executable file, to satisfy requests for -memory addresses. (Typically, these two classes of target are -complementary, since core files contain only a program's read-write -memory--variables and so on--plus machine status, while executable -files contain only the program text and initialized data.) - - When you type `run', your executable file becomes an active process -target as well. When a process target is active, all GDB commands -requesting memory addresses refer to that target; addresses in an -active core file or executable file target are obscured while the -process target is active. - - Use the `core-file' and `exec-file' commands to select a new core -file or executable target (*note Commands to specify files: Files.). -To specify as a target a process that is already running, use the -`attach' command (*note Debugging an already-running process: Attach.). - - -File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets - -Commands for managing targets -============================= - -`target TYPE PARAMETERS' - Connects the GDB host environment to a target machine or process. - A target is typically a protocol for talking to debugging - facilities. You use the argument TYPE to specify the type or - protocol of the target machine. - - Further PARAMETERS are interpreted by the target protocol, but - typically include things like device names or host names to connect - with, process numbers, and baud rates. - - The `target' command does not repeat if you press <RET> again - after executing the command. - -`help target' - Displays the names of all targets available. To display targets - currently selected, use either `info target' or `info files' - (*note Commands to specify files: Files.). - -`help target NAME' - Describe a particular target, including any parameters necessary to - select it. - -`set gnutarget ARGS' - GDB uses its own library BFD to read your files. GDB knows - whether it is reading an "executable", a "core", or a ".o" file; - however, you can specify the file format with the `set gnutarget' - command. Unlike most `target' commands, with `gnutarget' the - `target' refers to a program, not a machine. - - _Warning:_ To specify a file format with `set gnutarget', you - must know the actual BFD name. - - *Note Commands to specify files: Files. - -`show gnutarget' - Use the `show gnutarget' command to display what file format - `gnutarget' is set to read. If you have not set `gnutarget', GDB - will determine the file format for each file automatically, and - `show gnutarget' displays `The current BDF target is "auto"'. - - Here are some common targets (available, or not, depending on the GDB -configuration): - -`target exec PROGRAM' - An executable file. `target exec PROGRAM' is the same as - `exec-file PROGRAM'. - -`target core FILENAME' - A core dump file. `target core FILENAME' is the same as - `core-file FILENAME'. - -`target remote DEV' - Remote serial target in GDB-specific protocol. The argument DEV - specifies what serial device to use for the connection (e.g. - `/dev/ttya'). *Note Remote debugging: Remote. `target remote' - supports the `load' command. This is only useful if you have some - other way of getting the stub to the target system, and you can put - it somewhere in memory where it won't get clobbered by the - download. - -`target sim' - Builtin CPU simulator. GDB includes simulators for most - architectures. In general, - target sim - load - run - - works; however, you cannot assume that a specific memory map, - device drivers, or even basic I/O is available, although some - simulators do provide these. For info about any - processor-specific simulator details, see the appropriate section - in *Note Embedded Processors: Embedded Processors. - - - Some configurations may include these targets as well: - -`target nrom DEV' - NetROM ROM emulator. This target only supports downloading. - - - Different targets are available on different configurations of GDB; -your configuration may have more or fewer targets. - - Many remote targets require you to download the executable's code -once you've successfully established a connection. - -`load FILENAME' - Depending on what remote debugging facilities are configured into - GDB, the `load' command may be available. Where it exists, it is - meant to make FILENAME (an executable) available for debugging on - the remote system--by downloading, or dynamic linking, for example. - `load' also records the FILENAME symbol table in GDB, like the - `add-symbol-file' command. - - If your GDB does not have a `load' command, attempting to execute - it gets the error message "`You can't do that when your target is - ...'" - - The file is loaded at whatever address is specified in the - executable. For some object file formats, you can specify the - load address when you link the program; for other formats, like - a.out, the object file format specifies a fixed address. - - `load' does not repeat if you press <RET> again after using it. - - -File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets - -Choosing target byte order -========================== - -Some types of processors, such as the MIPS, PowerPC, and Renesas SH, -offer the ability to run either big-endian or little-endian byte -orders. Usually the executable or symbol will include a bit to -designate the endian-ness, and you will not need to worry about which -to use. However, you may still find it useful to adjust GDB's idea of -processor endian-ness manually. - -`set endian big' - Instruct GDB to assume the target is big-endian. - -`set endian little' - Instruct GDB to assume the target is little-endian. - -`set endian auto' - Instruct GDB to use the byte order associated with the executable. - -`show endian' - Display GDB's current idea of the target byte order. - - - Note that these commands merely adjust interpretation of symbolic -data on the host, and that they have absolutely no effect on the target -system. - - -File: gdb.info, Node: Remote, Next: KOD, Prev: Byte Order, Up: Targets - -Remote debugging -================ - -If you are trying to debug a program running on a machine that cannot -run GDB in the usual way, it is often useful to use remote debugging. -For example, you might use remote debugging on an operating system -kernel, or on a small system which does not have a general purpose -operating system powerful enough to run a full-featured debugger. - - Some configurations of GDB have special serial or TCP/IP interfaces -to make this work with particular debugging targets. In addition, GDB -comes with a generic serial protocol (specific to GDB, but not specific -to any particular target system) which you can use if you write the -remote stubs--the code that runs on the remote system to communicate -with GDB. - - Other remote targets may be available in your configuration of GDB; -use `help target' to list them. - - -File: gdb.info, Node: KOD, Prev: Remote, Up: Targets - -Kernel Object Display -===================== - -Some targets support kernel object display. Using this facility, GDB -communicates specially with the underlying operating system and can -display information about operating system-level objects such as -mutexes and other synchronization objects. Exactly which objects can be -displayed is determined on a per-OS basis. - - Use the `set os' command to set the operating system. This tells -GDB which kernel object display module to initialize: - - (gdb) set os cisco - - The associated command `show os' displays the operating system set -with the `set os' command; if no operating system has been set, `show -os' will display an empty string `""'. - - If `set os' succeeds, GDB will display some information about the -operating system, and will create a new `info' command which can be -used to query the target. The `info' command is named after the -operating system: - - (gdb) info cisco - List of Cisco Kernel Objects - Object Description - any Any and all objects - - Further subcommands can be used to query about particular objects -known by the kernel. - - There is currently no way to determine whether a given operating -system is supported other than to try setting it with `set os NAME', -where NAME is the name of the operating system you want to try. - - -File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top - -Debugging remote programs -************************* - -* Menu: - -* Connecting:: Connecting to a remote target -* Server:: Using the gdbserver program -* NetWare:: Using the gdbserve.nlm program -* Remote configuration:: Remote configuration -* remote stub:: Implementing a remote stub - - -File: gdb.info, Node: Connecting, Next: Server, Up: Remote Debugging - -Connecting to a remote target -============================= - -On the GDB host machine, you will need an unstripped copy of your -program, since GDB needs symobl and debugging information. Start up -GDB as usual, using the name of the local copy of your program as the -first argument. - - If you're using a serial line, you may want to give GDB the `--baud' -option, or use the `set remotebaud' command before the `target' command. - - After that, use `target remote' to establish communications with the -target machine. Its argument specifies how to communicate--either via -a devicename attached to a direct serial line, or a TCP or UDP port -(possibly to a terminal server which in turn has a serial line to the -target). For example, to use a serial line connected to the device -named `/dev/ttyb': - - target remote /dev/ttyb - - To use a TCP connection, use an argument of the form `HOST:PORT' or -`tcp:HOST:PORT'. For example, to connect to port 2828 on a terminal -server named `manyfarms': - - target remote manyfarms:2828 - - If your remote target is actually running on the same machine as -your debugger session (e.g. a simulator of your target running on the -same host), you can omit the hostname. For example, to connect to port -1234 on your local machine: - - target remote :1234 - -Note that the colon is still required here. - - To use a UDP connection, use an argument of the form -`udp:HOST:PORT'. For example, to connect to UDP port 2828 on a -terminal server named `manyfarms': - - target remote udp:manyfarms:2828 - - When using a UDP connection for remote debugging, you should keep in -mind that the `U' stands for "Unreliable". UDP can silently drop -packets on busy or unreliable networks, which will cause havoc with -your debugging session. - - Now you can use all the usual commands to examine and change data -and to step and continue the remote program. - - Whenever GDB is waiting for the remote program, if you type the -interrupt character (often <C-C>), GDB attempts to stop the program. -This may or may not succeed, depending in part on the hardware and the -serial drivers the remote system uses. If you type the interrupt -character once again, GDB displays this prompt: - - Interrupted while waiting for the program. - Give up (and stop debugging it)? (y or n) - - If you type `y', GDB abandons the remote debugging session. (If you -decide you want to try again later, you can use `target remote' again -to connect once more.) If you type `n', GDB goes back to waiting. - -`detach' - When you have finished debugging the remote program, you can use - the `detach' command to release it from GDB control. Detaching - from the target normally resumes its execution, but the results - will depend on your particular remote stub. After the `detach' - command, GDB is free to connect to another target. - -`disconnect' - The `disconnect' command behaves like `detach', except that the - target is generally not resumed. It will wait for GDB (this - instance or another one) to connect and continue debugging. After - the `disconnect' command, GDB is again free to connect to another - target. - - -File: gdb.info, Node: Server, Next: NetWare, Prev: Connecting, Up: Remote Debugging - -Using the `gdbserver' program -============================= - -`gdbserver' is a control program for Unix-like systems, which allows -you to connect your program with a remote GDB via `target remote'--but -without linking in the usual debugging stub. - - `gdbserver' is not a complete replacement for the debugging stubs, -because it requires essentially the same operating-system facilities -that GDB itself does. In fact, a system that can run `gdbserver' to -connect to a remote GDB could also run GDB locally! `gdbserver' is -sometimes useful nevertheless, because it is a much smaller program -than GDB itself. It is also easier to port than all of GDB, so you may -be able to get started more quickly on a new system by using -`gdbserver'. Finally, if you develop code for real-time systems, you -may find that the tradeoffs involved in real-time operation make it -more convenient to do as much development work as possible on another -system, for example by cross-compiling. You can use `gdbserver' to -make a similar choice for debugging. - - GDB and `gdbserver' communicate via either a serial line or a TCP -connection, using the standard GDB remote serial protocol. - -_On the target machine,_ - you need to have a copy of the program you want to debug. - `gdbserver' does not need your program's symbol table, so you can - strip the program if necessary to save space. GDB on the host - system does all the symbol handling. - - To use the server, you must tell it how to communicate with GDB; - the name of your program; and the arguments for your program. The - usual syntax is: - - target> gdbserver COMM PROGRAM [ ARGS ... ] - - COMM is either a device name (to use a serial line) or a TCP - hostname and portnumber. For example, to debug Emacs with the - argument `foo.txt' and communicate with GDB over the serial port - `/dev/com1': - - target> gdbserver /dev/com1 emacs foo.txt - - `gdbserver' waits passively for the host GDB to communicate with - it. - - To use a TCP connection instead of a serial line: - - target> gdbserver host:2345 emacs foo.txt - - The only difference from the previous example is the first - argument, specifying that you are communicating with the host GDB - via TCP. The `host:2345' argument means that `gdbserver' is to - expect a TCP connection from machine `host' to local TCP port 2345. - (Currently, the `host' part is ignored.) You can choose any number - you want for the port number as long as it does not conflict with - any TCP ports already in use on the target system (for example, - `23' is reserved for `telnet').(1) You must use the same port - number with the host GDB `target remote' command. - - On some targets, `gdbserver' can also attach to running programs. - This is accomplished via the `--attach' argument. The syntax is: - - target> gdbserver COMM --attach PID - - PID is the process ID of a currently running process. It isn't - necessary to point `gdbserver' at a binary for the running process. - - You can debug processes by name instead of process ID if your - target has the `pidof' utility: - - target> gdbserver COMM --attach `pidof PROGRAM` - - In case more than one copy of PROGRAM is running, or PROGRAM has - multiple threads, most versions of `pidof' support the `-s' option - to only return the first process ID. - -_On the host machine,_ - connect to your target (*note Connecting to a remote target: - Connecting.). For TCP connections, you must start up `gdbserver' - prior to using the `target remote' command. Otherwise you may get - an error whose text depends on the host system, but which usually - looks something like `Connection refused'. You don't need to use - the `load' command in GDB when using gdbserver, since the program - is already on the target. - - - ---------- Footnotes ---------- - - (1) If you choose a port number that conflicts with another service, -`gdbserver' prints an error message and exits. - - -File: gdb.info, Node: NetWare, Next: Remote configuration, Prev: Server, Up: Remote Debugging - -Using the `gdbserve.nlm' program -================================ - -`gdbserve.nlm' is a control program for NetWare systems, which allows -you to connect your program with a remote GDB via `target remote'. - - GDB and `gdbserve.nlm' communicate via a serial line, using the -standard GDB remote serial protocol. - -_On the target machine,_ - you need to have a copy of the program you want to debug. - `gdbserve.nlm' does not need your program's symbol table, so you - can strip the program if necessary to save space. GDB on the host - system does all the symbol handling. - - To use the server, you must tell it how to communicate with GDB; - the name of your program; and the arguments for your program. The - syntax is: - - load gdbserve [ BOARD=BOARD ] [ PORT=PORT ] - [ BAUD=BAUD ] PROGRAM [ ARGS ... ] - - BOARD and PORT specify the serial line; BAUD specifies the baud - rate used by the connection. PORT and NODE default to 0, BAUD - defaults to 9600bps. - - For example, to debug Emacs with the argument `foo.txt'and - communicate with GDB over serial port number 2 or board 1 using a - 19200bps connection: - - load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt - -__ - On the GDB host machine, connect to your target (*note Connecting - to a remote target: Connecting.). - - - -File: gdb.info, Node: Remote configuration, Next: remote stub, Prev: NetWare, Up: Remote Debugging - -Remote configuration -==================== - -The following configuration options are available when debugging remote -programs: - -`set remote hardware-watchpoint-limit LIMIT' -`set remote hardware-breakpoint-limit LIMIT' - Restrict GDB to using LIMIT remote hardware breakpoint or - watchpoints. A limit of -1, the default, is treated as unlimited. - - -File: gdb.info, Node: remote stub, Prev: Remote configuration, Up: Remote Debugging - -Implementing a remote stub -========================== - -The stub files provided with GDB implement the target side of the -communication protocol, and the GDB side is implemented in the GDB -source file `remote.c'. Normally, you can simply allow these -subroutines to communicate, and ignore the details. (If you're -implementing your own stub file, you can still ignore the details: start -with one of the existing stub files. `sparc-stub.c' is the best -organized, and therefore the easiest to read.) - - To debug a program running on another machine (the debugging -"target" machine), you must first arrange for all the usual -prerequisites for the program to run by itself. For example, for a C -program, you need: - - 1. A startup routine to set up the C runtime environment; these - usually have a name like `crt0'. The startup routine may be - supplied by your hardware supplier, or you may have to write your - own. - - 2. A C subroutine library to support your program's subroutine calls, - notably managing input and output. - - 3. A way of getting your program to the other machine--for example, a - download program. These are often supplied by the hardware - manufacturer, but you may have to write your own from hardware - documentation. - - The next step is to arrange for your program to use a serial port to -communicate with the machine where GDB is running (the "host" machine). -In general terms, the scheme looks like this: - -_On the host,_ - GDB already understands how to use this protocol; when everything - else is set up, you can simply use the `target remote' command - (*note Specifying a Debugging Target: Targets.). - -_On the target,_ - you must link with your program a few special-purpose subroutines - that implement the GDB remote serial protocol. The file - containing these subroutines is called a "debugging stub". - - On certain remote targets, you can use an auxiliary program - `gdbserver' instead of linking a stub into your program. *Note - Using the `gdbserver' program: Server, for details. - - The debugging stub is specific to the architecture of the remote -machine; for example, use `sparc-stub.c' to debug programs on SPARC -boards. - - These working remote stubs are distributed with GDB: - -`i386-stub.c' - For Intel 386 and compatible architectures. - -`m68k-stub.c' - For Motorola 680x0 architectures. - -`sh-stub.c' - For Renesas SH architectures. - -`sparc-stub.c' - For SPARC architectures. - -`sparcl-stub.c' - For Fujitsu SPARCLITE architectures. - - - The `README' file in the GDB distribution may list other recently -added stubs. - -* Menu: - -* Stub Contents:: What the stub can do for you -* Bootstrapping:: What you must do for the stub -* Debug Session:: Putting it all together - - -File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: remote stub - -What the stub can do for you ----------------------------- - -The debugging stub for your architecture supplies these three -subroutines: - -`set_debug_traps' - This routine arranges for `handle_exception' to run when your - program stops. You must call this subroutine explicitly near the - beginning of your program. - -`handle_exception' - This is the central workhorse, but your program never calls it - explicitly--the setup code arranges for `handle_exception' to run - when a trap is triggered. - - `handle_exception' takes control when your program stops during - execution (for example, on a breakpoint), and mediates - communications with GDB on the host machine. This is where the - communications protocol is implemented; `handle_exception' acts as - the GDB representative on the target machine. It begins by - sending summary information on the state of your program, then - continues to execute, retrieving and transmitting any information - GDB needs, until you execute a GDB command that makes your program - resume; at that point, `handle_exception' returns control to your - own code on the target machine. - -`breakpoint' - Use this auxiliary subroutine to make your program contain a - breakpoint. Depending on the particular situation, this may be - the only way for GDB to get control. For instance, if your target - machine has some sort of interrupt button, you won't need to call - this; pressing the interrupt button transfers control to - `handle_exception'--in effect, to GDB. On some machines, simply - receiving characters on the serial port may also trigger a trap; - again, in that situation, you don't need to call `breakpoint' from - your own program--simply running `target remote' from the host GDB - session gets control. - - Call `breakpoint' if none of these is true, or if you simply want - to make certain your program stops at a predetermined point for the - start of your debugging session. - - -File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: remote stub - -What you must do for the stub ------------------------------ - -The debugging stubs that come with GDB are set up for a particular chip -architecture, but they have no information about the rest of your -debugging target machine. - - First of all you need to tell the stub how to communicate with the -serial port. - -`int getDebugChar()' - Write this subroutine to read a single character from the serial - port. It may be identical to `getchar' for your target system; a - different name is used to allow you to distinguish the two if you - wish. - -`void putDebugChar(int)' - Write this subroutine to write a single character to the serial - port. It may be identical to `putchar' for your target system; a - different name is used to allow you to distinguish the two if you - wish. - - If you want GDB to be able to stop your program while it is running, -you need to use an interrupt-driven serial driver, and arrange for it -to stop when it receives a `^C' (`\003', the control-C character). -That is the character which GDB uses to tell the remote system to stop. - - Getting the debugging target to return the proper status to GDB -probably requires changes to the standard stub; one quick and dirty way -is to just execute a breakpoint instruction (the "dirty" part is that -GDB reports a `SIGTRAP' instead of a `SIGINT'). - - Other routines you need to supply are: - -`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' - Write this function to install EXCEPTION_ADDRESS in the exception - handling tables. You need to do this because the stub does not - have any way of knowing what the exception handling tables on your - target system are like (for example, the processor's table might - be in ROM, containing entries which point to a table in RAM). - EXCEPTION_NUMBER is the exception number which should be changed; - its meaning is architecture-dependent (for example, different - numbers might represent divide by zero, misaligned access, etc). - When this exception occurs, control should be transferred directly - to EXCEPTION_ADDRESS, and the processor state (stack, registers, - and so on) should be just as it is when a processor exception - occurs. So if you want to use a jump instruction to reach - EXCEPTION_ADDRESS, it should be a simple jump, not a jump to - subroutine. - - For the 386, EXCEPTION_ADDRESS should be installed as an interrupt - gate so that interrupts are masked while the handler runs. The - gate should be at privilege level 0 (the most privileged level). - The SPARC and 68k stubs are able to mask interrupts themselves - without help from `exceptionHandler'. - -`void flush_i_cache()' - On SPARC and SPARCLITE only, write this subroutine to flush the - instruction cache, if any, on your target machine. If there is no - instruction cache, this subroutine may be a no-op. - - On target machines that have instruction caches, GDB requires this - function to make certain that the state of your program is stable. - -You must also make sure this library routine is available: - -`void *memset(void *, int, int)' - This is the standard library function `memset' that sets an area of - memory to a known value. If you have one of the free versions of - `libc.a', `memset' can be found there; otherwise, you must either - obtain it from your hardware manufacturer, or write your own. - - If you do not use the GNU C compiler, you may need other standard -library subroutines as well; this varies from one stub to another, but -in general the stubs are likely to use any of the common library -subroutines which `gcc' generates as inline code. - - -File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: remote stub - -Putting it all together ------------------------ - -In summary, when your program is ready to debug, you must follow these -steps. - - 1. Make sure you have defined the supporting low-level routines - (*note What you must do for the stub: Bootstrapping.): - `getDebugChar', `putDebugChar', - `flush_i_cache', `memset', `exceptionHandler'. - - 2. Insert these lines near the top of your program: - - set_debug_traps(); - breakpoint(); - - 3. For the 680x0 stub only, you need to provide a variable called - `exceptionHook'. Normally you just use: - - void (*exceptionHook)() = 0; - - but if before calling `set_debug_traps', you set it to point to a - function in your program, that function is called when `GDB' - continues after stopping on a trap (for example, bus error). The - function indicated by `exceptionHook' is called with one - parameter: an `int' which is the exception number. - - 4. Compile and link together: your program, the GDB debugging stub for - your target architecture, and the supporting subroutines. - - 5. Make sure you have a serial connection between your target machine - and the GDB host, and identify the serial port on the host. - - 6. Download your program to your target machine (or get it there by - whatever means the manufacturer provides), and start it. - - 7. Start GDB on the host, and connect to the target (*note Connecting - to a remote target: Connecting.). - - - -File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top - -Configuration-Specific Information -********************************** - -While nearly all GDB commands are available for all native and cross -versions of the debugger, there are some exceptions. This chapter -describes things that are only available in certain configurations. - - There are three major categories of configurations: native -configurations, where the host and target are the same, embedded -operating system configurations, which are usually the same for several -different processor architectures, and bare embedded processors, which -are quite different from each other. - -* Menu: - -* Native:: -* Embedded OS:: -* Embedded Processors:: -* Architectures:: - - -File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations - -Native -====== - -This section describes details specific to particular native -configurations. - -* Menu: - -* HP-UX:: HP-UX -* SVR4 Process Information:: SVR4 process information -* DJGPP Native:: Features specific to the DJGPP port -* Cygwin Native:: Features specific to the Cygwin port - - -File: gdb.info, Node: HP-UX, Next: SVR4 Process Information, Up: Native - -HP-UX ------ - -On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, GDB searches for a user or system name -first, before it searches for a convenience variable. - - -File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: HP-UX, Up: Native - -SVR4 process information ------------------------- - -Many versions of SVR4 provide a facility called `/proc' that can be -used to examine the image of a running process using file-system -subroutines. If GDB is configured for an operating system with this -facility, the command `info proc' is available to report on several -kinds of information about the process running your program. `info -proc' works only on SVR4 systems that include the `procfs' code. This -includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not -HP-UX or GNU/Linux, for example. - -`info proc' - Summarize available information about the process. - -`info proc mappings' - Report on the address ranges accessible in the program, with - information on whether your program may read, write, or execute - each range. - - -File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native - -Features for Debugging DJGPP Programs -------------------------------------- - -DJGPP is the port of GNU development tools to MS-DOS and MS-Windows. -DJGPP programs are 32-bit protected-mode programs that use the "DPMI" -(DOS Protected-Mode Interface) API to run on top of real-mode DOS -systems and their emulations. - - GDB supports native debugging of DJGPP programs, and defines a few -commands specific to the DJGPP port. This subsection describes those -commands. - -`info dos' - This is a prefix of DJGPP-specific commands which print - information about the target system and important OS structures. - -`info dos sysinfo' - This command displays assorted information about the underlying - platform: the CPU type and features, the OS version and flavor, the - DPMI version, and the available conventional and DPMI memory. - -`info dos gdt' -`info dos ldt' -`info dos idt' - These 3 commands display entries from, respectively, Global, Local, - and Interrupt Descriptor Tables (GDT, LDT, and IDT). The - descriptor tables are data structures which store a descriptor for - each segment that is currently in use. The segment's selector is - an index into a descriptor table; the table entry for that index - holds the descriptor's base address and limit, and its attributes - and access rights. - - A typical DJGPP program uses 3 segments: a code segment, a data - segment (used for both data and the stack), and a DOS segment - (which allows access to DOS/BIOS data structures and absolute - addresses in conventional memory). However, the DPMI host will - usually define additional segments in order to support the DPMI - environment. - - These commands allow to display entries from the descriptor tables. - Without an argument, all entries from the specified table are - displayed. An argument, which should be an integer expression, - means display a single entry whose index is given by the argument. - For example, here's a convenient way to display information about - the debugged program's data segment: - - `(gdb) info dos ldt $ds' - `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)' - - - This comes in handy when you want to see whether a pointer is - outside the data segment's limit (i.e. "garbled"). - -`info dos pde' -`info dos pte' - These two commands display entries from, respectively, the Page - Directory and the Page Tables. Page Directories and Page Tables - are data structures which control how virtual memory addresses are - mapped into physical addresses. A Page Table includes an entry - for every page of memory that is mapped into the program's address - space; there may be several Page Tables, each one holding up to - 4096 entries. A Page Directory has up to 4096 entries, one each - for every Page Table that is currently in use. - - Without an argument, `info dos pde' displays the entire Page - Directory, and `info dos pte' displays all the entries in all of - the Page Tables. An argument, an integer expression, given to the - `info dos pde' command means display only that entry from the Page - Directory table. An argument given to the `info dos pte' command - means display entries from a single Page Table, the one pointed to - by the specified entry in the Page Directory. - - These commands are useful when your program uses "DMA" (Direct - Memory Access), which needs physical addresses to program the DMA - controller. - - These commands are supported only with some DPMI servers. - -`info dos address-pte ADDR' - This command displays the Page Table entry for a specified linear - address. The argument linear address ADDR should already have the - appropriate segment's base address added to it, because this - command accepts addresses which may belong to _any_ segment. For - example, here's how to display the Page Table entry for the page - where the variable `i' is stored: - - `(gdb) info dos address-pte __djgpp_base_address + (char *)&i' - `Page Table entry for address 0x11a00d30:' - `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30' - - - This says that `i' is stored at offset `0xd30' from the page whose - physical base address is `0x02698000', and prints all the - attributes of that page. - - Note that you must cast the addresses of variables to a `char *', - since otherwise the value of `__djgpp_base_address', the base - address of all variables and functions in a DJGPP program, will be - added using the rules of C pointer arithmetics: if `i' is declared - an `int', GDB will add 4 times the value of `__djgpp_base_address' - to the address of `i'. - - Here's another example, it displays the Page Table entry for the - transfer buffer: - - `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)' - `Page Table entry for address 0x29110:' - `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110' - - - (The `+ 3' offset is because the transfer buffer's address is the - 3rd member of the `_go32_info_block' structure.) The output of - this command clearly shows that addresses in conventional memory - are mapped 1:1, i.e. the physical and linear addresses are - identical. - - This command is supported only with some DPMI servers. - - -File: gdb.info, Node: Cygwin Native, Prev: DJGPP Native, Up: Native - -Features for Debugging MS Windows PE executables ------------------------------------------------- - -GDB supports native debugging of MS Windows programs, including DLLs -with and without symbolic debugging information. There are various -additional Cygwin-specific commands, described in this subsection. The -subsubsection *note Non-debug DLL symbols:: describes working with DLLs -that have no debugging symbols. - -`info w32' - This is a prefix of MS Windows specific commands which print - information about the target system and important OS structures. - -`info w32 selector' - This command displays information returned by the Win32 API - `GetThreadSelectorEntry' function. It takes an optional argument - that is evaluated to a long value to give the information about - this given selector. Without argument, this command displays - information about the the six segment registers. - -`info dll' - This is a Cygwin specific alias of info shared. - -`dll-symbols' - This command loads symbols from a dll similarly to add-sym command - but without the need to specify a base address. - -`set new-console MODE' - If MODE is `on' the debuggee will be started in a new console on - next start. If MODE is `off'i, the debuggee will be started in - the same console as the debugger. - -`show new-console' - Displays whether a new console is used when the debuggee is - started. - -`set new-group MODE' - This boolean value controls whether the debuggee should start a - new group or stay in the same group as the debugger. This affects - the way the Windows OS handles Ctrl-C. - -`show new-group' - Displays current value of new-group boolean. - -`set debugevents' - This boolean value adds debug output concerning events seen by the - debugger. - -`set debugexec' - This boolean value adds debug output concerning execute events - seen by the debugger. - -`set debugexceptions' - This boolean value adds debug ouptut concerning exception events - seen by the debugger. - -`set debugmemory' - This boolean value adds debug ouptut concerning memory events seen - by the debugger. - -`set shell' - This boolean values specifies whether the debuggee is called via a - shell or directly (default value is on). - -`show shell' - Displays if the debuggee will be started with a shell. - - -* Menu: - -* Non-debug DLL symbols:: Support for DLLs without debugging symbols - - -File: gdb.info, Node: Non-debug DLL symbols, Up: Cygwin Native - -Support for DLLs without debugging symbols -.......................................... - -Very often on windows, some of the DLLs that your program relies on do -not include symbolic debugging information (for example, -`kernel32.dll'). When GDB doesn't recognize any debugging symbols in a -DLL, it relies on the minimal amount of symbolic information contained -in the DLL's export table. This subsubsection describes working with -such symbols, known internally to GDB as "minimal symbols". - - Note that before the debugged program has started execution, no DLLs -will have been loaded. The easiest way around this problem is simply to -start the program -- either by setting a breakpoint or letting the -program run once to completion. It is also possible to force GDB to -load a particular DLL before starting the executable -- see the shared -library information in *note Files:: or the `dll-symbols' command in -*note Cygwin Native::. Currently, explicitly loading symbols from a DLL -with no debugging information will cause the symbol names to be -duplicated in GDB's lookup table, which may adversely affect symbol -lookup performance. - -DLL name prefixes -................. - -In keeping with the naming conventions used by the Microsoft debugging -tools, DLL export symbols are made available with a prefix based on the -DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also -entered into the symbol table, so `CreateFileA' is often sufficient. In -some cases there will be name clashes within a program (particularly if -the executable itself includes full debugging symbols) necessitating -the use of the fully qualified name when referring to the contents of -the DLL. Use single-quotes around the name to avoid the exclamation -mark ("!") being interpreted as a language operator. - - Note that the internal name of the DLL may be all upper-case, even -though the file name of the DLL is lower-case, or vice-versa. Since -symbols within GDB are _case-sensitive_ this may cause some confusion. -If in doubt, try the `info functions' and `info variables' commands or -even `maint print msymbols' (see *note Symbols::). Here's an example: - - (gdb) info function CreateFileA - All functions matching regular expression "CreateFileA": - - Non-debugging symbols: - 0x77e885f4 CreateFileA - 0x77e885f4 KERNEL32!CreateFileA - - (gdb) info function ! - All functions matching regular expression "!": - - Non-debugging symbols: - 0x6100114c cygwin1!__assert - 0x61004034 cygwin1!_dll_crt0@0 - 0x61004240 cygwin1!dll_crt0(per_process *) - [etc...] - -Working with minimal symbols -............................ - -Symbols extracted from a DLL's export table do not contain very much -type information. All that GDB can do is guess whether a symbol refers -to a function or variable depending on the linker section that contains -the symbol. Also note that the actual contents of the memory contained -in a DLL are not available unless the program is running. This means -that you cannot examine the contents of a variable or disassemble a -function within a DLL without a running program. - - Variables are generally treated as pointers and dereferenced -automatically. For this reason, it is often necessary to prefix a -variable name with the address-of operator ("&") and provide explicit -type information in the command. Here's an example of the type of -problem: - - (gdb) print 'cygwin1!__argv' - $1 = 268572168 - - (gdb) x 'cygwin1!__argv' - 0x10021610: "\230y\"" - - And two possible solutions: - - (gdb) print ((char **)'cygwin1!__argv')[0] - $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" - - (gdb) x/2x &'cygwin1!__argv' - 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 - (gdb) x/x 0x10021608 - 0x10021608: 0x0022fd98 - (gdb) x/s 0x0022fd98 - 0x22fd98: "/cygdrive/c/mydirectory/myprogram" - - Setting a break point within a DLL is possible even before the -program starts execution. However, under these circumstances, GDB can't -examine the initial instructions of the function in order to skip the -function's frame set-up code. You can work around this by using "*&" to -set the breakpoint at a raw memory address: - - (gdb) break *&'python22!PyOS_Readline' - Breakpoint 1 at 0x1e04eff0 - - The author of these extensions is not entirely convinced that -setting a break point within a shared DLL like `kernel32.dll' is -completely safe. - - -File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations - -Embedded Operating Systems -========================== - -This section describes configurations involving the debugging of -embedded operating systems that are available for several different -architectures. - -* Menu: - -* VxWorks:: Using GDB with VxWorks - - GDB includes the ability to debug programs running on various -real-time operating systems. - - -File: gdb.info, Node: VxWorks, Up: Embedded OS - -Using GDB with VxWorks ----------------------- - -`target vxworks MACHINENAME' - A VxWorks system, attached via TCP/IP. The argument MACHINENAME - is the target system's machine name or IP address. - - - On VxWorks, `load' links FILENAME dynamically on the current target -system as well as adding its symbols in GDB. - - GDB enables developers to spawn and debug tasks running on networked -VxWorks targets from a Unix host. Already-running tasks spawned from -the VxWorks shell can also be debugged. GDB uses code that runs on -both the Unix host and on the VxWorks target. The program `gdb' is -installed and executed on the Unix host. (It may be installed with the -name `vxgdb', to distinguish it from a GDB for debugging programs on -the host itself.) - -`VxWorks-timeout ARGS' - All VxWorks-based targets now support the option `vxworks-timeout'. - This option is set by the user, and ARGS represents the number of - seconds GDB waits for responses to rpc's. You might use this if - your VxWorks target is a slow software simulator or is on the far - side of a thin network line. - - The following information on connecting to VxWorks was current when -this manual was produced; newer releases of VxWorks may use revised -procedures. - - To use GDB with VxWorks, you must rebuild your VxWorks kernel to -include the remote debugging interface routines in the VxWorks library -`rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration -file `configAll.h' and rebuild your VxWorks kernel. The resulting -kernel contains `rdb.a', and spawns the source debugging task -`tRdbTask' when VxWorks is booted. For more information on configuring -and remaking VxWorks, see the manufacturer's manual. - - Once you have included `rdb.a' in your VxWorks system image and set -your Unix execution search path to find GDB, you are ready to run GDB. -From your Unix host, run `gdb' (or `vxgdb', depending on your -installation). - - GDB comes up showing the prompt: - - (vxgdb) - -* Menu: - -* VxWorks Connection:: Connecting to VxWorks -* VxWorks Download:: VxWorks download -* VxWorks Attach:: Running tasks - - -File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks - -Connecting to VxWorks -..................... - -The GDB command `target' lets you connect to a VxWorks target on the -network. To connect to a target whose host name is "`tt'", type: - - (vxgdb) target vxworks tt - - GDB displays messages like these: - - Attaching remote machine across net... - Connected to tt. - - GDB then attempts to read the symbol tables of any object modules -loaded into the VxWorks target since it was last booted. GDB locates -these files by searching the directories listed in the command search -path (*note Your program's environment: Environment.); if it fails to -find an object file, it displays a message such as: - - prog.o: No such file or directory. - - When this happens, add the appropriate directory to the search path -with the GDB command `path', and execute the `target' command again. - - -File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks - -VxWorks download -................ - -If you have connected to the VxWorks target and you want to debug an -object that has not yet been loaded, you can use the GDB `load' command -to download a file from Unix to VxWorks incrementally. The object file -given as an argument to the `load' command is actually opened twice: -first by the VxWorks target in order to download the code, then by GDB -in order to read the symbol table. This can lead to problems if the -current working directories on the two systems differ. If both systems -have NFS mounted the same filesystems, you can avoid these problems by -using absolute paths. Otherwise, it is simplest to set the working -directory on both systems to the directory in which the object file -resides, and then to reference the file by its name, without any path. -For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in -VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this -program, type this on VxWorks: - - -> cd "VXPATH/vw/demo/rdb" - -Then, in GDB, type: - - (vxgdb) cd HOSTPATH/vw/demo/rdb - (vxgdb) load prog.o - - GDB displays a response similar to this: - - Reading symbol data from wherever/vw/demo/rdb/prog.o... done. - - You can also use the `load' command to reload an object module after -editing and recompiling the corresponding source file. Note that this -makes GDB delete all currently-defined breakpoints, auto-displays, and -convenience variables, and to clear the value history. (This is -necessary in order to preserve the integrity of debugger's data -structures that reference the target system's symbol table.) - - -File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks - -Running tasks -............. - -You can also attach to an existing task using the `attach' command as -follows: - - (vxgdb) attach TASK - -where TASK is the VxWorks hexadecimal task ID. The task can be running -or suspended when you attach to it. Running tasks are suspended at the -time of attachment. - - -File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations - -Embedded Processors -=================== - -This section goes into details specific to particular embedded -configurations. - -* Menu: - -* ARM:: ARM -* H8/300:: Renesas H8/300 -* H8/500:: Renesas H8/500 -* M32R/D:: Renesas M32R/D -* M68K:: Motorola M68K -* MIPS Embedded:: MIPS Embedded -* OpenRISC 1000:: OpenRisc 1000 -* PA:: HP PA Embedded -* PowerPC: PowerPC -* SH:: Renesas SH -* Sparclet:: Tsqware Sparclet -* Sparclite:: Fujitsu Sparclite -* ST2000:: Tandem ST2000 -* Z8000:: Zilog Z8000 - - -File: gdb.info, Node: ARM, Next: H8/300, Up: Embedded Processors - -ARM ---- - -`target rdi DEV' - ARM Angel monitor, via RDI library interface to ADP protocol. You - may use this target to communicate with both boards running the - Angel monitor, or with the EmbeddedICE JTAG debug device. - -`target rdp DEV' - ARM Demon monitor. - - - -File: gdb.info, Node: H8/300, Next: H8/500, Prev: ARM, Up: Embedded Processors - -Renesas H8/300 --------------- - -`target hms DEV' - A Renesas SH, H8/300, or H8/500 board, attached via serial line to - your host. Use special commands `device' and `speed' to control - the serial line and the communications speed used. - -`target e7000 DEV' - E7000 emulator for Renesas H8 and SH. - -`target sh3 DEV' -`target sh3e DEV' - Renesas SH-3 and SH-3E target systems. - - - When you select remote debugging to a Renesas SH, H8/300, or H8/500 -board, the `load' command downloads your program to the Renesas board -and also opens it as the current executable target for GDB on your host -(like the `file' command). - - GDB needs to know these things to talk to your Renesas SH, H8/300, -or H8/500: - - 1. that you want to use `target hms', the remote debugging interface - for Renesas microprocessors, or `target e7000', the in-circuit - emulator for the Renesas SH and the Renesas 300H. (`target hms' is - the default when GDB is configured specifically for the Renesas SH, - H8/300, or H8/500.) - - 2. what serial device connects your host to your Renesas board (the - first serial device available on your host is the default). - - 3. what speed to use over the serial device. - -* Menu: - -* Renesas Boards:: Connecting to Renesas boards. -* Renesas ICE:: Using the E7000 In-Circuit Emulator. -* Renesas Special:: Special GDB commands for Renesas micros. - - -File: gdb.info, Node: Renesas Boards, Next: Renesas ICE, Up: H8/300 - -Connecting to Renesas boards -............................ - -Use the special `GDB' command `device PORT' if you need to explicitly -set the serial device. The default PORT is the first available port on -your host. This is only necessary on Unix hosts, where it is typically -something like `/dev/ttya'. - - `GDB' has another special command to set the communications speed: -`speed BPS'. This command also is only used from Unix hosts; on DOS -hosts, set the line speed as usual from outside GDB with the DOS `mode' -command (for instance, `mode com2:9600,n,8,1,p' for a 9600bps -connection). - - The `device' and `speed' commands are available only when you use a -Unix host to debug your Renesas microprocessor programs. If you use a -DOS host, GDB depends on an auxiliary terminate-and-stay-resident -program called `asynctsr' to communicate with the development board -through a PC serial port. You must also use the DOS `mode' command to -set up the serial port on the DOS side. - - The following sample session illustrates the steps needed to start a -program under GDB control on an H8/300. The example uses a sample -H8/300 program called `t.x'. The procedure is the same for the Renesas -SH and the H8/500. - - First hook up your development board. In this example, we use a -board attached to serial port `COM2'; if you use a different serial -port, substitute its name in the argument of the `mode' command. When -you call `asynctsr', the auxiliary comms program used by the debugger, -you give it just the numeric part of the serial port's name; for -example, `asyncstr 2' below runs `asyncstr' on `COM2'. - - C:\H8300\TEST> asynctsr 2 - C:\H8300\TEST> mode com2:9600,n,8,1,p - - Resident portion of MODE loaded - - COM2: 9600, n, 8, 1, p - - _Warning:_ We have noticed a bug in PC-NFS that conflicts with - `asynctsr'. If you also run PC-NFS on your DOS host, you may need - to disable it, or even boot without it, to use `asynctsr' to - control your development board. - - Now that serial communications are set up, and the development board -is connected, you can start up GDB. Call `gdb' with the name of your -program as the argument. `GDB' prompts you, as usual, with the prompt -`(gdb)'. Use two special commands to begin your debugging session: -`target hms' to specify cross-debugging to the Renesas board, and the -`load' command to download your program to the board. `load' displays -the names of the program's sections, and a `*' for each 2K of data -downloaded. (If you want to refresh GDB data on symbols or on the -executable file without downloading, use the GDB commands `file' or -`symbol-file'. These commands, and `load' itself, are described in -*Note Commands to specify files: Files.) - - (eg-C:\H8300\TEST) gdb t.x - GDB is free software and you are welcome to distribute copies - of it under certain conditions; type "show copying" to see - the conditions. - There is absolutely no warranty for GDB; type "show warranty" - for details. - GDB 6.1.1, Copyright 1992 Free Software Foundation, Inc... - (gdb) target hms - Connected to remote H8/300 HMS system. - (gdb) load t.x - .text : 0x8000 .. 0xabde *********** - .data : 0xabde .. 0xad30 * - .stack : 0xf000 .. 0xf014 * - - At this point, you're ready to run or debug your program. From here -on, you can use all the usual GDB commands. The `break' command sets -breakpoints; the `run' command starts your program; `print' or `x' -display data; the `continue' command resumes execution after stopping -at a breakpoint. You can use the `help' command at any time to find -out more about GDB commands. - - Remember, however, that _operating system_ facilities aren't -available on your development board; for example, if your program hangs, -you can't send an interrupt--but you can press the RESET switch! - - Use the RESET button on the development board - * to interrupt your program (don't use `ctl-C' on the DOS host--it - has no way to pass an interrupt signal to the development board); - and - - * to return to the GDB command prompt after your program finishes - normally. The communications protocol provides no other way for - GDB to detect program completion. - - In either case, GDB sees the effect of a RESET on the development -board as a "normal exit" of your program. - - -File: gdb.info, Node: Renesas ICE, Next: Renesas Special, Prev: Renesas Boards, Up: H8/300 - -Using the E7000 in-circuit emulator -................................... - -You can use the E7000 in-circuit emulator to develop code for either the -Renesas SH or the H8/300H. Use one of these forms of the `target -e7000' command to connect GDB to your E7000: - -`target e7000 PORT SPEED' - Use this form if your E7000 is connected to a serial port. The - PORT argument identifies what serial port to use (for example, - `com2'). The third argument is the line speed in bits per second - (for example, `9600'). - -`target e7000 HOSTNAME' - If your E7000 is installed as a host on a TCP/IP network, you can - just specify its hostname; GDB uses `telnet' to connect. - - -File: gdb.info, Node: Renesas Special, Prev: Renesas ICE, Up: H8/300 - -Special GDB commands for Renesas micros -....................................... - -Some GDB commands are available only for the H8/300: - -`set machine h8300' -`set machine h8300h' - Condition GDB for one of the two variants of the H8/300 - architecture with `set machine'. You can use `show machine' to - check which variant is currently in effect. - - - -File: gdb.info, Node: H8/500, Next: M32R/D, Prev: H8/300, Up: Embedded Processors - -H8/500 ------- - -`set memory MOD' -`show memory' - Specify which H8/500 memory model (MOD) you are using with `set - memory'; check which memory model is in effect with `show memory'. - The accepted values for MOD are `small', `big', `medium', and - `compact'. - - - -File: gdb.info, Node: M32R/D, Next: M68K, Prev: H8/500, Up: Embedded Processors - -Renesas M32R/D --------------- - -`target m32r DEV' - Renesas M32R/D ROM monitor. - -`target m32rsdi DEV' - Renesas M32R SDI server, connected via parallel port to the board. - - - -File: gdb.info, Node: M68K, Next: MIPS Embedded, Prev: M32R/D, Up: Embedded Processors - -M68k ----- - -The Motorola m68k configuration includes ColdFire support, and target -command for the following ROM monitors. - -`target abug DEV' - ABug ROM monitor for M68K. - -`target cpu32bug DEV' - CPU32BUG monitor, running on a CPU32 (M68K) board. - -`target dbug DEV' - dBUG ROM monitor for Motorola ColdFire. - -`target est DEV' - EST-300 ICE monitor, running on a CPU32 (M68K) board. - -`target rom68k DEV' - ROM 68K monitor, running on an M68K IDP board. - - -`target rombug DEV' - ROMBUG ROM monitor for OS/9000. - - - -File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: M68K, Up: Embedded Processors - -MIPS Embedded -------------- - -GDB can use the MIPS remote debugging protocol to talk to a MIPS board -attached to a serial line. This is available when you configure GDB -with `--target=mips-idt-ecoff'. - - Use these GDB commands to specify the connection to your target -board: - -`target mips PORT' - To run a program on the board, start up `gdb' with the name of - your program as the argument. To connect to the board, use the - command `target mips PORT', where PORT is the name of the serial - port connected to the board. If the program has not already been - downloaded to the board, you may use the `load' command to - download it. You can then use all the usual GDB commands. - - For example, this sequence connects to the target board through a - serial port, and loads and runs a program called PROG through the - debugger: - - host$ gdb PROG - GDB is free software and ... - (gdb) target mips /dev/ttyb - (gdb) load PROG - (gdb) run - -`target mips HOSTNAME:PORTNUMBER' - On some GDB host configurations, you can specify a TCP connection - (for instance, to a serial line managed by a terminal - concentrator) instead of a serial port, using the syntax - `HOSTNAME:PORTNUMBER'. - -`target pmon PORT' - PMON ROM monitor. - -`target ddb PORT' - NEC's DDB variant of PMON for Vr4300. - -`target lsi PORT' - LSI variant of PMON. - -`target r3900 DEV' - Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. - -`target array DEV' - Array Tech LSI33K RAID controller board. - - -GDB also supports these special commands for MIPS targets: - -`set processor ARGS' -`show processor' - Use the `set processor' command to set the type of MIPS processor - when you want to access processor-type-specific registers. For - example, `set processor R3041' tells GDB to use the CPU registers - appropriate for the 3041 chip. Use the `show processor' command - to see what MIPS processor GDB is using. Use the `info reg' - command to see what registers GDB is using. - -`set mipsfpu double' -`set mipsfpu single' -`set mipsfpu none' -`show mipsfpu' - If your target board does not support the MIPS floating point - coprocessor, you should use the command `set mipsfpu none' (if you - need this, you may wish to put the command in your GDB init file). - This tells GDB how to find the return value of functions which - return floating point values. It also allows GDB to avoid saving - the floating point registers when calling functions on the board. - If you are using a floating point coprocessor with only single - precision floating point support, as on the R4650 processor, use - the command `set mipsfpu single'. The default double precision - floating point coprocessor may be selected using `set mipsfpu - double'. - - In previous versions the only choices were double precision or no - floating point, so `set mipsfpu on' will select double precision - and `set mipsfpu off' will select no floating point. - - As usual, you can inquire about the `mipsfpu' variable with `show - mipsfpu'. - -`set remotedebug N' -`show remotedebug' - You can see some debugging information about communications with - the board by setting the `remotedebug' variable. If you set it to - `1' using `set remotedebug 1', every packet is displayed. If you - set it to `2', every character is displayed. You can check the - current value at any time with the command `show remotedebug'. - -`set timeout SECONDS' -`set retransmit-timeout SECONDS' -`show timeout' -`show retransmit-timeout' - You can control the timeout used while waiting for a packet, in - the MIPS remote protocol, with the `set timeout SECONDS' command. - The default is 5 seconds. Similarly, you can control the timeout - used while waiting for an acknowledgement of a packet with the `set - retransmit-timeout SECONDS' command. The default is 3 seconds. - You can inspect both values with `show timeout' and `show - retransmit-timeout'. (These commands are _only_ available when - GDB is configured for `--target=mips-idt-ecoff'.) - - The timeout set by `set timeout' does not apply when GDB is - waiting for your program to stop. In that case, GDB waits forever - because it has no way of knowing how long the program is going to - run before stopping. - - -File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors - -OpenRISC 1000 -------------- - -See OR1k Architecture document (`www.opencores.org') for more -information about platform and commands. - -`target jtag jtag://HOST:PORT' - Connects to remote JTAG server. JTAG remote server can be either - an or1ksim or JTAG server, connected via parallel port to the - board. - - Example: `target jtag jtag://localhost:9999' - -`or1ksim COMMAND' - If connected to `or1ksim' OpenRISC 1000 Architectural Simulator, - proprietary commands can be executed. - -`info or1k spr' - Displays spr groups. - -`info or1k spr GROUP' -`info or1k spr GROUPNO' - Displays register names in selected group. - -`info or1k spr GROUP REGISTER' -`info or1k spr REGISTER' -`info or1k spr GROUPNO REGISTERNO' -`info or1k spr REGISTERNO' - Shows information about specified spr register. - -`spr GROUP REGISTER VALUE' -`spr REGISTER VALUE' -`spr GROUPNO REGISTERNO VALUE' -`spr REGISTERNO VALUE' - Writes VALUE to specified spr register. - - Some implementations of OpenRISC 1000 Architecture also have -hardware trace. It is very similar to GDB trace, except it does not -interfere with normal program execution and is thus much faster. -Hardware breakpoints/watchpoint triggers can be set using: -`$LEA/$LDATA' - Load effective address/data - -`$SEA/$SDATA' - Store effective address/data - -`$AEA/$ADATA' - Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) - -`$FETCH' - Fetch data - - When triggered, it can capture low level data, like: `PC', `LSEA', -`LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'. - - `htrace' commands: -`hwatch CONDITIONAL' - Set hardware watchpoint on combination of Load/Store Effecive - Address(es) or Data. For example: - - `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && - ($SDATA >= 50)' - - `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && - ($SDATA >= 50)' - -`htrace info' - Display information about current HW trace configuration. - -`htrace trigger CONDITIONAL' - Set starting criteria for HW trace. - -`htrace qualifier CONDITIONAL' - Set acquisition qualifier for HW trace. - -`htrace stop CONDITIONAL' - Set HW trace stopping criteria. - -`htrace record [DATA]*' - Selects the data to be recorded, when qualifier is met and HW - trace was triggered. - -`htrace enable' -`htrace disable' - Enables/disables the HW trace. - -`htrace rewind [FILENAME]' - Clears currently recorded trace data. - - If filename is specified, new trace file is made and any newly - collected data will be written there. - -`htrace print [START [LEN]]' - Prints trace buffer, using current record configuration. - -`htrace mode continuous' - Set continuous trace mode. - -`htrace mode suspend' - Set suspend trace mode. - - - -File: gdb.info, Node: PowerPC, Next: SH, Prev: PA, Up: Embedded Processors - -PowerPC -------- - -`target dink32 DEV' - DINK32 ROM monitor. - -`target ppcbug DEV' - -`target ppcbug1 DEV' - PPCBUG ROM monitor for PowerPC. - -`target sds DEV' - SDS monitor, running on a PowerPC board (such as Motorola's ADS). - - - -File: gdb.info, Node: PA, Next: PowerPC, Prev: OpenRISC 1000, Up: Embedded Processors - -HP PA Embedded --------------- - -`target op50n DEV' - OP50N monitor, running on an OKI HPPA board. - -`target w89k DEV' - W89K monitor, running on a Winbond HPPA board. - - - -File: gdb.info, Node: SH, Next: Sparclet, Prev: PowerPC, Up: Embedded Processors - -Renesas SH ----------- - -`target hms DEV' - A Renesas SH board attached via serial line to your host. Use - special commands `device' and `speed' to control the serial line - and the communications speed used. - -`target e7000 DEV' - E7000 emulator for Renesas SH. - -`target sh3 DEV' - -`target sh3e DEV' - Renesas SH-3 and SH-3E target systems. - - - -File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: SH, Up: Embedded Processors - -Tsqware Sparclet ----------------- - -GDB enables developers to debug tasks running on Sparclet targets from -a Unix host. GDB uses code that runs on both the Unix host and on the -Sparclet target. The program `gdb' is installed and executed on the -Unix host. - -`remotetimeout ARGS' - GDB supports the option `remotetimeout'. This option is set by - the user, and ARGS represents the number of seconds GDB waits for - responses. - - When compiling for debugging, include the options `-g' to get debug -information and `-Ttext' to relocate the program to where you wish to -load it on the target. You may also want to add the options `-n' or -`-N' in order to reduce the size of the sections. Example: - - sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N - - You can use `objdump' to verify that the addresses are what you -intended: - - sparclet-aout-objdump --headers --syms prog - - Once you have set your Unix execution search path to find GDB, you -are ready to run GDB. From your Unix host, run `gdb' (or -`sparclet-aout-gdb', depending on your installation). - - GDB comes up showing the prompt: - - (gdbslet) - -* Menu: - -* Sparclet File:: Setting the file to debug -* Sparclet Connection:: Connecting to Sparclet -* Sparclet Download:: Sparclet download -* Sparclet Execution:: Running and debugging - - -File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet - -Setting file to debug -..................... - -The GDB command `file' lets you choose with program to debug. - - (gdbslet) file prog - - GDB then attempts to read the symbol table of `prog'. GDB locates -the file by searching the directories listed in the command search path. -If the file was compiled with debug information (option "-g"), source -files will be searched as well. GDB locates the source files by -searching the directories listed in the directory search path (*note -Your program's environment: Environment.). If it fails to find a file, -it displays a message such as: - - prog: No such file or directory. - - When this happens, add the appropriate directories to the search -paths with the GDB commands `path' and `dir', and execute the `target' -command again. - - -File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet - -Connecting to Sparclet -...................... - -The GDB command `target' lets you connect to a Sparclet target. To -connect to a target on serial port "`ttya'", type: - - (gdbslet) target sparclet /dev/ttya - Remote target sparclet connected to /dev/ttya - main () at ../prog.c:3 - - GDB displays messages like these: - - Connected to ttya. - - -File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet - -Sparclet download -................. - -Once connected to the Sparclet target, you can use the GDB `load' -command to download the file from the host to the target. The file -name and load offset should be given as arguments to the `load' command. -Since the file format is aout, the program must be loaded to the -starting address. You can use `objdump' to find out what this value -is. The load offset is an offset which is added to the VMA (virtual -memory address) of each of the file's sections. For instance, if the -program `prog' was linked to text address 0x1201000, with data at -0x12010160 and bss at 0x12010170, in GDB, type: - - (gdbslet) load prog 0x12010000 - Loading section .text, size 0xdb0 vma 0x12010000 - - If the code is loaded at a different address then what the program -was linked to, you may need to use the `section' and `add-symbol-file' -commands to tell GDB where to map the symbol table. - - -File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet - -Running and debugging -..................... - -You can now begin debugging the task using GDB's execution control -commands, `b', `step', `run', etc. See the GDB manual for the list of -commands. - - (gdbslet) b main - Breakpoint 1 at 0x12010000: file prog.c, line 3. - (gdbslet) run - Starting program: prog - Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 - 3 char *symarg = 0; - (gdbslet) step - 4 char *execarg = "hello!"; - (gdbslet) - - -File: gdb.info, Node: Sparclite, Next: ST2000, Prev: Sparclet, Up: Embedded Processors - -Fujitsu Sparclite ------------------ - -`target sparclite DEV' - Fujitsu sparclite boards, used only for the purpose of loading. - You must use an additional command to debug the program. For - example: target remote DEV using GDB standard remote protocol. - - - -File: gdb.info, Node: ST2000, Next: Z8000, Prev: Sparclite, Up: Embedded Processors - -Tandem ST2000 -------------- - -GDB may be used with a Tandem ST2000 phone switch, running Tandem's -STDBUG protocol. - - To connect your ST2000 to the host system, see the manufacturer's -manual. Once the ST2000 is physically attached, you can run: - - target st2000 DEV SPEED - -to establish it as your debugging environment. DEV is normally the -name of a serial device, such as `/dev/ttya', connected to the ST2000 -via a serial line. You can instead specify DEV as a TCP connection -(for example, to a serial line attached via a terminal concentrator) -using the syntax `HOSTNAME:PORTNUMBER'. - - The `load' and `attach' commands are _not_ defined for this target; -you must load your program into the ST2000 as you normally would for -standalone operation. GDB reads debugging information (such as -symbols) from a separate, debugging version of the program available on -your host computer. - - These auxiliary GDB commands are available to help you with the -ST2000 environment: - -`st2000 COMMAND' - Send a COMMAND to the STDBUG monitor. See the manufacturer's - manual for available commands. - -`connect' - Connect the controlling terminal to the STDBUG command monitor. - When you are done interacting with STDBUG, typing either of two - character sequences gets you back to the GDB command prompt: - `<RET>~.' (Return, followed by tilde and period) or `<RET>~<C-d>' - (Return, followed by tilde and control-D). - - -File: gdb.info, Node: Z8000, Prev: ST2000, Up: Embedded Processors - -Zilog Z8000 ------------ - -When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 -simulator. - - For the Z8000 family, `target sim' simulates either the Z8002 (the -unsegmented variant of the Z8000 architecture) or the Z8001 (the -segmented variant). The simulator recognizes which architecture is -appropriate by inspecting the object code. - -`target sim ARGS' - Debug programs on a simulated CPU. If the simulator supports setup - options, specify them via ARGS. - -After specifying this target, you can debug programs for the simulated -CPU in the same style as programs for your host computer; use the -`file' command to load a new program image, the `run' command to run -your program, and so on. - - As well as making available all the usual machine registers (*note -Registers: Registers.), the Z8000 simulator provides three additional -items of information as specially named registers: - -`cycles' - Counts clock-ticks in the simulator. - -`insts' - Counts instructions run in the simulator. - -`time' - Execution time in 60ths of a second. - - - You can refer to these values in GDB expressions with the usual -conventions; for example, `b fputc if $cycles>5000' sets a conditional -breakpoint that suspends only after at least 5000 simulated clock ticks. - - -File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations - -Architectures -============= - -This section describes characteristics of architectures that affect all -uses of GDB with the architecture, both native and cross. - -* Menu: - -* A29K:: -* Alpha:: -* MIPS:: - - -File: gdb.info, Node: A29K, Next: Alpha, Up: Architectures - -A29K ----- - -`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 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. - - - -File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures - -Alpha ------ - -See the following section. - - -File: gdb.info, Node: MIPS, Prev: Alpha, Up: Architectures - -MIPS ----- - -Alpha- and MIPS-based computers use an unusual stack frame, which -sometimes requires GDB to search backward in the object code to find -the beginning of a function. - - To improve response time (especially for embedded applications, where -GDB may be restricted to a slow serial line for this search) you may -want to limit the size of this search, using one of these commands: - -`set heuristic-fence-post LIMIT' - Restrict GDB to examining at most LIMIT bytes in its search for - the beginning of a function. A value of 0 (the default) means - there is no limit. However, except for 0, the larger the limit - the more bytes `heuristic-fence-post' must search and therefore - the longer it takes to run. - -`show heuristic-fence-post' - Display the current limit. - -These commands are available _only_ when GDB is configured for -debugging programs on Alpha or MIPS processors. - - -File: gdb.info, Node: Controlling GDB, Next: Sequences, Prev: Configurations, Up: Top - -Controlling GDB -*************** - -You can alter the way GDB interacts with you by using the `set' -command. For commands controlling how GDB displays data, see *Note -Print settings: Print Settings. Other settings are described here. - -* Menu: - -* Prompt:: Prompt -* Editing:: Command editing -* History:: Command history -* Screen Size:: Screen size -* Numbers:: Numbers -* ABI:: Configuring the current ABI -* Messages/Warnings:: Optional warnings and messages -* Debugging Output:: Optional messages about internal happenings - - -File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB - -Prompt -====== - -GDB indicates its readiness to read a command by printing a string -called the "prompt". This string is normally `(gdb)'. You can change -the prompt string with the `set prompt' command. For instance, when -debugging GDB with GDB, it is useful to change the prompt in one of the -GDB sessions so that you can always tell which one you are talking to. - - _Note:_ `set prompt' does not add a space for you after the prompt -you set. This allows you to set a prompt which ends in a space or a -prompt that does not. - -`set prompt NEWPROMPT' - Directs GDB to use NEWPROMPT as its prompt string henceforth. - -`show prompt' - Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT' - - -File: gdb.info, Node: Editing, Next: History, Prev: Prompt, Up: Controlling GDB - -Command editing -=============== - -GDB reads its input commands via the "readline" interface. This GNU -library provides consistent behavior for programs which provide a -command line interface to the user. Advantages are GNU Emacs-style or -"vi"-style inline editing of commands, `csh'-like history substitution, -and a storage and recall of command history across debugging sessions. - - You may control the behavior of command line editing in GDB with the -command `set'. - -`set editing' -`set editing on' - Enable command line editing (enabled by default). - -`set editing off' - Disable command line editing. - -`show editing' - Show whether command line editing is enabled. - - -File: gdb.info, Node: History, Next: Screen Size, Prev: Editing, Up: Controlling GDB - -Command history -=============== - -GDB can keep track of the commands you type during your debugging -sessions, so that you can be certain of precisely what happened. Use -these commands to manage the GDB command history facility. - -`set history filename FNAME' - Set the name of the GDB command history file to FNAME. This is - the file where GDB reads an initial command history list, and - where it writes the command history from this session when it - exits. You can access this list through history expansion or - through the history command editing characters listed below. This - file defaults to the value of the environment variable - `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS) - if this variable is not set. - -`set history save' -`set history save on' - Record command history in a file, whose name may be specified with - the `set history filename' command. By default, this option is - disabled. - -`set history save off' - Stop recording command history in a file. - -`set history size SIZE' - Set the number of commands which GDB keeps in its history list. - This defaults to the value of the environment variable `HISTSIZE', - or to 256 if this variable is not set. - - History expansion assigns special meaning to the character `!'. - - Since `!' is also the logical not operator in C, history expansion -is off by default. If you decide to enable history expansion with the -`set history expansion on' command, you may sometimes need to follow -`!' (when it is used as logical not, in an expression) with a space or -a tab to prevent it from being expanded. The readline history -facilities do not attempt substitution on the strings `!=' and `!(', -even when history expansion is enabled. - - The commands to control history expansion are: - -`set history expansion on' -`set history expansion' - Enable history expansion. History expansion is off by default. - -`set history expansion off' - Disable history expansion. - - The readline code comes with more complete documentation of - editing and history expansion features. Users unfamiliar with GNU - Emacs or `vi' may wish to read it. - -`show history' -`show history filename' -`show history save' -`show history size' -`show history expansion' - These commands display the state of the GDB history parameters. - `show history' by itself displays all four states. - -`show commands' - Display the last ten commands in the command history. - -`show commands N' - Print ten commands centered on command number N. - -`show commands +' - Print ten commands just after the commands last printed. - - -File: gdb.info, Node: Screen Size, Next: Numbers, Prev: History, Up: Controlling GDB - -Screen size -=========== - -Certain commands to GDB may produce large amounts of information output -to the screen. To help you read all of it, GDB pauses and asks you for -input at the end of each page of output. Type <RET> when you want to -continue the output, or `q' to discard the remaining output. Also, the -screen width setting determines when to wrap lines of output. -Depending on what is being printed, GDB tries to break the line at a -readable place, rather than simply letting it overflow onto the -following line. - - Normally GDB knows the size of the screen from the terminal driver -software. For example, on Unix GDB uses the termcap data base together -with the value of the `TERM' environment variable and the `stty rows' -and `stty cols' settings. If this is not correct, you can override it -with the `set height' and `set width' commands: - -`set height LPP' -`show height' -`set width CPL' -`show width' - These `set' commands specify a screen height of LPP lines and a - screen width of CPL characters. The associated `show' commands - display the current settings. - - If you specify a height of zero lines, GDB does not pause during - output no matter how long the output is. This is useful if output - is to a file or to an editor buffer. - - Likewise, you can specify `set width 0' to prevent GDB from - wrapping its output. - - -File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB - -Numbers -======= - -You can always enter numbers in octal, decimal, or hexadecimal in GDB -by the usual conventions: octal numbers begin with `0', decimal numbers -end with `.', and hexadecimal numbers begin with `0x'. Numbers that -begin with none of these are, by default, entered in base 10; likewise, -the default display for numbers--when no particular format is -specified--is base 10. You can change the default base for both input -and output with the `set radix' command. - -`set input-radix BASE' - Set the default base for numeric input. Supported choices for - BASE are decimal 8, 10, or 16. BASE must itself be specified - either unambiguously or using the current default radix; for - example, any of - - set radix 012 - set radix 10. - set radix 0xa - - sets the base to decimal. On the other hand, `set radix 10' - leaves the radix unchanged no matter what it was. - -`set output-radix BASE' - Set the default base for numeric display. Supported choices for - BASE are decimal 8, 10, or 16. BASE must itself be specified - either unambiguously or using the current default radix. - -`show input-radix' - Display the current default base for numeric input. - -`show output-radix' - Display the current default base for numeric display. - - -File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB - -Configuring the current ABI -=========================== - -GDB can determine the "ABI" (Application Binary Interface) of your -application automatically. However, sometimes you need to override its -conclusions. Use these commands to manage GDB's view of the current -ABI. - - One GDB configuration can debug binaries for multiple operating -system targets, either via remote debugging or native emulation. GDB -will autodetect the "OS ABI" (Operating System ABI) in use, but you can -override its conclusion using the `set osabi' command. One example -where this is useful is in debugging of binaries which use an alternate -C library (e.g. UCLIBC for GNU/Linux) which does not have the same -identifying marks that the standard C library for your platform -provides. - -`show osabi' - Show the OS ABI currently in use. - -`set osabi' - With no argument, show the list of registered available OS ABI's. - -`set osabi ABI' - Set the current OS ABI to ABI. - - Generally, the way that an argument of type `float' is passed to a -function depends on whether the function is prototyped. For a -prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed -unchanged, according to the architecture's convention for `float'. For -unprototyped (i.e. K&R style) functions, `float' arguments are first -promoted to type `double' and then passed. - - Unfortunately, some forms of debug information do not reliably -indicate whether a function is prototyped. If GDB calls a function -that is not marked as prototyped, it consults `set -coerce-float-to-double'. - -`set coerce-float-to-double' -`set coerce-float-to-double on' - Arguments of type `float' will be promoted to `double' when passed - to an unprototyped function. This is the default setting. - -`set coerce-float-to-double off' - Arguments of type `float' will be passed directly to unprototyped - functions. - - GDB needs to know the ABI used for your program's C++ objects. The -correct C++ ABI depends on which C++ compiler was used to build your -application. GDB only fully supports programs with a single C++ ABI; -if your program contains code using multiple C++ ABI's or if GDB can -not identify your program's ABI correctly, you can tell GDB which ABI -to use. Currently supported ABI's include "gnu-v2", for `g++' versions -before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for -the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or -"gnu-v3" ABI's as well. The default setting is "auto". - -`show cp-abi' - Show the C++ ABI currently in use. - -`set cp-abi' - With no argument, show the list of supported C++ ABI's. - -`set cp-abi ABI' -`set cp-abi auto' - Set the current C++ ABI to ABI, or return to automatic detection. - - -File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB - -Optional warnings and messages -============================== - -By default, GDB is silent about its inner workings. If you are running -on a slow machine, you may want to use the `set verbose' command. This -makes GDB tell you when it does a lengthy internal operation, so you -will not think it has crashed. - - Currently, the messages controlled by `set verbose' are those which -announce that the symbol table for a source file is being read; see -`symbol-file' in *Note Commands to specify files: Files. - -`set verbose on' - Enables GDB output of certain informational messages. - -`set verbose off' - Disables GDB output of certain informational messages. - -`show verbose' - Displays whether `set verbose' is on or off. - - By default, if GDB encounters bugs in the symbol table of an object -file, it is silent; but if you are debugging a compiler, you may find -this information useful (*note Errors reading symbol files: Symbol -Errors.). - -`set complaints LIMIT' - Permits GDB to output LIMIT complaints about each type of unusual - symbols before becoming silent about the problem. Set LIMIT to - zero to suppress all complaints; set it to a large number to - prevent complaints from being suppressed. - -`show complaints' - Displays how many symbol complaints GDB is permitted to produce. - - - By default, GDB is cautious, and asks what sometimes seems to be a -lot of stupid questions to confirm certain commands. For example, if -you try to run a program which is already running: - - (gdb) run - The program being debugged has been started already. - Start it from the beginning? (y or n) - - If you are willing to unflinchingly face the consequences of your own -commands, you can disable this "feature": - -`set confirm off' - Disables confirmation requests. - -`set confirm on' - Enables confirmation requests (the default). - -`show confirm' - Displays state of confirmation requests. - - - -File: gdb.info, Node: Debugging Output, Prev: Messages/Warnings, Up: Controlling GDB - -Optional messages about internal happenings -=========================================== - -`set debug arch' - Turns on or off display of gdbarch debugging info. The default is - off - -`show debug arch' - Displays the current state of displaying gdbarch debugging info. - -`set debug event' - Turns on or off display of GDB event debugging info. The default - is off. - -`show debug event' - Displays the current state of displaying GDB event debugging info. - -`set debug expression' - Turns on or off display of GDB expression debugging info. The - default is off. - -`show debug expression' - Displays the current state of displaying GDB expression debugging - info. - -`set debug frame' - Turns on or off display of GDB frame debugging info. The default - is off. - -`show debug frame' - Displays the current state of displaying GDB frame debugging info. - -`set debug overload' - Turns on or off display of GDB C++ overload debugging info. This - includes info such as ranking of functions, etc. The default is - off. - -`show debug overload' - Displays the current state of displaying GDB C++ overload - debugging info. - -`set debug remote' - Turns on or off display of reports on all packets sent back and - forth across the serial line to the remote machine. The info is - printed on the GDB standard output stream. The default is off. - -`show debug remote' - Displays the state of display of remote packets. - -`set debug serial' - Turns on or off display of GDB serial debugging info. The default - is off. - -`show debug serial' - Displays the current state of displaying GDB serial debugging info. - -`set debug target' - Turns on or off display of GDB target debugging info. This info - includes what is going on at the target level of GDB, as it - happens. The default is off. - -`show debug target' - Displays the current state of displaying GDB target debugging info. - -`set debug varobj' - Turns on or off display of GDB variable object debugging info. The - default is off. - -`show debug varobj' - Displays the current state of displaying GDB variable object - debugging info. - - -File: gdb.info, Node: Sequences, Next: TUI, Prev: Controlling GDB, Up: Top - -Canned Sequences of Commands -**************************** - -Aside from breakpoint commands (*note Breakpoint command lists: Break -Commands.), GDB provides two ways to store sequences of commands for -execution as a unit: user-defined commands and command files. - -* Menu: - -* Define:: User-defined commands -* Hooks:: User-defined command hooks -* Command Files:: Command files -* Output:: Commands for controlled output - - -File: gdb.info, Node: Define, Next: Hooks, Up: Sequences - -User-defined commands -===================== - -A "user-defined command" is a sequence of GDB commands to which you -assign a new name as a command. This is done with the `define' -command. User commands may accept up to 10 arguments separated by -whitespace. Arguments are accessed within the user command via -$ARG0...$ARG9. A trivial example: - - define adder - print $arg0 + $arg1 + $arg2 - -To execute the command use: - - adder 1 2 3 - -This defines the command `adder', which prints the sum of its three -arguments. Note the arguments are text substitutions, so they may -reference variables, use complex expressions, or even perform inferior -functions calls. - -`define COMMANDNAME' - Define a command named COMMANDNAME. If there is already a command - by that name, you are asked to confirm that you want to redefine - it. - - The definition of the command is made up of other GDB command - lines, which are given following the `define' command. The end of - these commands is marked by a line containing `end'. - -`if' - Takes a single argument, which is an expression to evaluate. It - is followed by a series of commands that are executed only if the - expression is true (nonzero). There can then optionally be a line - `else', followed by a series of commands that are only executed if - the expression was false. The end of the list is marked by a line - containing `end'. - -`while' - The syntax is similar to `if': the command takes a single argument, - which is an expression to evaluate, and must be followed by the - commands to execute, one per line, terminated by an `end'. The - commands are executed repeatedly as long as the expression - evaluates to true. - -`document COMMANDNAME' - Document the user-defined command COMMANDNAME, so that it can be - accessed by `help'. The command COMMANDNAME must already be - defined. This command reads lines of documentation just as - `define' reads the lines of the command definition, ending with - `end'. After the `document' command is finished, `help' on command - COMMANDNAME displays the documentation you have written. - - You may use the `document' command again to change the - documentation of a command. Redefining the command with `define' - does not change the documentation. - -`help user-defined' - List all user-defined commands, with the first line of the - documentation (if any) for each. - -`show user' -`show user COMMANDNAME' - Display the GDB commands used to define COMMANDNAME (but not its - documentation). If no COMMANDNAME is given, display the - definitions for all user-defined commands. - -`show max-user-call-depth' -`set max-user-call-depth' - The value of `max-user-call-depth' controls how many recursion - levels are allowed in user-defined commands before GDB suspects an - infinite recursion and aborts the command. - - - When user-defined commands are executed, the commands of the -definition are not printed. An error in any command stops execution of -the user-defined command. - - If used interactively, commands that would ask for confirmation -proceed without asking when used inside a user-defined command. Many -GDB commands that normally print messages to say what they are doing -omit the messages when used in a user-defined command. - - -File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences - -User-defined command hooks -========================== - -You may define "hooks", which are a special kind of user-defined -command. Whenever you run the command `foo', if the user-defined -command `hook-foo' exists, it is executed (with no arguments) before -that command. - - A hook may also be defined which is run after the command you -executed. Whenever you run the command `foo', if the user-defined -command `hookpost-foo' exists, it is executed (with no arguments) after -that command. Post-execution hooks may exist simultaneously with -pre-execution hooks, for the same command. - - It is valid for a hook to call the command which it hooks. If this -occurs, the hook is not re-executed, thereby avoiding infinte recursion. - - In addition, a pseudo-command, `stop' exists. Defining -(`hook-stop') makes the associated commands execute every time -execution stops in your program: before breakpoint commands are run, -displays are printed, or the stack frame is printed. - - For example, to ignore `SIGALRM' signals while single-stepping, but -treat them normally during normal execution, you could define: - - define hook-stop - handle SIGALRM nopass - end - - define hook-run - handle SIGALRM pass - end - - define hook-continue - handle SIGLARM pass - end - - As a further example, to hook at the begining and end of the `echo' -command, and to add extra text to the beginning and end of the message, -you could define: - - define hook-echo - echo <<<--- - end - - define hookpost-echo - echo --->>>\n - end - - (gdb) echo Hello World - <<<---Hello World--->>> - (gdb) - - You can define a hook for any single-word command in GDB, but not -for command aliases; you should define a hook for the basic command -name, e.g. `backtrace' rather than `bt'. If an error occurs during -the execution of your hook, execution of GDB commands stops and GDB -issues a prompt (before the command that you actually typed had a -chance to run). - - If you try to define a hook which does not match any known command, -you get a warning from the `define' command. - - -File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences - -Command files -============= - -A command file for GDB is a file of lines that are GDB commands. -Comments (lines starting with `#') may also be included. An empty line -in a command file does nothing; it does not mean to repeat the last -command, as it would from the terminal. - - When you start GDB, it automatically executes commands from its -"init files", normally called `.gdbinit'(1). During startup, GDB does -the following: - - 1. Reads the init file (if any) in your home directory(2). - - 2. Processes command line options and operands. - - 3. Reads the init file (if any) in the current working directory. - - 4. Reads command files specified by the `-x' option. - - The init file in your home directory can set options (such as `set -complaints') that affect subsequent processing of command line options -and operands. Init files are not executed if you use the `-nx' option -(*note Choosing modes: Mode Options.). - - On some configurations of GDB, the init file is known by a different -name (these are typically environments where a specialized form of GDB -may need to coexist with other forms, hence a different name for the -specialized version's init file). These are the environments with -special init file names: - - * VxWorks (Wind River Systems real-time OS): `.vxgdbinit' - - * OS68K (Enea Data Systems real-time OS): `.os68gdbinit' - - * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit' - - You can also request the execution of a command file with the -`source' command: - -`source FILENAME' - Execute the command file FILENAME. - - The lines in a command file are executed sequentially. They are not -printed as they are executed. An error in any command terminates -execution of the command file and control is returned to the console. - - Commands that would ask for confirmation if used interactively -proceed without asking when used in a command file. Many GDB commands -that normally print messages to say what they are doing omit the -messages when called from command files. - - GDB also accepts command input from standard input. In this mode, -normal output goes to standard output and error output goes to standard -error. Errors in a command file supplied on standard input do not -terminate execution of the command file -- execution continues with the -next command. - - gdb < cmds > log 2>&1 - - (The syntax above will vary depending on the shell used.) This -example will execute commands from the file `cmds'. All output and -errors would be directed to `log'. - - ---------- Footnotes ---------- - - (1) The DJGPP port of GDB uses the name `gdb.ini' instead, due to the -limitations of file names imposed by DOS filesystems. - - (2) On DOS/Windows systems, the home directory is the one pointed to -by the `HOME' environment variable. - - -File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences - -Commands for controlled output -============================== - -During the execution of a command file or a user-defined command, normal -GDB output is suppressed; the only output that appears is what is -explicitly printed by the commands in the definition. This section -describes three commands useful for generating exactly the output you -want. - -`echo TEXT' - Print TEXT. Nonprinting characters can be included in TEXT using - C escape sequences, such as `\n' to print a newline. *No newline - is printed unless you specify one.* In addition to the standard C - escape sequences, a backslash followed by a space stands for a - space. This is useful for displaying a string with spaces at the - beginning or the end, since leading and trailing spaces are - otherwise trimmed from all arguments. To print ` and foo = ', use - the command `echo \ and foo = \ '. - - A backslash at the end of TEXT can be used, as in C, to continue - the command onto subsequent lines. For example, - - echo This is some text\n\ - which is continued\n\ - onto several lines.\n - - produces the same output as - - echo This is some text\n - echo which is continued\n - echo onto several lines.\n - -`output EXPRESSION' - Print the value of EXPRESSION and nothing but that value: no - newlines, no `$NN = '. The value is not entered in the value - history either. *Note Expressions: Expressions, for more - information on expressions. - -`output/FMT EXPRESSION' - Print the value of EXPRESSION in format FMT. You can use the same - formats as for `print'. *Note Output formats: Output Formats, for - more information. - -`printf STRING, EXPRESSIONS...' - Print the values of the EXPRESSIONS under the control of STRING. - The EXPRESSIONS are separated by commas and may be either numbers - or pointers. Their values are printed as specified by STRING, - exactly as if your program were to execute the C subroutine - - printf (STRING, EXPRESSIONS...); - - For example, you can print two values in hex like this: - - printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo - - The only backslash-escape sequences that you can use in the format - string are the simple ones that consist of backslash followed by a - letter. - - -File: gdb.info, Node: Interpreters, Next: Emacs, Prev: TUI, Up: Top - -Command Interpreters -******************** - -GDB supports multiple command interpreters, and some command -infrastructure to allow users or user interface writers to switch -between interpreters or run commands in other interpreters. - - GDB currently supports two command interpreters, the console -interpreter (sometimes called the command-line interpreter or CLI) and -the machine interface interpreter (or GDB/MI). This manual describes -both of these interfaces in great detail. - - By default, GDB will start with the console interpreter. However, -the user may choose to start GDB with another interpreter by specifying -the `-i' or `--interpreter' startup options. Defined interpreters -include: - -`console' - The traditional console or command-line interpreter. This is the - most often used interpreter with GDB. With no interpreter - specified at runtime, GDB will use this interpreter. - -`mi' - The newest GDB/MI interface (currently `mi2'). Used primarily by - programs wishing to use GDB as a backend for a debugger GUI or an - IDE. For more information, see *Note The GDB/MI Interface: GDB/MI. - -`mi2' - The current GDB/MI interface. - -`mi1' - The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. - - - The interpreter being used by GDB may not be dynamically switched at -runtime. Although possible, this could lead to a very precarious -situation. Consider an IDE using GDB/MI. If a user enters the command -"interpreter-set console" in a console view, GDB would switch to using -the console interpreter, rendering the IDE inoperable! - - Although you may only choose a single interpreter at startup, you -may execute commands in any interpreter from the current interpreter -using the appropriate command. If you are running the console -interpreter, simply use the `interpreter-exec' command: - - interpreter-exec mi "-data-list-register-names" - - GDB/MI has a similar command, although it is only available in -versions of GDB which support GDB/MI version 2 (or greater). - - -File: gdb.info, Node: TUI, Next: Interpreters, Prev: Sequences, Up: Top - -GDB Text User Interface -*********************** - -* Menu: - -* TUI Overview:: TUI overview -* TUI Keys:: TUI key bindings -* TUI Single Key Mode:: TUI single key mode -* TUI Commands:: TUI specific commands -* TUI Configuration:: TUI configuration variables - - The GDB Text User Interface, TUI in short, is a terminal interface -which uses the `curses' library to show the source file, the assembly -output, the program registers and GDB commands in separate text windows. - - The TUI is enabled by invoking GDB using either `gdbtui' or `gdb --tui'. - - -File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI - -TUI overview -============ - -The TUI has two display modes that can be switched while GDB runs: - - * A curses (or TUI) mode in which it displays several text windows - on the terminal. - - * A standard mode which corresponds to the GDB configured without - the TUI. - - In the TUI mode, GDB can display several text window on the terminal: - -_command_ - This window is the GDB command window with the GDB prompt and the - GDB outputs. The GDB input is still managed using readline but - through the TUI. The _command_ window is always visible. - -_source_ - The source window shows the source file of the program. The - current line as well as active breakpoints are displayed in this - window. - -_assembly_ - The assembly window shows the disassembly output of the program. - -_register_ - This window shows the processor registers. It detects when a - register is changed and when this is the case, registers that have - changed are highlighted. - - - The source and assembly windows show the current program position by -highlighting the current line and marking them with the `>' marker. -Breakpoints are also indicated with two markers. A first one indicates -the breakpoint type: - -`B' - Breakpoint which was hit at least once. - -`b' - Breakpoint which was never hit. - -`H' - Hardware breakpoint which was hit at least once. - -`h' - Hardware breakpoint which was never hit. - - - The second marker indicates whether the breakpoint is enabled or not: - -`+' - Breakpoint is enabled. - -`-' - Breakpoint is disabled. - - - The source, assembly and register windows are attached to the thread -and the frame position. They are updated when the current thread -changes, when the frame changes or when the program counter changes. -These three windows are arranged by the TUI according to several -layouts. The layout defines which of these three windows are visible. -The following layouts are available: - - * source - - * assembly - - * source and assembly - - * source and registers - - * assembly and registers - - - On top of the command window a status line gives various information -concerning the current process begin debugged. The status line is -updated when the information it shows changes. The following fields -are displayed: - -_target_ - Indicates the current gdb target (*note Specifying a Debugging - Target: Targets.). - -_process_ - Gives information about the current process or thread number. - When no process is being debugged, this field is set to `No - process'. - -_function_ - Gives the current function name for the selected frame. The name - is demangled if demangling is turned on (*note Print Settings::). - When there is no symbol corresponding to the current program - counter the string `??' is displayed. - -_line_ - Indicates the current line number for the selected frame. When - the current line number is not known the string `??' is displayed. - -_pc_ - Indicates the current program counter address. - - - -File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI - -TUI Key Bindings -================ - -The TUI installs several key bindings in the readline keymaps (*note -Command Line Editing::). They allow to leave or enter in the TUI mode -or they operate directly on the TUI layout and windows. The TUI also -provides a _SingleKey_ keymap which binds several keys directly to GDB -commands. The following key bindings are installed for both TUI mode -and the GDB standard mode. - -`C-x C-a' -`C-x a' -`C-x A' - Enter or leave the TUI mode. When the TUI mode is left, the - curses window management is left and GDB operates using its - standard mode writing on the terminal directly. When the TUI mode - is entered, the control is given back to the curses windows. The - screen is then refreshed. - -`C-x 1' - Use a TUI layout with only one window. The layout will either be - `source' or `assembly'. When the TUI mode is not active, it will - switch to the TUI mode. - - Think of this key binding as the Emacs `C-x 1' binding. - -`C-x 2' - Use a TUI layout with at least two windows. When the current - layout shows already two windows, a next layout with two windows - is used. When a new layout is chosen, one window will always be - common to the previous layout and the new one. - - Think of it as the Emacs `C-x 2' binding. - -`C-x o' - Change the active window. The TUI associates several key bindings - (like scrolling and arrow keys) to the active window. This command - gives the focus to the next TUI window. - - Think of it as the Emacs `C-x o' binding. - -`C-x s' - Use the TUI _SingleKey_ keymap that binds single key to gdb - commands (*note TUI Single Key Mode::). - - - The following key bindings are handled only by the TUI mode: - -<PgUp> - Scroll the active window one page up. - -<PgDn> - Scroll the active window one page down. - -<Up> - Scroll the active window one line up. - -<Down> - Scroll the active window one line down. - -<Left> - Scroll the active window one column left. - -<Right> - Scroll the active window one column right. - -<C-L> - Refresh the screen. - - - In the TUI mode, the arrow keys are used by the active window for -scrolling. This means they are available for readline when the active -window is the command window. When the command window does not have -the focus, it is necessary to use other readline key bindings such as -<C-p>, <C-n>, <C-b> and <C-f>. - - -File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI - -TUI Single Key Mode -=================== - -The TUI provides a _SingleKey_ mode in which it installs a particular -key binding in the readline keymaps to connect single keys to some gdb -commands. - -`c' - continue - -`d' - down - -`f' - finish - -`n' - next - -`q' - exit the _SingleKey_ mode. - -`r' - run - -`s' - step - -`u' - up - -`v' - info locals - -`w' - where - - - Other keys temporarily switch to the GDB command prompt. The key -that was pressed is inserted in the editing buffer so that it is -possible to type most GDB commands without interaction with the TUI -_SingleKey_ mode. Once the command is entered the TUI _SingleKey_ mode -is restored. The only way to permanently leave this mode is by hitting -<q> or `<C-x> <s>'. - - -File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI - -TUI specific commands -===================== - -The TUI has specific commands to control the text windows. These -commands are always available, that is they do not depend on the -current terminal mode in which GDB runs. When GDB is in the standard -mode, using these commands will automatically switch in the TUI mode. - -`info win' - List and give the size of all displayed windows. - -`layout next' - Display the next layout. - -`layout prev' - Display the previous layout. - -`layout src' - Display the source window only. - -`layout asm' - Display the assembly window only. - -`layout split' - Display the source and assembly window. - -`layout regs' - Display the register window together with the source or assembly - window. - -`focus next | prev | src | asm | regs | split' - Set the focus to the named window. This command allows to change - the active window so that scrolling keys can be affected to - another window. - -`refresh' - Refresh the screen. This is similar to using <C-L> key. - -`tui reg float' - Show the floating point registers in the register window. - -`tui reg general' - Show the general registers in the register window. - -`tui reg next' - Show the next register group. The list of register groups as well - as their order is target specific. The predefined register groups - are the following: `general', `float', `system', `vector', `all', - `save', `restore'. - -`tui reg system' - Show the system registers in the register window. - -`update' - Update the source window and the current execution point. - -`winheight NAME +COUNT' -`winheight NAME -COUNT' - Change the height of the window NAME by COUNT lines. Positive - counts increase the height, while negative counts decrease it. - - - -File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI - -TUI configuration variables -=========================== - -The TUI has several configuration variables that control the appearance -of windows on the terminal. - -`set tui border-kind KIND' - Select the border appearance for the source, assembly and register - windows. The possible values are the following: - `space' - Use a space character to draw the border. - - `ascii' - Use ascii characters + - and | to draw the border. - - `acs' - Use the Alternate Character Set to draw the border. The - border is drawn using character line graphics if the terminal - supports them. - - -`set tui active-border-mode MODE' - Select the attributes to display the border of the active window. - The possible values are `normal', `standout', `reverse', `half', - `half-standout', `bold' and `bold-standout'. - -`set tui border-mode MODE' - Select the attributes to display the border of other windows. The - MODE can be one of the following: - `normal' - Use normal attributes to display the border. - - `standout' - Use standout mode. - - `reverse' - Use reverse video mode. - - `half' - Use half bright mode. - - `half-standout' - Use half bright and standout mode. - - `bold' - Use extra bright or bold mode. - - `bold-standout' - Use extra bright or bold and standout mode. - - - - -File: gdb.info, Node: Emacs, Next: Annotations, Prev: Interpreters, Up: Top - -Using GDB under GNU Emacs -************************* - -A special interface allows you to use GNU Emacs to view (and edit) the -source files for the program you are debugging with GDB. - - To use this interface, use the command `M-x gdb' in Emacs. Give the -executable file you want to debug as an argument. This command starts -GDB as a subprocess of Emacs, with input and output through a newly -created Emacs buffer. - - Using GDB under Emacs is just like using GDB normally except for two -things: - - * All "terminal" input and output goes through the Emacs buffer. - - This applies both to GDB commands and their output, and to the input -and output done by the program you are debugging. - - This is useful because it means that you can copy the text of -previous commands and input them again; you can even use parts of the -output in this way. - - All the facilities of Emacs' Shell mode are available for interacting -with your program. In particular, you can send signals the usual -way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop. - - * GDB displays source code through Emacs. - - Each time GDB displays a stack frame, Emacs automatically finds the -source file for that frame and puts an arrow (`=>') at the left margin -of the current line. Emacs uses a separate buffer for source display, -and splits the screen to show both your GDB session and the source. - - Explicit GDB `list' or search commands still produce output as -usual, but you probably have no reason to use them from Emacs. - - If you specify an absolute file name when prompted for the `M-x gdb' -argument, then Emacs sets your current working directory to where your -program resides. If you only specify the file name, then Emacs sets -your current working directory to to the directory associated with the -previous buffer. In this case, GDB may find your program by searching -your environment's `PATH' variable, but on some operating systems it -might not find the source. So, although the GDB input and output -session proceeds normally, the auxiliary buffer does not display the -current source and line of execution. - - The initial working directory of GDB is printed on the top line of -the GDB I/O buffer and this serves as a default for the commands that -specify files for GDB to operate on. *Note Commands to specify files: -Files. - - By default, `M-x gdb' calls the program called `gdb'. If you need -to call GDB by a different name (for example, if you keep several -configurations around, with different names) you can customize the -Emacs variable `gud-gdb-command-name' to run the one you want. - - In the GDB I/O buffer, you can use these special Emacs commands in -addition to the standard Shell mode commands: - -`C-h m' - Describe the features of Emacs' GDB Mode. - -`C-c C-s' - Execute to another source line, like the GDB `step' command; also - update the display window to show the current file and location. - -`C-c C-n' - Execute to next source line in this function, skipping all function - calls, like the GDB `next' command. Then update the display window - to show the current file and location. - -`C-c C-i' - Execute one instruction, like the GDB `stepi' command; update - display window accordingly. - -`C-c C-f' - Execute until exit from the selected stack frame, like the GDB - `finish' command. - -`C-c C-r' - Continue execution of your program, like the GDB `continue' - command. - -`C-c <' - Go up the number of frames indicated by the numeric argument - (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' - command. - -`C-c >' - Go down the number of frames indicated by the numeric argument, - like the GDB `down' command. - - In any source file, the Emacs command `C-x SPC' (`gud-break') tells -GDB to set a breakpoint on the source line point is on. - - If you type `M-x speedbar', then Emacs displays a separate frame -which shows a backtrace when the GDB I/O buffer is current. Move point -to any frame in the stack and type <RET> to make it become the current -frame and display the associated source in the source buffer. -Alternatively, click `Mouse-2' to make the selected frame become the -current one. - - If you accidentally delete the source-display buffer, an easy way to -get it back is to type the command `f' in the GDB buffer, to request a -frame display; when you run under Emacs, this recreates the source -buffer if necessary to show you the context of the current frame. - - The source files displayed in Emacs are in ordinary Emacs buffers -which are visiting the source files in the usual way. You can edit the -files with these buffers if you wish; but keep in mind that GDB -communicates with Emacs in terms of line numbers. If you add or delete -lines from the text, the line numbers that GDB knows cease to -correspond properly with the code. - - The description given here is for GNU Emacs version 21.3 and a more -detailed description of its interaction with GDB is given in the Emacs -manual (*note Debuggers: (Emacs)Debuggers.). - - -File: gdb.info, Node: GDB/MI, Next: GDB Bugs, Prev: Annotations, Up: Top - -The GDB/MI Interface -******************** - -Function and Purpose -==================== - -GDB/MI is a line based machine oriented text interface to GDB. It is -specifically intended to support the development of systems which use -the debugger as just one small component of a larger system. - - This chapter is a specification of the GDB/MI interface. It is -written in the form of a reference manual. - - Note that GDB/MI is still under construction, so some of the -features described below are incomplete and subject to change. - -Notation and Terminology -======================== - -This chapter uses the following notation: - - * `|' separates two alternatives. - - * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or - may not be given. - - * `( GROUP )*' means that GROUP inside the parentheses may repeat - zero or more times. - - * `( GROUP )+' means that GROUP inside the parentheses may repeat - one or more times. - - * `"STRING"' means a literal STRING. - -Acknowledgments -=============== - -In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and -Elena Zannoni. - -* Menu: - -* GDB/MI Command Syntax:: -* GDB/MI Compatibility with CLI:: -* GDB/MI Output Records:: -* GDB/MI Command Description Format:: -* GDB/MI Breakpoint Table Commands:: -* GDB/MI Data Manipulation:: -* GDB/MI Program Control:: -* GDB/MI Miscellaneous Commands:: -* GDB/MI Stack Manipulation:: -* GDB/MI Symbol Query:: -* GDB/MI Target Manipulation:: -* GDB/MI Thread Commands:: -* GDB/MI Tracepoint Commands:: -* GDB/MI Variable Objects:: - - -File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Up: GDB/MI - -GDB/MI Command Syntax -===================== - -* Menu: - -* GDB/MI Input Syntax:: -* GDB/MI Output Syntax:: -* GDB/MI Simple Examples:: - - -File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax - -GDB/MI Input Syntax -------------------- - -`COMMAND ==>' - `CLI-COMMAND | MI-COMMAND' - -`CLI-COMMAND ==>' - `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB - CLI command. - -`MI-COMMAND ==>' - `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " - PARAMETER )* NL' - -`TOKEN ==>' - "any sequence of digits" - -`OPTION ==>' - `"-" PARAMETER [ " " PARAMETER ]' - -`PARAMETER ==>' - `NON-BLANK-SEQUENCE | C-STRING' - -`OPERATION ==>' - _any of the operations described in this chapter_ - -`NON-BLANK-SEQUENCE ==>' - _anything, provided it doesn't contain special characters such as - "-", NL, """ and of course " "_ - -`C-STRING ==>' - `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' - -`NL ==>' - `CR | CR-LF' - -Notes: - - * The CLI commands are still handled by the MI interpreter; their - output is described below. - - * The `TOKEN', when present, is passed back when the command - finishes. - - * Some MI commands accept optional arguments as part of the parameter - list. Each option is identified by a leading `-' (dash) and may be - followed by an optional argument parameter. Options occur first - in the parameter list and can be delimited from normal parameters - using `--' (this is useful when some parameters begin with a dash). - - Pragmatics: - - * We want easy access to the existing CLI syntax (for debugging). - - * We want it to be easy to spot a MI operation. - - -File: gdb.info, Node: GDB/MI Output Syntax, Next: GDB/MI Simple Examples, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax - -GDB/MI Output Syntax --------------------- - -The output from GDB/MI consists of zero or more out-of-band records -followed, optionally, by a single result record. This result record is -for the most recent command. The sequence of output records is -terminated by `(gdb)'. - - If an input command was prefixed with a `TOKEN' then the -corresponding output for that command will also be prefixed by that same -TOKEN. - -`OUTPUT ==>' - `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' - -`RESULT-RECORD ==>' - ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' - -`OUT-OF-BAND-RECORD ==>' - `ASYNC-RECORD | STREAM-RECORD' - -`ASYNC-RECORD ==>' - `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' - -`EXEC-ASYNC-OUTPUT ==>' - `[ TOKEN ] "*" ASYNC-OUTPUT' - -`STATUS-ASYNC-OUTPUT ==>' - `[ TOKEN ] "+" ASYNC-OUTPUT' - -`NOTIFY-ASYNC-OUTPUT ==>' - `[ TOKEN ] "=" ASYNC-OUTPUT' - -`ASYNC-OUTPUT ==>' - `ASYNC-CLASS ( "," RESULT )* NL' - -`RESULT-CLASS ==>' - `"done" | "running" | "connected" | "error" | "exit"' - -`ASYNC-CLASS ==>' - `"stopped" | OTHERS' (where OTHERS will be added depending on the - needs--this is still in development). - -`RESULT ==>' - ` VARIABLE "=" VALUE' - -`VARIABLE ==>' - ` STRING ' - -`VALUE ==>' - ` CONST | TUPLE | LIST ' - -`CONST ==>' - `C-STRING' - -`TUPLE ==>' - ` "{}" | "{" RESULT ( "," RESULT )* "}" ' - -`LIST ==>' - ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* - "]" ' - -`STREAM-RECORD ==>' - `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' - -`CONSOLE-STREAM-OUTPUT ==>' - `"~" C-STRING' - -`TARGET-STREAM-OUTPUT ==>' - `"@" C-STRING' - -`LOG-STREAM-OUTPUT ==>' - `"&" C-STRING' - -`NL ==>' - `CR | CR-LF' - -`TOKEN ==>' - _any sequence of digits_. - -Notes: - - * All output sequences end in a single line containing a period. - - * The `TOKEN' is from the corresponding request. If an execution - command is interrupted by the `-exec-interrupt' command, the TOKEN - associated with the `*stopped' message is the one of the original - execution command, not the one of the interrupt command. - - * STATUS-ASYNC-OUTPUT contains on-going status information about the - progress of a slow operation. It can be discarded. All status - output is prefixed by `+'. - - * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target - (stopped, started, disappeared). All async output is prefixed by - `*'. - - * NOTIFY-ASYNC-OUTPUT contains supplementary information that the - client should handle (e.g., a new breakpoint information). All - notify output is prefixed by `='. - - * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in - the console. It is the textual response to a CLI command. All - the console output is prefixed by `~'. - - * TARGET-STREAM-OUTPUT is the output produced by the target program. - All the target output is prefixed by `@'. - - * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for - instance messages that should be displayed as part of an error - log. All the log output is prefixed by `&'. - - * New GDB/MI commands should only output LISTS containing VALUES. - - - *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details -about the various output records. - - -File: gdb.info, Node: GDB/MI Simple Examples, Prev: GDB/MI Output Syntax, Up: GDB/MI Command Syntax - -Simple Examples of GDB/MI Interaction -------------------------------------- - -This subsection presents several simple examples of interaction using -the GDB/MI interface. In these examples, `->' means that the following -line is passed to GDB/MI as input, while `<-' means the output received -from GDB/MI. - -Target Stop -........... - -Here's an example of stopping the inferior process: - - -> -stop - <- (gdb) - -and later: - - <- *stop,reason="stop",address="0x123",source="a.c:123" - <- (gdb) - -Simple CLI Command -.................. - -Here's an example of a simple CLI command being passed through GDB/MI -and on to the CLI. - - -> print 1+2 - <- &"print 1+2\n" - <- ~"$1 = 3\n" - <- ^done - <- (gdb) - -Command With Side Effects -......................... - - -> -symbol-file xyz.exe - <- *breakpoint,nr="3",address="0x123",source="a.c:123" - <- (gdb) - -A Bad Command -............. - -Here's what happens if you pass a non-existent command: - - -> -rubbish - <- ^error,msg="Undefined MI command: rubbish" - <- (gdb) - - -File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Output Records, Prev: GDB/MI Command Syntax, Up: GDB/MI - -GDB/MI Compatibility with CLI -============================= - -To help users familiar with GDB's existing CLI interface, GDB/MI -accepts existing CLI commands. As specified by the syntax, such -commands can be directly entered into the GDB/MI interface and GDB will -respond. - - This mechanism is provided as an aid to developers of GDB/MI clients -and not as a reliable interface into the CLI. Since the command is -being interpreteted in an environment that assumes GDB/MI behaviour, -the exact output of such commands is likely to end up being an -un-supported hybrid of GDB/MI and CLI output. - - -File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Command Description Format, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI - -GDB/MI Output Records -===================== - -* Menu: - -* GDB/MI Result Records:: -* GDB/MI Stream Records:: -* GDB/MI Out-of-band Records:: - - -File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records - -GDB/MI Result Records ---------------------- - -In addition to a number of out-of-band notifications, the response to a -GDB/MI command includes one of the following result indications: - -`"^done" [ "," RESULTS ]' - The synchronous operation was successful, `RESULTS' are the return - values. - -`"^running"' - The asynchronous operation was successfully started. The target is - running. - -`"^error" "," C-STRING' - The operation failed. The `C-STRING' contains the corresponding - error message. - - -File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Out-of-band Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records - -GDB/MI Stream Records ---------------------- - -GDB internally maintains a number of output streams: the console, the -target, and the log. The output intended for each of these streams is -funneled through the GDB/MI interface using "stream records". - - Each stream record begins with a unique "prefix character" which -identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output -Syntax.). In addition to the prefix, each stream record contains a -`STRING-OUTPUT'. This is either raw text (with an implicit new line) -or a quoted C string (which does not contain an implicit newline). - -`"~" STRING-OUTPUT' - The console output stream contains text that should be displayed - in the CLI console window. It contains the textual responses to - CLI commands. - -`"@" STRING-OUTPUT' - The target output stream contains any textual output from the - running target. - -`"&" STRING-OUTPUT' - The log stream contains debugging messages being produced by GDB's - internals. - - -File: gdb.info, Node: GDB/MI Out-of-band Records, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records - -GDB/MI Out-of-band Records --------------------------- - -"Out-of-band" records are used to notify the GDB/MI client of -additional changes that have occurred. Those changes can either be a -consequence of GDB/MI (e.g., a breakpoint modified) or a result of -target activity (e.g., target stopped). - - The following is a preliminary list of possible out-of-band records. - -`"*" "stop"' - - -File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Table Commands, Prev: GDB/MI Output Records, Up: GDB/MI - -GDB/MI Command Description Format -================================= - -The remaining sections describe blocks of commands. Each block of -commands is laid out in a fashion similar to this section. - - Note the the line breaks shown in the examples are here only for -readability. They don't appear in the real output. Also note that the -commands with a non-available example (N.A.) are not yet implemented. - -Motivation ----------- - -The motivation for this collection of commands. - -Introduction ------------- - -A brief introduction to this collection of commands as a whole. - -Commands --------- - -For each command in the block, the following is described: - -Synopsis -........ - - -command ARGS... - -GDB Command -........... - -The corresponding GDB CLI command. - -Result -...... - -Out-of-band -........... - -Notes -..... - -Example -....... - - -File: gdb.info, Node: GDB/MI Breakpoint Table Commands, Next: GDB/MI Data Manipulation, Prev: GDB/MI Command Description Format, Up: GDB/MI - -GDB/MI Breakpoint table commands -================================ - -This section documents GDB/MI commands for manipulating breakpoints. - -The `-break-after' Command --------------------------- - -Synopsis -........ - - -break-after NUMBER COUNT - - The breakpoint number NUMBER is not in effect until it has been hit -COUNT times. To see how this is reflected in the output of the -`-break-list' command, see the description of the `-break-list' command -below. - -GDB Command -........... - -The corresponding GDB command is `ignore'. - -Example -....... - - (gdb) - -break-insert main - ^done,bkpt={number="1",addr="0x000100d0",file="hello.c",line="5"} - (gdb) - -break-after 1 3 - ~ - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x000100d0",func="main",file="hello.c",line="5",times="0", - ignore="3"}]} - (gdb) - -The `-break-condition' Command ------------------------------- - -Synopsis -........ - - -break-condition NUMBER EXPR - - Breakpoint NUMBER will stop the program only if the condition in -EXPR is true. The condition becomes part of the `-break-list' output -(see the description of the `-break-list' command below). - -GDB Command -........... - -The corresponding GDB command is `condition'. - -Example -....... - - (gdb) - -break-condition 1 1 - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x000100d0",func="main",file="hello.c",line="5",cond="1", - times="0",ignore="3"}]} - (gdb) - -The `-break-delete' Command ---------------------------- - -Synopsis -........ - - -break-delete ( BREAKPOINT )+ - - Delete the breakpoint(s) whose number(s) are specified in the -argument list. This is obviously reflected in the breakpoint list. - -GDB command -........... - -The corresponding GDB command is `delete'. - -Example -....... - - (gdb) - -break-delete 1 - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="0",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[]} - (gdb) - -The `-break-disable' Command ----------------------------- - -Synopsis -........ - - -break-disable ( BREAKPOINT )+ - - Disable the named BREAKPOINT(s). The field `enabled' in the break -list is now set to `n' for the named BREAKPOINT(s). - -GDB Command -........... - -The corresponding GDB command is `disable'. - -Example -....... - - (gdb) - -break-disable 2 - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", - addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]} - (gdb) - -The `-break-enable' Command ---------------------------- - -Synopsis -........ - - -break-enable ( BREAKPOINT )+ - - Enable (previously disabled) BREAKPOINT(s). - -GDB Command -........... - -The corresponding GDB command is `enable'. - -Example -....... - - (gdb) - -break-enable 2 - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", - addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]} - (gdb) - -The `-break-info' Command -------------------------- - -Synopsis -........ - - -break-info BREAKPOINT - - Get information about a single breakpoint. - -GDB command -........... - -The corresponding GDB command is `info break BREAKPOINT'. - -Example -....... - -N.A. - -The `-break-insert' Command ---------------------------- - -Synopsis -........ - - -break-insert [ -t ] [ -h ] [ -r ] - [ -c CONDITION ] [ -i IGNORE-COUNT ] - [ -p THREAD ] [ LINE | ADDR ] - -If specified, LINE, can be one of: - - * function - - * filename:linenum - - * filename:function - - * *address - - The possible optional parameters of this command are: - -`-t' - Insert a tempoary breakpoint. - -`-h' - Insert a hardware breakpoint. - -`-c CONDITION' - Make the breakpoint conditional on CONDITION. - -`-i IGNORE-COUNT' - Initialize the IGNORE-COUNT. - -`-r' - Insert a regular breakpoint in all the functions whose names match - the given regular expression. Other flags are not applicable to - regular expresson. - -Result -...... - -The result is in the form: - - ^done,bkptno="NUMBER",func="FUNCNAME", - file="FILENAME",line="LINENO" - -where NUMBER is the GDB number for this breakpoint, FUNCNAME is the -name of the function where the breakpoint was inserted, FILENAME is the -name of the source file which contains this function, and LINENO is the -source line number within that file. - - Note: this format is open to change. - -GDB Command -........... - -The corresponding GDB commands are `break', `tbreak', `hbreak', -`thbreak', and `rbreak'. - -Example -....... - - (gdb) - -break-insert main - ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} - (gdb) - -break-insert -t foo - ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",line="11"} - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="2",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"}, - bkpt={number="2",type="breakpoint",disp="del",enabled="y", - addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"}]} - (gdb) - -break-insert -r foo.* - ~int foo(int, int); - ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c",line="11"} - (gdb) - -The `-break-list' Command -------------------------- - -Synopsis -........ - - -break-list - - Displays the list of inserted breakpoints, showing the following -fields: - -`Number' - number of the breakpoint - -`Type' - type of the breakpoint: `breakpoint' or `watchpoint' - -`Disposition' - should the breakpoint be deleted or disabled when it is hit: `keep' - or `nokeep' - -`Enabled' - is the breakpoint enabled or no: `y' or `n' - -`Address' - memory location at which the breakpoint is set - -`What' - logical location of the breakpoint, expressed by function name, - file name, line number - -`Times' - number of times the breakpoint has been hit - - If there are no breakpoints or watchpoints, the `BreakpointTable' -`body' field is an empty list. - -GDB Command -........... - -The corresponding GDB command is `info break'. - -Example -....... - - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="2",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, - bkpt={number="2",type="breakpoint",disp="keep",enabled="y", - addr="0x00010114",func="foo",file="hello.c",line="13",times="0"}]} - (gdb) - - Here's an example of the result when there are no breakpoints: - - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="0",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[]} - (gdb) - -The `-break-watch' Command --------------------------- - -Synopsis -........ - - -break-watch [ -a | -r ] - - Create a watchpoint. With the `-a' option it will create an -"access" watchpoint, i.e. a watchpoint that triggers either on a read -from or on a write to the memory location. With the `-r' option, the -watchpoint created is a "read" watchpoint, i.e. it will trigger only -when the memory location is accessed for reading. Without either of -the options, the watchpoint created is a regular watchpoint, i.e. it -will trigger when the memory location is accessed for writing. *Note -Setting watchpoints: Set Watchpoints. - - Note that `-break-list' will report a single list of watchpoints and -breakpoints inserted. - -GDB Command -........... - -The corresponding GDB commands are `watch', `awatch', and `rwatch'. - -Example -....... - -Setting a watchpoint on a variable in the `main' function: - - (gdb) - -break-watch x - ^done,wpt={number="2",exp="x"} - (gdb) - -exec-continue - ^running - ^done,reason="watchpoint-trigger",wpt={number="2",exp="x"}, - value={old="-268439212",new="55"}, - frame={func="main",args=[],file="recursive2.c",line="5"} - (gdb) - - Setting a watchpoint on a variable local to a function. GDB will -stop the program execution twice: first for the variable changing -value, then for the watchpoint going out of scope. - - (gdb) - -break-watch C - ^done,wpt={number="5",exp="C"} - (gdb) - -exec-continue - ^running - ^done,reason="watchpoint-trigger", - wpt={number="5",exp="C"},value={old="-276895068",new="3"}, - frame={func="callee4",args=[], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"} - (gdb) - -exec-continue - ^running - ^done,reason="watchpoint-scope",wpnum="5", - frame={func="callee3",args=[{name="strarg", - value="0x11940 \"A string argument.\""}], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"} - (gdb) - - Listing breakpoints and watchpoints, at different points in the -program execution. Note that once the watchpoint goes out of scope, it -is deleted. - - (gdb) - -break-watch C - ^done,wpt={number="2",exp="C"} - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="2",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00010734",func="callee4", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, - bkpt={number="2",type="watchpoint",disp="keep", - enabled="y",addr="",what="C",times="0"}]} - (gdb) - -exec-continue - ^running - ^done,reason="watchpoint-trigger",wpt={number="2",exp="C"}, - value={old="-276895068",new="3"}, - frame={func="callee4",args=[], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"} - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="2",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00010734",func="callee4", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, - bkpt={number="2",type="watchpoint",disp="keep", - enabled="y",addr="",what="C",times="-5"}]} - (gdb) - -exec-continue - ^running - ^done,reason="watchpoint-scope",wpnum="2", - frame={func="callee3",args=[{name="strarg", - value="0x11940 \"A string argument.\""}], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"} - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00010734",func="callee4", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}]} - (gdb) - - -File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Program Control, Prev: GDB/MI Breakpoint Table Commands, Up: GDB/MI - -GDB/MI Data Manipulation -======================== - -This section describes the GDB/MI commands that manipulate data: -examine memory and registers, evaluate expressions, etc. - -The `-data-disassemble' Command -------------------------------- - -Synopsis -........ - - -data-disassemble - [ -s START-ADDR -e END-ADDR ] - | [ -f FILENAME -l LINENUM [ -n LINES ] ] - -- MODE - -Where: - -`START-ADDR' - is the beginning address (or `$pc') - -`END-ADDR' - is the end address - -`FILENAME' - is the name of the file to disassemble - -`LINENUM' - is the line number to disassemble around - -`LINES' - is the the number of disassembly lines to be produced. If it is - -1, the whole function will be disassembled, in case no END-ADDR is - specified. If END-ADDR is specified as a non-zero value, and - LINES is lower than the number of disassembly lines between - START-ADDR and END-ADDR, only LINES lines are displayed; if LINES - is higher than the number of lines between START-ADDR and - END-ADDR, only the lines up to END-ADDR are displayed. - -`MODE' - is either 0 (meaning only disassembly) or 1 (meaning mixed source - and disassembly). - -Result -...... - -The output for each instruction is composed of four fields: - - * Address - - * Func-name - - * Offset - - * Instruction - - Note that whatever included in the instruction field, is not -manipulated directely by GDB/MI, i.e. it is not possible to adjust its -format. - -GDB Command -........... - -There's no direct mapping from this command to the CLI. - -Example -....... - -Disassemble from the current value of `$pc' to `$pc + 20': - - (gdb) - -data-disassemble -s $pc -e "$pc + 20" -- 0 - ^done, - asm_insns=[ - {address="0x000107c0",func-name="main",offset="4", - inst="mov 2, %o0"}, - {address="0x000107c4",func-name="main",offset="8", - inst="sethi %hi(0x11800), %o2"}, - {address="0x000107c8",func-name="main",offset="12", - inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, - {address="0x000107cc",func-name="main",offset="16", - inst="sethi %hi(0x11800), %o2"}, - {address="0x000107d0",func-name="main",offset="20", - inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] - (gdb) - - Disassemble the whole `main' function. Line 32 is part of `main'. - - -data-disassemble -f basics.c -l 32 -- 0 - ^done,asm_insns=[ - {address="0x000107bc",func-name="main",offset="0", - inst="save %sp, -112, %sp"}, - {address="0x000107c0",func-name="main",offset="4", - inst="mov 2, %o0"}, - {address="0x000107c4",func-name="main",offset="8", - inst="sethi %hi(0x11800), %o2"}, - [...] - {address="0x0001081c",func-name="main",offset="96",inst="ret "}, - {address="0x00010820",func-name="main",offset="100",inst="restore "}] - (gdb) - - Disassemble 3 instructions from the start of `main': - - (gdb) - -data-disassemble -f basics.c -l 32 -n 3 -- 0 - ^done,asm_insns=[ - {address="0x000107bc",func-name="main",offset="0", - inst="save %sp, -112, %sp"}, - {address="0x000107c0",func-name="main",offset="4", - inst="mov 2, %o0"}, - {address="0x000107c4",func-name="main",offset="8", - inst="sethi %hi(0x11800), %o2"}] - (gdb) - - Disassemble 3 instructions from the start of `main' in mixed mode: - - (gdb) - -data-disassemble -f basics.c -l 32 -n 3 -- 1 - ^done,asm_insns=[ - src_and_asm_line={line="31", - file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ - testsuite/gdb.mi/basics.c",line_asm_insn=[ - {address="0x000107bc",func-name="main",offset="0", - inst="save %sp, -112, %sp"}]}, - src_and_asm_line={line="32", - file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ - testsuite/gdb.mi/basics.c",line_asm_insn=[ - {address="0x000107c0",func-name="main",offset="4", - inst="mov 2, %o0"}, - {address="0x000107c4",func-name="main",offset="8", - inst="sethi %hi(0x11800), %o2"}]}] - (gdb) - -The `-data-evaluate-expression' Command ---------------------------------------- - -Synopsis -........ - - -data-evaluate-expression EXPR - - Evaluate EXPR as an expression. The expression could contain an -inferior function call. The function call will execute synchronously. -If the expression contains spaces, it must be enclosed in double quotes. - -GDB Command -........... - -The corresponding GDB commands are `print', `output', and `call'. In -`gdbtk' only, there's a corresponding `gdb_eval' command. - -Example -....... - -In the following example, the numbers that precede the commands are the -"tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command -Syntax. Notice how GDB/MI returns the same tokens in its output. - - 211-data-evaluate-expression A - 211^done,value="1" - (gdb) - 311-data-evaluate-expression &A - 311^done,value="0xefffeb7c" - (gdb) - 411-data-evaluate-expression A+3 - 411^done,value="4" - (gdb) - 511-data-evaluate-expression "A + 3" - 511^done,value="4" - (gdb) - -The `-data-list-changed-registers' Command ------------------------------------------- - -Synopsis -........ - - -data-list-changed-registers - - Display a list of the registers that have changed. - -GDB Command -........... - -GDB doesn't have a direct analog for this command; `gdbtk' has the -corresponding command `gdb_changed_register_list'. - -Example -....... - -On a PPC MBX board: - - (gdb) - -exec-continue - ^running - - (gdb) - *stopped,reason="breakpoint-hit",bkptno="1",frame={func="main", - args=[],file="try.c",line="5"} - (gdb) - -data-list-changed-registers - ^done,changed-registers=["0","1","2","4","5","6","7","8","9", - "10","11","13","14","15","16","17","18","19","20","21","22","23", - "24","25","26","27","28","30","31","64","65","66","67","69"] - (gdb) - -The `-data-list-register-names' Command ---------------------------------------- - -Synopsis -........ - - -data-list-register-names [ ( REGNO )+ ] - - Show a list of register names for the current target. If no -arguments are given, it shows a list of the names of all the registers. -If integer numbers are given as arguments, it will print a list of the -names of the registers corresponding to the arguments. To ensure -consistency between a register name and its number, the output list may -include empty register names. - -GDB Command -........... - -GDB does not have a command which corresponds to -`-data-list-register-names'. In `gdbtk' there is a corresponding -command `gdb_regnames'. - -Example -....... - -For the PPC MBX board: - (gdb) - -data-list-register-names - ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", - "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", - "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", - "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", - "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", - "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", - "", "pc","ps","cr","lr","ctr","xer"] - (gdb) - -data-list-register-names 1 2 3 - ^done,register-names=["r1","r2","r3"] - (gdb) - -The `-data-list-register-values' Command ----------------------------------------- - -Synopsis -........ - - -data-list-register-values FMT [ ( REGNO )*] - - Display the registers' contents. FMT is the format according to -which the registers' contents are to be returned, followed by an -optional list of numbers specifying the registers to display. A -missing list of numbers indicates that the contents of all the -registers must be returned. - - Allowed formats for FMT are: - -`x' - Hexadecimal - -`o' - Octal - -`t' - Binary - -`d' - Decimal - -`r' - Raw - -`N' - Natural - -GDB Command -........... - -The corresponding GDB commands are `info reg', `info all-reg', and (in -`gdbtk') `gdb_fetch_registers'. - -Example -....... - -For a PPC MBX board (note: line breaks are for readability only, they -don't appear in the actual output): - - (gdb) - -data-list-register-values r 64 65 - ^done,register-values=[{number="64",value="0xfe00a300"}, - {number="65",value="0x00029002"}] - (gdb) - -data-list-register-values x - ^done,register-values=[{number="0",value="0xfe0043c8"}, - {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, - {number="3",value="0x0"},{number="4",value="0xa"}, - {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, - {number="7",value="0xfe011e98"},{number="8",value="0x2"}, - {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, - {number="11",value="0x1"},{number="12",value="0x0"}, - {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, - {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, - {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, - {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, - {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, - {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, - {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, - {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, - {number="29",value="0x0"},{number="30",value="0xfe010000"}, - {number="31",value="0x0"},{number="32",value="0x0"}, - {number="33",value="0x0"},{number="34",value="0x0"}, - {number="35",value="0x0"},{number="36",value="0x0"}, - {number="37",value="0x0"},{number="38",value="0x0"}, - {number="39",value="0x0"},{number="40",value="0x0"}, - {number="41",value="0x0"},{number="42",value="0x0"}, - {number="43",value="0x0"},{number="44",value="0x0"}, - {number="45",value="0x0"},{number="46",value="0x0"}, - {number="47",value="0x0"},{number="48",value="0x0"}, - {number="49",value="0x0"},{number="50",value="0x0"}, - {number="51",value="0x0"},{number="52",value="0x0"}, - {number="53",value="0x0"},{number="54",value="0x0"}, - {number="55",value="0x0"},{number="56",value="0x0"}, - {number="57",value="0x0"},{number="58",value="0x0"}, - {number="59",value="0x0"},{number="60",value="0x0"}, - {number="61",value="0x0"},{number="62",value="0x0"}, - {number="63",value="0x0"},{number="64",value="0xfe00a300"}, - {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, - {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, - {number="69",value="0x20002b03"}] - (gdb) - -The `-data-read-memory' Command -------------------------------- - -Synopsis -........ - - -data-read-memory [ -o BYTE-OFFSET ] - ADDRESS WORD-FORMAT WORD-SIZE - NR-ROWS NR-COLS [ ASCHAR ] - -where: - -`ADDRESS' - An expression specifying the address of the first memory word to be - read. Complex expressions containing embedded white space should - be quoted using the C convention. - -`WORD-FORMAT' - The format to be used to print the memory words. The notation is - the same as for GDB's `print' command (*note Output formats: - Output Formats.). - -`WORD-SIZE' - The size of each memory word in bytes. - -`NR-ROWS' - The number of rows in the output table. - -`NR-COLS' - The number of columns in the output table. - -`ASCHAR' - If present, indicates that each row should include an ASCII dump. - The value of ASCHAR is used as a padding character when a byte is - not a member of the printable ASCII character set (printable ASCII - characters are those whose code is between 32 and 126, - inclusively). - -`BYTE-OFFSET' - An offset to add to the ADDRESS before fetching memory. - - This command displays memory contents as a table of NR-ROWS by -NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS * -NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes'). -Should less than the requested number of bytes be returned by the -target, the missing words are identified using `N/A'. The number of -bytes read from the target is returned in `nr-bytes' and the starting -address used to read memory in `addr'. - - The address of the next/previous row or page is available in -`next-row' and `prev-row', `next-page' and `prev-page'. - -GDB Command -........... - -The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory -read command. - -Example -....... - -Read six bytes of memory starting at `bytes+6' but then offset by `-6' -bytes. Format as three rows of two columns. One byte per word. -Display each word in hex. - - (gdb) - 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 - 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", - next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", - prev-page="0x0000138a",memory=[ - {addr="0x00001390",data=["0x00","0x01"]}, - {addr="0x00001392",data=["0x02","0x03"]}, - {addr="0x00001394",data=["0x04","0x05"]}] - (gdb) - - Read two bytes of memory starting at address `shorts + 64' and -display as a single word formatted in decimal. - - (gdb) - 5-data-read-memory shorts+64 d 2 1 1 - 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", - next-row="0x00001512",prev-row="0x0000150e", - next-page="0x00001512",prev-page="0x0000150e",memory=[ - {addr="0x00001510",data=["128"]}] - (gdb) - - Read thirty two bytes of memory starting at `bytes+16' and format as -eight rows of four columns. Include a string encoding with `x' used as -the non-printable character. - - (gdb) - 4-data-read-memory bytes+16 x 1 8 4 x - 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", - next-row="0x000013c0",prev-row="0x0000139c", - next-page="0x000013c0",prev-page="0x00001380",memory=[ - {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, - {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, - {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, - {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, - {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, - {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, - {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, - {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] - (gdb) - -The `-display-delete' Command ------------------------------ - -Synopsis -........ - - -display-delete NUMBER - - Delete the display NUMBER. - -GDB Command -........... - -The corresponding GDB command is `delete display'. - -Example -....... - -N.A. - -The `-display-disable' Command ------------------------------- - -Synopsis -........ - - -display-disable NUMBER - - Disable display NUMBER. - -GDB Command -........... - -The corresponding GDB command is `disable display'. - -Example -....... - -N.A. - -The `-display-enable' Command ------------------------------ - -Synopsis -........ - - -display-enable NUMBER - - Enable display NUMBER. - -GDB Command -........... - -The corresponding GDB command is `enable display'. - -Example -....... - -N.A. - -The `-display-insert' Command ------------------------------ - -Synopsis -........ - - -display-insert EXPRESSION - - Display EXPRESSION every time the program stops. - -GDB Command -........... - -The corresponding GDB command is `display'. - -Example -....... - -N.A. - -The `-display-list' Command ---------------------------- - -Synopsis -........ - - -display-list - - List the displays. Do not show the current values. - -GDB Command -........... - -The corresponding GDB command is `info display'. - -Example -....... - -N.A. - -The `-environment-cd' Command ------------------------------ - -Synopsis -........ - - -environment-cd PATHDIR - - Set GDB's working directory. - -GDB Command -........... - -The corresponding GDB command is `cd'. - -Example -....... - - (gdb) - -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb - ^done - (gdb) - -The `-environment-directory' Command ------------------------------------- - -Synopsis -........ - - -environment-directory [ -r ] [ PATHDIR ]+ - - Add directories PATHDIR to beginning of search path for source files. -If the `-r' option is used, the search path is reset to the default -search path. If directories PATHDIR are supplied in addition to the -`-r' option, the search path is first reset and then addition occurs as -normal. Multiple directories may be specified, separated by blanks. -Specifying multiple directories in a single command results in the -directories added to the beginning of the search path in the same order -they were presented in the command. If blanks are needed as part of a -directory name, double-quotes should be used around the name. In the -command output, the path will show up separated by the system -directory-separator character. The directory-seperator character must -not be used in any directory name. If no directories are specified, -the current search path is displayed. - -GDB Command -........... - -The corresponding GDB command is `dir'. - -Example -....... - - (gdb) - -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb - ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" - (gdb) - -environment-directory "" - ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" - (gdb) - -environment-directory -r /home/jjohnstn/src/gdb /usr/src - ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" - (gdb) - -environment-directory -r - ^done,source-path="$cdir:$cwd" - (gdb) - -The `-environment-path' Command -------------------------------- - -Synopsis -........ - - -environment-path [ -r ] [ PATHDIR ]+ - - Add directories PATHDIR to beginning of search path for object files. -If the `-r' option is used, the search path is reset to the original -search path that existed at gdb start-up. If directories PATHDIR are -supplied in addition to the `-r' option, the search path is first reset -and then addition occurs as normal. Multiple directories may be -specified, separated by blanks. Specifying multiple directories in a -single command results in the directories added to the beginning of the -search path in the same order they were presented in the command. If -blanks are needed as part of a directory name, double-quotes should be -used around the name. In the command output, the path will show up -separated by the system directory-separator character. The -directory-seperator character must not be used in any directory name. -If no directories are specified, the current path is displayed. - -GDB Command -........... - -The corresponding GDB command is `path'. - -Example -....... - - (gdb) - -environment-path - ^done,path="/usr/bin" - (gdb) - -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin - ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" - (gdb) - -environment-path -r /usr/local/bin - ^done,path="/usr/local/bin:/usr/bin" - (gdb) - -The `-environment-pwd' Command ------------------------------- - -Synopsis -........ - - -environment-pwd - - Show the current working directory. - -GDB command -........... - -The corresponding GDB command is `pwd'. - -Example -....... - - (gdb) - -environment-pwd - ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" - (gdb) - - -File: gdb.info, Node: GDB/MI Program Control, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Data Manipulation, Up: GDB/MI - -GDB/MI Program control -====================== - -Program termination -................... - -As a result of execution, the inferior program can run to completion, if -it doesn't encounter any breakpoints. In this case the output will -include an exit code, if the program has exited exceptionally. - -Examples -........ - -Program exited normally: - - (gdb) - -exec-run - ^running - (gdb) - x = 55 - *stopped,reason="exited-normally" - (gdb) - -Program exited exceptionally: - - (gdb) - -exec-run - ^running - (gdb) - x = 55 - *stopped,reason="exited",exit-code="01" - (gdb) - - Another way the program can terminate is if it receives a signal -such as `SIGINT'. In this case, GDB/MI displays this: - - (gdb) - *stopped,reason="exited-signalled",signal-name="SIGINT", - signal-meaning="Interrupt" - -The `-exec-abort' Command -------------------------- - -Synopsis -........ - - -exec-abort - - Kill the inferior running program. - -GDB Command -........... - -The corresponding GDB command is `kill'. - -Example -....... - -N.A. - -The `-exec-arguments' Command ------------------------------ - -Synopsis -........ - - -exec-arguments ARGS - - Set the inferior program arguments, to be used in the next -`-exec-run'. - -GDB Command -........... - -The corresponding GDB command is `set args'. - -Example -....... - -Don't have one around. - -The `-exec-continue' Command ----------------------------- - -Synopsis -........ - - -exec-continue - - Asynchronous command. Resumes the execution of the inferior program -until a breakpoint is encountered, or until the inferior exits. - -GDB Command -........... - -The corresponding GDB corresponding is `continue'. - -Example -....... - - -exec-continue - ^running - (gdb) - @Hello world - *stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[], - file="hello.c",line="13"} - (gdb) - -The `-exec-finish' Command --------------------------- - -Synopsis -........ - - -exec-finish - - Asynchronous command. Resumes the execution of the inferior program -until the current function is exited. Displays the results returned by -the function. - -GDB Command -........... - -The corresponding GDB command is `finish'. - -Example -....... - -Function returning `void'. - - -exec-finish - ^running - (gdb) - @hello from foo - *stopped,reason="function-finished",frame={func="main",args=[], - file="hello.c",line="7"} - (gdb) - - Function returning other than `void'. The name of the internal GDB -variable storing the result is printed, together with the value itself. - - -exec-finish - ^running - (gdb) - *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", - args=[{name="a",value="1"],{name="b",value="9"}}, - file="recursive2.c",line="14"}, - gdb-result-var="$1",return-value="0" - (gdb) - -The `-exec-interrupt' Command ------------------------------ - -Synopsis -........ - - -exec-interrupt - - Asynchronous command. Interrupts the background execution of the -target. Note how the token associated with the stop message is the one -for the execution command that has been interrupted. The token for the -interrupt itself only appears in the `^done' output. If the user is -trying to interrupt a non-running program, an error message will be -printed. - -GDB Command -........... - -The corresponding GDB command is `interrupt'. - -Example -....... - - (gdb) - 111-exec-continue - 111^running - - (gdb) - 222-exec-interrupt - 222^done - (gdb) - 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", - frame={addr="0x00010140",func="foo",args=[],file="try.c",line="13"} - (gdb) - - (gdb) - -exec-interrupt - ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." - (gdb) - -The `-exec-next' Command ------------------------- - -Synopsis -........ - - -exec-next - - Asynchronous command. Resumes execution of the inferior program, -stopping when the beginning of the next source line is reached. - -GDB Command -........... - -The corresponding GDB command is `next'. - -Example -....... - - -exec-next - ^running - (gdb) - *stopped,reason="end-stepping-range",line="8",file="hello.c" - (gdb) - -The `-exec-next-instruction' Command ------------------------------------- - -Synopsis -........ - - -exec-next-instruction - - Asynchronous command. Executes one machine instruction. If the -instruction is a function call continues until the function returns. If -the program stops at an instruction in the middle of a source line, the -address will be printed as well. - -GDB Command -........... - -The corresponding GDB command is `nexti'. - -Example -....... - - (gdb) - -exec-next-instruction - ^running - - (gdb) - *stopped,reason="end-stepping-range", - addr="0x000100d4",line="5",file="hello.c" - (gdb) - -The `-exec-return' Command --------------------------- - -Synopsis -........ - - -exec-return - - Makes current function return immediately. Doesn't execute the -inferior. Displays the new current frame. - -GDB Command -........... - -The corresponding GDB command is `return'. - -Example -....... - - (gdb) - 200-break-insert callee4 - 200^done,bkpt={number="1",addr="0x00010734", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} - (gdb) - 000-exec-run - 000^running - (gdb) - 000*stopped,reason="breakpoint-hit",bkptno="1", - frame={func="callee4",args=[], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} - (gdb) - 205-break-delete - 205^done - (gdb) - 111-exec-return - 111^done,frame={level="0",func="callee3", - args=[{name="strarg", - value="0x11940 \"A string argument.\""}], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"} - (gdb) - -The `-exec-run' Command ------------------------ - -Synopsis -........ - - -exec-run - - Asynchronous command. Starts execution of the inferior from the -beginning. The inferior executes until either a breakpoint is -encountered or the program exits. - -GDB Command -........... - -The corresponding GDB command is `run'. - -Example -....... - - (gdb) - -break-insert main - ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} - (gdb) - -exec-run - ^running - (gdb) - *stopped,reason="breakpoint-hit",bkptno="1", - frame={func="main",args=[],file="recursive2.c",line="4"} - (gdb) - -The `-exec-show-arguments' Command ----------------------------------- - -Synopsis -........ - - -exec-show-arguments - - Print the arguments of the program. - -GDB Command -........... - -The corresponding GDB command is `show args'. - -Example -....... - -N.A. - -The `-exec-step' Command ------------------------- - -Synopsis -........ - - -exec-step - - Asynchronous command. Resumes execution of the inferior program, -stopping when the beginning of the next source line is reached, if the -next source line is not a function call. If it is, stop at the first -instruction of the called function. - -GDB Command -........... - -The corresponding GDB command is `step'. - -Example -....... - -Stepping into a function: - - -exec-step - ^running - (gdb) - *stopped,reason="end-stepping-range", - frame={func="foo",args=[{name="a",value="10"}, - {name="b",value="0"}],file="recursive2.c",line="11"} - (gdb) - - Regular stepping: - - -exec-step - ^running - (gdb) - *stopped,reason="end-stepping-range",line="14",file="recursive2.c" - (gdb) - -The `-exec-step-instruction' Command ------------------------------------- - -Synopsis -........ - - -exec-step-instruction - - Asynchronous command. Resumes the inferior which executes one -machine instruction. The output, once GDB has stopped, will vary -depending on whether we have stopped in the middle of a source line or -not. In the former case, the address at which the program stopped will -be printed as well. - -GDB Command -........... - -The corresponding GDB command is `stepi'. - -Example -....... - - (gdb) - -exec-step-instruction - ^running - - (gdb) - *stopped,reason="end-stepping-range", - frame={func="foo",args=[],file="try.c",line="10"} - (gdb) - -exec-step-instruction - ^running - - (gdb) - *stopped,reason="end-stepping-range", - frame={addr="0x000100f4",func="foo",args=[],file="try.c",line="10"} - (gdb) - -The `-exec-until' Command -------------------------- - -Synopsis -........ - - -exec-until [ LOCATION ] - - Asynchronous command. Executes the inferior until the LOCATION -specified in the argument is reached. If there is no argument, the -inferior executes until a source line greater than the current one is -reached. The reason for stopping in this case will be -`location-reached'. - -GDB Command -........... - -The corresponding GDB command is `until'. - -Example -....... - - (gdb) - -exec-until recursive2.c:6 - ^running - (gdb) - x = 55 - *stopped,reason="location-reached",frame={func="main",args=[], - file="recursive2.c",line="6"} - (gdb) - -The `-file-exec-and-symbols' Command ------------------------------------- - -Synopsis -........ - - -file-exec-and-symbols FILE - - Specify the executable file to be debugged. This file is the one -from which the symbol table is also read. If no file is specified, the -command clears the executable and symbol information. If breakpoints -are set when using this command with no arguments, GDB will produce -error messages. Otherwise, no output is produced, except a completion -notification. - -GDB Command -........... - -The corresponding GDB command is `file'. - -Example -....... - - (gdb) - -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx - ^done - (gdb) - -The `-file-exec-file' Command ------------------------------ - -Synopsis -........ - - -file-exec-file FILE - - Specify the executable file to be debugged. Unlike -`-file-exec-and-symbols', the symbol table is _not_ read from this -file. If used without argument, GDB clears the information about the -executable file. No output is produced, except a completion -notification. - -GDB Command -........... - -The corresponding GDB command is `exec-file'. - -Example -....... - - (gdb) - -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx - ^done - (gdb) - -The `-file-list-exec-sections' Command --------------------------------------- - -Synopsis -........ - - -file-list-exec-sections - - List the sections of the current executable file. - -GDB Command -........... - -The GDB command `info file' shows, among the rest, the same information -as this command. `gdbtk' has a corresponding command `gdb_load_info'. - -Example -....... - -N.A. - -The `-file-list-exec-source-file' Command ------------------------------------------ - -Synopsis -........ - - -file-list-exec-source-file - - List the line number, the current source file, and the absolute path -to the current source file for the current executable. - -GDB Command -........... - -There's no GDB command which directly corresponds to this one. - -Example -....... - - (gdb) - 123-file-list-exec-source-file - 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c" - (gdb) - -The `-file-list-exec-source-files' Command ------------------------------------------- - -Synopsis -........ - - -file-list-exec-source-files - - List the source files for the current executable. - -GDB Command -........... - -There's no GDB command which directly corresponds to this one. `gdbtk' -has an analogous command `gdb_listfiles'. - -Example -....... - -N.A. - -The `-file-list-shared-libraries' Command ------------------------------------------ - -Synopsis -........ - - -file-list-shared-libraries - - List the shared libraries in the program. - -GDB Command -........... - -The corresponding GDB command is `info shared'. - -Example -....... - -N.A. - -The `-file-list-symbol-files' Command -------------------------------------- - -Synopsis -........ - - -file-list-symbol-files - - List symbol files. - -GDB Command -........... - -The corresponding GDB command is `info file' (part of it). - -Example -....... - -N.A. - -The `-file-symbol-file' Command -------------------------------- - -Synopsis -........ - - -file-symbol-file FILE - - Read symbol table info from the specified FILE argument. When used -without arguments, clears GDB's symbol table info. No output is -produced, except for a completion notification. - -GDB Command -........... - -The corresponding GDB command is `symbol-file'. - -Example -....... - - (gdb) - -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx - ^done - (gdb) - - -File: gdb.info, Node: GDB/MI Miscellaneous Commands, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Program Control, Up: GDB/MI - -Miscellaneous GDB commands in GDB/MI -==================================== - -The `-gdb-exit' Command ------------------------ - -Synopsis -........ - - -gdb-exit - - Exit GDB immediately. - -GDB Command -........... - -Approximately corresponds to `quit'. - -Example -....... - - (gdb) - -gdb-exit - -The `-gdb-set' Command ----------------------- - -Synopsis -........ - - -gdb-set - - Set an internal GDB variable. - -GDB Command -........... - -The corresponding GDB command is `set'. - -Example -....... - - (gdb) - -gdb-set $foo=3 - ^done - (gdb) - -The `-gdb-show' Command ------------------------ - -Synopsis -........ - - -gdb-show - - Show the current value of a GDB variable. - -GDB command -........... - -The corresponding GDB command is `show'. - -Example -....... - - (gdb) - -gdb-show annotate - ^done,value="0" - (gdb) - -The `-gdb-version' Command --------------------------- - -Synopsis -........ - - -gdb-version - - Show version information for GDB. Used mostly in testing. - -GDB Command -........... - -There's no equivalent GDB command. GDB by default shows this -information when you start an interactive session. - -Example -....... - - (gdb) - -gdb-version - ~GNU gdb 5.2.1 - ~Copyright 2000 Free Software Foundation, Inc. - ~GDB is free software, covered by the GNU General Public License, and - ~you are welcome to change it and/or distribute copies of it under - ~ certain conditions. - ~Type "show copying" to see the conditions. - ~There is absolutely no warranty for GDB. Type "show warranty" for - ~ details. - ~This GDB was configured as - "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". - ^done - (gdb) - -The `-interpreter-exec' Command -------------------------------- - -Synopsis --------- - - -interpreter-exec INTERPRETER COMMAND - - Execute the specified COMMAND in the given INTERPRETER. - -GDB Command ------------ - -The corresponding GDB command is `interpreter-exec'. - -Example -------- - - (gdb) - -interpreter-exec console "break main" - &"During symbol reading, couldn't parse type; debugger out of date?.\n" - &"During symbol reading, bad structure-type format.\n" - ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" - ^done - (gdb) - - -File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Symbol Query, Prev: GDB/MI Miscellaneous Commands, Up: GDB/MI - -GDB/MI Stack Manipulation Commands -================================== - -The `-stack-info-frame' Command -------------------------------- - -Synopsis -........ - - -stack-info-frame - - Get info on the current frame. - -GDB Command -........... - -The corresponding GDB command is `info frame' or `frame' (without -arguments). - -Example -....... - -N.A. - -The `-stack-info-depth' Command -------------------------------- - -Synopsis -........ - - -stack-info-depth [ MAX-DEPTH ] - - Return the depth of the stack. If the integer argument MAX-DEPTH is -specified, do not count beyond MAX-DEPTH frames. - -GDB Command -........... - -There's no equivalent GDB command. - -Example -....... - -For a stack with frame levels 0 through 11: - - (gdb) - -stack-info-depth - ^done,depth="12" - (gdb) - -stack-info-depth 4 - ^done,depth="4" - (gdb) - -stack-info-depth 12 - ^done,depth="12" - (gdb) - -stack-info-depth 11 - ^done,depth="11" - (gdb) - -stack-info-depth 13 - ^done,depth="12" - (gdb) - -The `-stack-list-arguments' Command ------------------------------------ - -Synopsis -........ - - -stack-list-arguments SHOW-VALUES - [ LOW-FRAME HIGH-FRAME ] - - Display a list of the arguments for the frames between LOW-FRAME and -HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, -list the arguments for the whole call stack. - - The SHOW-VALUES argument must have a value of 0 or 1. A value of 0 -means that only the names of the arguments are listed, a value of 1 -means that both names and values of the arguments are printed. - -GDB Command -........... - -GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' -command which partially overlaps with the functionality of -`-stack-list-arguments'. - -Example -....... - - (gdb) - -stack-list-frames - ^done, - stack=[ - frame={level="0",addr="0x00010734",func="callee4", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, - frame={level="1",addr="0x0001076c",func="callee3", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, - frame={level="2",addr="0x0001078c",func="callee2", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, - frame={level="3",addr="0x000107b4",func="callee1", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, - frame={level="4",addr="0x000107e0",func="main", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] - (gdb) - -stack-list-arguments 0 - ^done, - stack-args=[ - frame={level="0",args=[]}, - frame={level="1",args=[name="strarg"]}, - frame={level="2",args=[name="intarg",name="strarg"]}, - frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, - frame={level="4",args=[]}] - (gdb) - -stack-list-arguments 1 - ^done, - stack-args=[ - frame={level="0",args=[]}, - frame={level="1", - args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, - frame={level="2",args=[ - {name="intarg",value="2"}, - {name="strarg",value="0x11940 \"A string argument.\""}]}, - {frame={level="3",args=[ - {name="intarg",value="2"}, - {name="strarg",value="0x11940 \"A string argument.\""}, - {name="fltarg",value="3.5"}]}, - frame={level="4",args=[]}] - (gdb) - -stack-list-arguments 0 2 2 - ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] - (gdb) - -stack-list-arguments 1 2 2 - ^done,stack-args=[frame={level="2", - args=[{name="intarg",value="2"}, - {name="strarg",value="0x11940 \"A string argument.\""}]}] - (gdb) - -The `-stack-list-frames' Command --------------------------------- - -Synopsis -........ - - -stack-list-frames [ LOW-FRAME HIGH-FRAME ] - - List the frames currently on the stack. For each frame it displays -the following info: - -`LEVEL' - The frame number, 0 being the topmost frame, i.e. the innermost - function. - -`ADDR' - The `$pc' value for that frame. - -`FUNC' - Function name. - -`FILE' - File name of the source file where the function lives. - -`LINE' - Line number corresponding to the `$pc'. - - If invoked without arguments, this command prints a backtrace for the -whole stack. If given two integer arguments, it shows the frames whose -levels are between the two arguments (inclusive). If the two arguments -are equal, it shows the single frame at the corresponding level. - -GDB Command -........... - -The corresponding GDB commands are `backtrace' and `where'. - -Example -....... - -Full stack backtrace: - - (gdb) - -stack-list-frames - ^done,stack= - [frame={level="0",addr="0x0001076c",func="foo", - file="recursive2.c",line="11"}, - frame={level="1",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="2",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="4",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="5",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="6",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="7",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="8",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="9",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="10",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="11",addr="0x00010738",func="main", - file="recursive2.c",line="4"}] - (gdb) - - Show frames between LOW_FRAME and HIGH_FRAME: - - (gdb) - -stack-list-frames 3 5 - ^done,stack= - [frame={level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="4",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}, - frame={level="5",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}] - (gdb) - - Show a single frame: - - (gdb) - -stack-list-frames 3 3 - ^done,stack= - [frame={level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"}] - (gdb) - -The `-stack-list-locals' Command --------------------------------- - -Synopsis -........ - - -stack-list-locals PRINT-VALUES - - Display the local variable names for the current frame. With an -argument of 0 or `--no-values', prints only the names of the variables. -With argument of 1 or `--all-values', prints also their values. With -argument of 2 or `--simple-values', prints the name, type and value for -simple data types and the name and type for arrays, structures and -unions. In this last case, the idea is that the user can see the value -of simple data types immediately and he can create variable objects for -other data types if he wishes to explore their values in more detail. - -GDB Command -........... - -`info locals' in GDB, `gdb_get_locals' in `gdbtk'. - -Example -....... - - (gdb) - -stack-list-locals 0 - ^done,locals=[name="A",name="B",name="C"] - (gdb) - -stack-list-locals --all-values - ^done,locals=[{name="A",value="1"},{name="B",value="2"}, - {name="C",value="{1, 2, 3}"}] - -stack-list-locals --simple-values - ^done,locals=[{name="A",type="int",value="1"}, - {name="B",type="int",value="2"},{name="C",type="int [3]"}] - (gdb) - -The `-stack-select-frame' Command ---------------------------------- - -Synopsis -........ - - -stack-select-frame FRAMENUM - - Change the current frame. Select a different frame FRAMENUM on the -stack. - -GDB Command -........... - -The corresponding GDB commands are `frame', `up', `down', -`select-frame', `up-silent', and `down-silent'. - -Example -....... - - (gdb) - -stack-select-frame 2 - ^done - (gdb) - - -File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI Target Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI - -GDB/MI Symbol Query Commands -============================ - -The `-symbol-info-address' Command ----------------------------------- - -Synopsis -........ - - -symbol-info-address SYMBOL - - Describe where SYMBOL is stored. - -GDB Command -........... - -The corresponding GDB command is `info address'. - -Example -....... - -N.A. - -The `-symbol-info-file' Command -------------------------------- - -Synopsis -........ - - -symbol-info-file - - Show the file for the symbol. - -GDB Command -........... - -There's no equivalent GDB command. `gdbtk' has `gdb_find_file'. - -Example -....... - -N.A. - -The `-symbol-info-function' Command ------------------------------------ - -Synopsis -........ - - -symbol-info-function - - Show which function the symbol lives in. - -GDB Command -........... - -`gdb_get_function' in `gdbtk'. - -Example -....... - -N.A. - -The `-symbol-info-line' Command -------------------------------- - -Synopsis -........ - - -symbol-info-line - - Show the core addresses of the code for a source line. - -GDB Command -........... - -The corresponding GDB command is `info line'. `gdbtk' has the -`gdb_get_line' and `gdb_get_file' commands. - -Example -....... - -N.A. - -The `-symbol-info-symbol' Command ---------------------------------- - -Synopsis -........ - - -symbol-info-symbol ADDR - - Describe what symbol is at location ADDR. - -GDB Command -........... - -The corresponding GDB command is `info symbol'. - -Example -....... - -N.A. - -The `-symbol-list-functions' Command ------------------------------------- - -Synopsis -........ - - -symbol-list-functions - - List the functions in the executable. - -GDB Command -........... - -`info functions' in GDB, `gdb_listfunc' and `gdb_search' in `gdbtk'. - -Example -....... - -N.A. - -The `-symbol-list-lines' Command --------------------------------- - -Synopsis -........ - - -symbol-list-lines FILENAME - - Print the list of lines that contain code and their associated -program addresses for the given source filename. The entries are -sorted in ascending PC order. - -GDB Command -........... - -There is no corresponding GDB command. - -Example -....... - - (gdb) - -symbol-list-lines basics.c - ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] - (gdb) - -The `-symbol-list-types' Command --------------------------------- - -Synopsis -........ - - -symbol-list-types - - List all the type names. - -GDB Command -........... - -The corresponding commands are `info types' in GDB, `gdb_search' in -`gdbtk'. - -Example -....... - -N.A. - -The `-symbol-list-variables' Command ------------------------------------- - -Synopsis -........ - - -symbol-list-variables - - List all the global and static variable names. - -GDB Command -........... - -`info variables' in GDB, `gdb_search' in `gdbtk'. - -Example -....... - -N.A. - -The `-symbol-locate' Command ----------------------------- - -Synopsis -........ - - -symbol-locate - -GDB Command -........... - -`gdb_loc' in `gdbtk'. - -Example -....... - -N.A. - -The `-symbol-type' Command --------------------------- - -Synopsis -........ - - -symbol-type VARIABLE - - Show type of VARIABLE. - -GDB Command -........... - -The corresponding GDB command is `ptype', `gdbtk' has -`gdb_obj_variable'. - -Example -....... - -N.A. - - -File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI Thread Commands, Prev: GDB/MI Symbol Query, Up: GDB/MI - -GDB/MI Target Manipulation Commands -=================================== - -The `-target-attach' Command ----------------------------- - -Synopsis -........ - - -target-attach PID | FILE - - Attach to a process PID or a file FILE outside of GDB. - -GDB command -........... - -The corresponding GDB command is `attach'. - -Example -....... - -N.A. - -The `-target-compare-sections' Command --------------------------------------- - -Synopsis -........ - - -target-compare-sections [ SECTION ] - - Compare data of section SECTION on target to the exec file. Without -the argument, all sections are compared. - -GDB Command -........... - -The GDB equivalent is `compare-sections'. - -Example -....... - -N.A. - -The `-target-detach' Command ----------------------------- - -Synopsis -........ - - -target-detach - - Disconnect from the remote target. There's no output. - -GDB command -........... - -The corresponding GDB command is `detach'. - -Example -....... - - (gdb) - -target-detach - ^done - (gdb) - -The `-target-disconnect' Command --------------------------------- - -Synopsis -........ - - -target-disconnect - - Disconnect from the remote target. There's no output. - -GDB command -........... - -The corresponding GDB command is `disconnect'. - -Example -....... - - (gdb) - -target-disconnect - ^done - (gdb) - -The `-target-download' Command ------------------------------- - -Synopsis -........ - - -target-download - - Loads the executable onto the remote target. It prints out an -update message every half second, which includes the fields: - -`section' - The name of the section. - -`section-sent' - The size of what has been sent so far for that section. - -`section-size' - The size of the section. - -`total-sent' - The total size of what was sent so far (the current and the - previous sections). - -`total-size' - The size of the overall executable to download. - -Each message is sent as status record (*note GDB/MI Output Syntax: -GDB/MI Output Syntax.). - - In addition, it prints the name and size of the sections, as they are -downloaded. These messages include the following fields: - -`section' - The name of the section. - -`section-size' - The size of the section. - -`total-size' - The size of the overall executable to download. - -At the end, a summary is printed. - -GDB Command -........... - -The corresponding GDB command is `load'. - -Example -....... - -Note: each status message appears on a single line. Here the messages -have been broken down so that they can fit onto a page. - - (gdb) - -target-download - +download,{section=".text",section-size="6668",total-size="9880"} - +download,{section=".text",section-sent="512",section-size="6668", - total-sent="512",total-size="9880"} - +download,{section=".text",section-sent="1024",section-size="6668", - total-sent="1024",total-size="9880"} - +download,{section=".text",section-sent="1536",section-size="6668", - total-sent="1536",total-size="9880"} - +download,{section=".text",section-sent="2048",section-size="6668", - total-sent="2048",total-size="9880"} - +download,{section=".text",section-sent="2560",section-size="6668", - total-sent="2560",total-size="9880"} - +download,{section=".text",section-sent="3072",section-size="6668", - total-sent="3072",total-size="9880"} - +download,{section=".text",section-sent="3584",section-size="6668", - total-sent="3584",total-size="9880"} - +download,{section=".text",section-sent="4096",section-size="6668", - total-sent="4096",total-size="9880"} - +download,{section=".text",section-sent="4608",section-size="6668", - total-sent="4608",total-size="9880"} - +download,{section=".text",section-sent="5120",section-size="6668", - total-sent="5120",total-size="9880"} - +download,{section=".text",section-sent="5632",section-size="6668", - total-sent="5632",total-size="9880"} - +download,{section=".text",section-sent="6144",section-size="6668", - total-sent="6144",total-size="9880"} - +download,{section=".text",section-sent="6656",section-size="6668", - total-sent="6656",total-size="9880"} - +download,{section=".init",section-size="28",total-size="9880"} - +download,{section=".fini",section-size="28",total-size="9880"} - +download,{section=".data",section-size="3156",total-size="9880"} - +download,{section=".data",section-sent="512",section-size="3156", - total-sent="7236",total-size="9880"} - +download,{section=".data",section-sent="1024",section-size="3156", - total-sent="7748",total-size="9880"} - +download,{section=".data",section-sent="1536",section-size="3156", - total-sent="8260",total-size="9880"} - +download,{section=".data",section-sent="2048",section-size="3156", - total-sent="8772",total-size="9880"} - +download,{section=".data",section-sent="2560",section-size="3156", - total-sent="9284",total-size="9880"} - +download,{section=".data",section-sent="3072",section-size="3156", - total-sent="9796",total-size="9880"} - ^done,address="0x10004",load-size="9880",transfer-rate="6586", - write-rate="429" - (gdb) - -The `-target-exec-status' Command ---------------------------------- - -Synopsis -........ - - -target-exec-status - - Provide information on the state of the target (whether it is -running or not, for instance). - -GDB Command -........... - -There's no equivalent GDB command. - -Example -....... - -N.A. - -The `-target-list-available-targets' Command --------------------------------------------- - -Synopsis -........ - - -target-list-available-targets - - List the possible targets to connect to. - -GDB Command -........... - -The corresponding GDB command is `help target'. - -Example -....... - -N.A. - -The `-target-list-current-targets' Command ------------------------------------------- - -Synopsis -........ - - -target-list-current-targets - - Describe the current target. - -GDB Command -........... - -The corresponding information is printed by `info file' (among other -things). - -Example -....... - -N.A. - -The `-target-list-parameters' Command -------------------------------------- - -Synopsis -........ - - -target-list-parameters - -GDB Command -........... - -No equivalent. - -Example -....... - -N.A. - -The `-target-select' Command ----------------------------- - -Synopsis -........ - - -target-select TYPE PARAMETERS ... - - Connect GDB to the remote target. This command takes two args: - -`TYPE' - The type of target, for instance `async', `remote', etc. - -`PARAMETERS' - Device names, host names and the like. *Note Commands for - managing targets: Target Commands, for more details. - - The output is a connection notification, followed by the address at -which the target program is, in the following form: - - ^connected,addr="ADDRESS",func="FUNCTION NAME", - args=[ARG LIST] - -GDB Command -........... - -The corresponding GDB command is `target'. - -Example -....... - - (gdb) - -target-select async /dev/ttya - ^connected,addr="0xfe00a300",func="??",args=[] - (gdb) - - -File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI - -GDB/MI Thread Commands -====================== - -The `-thread-info' Command --------------------------- - -Synopsis -........ - - -thread-info - -GDB command -........... - -No equivalent. - -Example -....... - -N.A. - -The `-thread-list-all-threads' Command --------------------------------------- - -Synopsis -........ - - -thread-list-all-threads - -GDB Command -........... - -The equivalent GDB command is `info threads'. - -Example -....... - -N.A. - -The `-thread-list-ids' Command ------------------------------- - -Synopsis -........ - - -thread-list-ids - - Produces a list of the currently known GDB thread ids. At the end -of the list it also prints the total number of such threads. - -GDB Command -........... - -Part of `info threads' supplies the same information. - -Example -....... - -No threads present, besides the main process: - - (gdb) - -thread-list-ids - ^done,thread-ids={},number-of-threads="0" - (gdb) - - Several threads: - - (gdb) - -thread-list-ids - ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, - number-of-threads="3" - (gdb) - -The `-thread-select' Command ----------------------------- - -Synopsis -........ - - -thread-select THREADNUM - - Make THREADNUM the current thread. It prints the number of the new -current thread, and the topmost frame for that thread. - -GDB Command -........... - -The corresponding GDB command is `thread'. - -Example -....... - - (gdb) - -exec-next - ^running - (gdb) - *stopped,reason="end-stepping-range",thread-id="2",line="187", - file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" - (gdb) - -thread-list-ids - ^done, - thread-ids={thread-id="3",thread-id="2",thread-id="1"}, - number-of-threads="3" - (gdb) - -thread-select 3 - ^done,new-thread-id="3", - frame={level="0",func="vprintf", - args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, - {name="arg",value="0x2"}],file="vprintf.c",line="31"} - (gdb) - - -File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Variable Objects, Prev: GDB/MI Thread Commands, Up: GDB/MI - -GDB/MI Tracepoint Commands -========================== - -The tracepoint commands are not yet implemented. - - -File: gdb.info, Node: GDB/MI Variable Objects, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI - -GDB/MI Variable Objects -======================= - -Motivation for Variable Objects in GDB/MI ------------------------------------------ - -For the implementation of a variable debugger window (locals, watched -expressions, etc.), we are proposing the adaptation of the existing code -used by `Insight'. - - The two main reasons for that are: - - 1. It has been proven in practice (it is already on its second - generation). - - 2. It will shorten development time (needless to say how important it - is now). - - The original interface was designed to be used by Tcl code, so it was -slightly changed so it could be used through GDB/MI. This section -describes the GDB/MI operations that will be available and gives some -hints about their use. - - _Note_: In addition to the set of operations described here, we -expect the GUI implementation of a variable window to require, at -least, the following operations: - - * `-gdb-show' `output-radix' - - * `-stack-list-arguments' - - * `-stack-list-locals' - - * `-stack-select-frame' - -Introduction to Variable Objects in GDB/MI ------------------------------------------- - -The basic idea behind variable objects is the creation of a named object -to represent a variable, an expression, a memory location or even a CPU -register. For each object created, a set of operations is available for -examining or changing its properties. - - Furthermore, complex data types, such as C structures, are -represented in a tree format. For instance, the `struct' type variable -is the root and the children will represent the struct members. If a -child is itself of a complex type, it will also have children of its -own. Appropriate language differences are handled for C, C++ and Java. - - When returning the actual values of the objects, this facility allows -for the individual selection of the display format used in the result -creation. It can be chosen among: binary, decimal, hexadecimal, octal -and natural. Natural refers to a default format automatically chosen -based on the variable type (like decimal for an `int', hex for -pointers, etc.). - - The following is the complete set of GDB/MI operations defined to -access this functionality: - -*Operation* *Description* -`-var-create' create a variable object -`-var-delete' delete the variable object and its children -`-var-set-format' set the display format of this variable -`-var-show-format' show the display format of this variable -`-var-info-num-children' tells how many children this object has -`-var-list-children' return a list of the object's children -`-var-info-type' show the type of this variable object -`-var-info-expression' print what this variable object represents -`-var-show-attributes' is this variable editable? does it exist - here? -`-var-evaluate-expression' get the value of this variable -`-var-assign' set the value of this variable -`-var-update' update the variable and its children - - In the next subsection we describe each operation in detail and -suggest how it can be used. - -Description And Use of Operations on Variable Objects ------------------------------------------------------ - -The `-var-create' Command -------------------------- - -Synopsis -........ - - -var-create {NAME | "-"} - {FRAME-ADDR | "*"} EXPRESSION - - This operation creates a variable object, which allows the -monitoring of a variable, the result of an expression, a memory cell or -a CPU register. - - The NAME parameter is the string by which the object can be -referenced. It must be unique. If `-' is specified, the varobj system -will generate a string "varNNNNNN" automatically. It will be unique -provided that one does not specify NAME on that format. The command -fails if a duplicate name is found. - - The frame under which the expression should be evaluated can be -specified by FRAME-ADDR. A `*' indicates that the current frame should -be used. - - EXPRESSION is any expression valid on the current language set (must -not begin with a `*'), or one of the following: - - * `*ADDR', where ADDR is the address of a memory cell - - * `*ADDR-ADDR' -- a memory address range (TBD) - - * `$REGNAME' -- a CPU register name - -Result -...... - -This operation returns the name, number of children and the type of the -object created. Type is returned as a string as the ones generated by -the GDB CLI: - - name="NAME",numchild="N",type="TYPE" - -The `-var-delete' Command -------------------------- - -Synopsis -........ - - -var-delete NAME - - Deletes a previously created variable object and all of its children. - - Returns an error if the object NAME is not found. - -The `-var-set-format' Command ------------------------------ - -Synopsis -........ - - -var-set-format NAME FORMAT-SPEC - - Sets the output format for the value of the object NAME to be -FORMAT-SPEC. - - The syntax for the FORMAT-SPEC is as follows: - - FORMAT-SPEC ==> - {binary | decimal | hexadecimal | octal | natural} - -The `-var-show-format' Command ------------------------------- - -Synopsis -........ - - -var-show-format NAME - - Returns the format used to display the value of the object NAME. - - FORMAT ==> - FORMAT-SPEC - -The `-var-info-num-children' Command ------------------------------------- - -Synopsis -........ - - -var-info-num-children NAME - - Returns the number of children of a variable object NAME: - - numchild=N - -The `-var-list-children' Command --------------------------------- - -Synopsis -........ - - -var-list-children [PRINT-VALUES] NAME - - Returns a list of the children of the specified variable object. -With just the variable object name as an argument or with an optional -preceding argument of 0 or `--no-values', prints only the names of the -variables. With an optional preceding argument of 1 or `--all-values', -also prints their values. - -Example -....... - - (gdb) - -var-list-children n - numchild=N,children=[{name=NAME, - numchild=N,type=TYPE},(repeats N times)] - (gdb) - -var-list-children --all-values n - numchild=N,children=[{name=NAME, - numchild=N,value=VALUE,type=TYPE},(repeats N times)] - -The `-var-info-type' Command ----------------------------- - -Synopsis -........ - - -var-info-type NAME - - Returns the type of the specified variable NAME. The type is -returned as a string in the same format as it is output by the GDB CLI: - - type=TYPENAME - -The `-var-info-expression' Command ----------------------------------- - -Synopsis -........ - - -var-info-expression NAME - - Returns what is represented by the variable object NAME: - - lang=LANG-SPEC,exp=EXPRESSION - -where LANG-SPEC is `{"C" | "C++" | "Java"}'. - -The `-var-show-attributes' Command ----------------------------------- - -Synopsis -........ - - -var-show-attributes NAME - - List attributes of the specified variable object NAME: - - status=ATTR [ ( ,ATTR )* ] - -where ATTR is `{ { editable | noneditable } | TBD }'. - -The `-var-evaluate-expression' Command --------------------------------------- - -Synopsis -........ - - -var-evaluate-expression NAME - - Evaluates the expression that is represented by the specified -variable object and returns its value as a string in the current format -specified for the object: - - value=VALUE - - Note that one must invoke `-var-list-children' for a variable before -the value of a child variable can be evaluated. - -The `-var-assign' Command -------------------------- - -Synopsis -........ - - -var-assign NAME EXPRESSION - - Assigns the value of EXPRESSION to the variable object specified by -NAME. The object must be `editable'. If the variable's value is -altered by the assign, the variable will show up in any subsequent -`-var-update' list. - -Example -....... - - (gdb) - -var-assign var1 3 - ^done,value="3" - (gdb) - -var-update * - ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] - (gdb) - -The `-var-update' Command -------------------------- - -Synopsis -........ - - -var-update {NAME | "*"} - - Update the value of the variable object NAME by evaluating its -expression after fetching all the new values from memory or registers. -A `*' causes all existing variable objects to be updated. - - -File: gdb.info, Node: Annotations, Next: GDB/MI, Prev: Emacs, Up: Top - -GDB Annotations -*************** - -This chapter describes annotations in GDB. Annotations were designed -to interface GDB to graphical user interfaces or other similar programs -which want to interact with GDB at a relatively high level. - - The annotation mechanism has largely been superseeded by GDB/MI -(*note GDB/MI::). - -* Menu: - -* Annotations Overview:: What annotations are; the general syntax. -* Server Prefix:: Issuing a command without affecting user state. -* Prompting:: Annotations marking GDB's need for input. -* Errors:: Annotations for error messages. -* Invalidation:: Some annotations describe things now invalid. -* Annotations for Running:: - Whether the program is running, how it stopped, etc. -* Source Annotations:: Annotations describing source code. - - -File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations - -What is an Annotation? -====================== - -Annotations start with a newline character, two `control-z' characters, -and the name of the annotation. If there is no additional information -associated with this annotation, the name of the annotation is followed -immediately by a newline. If there is additional information, the name -of the annotation is followed by a space, the additional information, -and a newline. The additional information cannot contain newline -characters. - - Any output not beginning with a newline and two `control-z' -characters denotes literal output from GDB. Currently there is no need -for GDB to output a newline followed by two `control-z' characters, but -if there was such a need, the annotations could be extended with an -`escape' annotation which means those three characters as output. - - The annotation LEVEL, which is specified using the `--annotate' -command line option (*note Mode Options::), controls how much -information GDB prints together with its prompt, values of expressions, -source lines, and other types of output. Level 0 is for no anntations, -level 1 is for use when GDB is run as a subprocess of GNU Emacs, level -3 is the maximum annotation suitable for programs that control GDB, and -level 2 annotations have been made obsolete (*note Limitations of the -Annotation Interface: (annotate)Limitations.). This chapter describes -level 3 annotations. - - A simple example of starting up GDB with annotations is: - - $ gdb --annotate=3 - GNU gdb 6.0 - Copyright 2003 Free Software Foundation, Inc. - GDB is free software, covered by the GNU General Public License, - and you are welcome to change it and/or distribute copies of it - under certain conditions. - Type "show copying" to see the conditions. - There is absolutely no warranty for GDB. Type "show warranty" - for details. - This GDB was configured as "i386-pc-linux-gnu" - - ^Z^Zpre-prompt - (gdb) - ^Z^Zprompt - quit - - ^Z^Zpost-prompt - $ - - Here `quit' is input to GDB; the rest is output from GDB. The three -lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are -annotations; the rest is output from GDB. - - -File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations - -The Server Prefix -================= - -To issue a command to GDB without affecting certain aspects of the -state which is seen by users, prefix it with `server '. This means -that this command will not affect the command history, nor will it -affect GDB's notion of which command to repeat if <RET> is pressed on a -line by itself. - - The server prefix does not affect the recording of values into the -value history; to print a value without recording it into the value -history, use the `output' command instead of the `print' command. - - -File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations - -Annotation for GDB Input -======================== - -When GDB prompts for input, it annotates this fact so it is possible to -know when to send output, when the output from a given command is over, -etc. - - Different kinds of input each have a different "input type". Each -input type has three annotations: a `pre-' annotation, which denotes -the beginning of any prompt which is being output, a plain annotation, -which denotes the end of the prompt, and then a `post-' annotation -which denotes the end of any echo which may (or may not) be associated -with the input. For example, the `prompt' input type features the -following annotations: - - ^Z^Zpre-prompt - ^Z^Zprompt - ^Z^Zpost-prompt - - The input types are - -`prompt' - When GDB is prompting for a command (the main GDB prompt). - -`commands' - When GDB prompts for a set of commands, like in the `commands' - command. The annotations are repeated for each command which is - input. - -`overload-choice' - When GDB wants the user to select between various overloaded - functions. - -`query' - When GDB wants the user to confirm a potentially dangerous - operation. - -`prompt-for-continue' - When GDB is asking the user to press return to continue. Note: - Don't expect this to work well; instead use `set height 0' to - disable prompting. This is because the counting of lines is buggy - in the presence of annotations. - - -File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations - -Errors -====== - - ^Z^Zquit - - This annotation occurs right before GDB responds to an interrupt. - - ^Z^Zerror - - This annotation occurs right before GDB responds to an error. - - Quit and error annotations indicate that any annotations which GDB -was in the middle of may end abruptly. For example, if a -`value-history-begin' annotation is followed by a `error', one cannot -expect to receive the matching `value-history-end'. One cannot expect -not to receive it either, however; an error annotation does not -necessarily mean that GDB is immediately returning all the way to the -top level. - - A quit or error annotation may be preceded by - - ^Z^Zerror-begin - - Any output between that and the quit or error annotation is the error -message. - - Warning messages are not yet annotated. - - -File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations - -Invalidation Notices -==================== - -The following annotations say that certain pieces of state may have -changed. - -`^Z^Zframes-invalid' - The frames (for example, output from the `backtrace' command) may - have changed. - -`^Z^Zbreakpoints-invalid' - The breakpoints may have changed. For example, the user just - added or deleted a breakpoint. - - -File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations - -Running the Program -=================== - -When the program starts executing due to a GDB command such as `step' -or `continue', - - ^Z^Zstarting - - is output. When the program stops, - - ^Z^Zstopped - - is output. Before the `stopped' annotation, a variety of -annotations describe how the program stopped. - -`^Z^Zexited EXIT-STATUS' - The program exited, and EXIT-STATUS is the exit status (zero for - successful exit, otherwise nonzero). - -`^Z^Zsignalled' - The program exited with a signal. After the `^Z^Zsignalled', the - annotation continues: - - INTRO-TEXT - ^Z^Zsignal-name - NAME - ^Z^Zsignal-name-end - MIDDLE-TEXT - ^Z^Zsignal-string - STRING - ^Z^Zsignal-string-end - END-TEXT - - where NAME is the name of the signal, such as `SIGILL' or - `SIGSEGV', and STRING is the explanation of the signal, such as - `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, - MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no - particular format. - -`^Z^Zsignal' - The syntax of this annotation is just like `signalled', but GDB is - just saying that the program received the signal, not that it was - terminated with it. - -`^Z^Zbreakpoint NUMBER' - The program hit breakpoint number NUMBER. - -`^Z^Zwatchpoint NUMBER' - The program hit watchpoint number NUMBER. - - -File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations - -Displaying Source -================= - -The following annotation is used instead of displaying source code: - - ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR - - where FILENAME is an absolute file name indicating which source -file, LINE is the line number within that file (where 1 is the first -line in the file), CHARACTER is the character position within the file -(where 0 is the first character in the file) (for most debug formats -this will necessarily point to the beginning of a line), MIDDLE is -`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at -the beginning of the line, and ADDR is the address in the target -program associated with the source which is being displayed. ADDR is -in the form `0x' followed by one or more lowercase hex digits (note -that this does not depend on the language). - - -File: gdb.info, Node: GDB Bugs, Next: Formatting Documentation, Prev: GDB/MI, Up: Top - -Reporting Bugs in GDB -********************* - -Your bug reports play an essential role in making GDB reliable. - - Reporting a bug may help you by bringing a solution to your problem, -or it may not. But in any case the principal function of a bug report -is to help the entire community by making the next version of GDB work -better. Bug reports are your contribution to the maintenance of GDB. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -* Menu: - -* Bug Criteria:: Have you found a bug? -* Bug Reporting:: How to report bugs - - -File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs - -Have you found a bug? -===================== - -If you are not sure whether you have found a bug, here are some -guidelines: - - * If the debugger gets a fatal signal, for any input whatever, that - is a GDB bug. Reliable debuggers never crash. - - * If GDB produces an error message for valid input, that is a bug. - (Note that if you're cross debugging, the problem may also be - somewhere in the connection to the target.) - - * If GDB does not produce an error message for invalid input, that - is a bug. However, you should note that your idea of "invalid - input" might be our idea of "an extension" or "support for - traditional practice". - - * If you are an experienced user of debugging tools, your suggestions - for improvement of GDB are welcome in any case. - - -File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs - -How to report bugs -================== - -A number of companies and individuals offer support for GNU products. -If you obtained GDB from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file `etc/SERVICE' in the GNU Emacs distribution. - - In any event, we also recommend that you submit bug reports for GDB. -The prefered method is to submit them directly using GDB's Bugs web -page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the -e-mail gateway <bug-gdb@gnu.org> can be used. - - *Do not send bug reports to `info-gdb', or to `help-gdb', or to any -newsgroups.* Most users of GDB do not want to receive bug reports. -Those that do have arranged to receive `bug-gdb'. - - The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which -serves as a repeater. The mailing list and the newsgroup carry exactly -the same messages. Often people think of posting bug reports to the -newsgroup instead of mailing them. This appears to work, but it has one -problem which can be crucial: a newsgroup posting often lacks a mail -path back to the sender. Thus, if we need to ask for more information, -we may be unable to reach you. For this reason, it is better to send -bug reports to the mailing list. - - The fundamental principle of reporting bugs usefully is this: -*report all the facts*. If you are not sure whether to state a fact or -leave it out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of the variable you use in an example does not -matter. Well, probably it does not, but one cannot be sure. Perhaps -the bug is a stray memory reference which happens to fetch from the -location where that name is stored in memory; perhaps, if the name were -different, the contents of that location would fool the debugger into -doing the right thing despite the bug. Play it safe and give a -specific, complete example. That is the easiest thing for you to do, -and the most helpful. - - Keep in mind that the purpose of a bug report is to enable us to fix -the bug. It may be that the bug has been reported previously, but -neither you nor we can know that unless your bug report is complete and -self-contained. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" Those bug reports are useless, and we urge everyone to _refuse -to respond to them_ except to chide the sender to report bugs properly. - - To enable us to fix the bug, you should include all these things: - - * The version of GDB. GDB announces it if you start with no - arguments; you can also print it at any time using `show version'. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of GDB. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile GDB--e.g. - "gcc-2.8.1". - - * What compiler (and its version) was used to compile the program - you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP - C Compiler". For GCC, you can say `gcc --version' to get this - information; for other compilers, see the documentation for those - compilers. - - * The command arguments you gave the compiler to compile your - example and observe the bug. For example, did you use `-O'? To - guarantee you will not omit something important, list them all. A - copy of the Makefile (or the output from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input script, and all necessary source files, that will - reproduce the bug. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that GDB gets a fatal signal, then we - will certainly notice it. But if the bug is incorrect output, we - might not notice unless it is glaringly wrong. You might as well - not give us a chance to make a mistake. - - Even if the problem you experience is a fatal signal, you should - still say so explicitly. Suppose something strange is going on, - such as, your copy of GDB is out of synch, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - * If you wish to suggest changes to the GDB source, send us context - diffs. If you even discuss something in the GDB source, refer to - it by context, not by line number. - - The line numbers in our development sources will not match those - in your sources. Your line numbers would convey no useful - information to us. - - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - Often people who encounter a bug spend a lot of time investigating - which changes to the input file will make the bug go away and which - changes will not affect it. - - This is often time consuming and not very useful, because the way - we will find the bug is by running a single example under the - debugger with breakpoints, not by pure deduction from a series of - examples. We recommend that you save your time for something else. - - Of course, if you can find a simpler example to report _instead_ - of the original one, that is a convenience for us. Errors in the - output will be easier to spot, running under the debugger will take - less time, and so on. - - However, simplification is not vital; if you do not want to do - this, report the bug anyway and send us the entire test case you - used. - - * A patch for the bug. - - A patch for the bug does help us if it is a good one. But do not - omit the necessary information, such as the test case, on the - assumption that a patch is all we need. We might see problems - with your patch and decide to fix the problem another way, or we - might not understand it at all. - - Sometimes with a program as complicated as GDB it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify - that the bug is fixed. - - And if we cannot understand what bug you are trying to fix, or why - your patch should be an improvement, we will not install it. A - test case will help us to understand. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - - -File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Formatting Documentation, Up: Top - -Command Line Editing -******************** - -This chapter describes the basic features of the GNU command line -editing interface. - -* Menu: - -* Introduction and Notation:: Notation used in this text. -* Readline Interaction:: The minimum set of commands for editing a line. -* Readline Init File:: Customizing Readline from a user's view. -* Bindable Readline Commands:: A description of most of the Readline commands - available for binding -* Readline vi Mode:: A short description of how to make Readline - behave like the vi editor. - - -File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing - -Introduction to Line Editing -============================ - -The following paragraphs describe the notation used to represent -keystrokes. - - The text `C-k' is read as `Control-K' and describes the character -produced when the <k> key is pressed while the Control key is depressed. - - The text `M-k' is read as `Meta-K' and describes the character -produced when the Meta key (if you have one) is depressed, and the <k> -key is pressed. The Meta key is labeled <ALT> on many keyboards. On -keyboards with two keys labeled <ALT> (usually to either side of the -space bar), the <ALT> on the left side is generally set to work as a -Meta key. The <ALT> key on the right may also be configured to work as -a Meta key or may be configured as some other modifier, such as a -Compose key for typing accented characters. - - If you do not have a Meta or <ALT> key, or another key working as a -Meta key, the identical keystroke can be generated by typing <ESC> -_first_, and then typing <k>. Either process is known as "metafying" -the <k> key. - - The text `M-C-k' is read as `Meta-Control-k' and describes the -character produced by "metafying" `C-k'. - - In addition, several keys have their own names. Specifically, -<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves -when seen in this text, or in an init file (*note Readline Init File::). -If your keyboard lacks a <LFD> key, typing <C-j> will produce the -desired character. The <RET> key may be labeled <Return> or <Enter> on -some keyboards. - - -File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing - -Readline Interaction -==================== - -Often during an interactive session you type in a long line of text, -only to notice that the first word on the line is misspelled. The -Readline library gives you a set of commands for manipulating the text -as you type it in, allowing you to just fix your typo, and not forcing -you to retype the majority of the line. Using these editing commands, -you move the cursor to the place that needs correction, and delete or -insert the text of the corrections. Then, when you are satisfied with -the line, you simply press <RET>. You do not have to be at the end of -the line to press <RET>; the entire line is accepted regardless of the -location of the cursor within the line. - -* Menu: - -* Readline Bare Essentials:: The least you need to know about Readline. -* Readline Movement Commands:: Moving about the input line. -* Readline Killing Commands:: How to delete text, and how to get it back! -* Readline Arguments:: Giving numeric arguments to commands. -* Searching:: Searching through previous lines. - - -File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction - -Readline Bare Essentials ------------------------- - -In order to enter characters into the line, simply type them. The typed -character appears where the cursor was, and then the cursor moves one -space to the right. If you mistype a character, you can use your erase -character to back up and delete the mistyped character. - - Sometimes you may mistype a character, and not notice the error -until you have typed several other characters. In that case, you can -type `C-b' to move the cursor to the left, and then correct your -mistake. Afterwards, you can move the cursor to the right with `C-f'. - - When you add text in the middle of a line, you will notice that -characters to the right of the cursor are `pushed over' to make room -for the text that you have inserted. Likewise, when you delete text -behind the cursor, characters to the right of the cursor are `pulled -back' to fill in the blank space created by the removal of the text. A -list of the bare essentials for editing the text of an input line -follows. - -`C-b' - Move back one character. - -`C-f' - Move forward one character. - -<DEL> or <Backspace> - Delete the character to the left of the cursor. - -`C-d' - Delete the character underneath the cursor. - -Printing characters - Insert the character into the line at the cursor. - -`C-_' or `C-x C-u' - Undo the last editing command. You can undo all the way back to an - empty line. - -(Depending on your configuration, the <Backspace> key be set to delete -the character to the left of the cursor and the <DEL> key set to delete -the character underneath the cursor, like `C-d', rather than the -character to the left of the cursor.) - - -File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction - -Readline Movement Commands --------------------------- - -The above table describes the most basic keystrokes that you need in -order to do editing of the input line. For your convenience, many -other commands have been added in addition to `C-b', `C-f', `C-d', and -<DEL>. Here are some commands for moving more rapidly about the line. - -`C-a' - Move to the start of the line. - -`C-e' - Move to the end of the line. - -`M-f' - Move forward a word, where a word is composed of letters and - digits. - -`M-b' - Move backward a word. - -`C-l' - Clear the screen, reprinting the current line at the top. - - Notice how `C-f' moves forward a character, while `M-f' moves -forward a word. It is a loose convention that control keystrokes -operate on characters while meta keystrokes operate on words. - - -File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction - -Readline Killing Commands -------------------------- - -"Killing" text means to delete the text from the line, but to save it -away for later use, usually by "yanking" (re-inserting) it back into -the line. (`Cut' and `paste' are more recent jargon for `kill' and -`yank'.) - - If the description for a command says that it `kills' text, then you -can be sure that you can get the text back in a different (or the same) -place later. - - When you use a kill command, the text is saved in a "kill-ring". -Any number of consecutive kills save all of the killed text together, so -that when you yank it back, you get it all. The kill ring is not line -specific; the text that you killed on a previously typed line is -available to be yanked back later, when you are typing another line. - - Here is the list of commands for killing text. - -`C-k' - Kill the text from the current cursor position to the end of the - line. - -`M-d' - Kill from the cursor to the end of the current word, or, if between - words, to the end of the next word. Word boundaries are the same - as those used by `M-f'. - -`M-<DEL>' - Kill from the cursor the start of the current word, or, if between - words, to the start of the previous word. Word boundaries are the - same as those used by `M-b'. - -`C-w' - Kill from the cursor to the previous whitespace. This is - different than `M-<DEL>' because the word boundaries differ. - - - Here is how to "yank" the text back into the line. Yanking means to -copy the most-recently-killed text from the kill buffer. - -`C-y' - Yank the most recently killed text back into the buffer at the - cursor. - -`M-y' - Rotate the kill-ring, and yank the new top. You can only do this - if the prior command is `C-y' or `M-y'. - - -File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction - -Readline Arguments ------------------- - -You can pass numeric arguments to Readline commands. Sometimes the -argument acts as a repeat count, other times it is the sign of the -argument that is significant. If you pass a negative argument to a -command which normally acts in a forward direction, that command will -act in a backward direction. For example, to kill text back to the -start of the line, you might type `M-- C-k'. - - The general way to pass numeric arguments to a command is to type -meta digits before the command. If the first `digit' typed is a minus -sign (`-'), then the sign of the argument will be negative. Once you -have typed one meta digit to get the argument started, you can type the -remainder of the digits, and then the command. For example, to give -the `C-d' command an argument of 10, you could type `M-1 0 C-d', which -will delete the next ten characters on the input line. - diff --git a/contrib/gdb/gdb/doc/gdb.info-3 b/contrib/gdb/gdb/doc/gdb.info-3 deleted file mode 100644 index ada53b48bb5f..000000000000 --- a/contrib/gdb/gdb/doc/gdb.info-3 +++ /dev/null @@ -1,6665 +0,0 @@ -This is gdb.info, produced by makeinfo version 4.6 from ./gdb.texinfo. - -INFO-DIR-SECTION Software development -START-INFO-DIR-ENTRY -* Gdb: (gdb). The GNU debugger. -END-INFO-DIR-ENTRY - - This file documents the GNU debugger GDB. - - This is the Ninth Edition, of `Debugging with GDB: the GNU -Source-Level Debugger' for GDB Version 6.1.1. - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1998, -1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "Free Software" and "Free Software Needs Free -Documentation", with the Front-Cover Texts being "A GNU Manual," and -with the Back-Cover Texts as in (a) below. - - (a) The Free Software Foundation's Back-Cover Text is: "You have -freedom to copy and modify this GNU Manual, like GNU software. Copies -published by the Free Software Foundation raise funds for GNU -development." - - -File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction - -Searching for Commands in the History -------------------------------------- - -Readline provides commands for searching through the command history -for lines containing a specified string. There are two search modes: -"incremental" and "non-incremental". - - Incremental searches begin before the user has finished typing the -search string. As each character of the search string is typed, -Readline displays the next entry from the history matching the string -typed so far. An incremental search requires only as many characters -as needed to find the desired history entry. To search backward in the -history for a particular string, type `C-r'. Typing `C-s' searches -forward through the history. The characters present in the value of -the `isearch-terminators' variable are used to terminate an incremental -search. If that variable has not been assigned a value, the <ESC> and -`C-J' characters will terminate an incremental search. `C-g' will -abort an incremental search and restore the original line. When the -search is terminated, the history entry containing the search string -becomes the current line. - - To find other matching entries in the history list, type `C-r' or -`C-s' as appropriate. This will search backward or forward in the -history for the next entry matching the search string typed so far. -Any other key sequence bound to a Readline command will terminate the -search and execute that command. For instance, a <RET> will terminate -the search and accept the line, thereby executing the command from the -history list. A movement command will terminate the search, make the -last line found the current line, and begin editing. - - Readline remembers the last incremental search string. If two -`C-r's are typed without any intervening characters defining a new -search string, any remembered search string is used. - - Non-incremental searches read the entire search string before -starting to search for matching history lines. The search string may be -typed by the user or be part of the contents of the current line. - - -File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing - -Readline Init File -================== - -Although the Readline library comes with a set of Emacs-like -keybindings installed by default, it is possible to use a different set -of keybindings. Any user can customize programs that use Readline by -putting commands in an "inputrc" file, conventionally in his home -directory. The name of this file is taken from the value of the -environment variable `INPUTRC'. If that variable is unset, the default -is `~/.inputrc'. - - When a program which uses the Readline library starts up, the init -file is read, and the key bindings are set. - - In addition, the `C-x C-r' command re-reads this init file, thus -incorporating any changes that you might have made to it. - -* Menu: - -* Readline Init File Syntax:: Syntax for the commands in the inputrc file. - -* Conditional Init Constructs:: Conditional key bindings in the inputrc file. - -* Sample Init File:: An example inputrc file. - - -File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File - -Readline Init File Syntax -------------------------- - -There are only a few basic constructs allowed in the Readline init -file. Blank lines are ignored. Lines beginning with a `#' are -comments. Lines beginning with a `$' indicate conditional constructs -(*note Conditional Init Constructs::). Other lines denote variable -settings and key bindings. - -Variable Settings - You can modify the run-time behavior of Readline by altering the - values of variables in Readline using the `set' command within the - init file. The syntax is simple: - - set VARIABLE VALUE - - Here, for example, is how to change from the default Emacs-like - key binding to use `vi' line editing commands: - - set editing-mode vi - - Variable names and values, where appropriate, are recognized - without regard to case. - - A great deal of run-time behavior is changeable with the following - variables. - - `bell-style' - Controls what happens when Readline wants to ring the - terminal bell. If set to `none', Readline never rings the - bell. If set to `visible', Readline uses a visible bell if - one is available. If set to `audible' (the default), - Readline attempts to ring the terminal's bell. - - `comment-begin' - The string to insert at the beginning of the line when the - `insert-comment' command is executed. The default value is - `"#"'. - - `completion-ignore-case' - If set to `on', Readline performs filename matching and - completion in a case-insensitive fashion. The default value - is `off'. - - `completion-query-items' - The number of possible completions that determines when the - user is asked whether he wants to see the list of - possibilities. If the number of possible completions is - greater than this value, Readline will ask the user whether - or not he wishes to view them; otherwise, they are simply - listed. This variable must be set to an integer value - greater than or equal to 0. The default limit is `100'. - - `convert-meta' - If set to `on', Readline will convert characters with the - eighth bit set to an ASCII key sequence by stripping the - eighth bit and prefixing an <ESC> character, converting them - to a meta-prefixed key sequence. The default value is `on'. - - `disable-completion' - If set to `On', Readline will inhibit word completion. - Completion characters will be inserted into the line as if - they had been mapped to `self-insert'. The default is `off'. - - `editing-mode' - The `editing-mode' variable controls which default set of key - bindings is used. By default, Readline starts up in Emacs - editing mode, where the keystrokes are most similar to Emacs. - This variable can be set to either `emacs' or `vi'. - - `enable-keypad' - When set to `on', Readline will try to enable the application - keypad when it is called. Some systems need this to enable - the arrow keys. The default is `off'. - - `expand-tilde' - If set to `on', tilde expansion is performed when Readline - attempts word completion. The default is `off'. - - If set to `on', the history code attempts to place point at - the same location on each history line retrived with - `previous-history' or `next-history'. - - `horizontal-scroll-mode' - This variable can be set to either `on' or `off'. Setting it - to `on' means that the text of the lines being edited will - scroll horizontally on a single screen line when they are - longer than the width of the screen, instead of wrapping onto - a new screen line. By default, this variable is set to `off'. - - `input-meta' - If set to `on', Readline will enable eight-bit input (it will - not clear the eighth bit in the characters it reads), - regardless of what the terminal claims it can support. The - default value is `off'. The name `meta-flag' is a synonym - for this variable. - - `isearch-terminators' - The string of characters that should terminate an incremental - search without subsequently executing the character as a - command (*note Searching::). If this variable has not been - given a value, the characters <ESC> and `C-J' will terminate - an incremental search. - - `keymap' - Sets Readline's idea of the current keymap for key binding - commands. Acceptable `keymap' names are `emacs', - `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', - `vi-command', and `vi-insert'. `vi' is equivalent to - `vi-command'; `emacs' is equivalent to `emacs-standard'. The - default value is `emacs'. The value of the `editing-mode' - variable also affects the default keymap. - - `mark-directories' - If set to `on', completed directory names have a slash - appended. The default is `on'. - - `mark-modified-lines' - This variable, when set to `on', causes Readline to display an - asterisk (`*') at the start of history lines which have been - modified. This variable is `off' by default. - - `mark-symlinked-directories' - If set to `on', completed names which are symbolic links to - directories have a slash appended (subject to the value of - `mark-directories'). The default is `off'. - - `match-hidden-files' - This variable, when set to `on', causes Readline to match - files whose names begin with a `.' (hidden files) when - performing filename completion, unless the leading `.' is - supplied by the user in the filename to be completed. This - variable is `on' by default. - - `output-meta' - If set to `on', Readline will display characters with the - eighth bit set directly rather than as a meta-prefixed escape - sequence. The default is `off'. - - `page-completions' - If set to `on', Readline uses an internal `more'-like pager - to display a screenful of possible completions at a time. - This variable is `on' by default. - - `print-completions-horizontally' - If set to `on', Readline will display completions with matches - sorted horizontally in alphabetical order, rather than down - the screen. The default is `off'. - - `show-all-if-ambiguous' - This alters the default behavior of the completion functions. - If set to `on', words which have more than one possible - completion cause the matches to be listed immediately instead - of ringing the bell. The default value is `off'. - - `visible-stats' - If set to `on', a character denoting a file's type is - appended to the filename when listing possible completions. - The default is `off'. - - -Key Bindings - The syntax for controlling key bindings in the init file is - simple. First you need to find the name of the command that you - want to change. The following sections contain tables of the - command name, the default keybinding, if any, and a short - description of what the command does. - - Once you know the name of the command, simply place on a line in - the init file the name of the key you wish to bind the command to, - a colon, and then the name of the command. The name of the key - can be expressed in different ways, depending on what you find most - comfortable. - - In addition to command names, readline allows keys to be bound to - a string that is inserted when the key is pressed (a MACRO). - - KEYNAME: FUNCTION-NAME or MACRO - KEYNAME is the name of a key spelled out in English. For - example: - Control-u: universal-argument - Meta-Rubout: backward-kill-word - Control-o: "> output" - - In the above example, `C-u' is bound to the function - `universal-argument', `M-DEL' is bound to the function - `backward-kill-word', and `C-o' is bound to run the macro - expressed on the right hand side (that is, to insert the text - `> output' into the line). - - A number of symbolic character names are recognized while - processing this key binding syntax: DEL, ESC, ESCAPE, LFD, - NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. - - "KEYSEQ": FUNCTION-NAME or MACRO - KEYSEQ differs from KEYNAME above in that strings denoting an - entire key sequence can be specified, by placing the key - sequence in double quotes. Some GNU Emacs style key escapes - can be used, as in the following example, but the special - character names are not recognized. - - "\C-u": universal-argument - "\C-x\C-r": re-read-init-file - "\e[11~": "Function Key 1" - - In the above example, `C-u' is again bound to the function - `universal-argument' (just as it was in the first example), - `C-x C-r' is bound to the function `re-read-init-file', and - `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function - Key 1'. - - - The following GNU Emacs style escape sequences are available when - specifying key sequences: - - `\C-' - control prefix - - `\M-' - meta prefix - - `\e' - an escape character - - `\\' - backslash - - `\"' - <">, a double quotation mark - - `\'' - <'>, a single quote or apostrophe - - In addition to the GNU Emacs style escape sequences, a second set - of backslash escapes is available: - - `\a' - alert (bell) - - `\b' - backspace - - `\d' - delete - - `\f' - form feed - - `\n' - newline - - `\r' - carriage return - - `\t' - horizontal tab - - `\v' - vertical tab - - `\NNN' - the eight-bit character whose value is the octal value NNN - (one to three digits) - - `\xHH' - the eight-bit character whose value is the hexadecimal value - HH (one or two hex digits) - - When entering the text of a macro, single or double quotes must be - used to indicate a macro definition. Unquoted text is assumed to - be a function name. In the macro body, the backslash escapes - described above are expanded. Backslash will quote any other - character in the macro text, including `"' and `''. For example, - the following binding will make `C-x \' insert a single `\' into - the line: - "\C-x\\": "\\" - - - -File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File - -Conditional Init Constructs ---------------------------- - -Readline implements a facility similar in spirit to the conditional -compilation features of the C preprocessor which allows key bindings -and variable settings to be performed as the result of tests. There -are four parser directives used. - -`$if' - The `$if' construct allows bindings to be made based on the - editing mode, the terminal being used, or the application using - Readline. The text of the test extends to the end of the line; no - characters are required to isolate it. - - `mode' - The `mode=' form of the `$if' directive is used to test - whether Readline is in `emacs' or `vi' mode. This may be - used in conjunction with the `set keymap' command, for - instance, to set bindings in the `emacs-standard' and - `emacs-ctlx' keymaps only if Readline is starting out in - `emacs' mode. - - `term' - The `term=' form may be used to include terminal-specific key - bindings, perhaps to bind the key sequences output by the - terminal's function keys. The word on the right side of the - `=' is tested against both the full name of the terminal and - the portion of the terminal name before the first `-'. This - allows `sun' to match both `sun' and `sun-cmd', for instance. - - `application' - The APPLICATION construct is used to include - application-specific settings. Each program using the - Readline library sets the APPLICATION NAME, and you can test - for a particular value. This could be used to bind key - sequences to functions useful for a specific program. For - instance, the following command adds a key sequence that - quotes the current or previous word in Bash: - $if Bash - # Quote the current or previous word - "\C-xq": "\eb\"\ef\"" - $endif - -`$endif' - This command, as seen in the previous example, terminates an `$if' - command. - -`$else' - Commands in this branch of the `$if' directive are executed if the - test fails. - -`$include' - This directive takes a single filename as an argument and reads - commands and bindings from that file. For example, the following - directive reads from `/etc/inputrc': - $include /etc/inputrc - - -File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File - -Sample Init File ----------------- - -Here is an example of an INPUTRC file. This illustrates key binding, -variable assignment, and conditional syntax. - - - # This file controls the behaviour of line input editing for - # programs that use the GNU Readline library. Existing - # programs include FTP, Bash, and GDB. - # - # You can re-read the inputrc file with C-x C-r. - # Lines beginning with '#' are comments. - # - # First, include any systemwide bindings and variable - # assignments from /etc/Inputrc - $include /etc/Inputrc - - # - # Set various bindings for emacs mode. - - set editing-mode emacs - - $if mode=emacs - - Meta-Control-h: backward-kill-word Text after the function name is ignored - - # - # Arrow keys in keypad mode - # - #"\M-OD": backward-char - #"\M-OC": forward-char - #"\M-OA": previous-history - #"\M-OB": next-history - # - # Arrow keys in ANSI mode - # - "\M-[D": backward-char - "\M-[C": forward-char - "\M-[A": previous-history - "\M-[B": next-history - # - # Arrow keys in 8 bit keypad mode - # - #"\M-\C-OD": backward-char - #"\M-\C-OC": forward-char - #"\M-\C-OA": previous-history - #"\M-\C-OB": next-history - # - # Arrow keys in 8 bit ANSI mode - # - #"\M-\C-[D": backward-char - #"\M-\C-[C": forward-char - #"\M-\C-[A": previous-history - #"\M-\C-[B": next-history - - C-q: quoted-insert - - $endif - - # An old-style binding. This happens to be the default. - TAB: complete - - # Macros that are convenient for shell interaction - $if Bash - # edit the path - "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" - # prepare to type a quoted word -- - # insert open and close double quotes - # and move to just after the open quote - "\C-x\"": "\"\"\C-b" - # insert a backslash (testing backslash escapes - # in sequences and macros) - "\C-x\\": "\\" - # Quote the current or previous word - "\C-xq": "\eb\"\ef\"" - # Add a binding to refresh the line, which is unbound - "\C-xr": redraw-current-line - # Edit variable on current line. - "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" - $endif - - # use a visible bell if one is available - set bell-style visible - - # don't strip characters to 7 bits when reading - set input-meta on - - # allow iso-latin1 characters to be inserted rather - # than converted to prefix-meta sequences - set convert-meta off - - # display characters with the eighth bit set directly - # rather than as meta-prefixed characters - set output-meta on - - # if there are more than 150 possible completions for - # a word, ask the user if he wants to see all of them - set completion-query-items 150 - - # For FTP - $if Ftp - "\C-xg": "get \M-?" - "\C-xt": "put \M-?" - "\M-.": yank-last-arg - $endif - - -File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing - -Bindable Readline Commands -========================== - -* Menu: - -* Commands For Moving:: Moving about the line. -* Commands For History:: Getting at previous lines. -* Commands For Text:: Commands for changing text. -* Commands For Killing:: Commands for killing and yanking. -* Numeric Arguments:: Specifying numeric arguments, repeat counts. -* Commands For Completion:: Getting Readline to do the typing for you. -* Keyboard Macros:: Saving and re-executing typed characters -* Miscellaneous Commands:: Other miscellaneous commands. - - This section describes Readline commands that may be bound to key -sequences. Command names without an accompanying key sequence are -unbound by default. - - In the following descriptions, "point" refers to the current cursor -position, and "mark" refers to a cursor position saved by the -`set-mark' command. The text between the point and mark is referred to -as the "region". - - -File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands - -Commands For Moving -------------------- - -`beginning-of-line (C-a)' - Move to the start of the current line. - -`end-of-line (C-e)' - Move to the end of the line. - -`forward-char (C-f)' - Move forward a character. - -`backward-char (C-b)' - Move back a character. - -`forward-word (M-f)' - Move forward to the end of the next word. Words are composed of - letters and digits. - -`backward-word (M-b)' - Move back to the start of the current or previous word. Words are - composed of letters and digits. - -`clear-screen (C-l)' - Clear the screen and redraw the current line, leaving the current - line at the top of the screen. - -`redraw-current-line ()' - Refresh the current line. By default, this is unbound. - - - -File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands - -Commands For Manipulating The History -------------------------------------- - -`accept-line (Newline or Return)' - Accept the line regardless of where the cursor is. If this line is - non-empty, it may be added to the history list for future recall - with `add_history()'. If this line is a modified history line, - the history line is restored to its original state. - -`previous-history (C-p)' - Move `back' through the history list, fetching the previous - command. - -`next-history (C-n)' - Move `forward' through the history list, fetching the next command. - -`beginning-of-history (M-<)' - Move to the first line in the history. - -`end-of-history (M->)' - Move to the end of the input history, i.e., the line currently - being entered. - -`reverse-search-history (C-r)' - Search backward starting at the current line and moving `up' - through the history as necessary. This is an incremental search. - -`forward-search-history (C-s)' - Search forward starting at the current line and moving `down' - through the the history as necessary. This is an incremental - search. - -`non-incremental-reverse-search-history (M-p)' - Search backward starting at the current line and moving `up' - through the history as necessary using a non-incremental search - for a string supplied by the user. - -`non-incremental-forward-search-history (M-n)' - Search forward starting at the current line and moving `down' - through the the history as necessary using a non-incremental search - for a string supplied by the user. - -`history-search-forward ()' - Search forward through the history for the string of characters - between the start of the current line and the point. This is a - non-incremental search. By default, this command is unbound. - -`history-search-backward ()' - Search backward through the history for the string of characters - between the start of the current line and the point. This is a - non-incremental search. By default, this command is unbound. - -`yank-nth-arg (M-C-y)' - Insert the first argument to the previous command (usually the - second word on the previous line) at point. With an argument N, - insert the Nth word from the previous command (the words in the - previous command begin with word 0). A negative argument inserts - the Nth word from the end of the previous command. - -`yank-last-arg (M-. or M-_)' - Insert last argument to the previous command (the last word of the - previous history entry). With an argument, behave exactly like - `yank-nth-arg'. Successive calls to `yank-last-arg' move back - through the history list, inserting the last argument of each line - in turn. - - - -File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands - -Commands For Changing Text --------------------------- - -`delete-char (C-d)' - Delete the character at point. If point is at the beginning of - the line, there are no characters in the line, and the last - character typed was not bound to `delete-char', then return EOF. - -`backward-delete-char (Rubout)' - Delete the character behind the cursor. A numeric argument means - to kill the characters instead of deleting them. - -`forward-backward-delete-char ()' - Delete the character under the cursor, unless the cursor is at the - end of the line, in which case the character behind the cursor is - deleted. By default, this is not bound to a key. - -`quoted-insert (C-q or C-v)' - Add the next character typed to the line verbatim. This is how to - insert key sequences like `C-q', for example. - -`tab-insert (M-<TAB>)' - Insert a tab character. - -`self-insert (a, b, A, 1, !, ...)' - Insert yourself. - -`transpose-chars (C-t)' - Drag the character before the cursor forward over the character at - the cursor, moving the cursor forward as well. If the insertion - point is at the end of the line, then this transposes the last two - characters of the line. Negative arguments have no effect. - -`transpose-words (M-t)' - Drag the word before point past the word after point, moving point - past that word as well. If the insertion point is at the end of - the line, this transposes the last two words on the line. - -`upcase-word (M-u)' - Uppercase the current (or following) word. With a negative - argument, uppercase the previous word, but do not move the cursor. - -`downcase-word (M-l)' - Lowercase the current (or following) word. With a negative - argument, lowercase the previous word, but do not move the cursor. - -`capitalize-word (M-c)' - Capitalize the current (or following) word. With a negative - argument, capitalize the previous word, but do not move the cursor. - -`overwrite-mode ()' - Toggle overwrite mode. With an explicit positive numeric argument, - switches to overwrite mode. With an explicit non-positive numeric - argument, switches to insert mode. This command affects only - `emacs' mode; `vi' mode does overwrite differently. Each call to - `readline()' starts in insert mode. - - In overwrite mode, characters bound to `self-insert' replace the - text at point rather than pushing the text to the right. - Characters bound to `backward-delete-char' replace the character - before point with a space. - - By default, this command is unbound. - - - -File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands - -Killing And Yanking -------------------- - -`kill-line (C-k)' - Kill the text from point to the end of the line. - -`backward-kill-line (C-x Rubout)' - Kill backward to the beginning of the line. - -`unix-line-discard (C-u)' - Kill backward from the cursor to the beginning of the current line. - -`kill-whole-line ()' - Kill all characters on the current line, no matter where point is. - By default, this is unbound. - -`kill-word (M-d)' - Kill from point to the end of the current word, or if between - words, to the end of the next word. Word boundaries are the same - as `forward-word'. - -`backward-kill-word (M-<DEL>)' - Kill the word behind point. Word boundaries are the same as - `backward-word'. - -`unix-word-rubout (C-w)' - Kill the word behind point, using white space as a word boundary. - The killed text is saved on the kill-ring. - -`delete-horizontal-space ()' - Delete all spaces and tabs around point. By default, this is - unbound. - -`kill-region ()' - Kill the text in the current region. By default, this command is - unbound. - -`copy-region-as-kill ()' - Copy the text in the region to the kill buffer, so it can be yanked - right away. By default, this command is unbound. - -`copy-backward-word ()' - Copy the word before point to the kill buffer. The word - boundaries are the same as `backward-word'. By default, this - command is unbound. - -`copy-forward-word ()' - Copy the word following point to the kill buffer. The word - boundaries are the same as `forward-word'. By default, this - command is unbound. - -`yank (C-y)' - Yank the top of the kill ring into the buffer at point. - -`yank-pop (M-y)' - Rotate the kill-ring, and yank the new top. You can only do this - if the prior command is `yank' or `yank-pop'. - - -File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands - -Specifying Numeric Arguments ----------------------------- - -`digit-argument (M-0, M-1, ... M--)' - Add this digit to the argument already accumulating, or start a new - argument. `M--' starts a negative argument. - -`universal-argument ()' - This is another way to specify an argument. If this command is - followed by one or more digits, optionally with a leading minus - sign, those digits define the argument. If the command is - followed by digits, executing `universal-argument' again ends the - numeric argument, but is otherwise ignored. As a special case, if - this command is immediately followed by a character that is - neither a digit or minus sign, the argument count for the next - command is multiplied by four. The argument count is initially - one, so executing this function the first time makes the argument - count four, a second time makes the argument count sixteen, and so - on. By default, this is not bound to a key. - - -File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands - -Letting Readline Type For You ------------------------------ - -`complete (<TAB>)' - Attempt to perform completion on the text before point. The - actual completion performed is application-specific. The default - is filename completion. - -`possible-completions (M-?)' - List the possible completions of the text before point. - -`insert-completions (M-*)' - Insert all completions of the text before point that would have - been generated by `possible-completions'. - -`menu-complete ()' - Similar to `complete', but replaces the word to be completed with - a single match from the list of possible completions. Repeated - execution of `menu-complete' steps through the list of possible - completions, inserting each match in turn. At the end of the list - of completions, the bell is rung (subject to the setting of - `bell-style') and the original text is restored. An argument of N - moves N positions forward in the list of matches; a negative - argument may be used to move backward through the list. This - command is intended to be bound to <TAB>, but is unbound by - default. - -`delete-char-or-list ()' - Deletes the character under the cursor if not at the beginning or - end of the line (like `delete-char'). If at the end of the line, - behaves identically to `possible-completions'. This command is - unbound by default. - - - -File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands - -Keyboard Macros ---------------- - -`start-kbd-macro (C-x ()' - Begin saving the characters typed into the current keyboard macro. - -`end-kbd-macro (C-x ))' - Stop saving the characters typed into the current keyboard macro - and save the definition. - -`call-last-kbd-macro (C-x e)' - Re-execute the last keyboard macro defined, by making the - characters in the macro appear as if typed at the keyboard. - - - -File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands - -Some Miscellaneous Commands ---------------------------- - -`re-read-init-file (C-x C-r)' - Read in the contents of the INPUTRC file, and incorporate any - bindings or variable assignments found there. - -`abort (C-g)' - Abort the current editing command and ring the terminal's bell - (subject to the setting of `bell-style'). - -`do-uppercase-version (M-a, M-b, M-X, ...)' - If the metafied character X is lowercase, run the command that is - bound to the corresponding uppercase character. - -`prefix-meta (<ESC>)' - Metafy the next character typed. This is for keyboards without a - meta key. Typing `<ESC> f' is equivalent to typing `M-f'. - -`undo (C-_ or C-x C-u)' - Incremental undo, separately remembered for each line. - -`revert-line (M-r)' - Undo all changes made to this line. This is like executing the - `undo' command enough times to get back to the beginning. - -`tilde-expand (M-~)' - Perform tilde expansion on the current word. - -`set-mark (C-@)' - Set the mark to the point. If a numeric argument is supplied, the - mark is set to that position. - -`exchange-point-and-mark (C-x C-x)' - Swap the point with the mark. The current cursor position is set - to the saved position, and the old cursor position is saved as the - mark. - -`character-search (C-])' - A character is read and point is moved to the next occurrence of - that character. A negative count searches for previous - occurrences. - -`character-search-backward (M-C-])' - A character is read and point is moved to the previous occurrence - of that character. A negative count searches for subsequent - occurrences. - -`insert-comment (M-#)' - Without a numeric argument, the value of the `comment-begin' - variable is inserted at the beginning of the current line. If a - numeric argument is supplied, this command acts as a toggle: if - the characters at the beginning of the line do not match the value - of `comment-begin', the value is inserted, otherwise the - characters in `comment-begin' are deleted from the beginning of - the line. In either case, the line is accepted as if a newline - had been typed. - -`dump-functions ()' - Print all of the functions and their key bindings to the Readline - output stream. If a numeric argument is supplied, the output is - formatted in such a way that it can be made part of an INPUTRC - file. This command is unbound by default. - -`dump-variables ()' - Print all of the settable variables and their values to the - Readline output stream. If a numeric argument is supplied, the - output is formatted in such a way that it can be made part of an - INPUTRC file. This command is unbound by default. - -`dump-macros ()' - Print all of the Readline key sequences bound to macros and the - strings they output. If a numeric argument is supplied, the - output is formatted in such a way that it can be made part of an - INPUTRC file. This command is unbound by default. - -`emacs-editing-mode (C-e)' - When in `vi' command mode, this causes a switch to `emacs' editing - mode. - -`vi-editing-mode (M-C-j)' - When in `emacs' editing mode, this causes a switch to `vi' editing - mode. - - - -File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing - -Readline vi Mode -================ - -While the Readline library does not have a full set of `vi' editing -functions, it does contain enough to allow simple editing of the line. -The Readline `vi' mode behaves as specified in the POSIX 1003.2 -standard. - - In order to switch interactively between `emacs' and `vi' editing -modes, use the command `M-C-j' (bound to emacs-editing-mode when in -`vi' mode and to vi-editing-mode in `emacs' mode). The Readline -default is `emacs' mode. - - When you enter a line in `vi' mode, you are already placed in -`insertion' mode, as if you had typed an `i'. Pressing <ESC> switches -you into `command' mode, where you can edit the text of the line with -the standard `vi' movement keys, move to previous history lines with -`k' and subsequent lines with `j', and so forth. - - -File: gdb.info, Node: Using History Interactively, Next: Installing GDB, Prev: Command Line Editing, Up: Top - -Using History Interactively -*************************** - -This chapter describes how to use the GNU History Library interactively, -from a user's standpoint. It should be considered a user's guide. - -* Menu: - -* History Interaction:: What it feels like using History as a user. - - -File: gdb.info, Node: History Interaction, Up: Using History Interactively - -History Expansion -================= - -The History library provides a history expansion feature that is similar -to the history expansion provided by `csh'. This section describes the -syntax used to manipulate the history information. - - History expansions introduce words from the history list into the -input stream, making it easy to repeat commands, insert the arguments -to a previous command into the current input line, or fix errors in -previous commands quickly. - - History expansion takes place in two parts. The first is to -determine which line from the history list should be used during -substitution. The second is to select portions of that line for -inclusion into the current one. The line selected from the history is -called the "event", and the portions of that line that are acted upon -are called "words". Various "modifiers" are available to manipulate -the selected words. The line is broken into words in the same fashion -that Bash does, so that several words surrounded by quotes are -considered one word. History expansions are introduced by the -appearance of the history expansion character, which is `!' by default. - -* Menu: - -* Event Designators:: How to specify which history line to use. -* Word Designators:: Specifying which words are of interest. -* Modifiers:: Modifying the results of substitution. - - -File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction - -Event Designators ------------------ - -An event designator is a reference to a command line entry in the -history list. - -`!' - Start a history substitution, except when followed by a space, tab, - the end of the line, `=' or `('. - -`!N' - Refer to command line N. - -`!-N' - Refer to the command N lines back. - -`!!' - Refer to the previous command. This is a synonym for `!-1'. - -`!STRING' - Refer to the most recent command starting with STRING. - -`!?STRING[?]' - Refer to the most recent command containing STRING. The trailing - `?' may be omitted if the STRING is followed immediately by a - newline. - -`^STRING1^STRING2^' - Quick Substitution. Repeat the last command, replacing STRING1 - with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. - -`!#' - The entire command line typed so far. - - - -File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction - -Word Designators ----------------- - -Word designators are used to select desired words from the event. A -`:' separates the event specification from the word designator. It may -be omitted if the word designator begins with a `^', `$', `*', `-', or -`%'. Words are numbered from the beginning of the line, with the first -word being denoted by 0 (zero). Words are inserted into the current -line separated by single spaces. - - For example, - -`!!' - designates the preceding command. When you type this, the - preceding command is repeated in toto. - -`!!:$' - designates the last argument of the preceding command. This may be - shortened to `!$'. - -`!fi:2' - designates the second argument of the most recent command starting - with the letters `fi'. - - Here are the word designators: - -`0 (zero)' - The `0'th word. For many applications, this is the command word. - -`N' - The Nth word. - -`^' - The first argument; that is, word 1. - -`$' - The last argument. - -`%' - The word matched by the most recent `?STRING?' search. - -`X-Y' - A range of words; `-Y' abbreviates `0-Y'. - -`*' - All of the words, except the `0'th. This is a synonym for `1-$'. - It is not an error to use `*' if there is just one word in the - event; the empty string is returned in that case. - -`X*' - Abbreviates `X-$' - -`X-' - Abbreviates `X-$' like `X*', but omits the last word. - - - If a word designator is supplied without an event specification, the -previous command is used as the event. - - -File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction - -Modifiers ---------- - -After the optional word designator, you can add a sequence of one or -more of the following modifiers, each preceded by a `:'. - -`h' - Remove a trailing pathname component, leaving only the head. - -`t' - Remove all leading pathname components, leaving the tail. - -`r' - Remove a trailing suffix of the form `.SUFFIX', leaving the - basename. - -`e' - Remove all but the trailing suffix. - -`p' - Print the new command but do not execute it. - -`s/OLD/NEW/' - Substitute NEW for the first occurrence of OLD in the event line. - Any delimiter may be used in place of `/'. The delimiter may be - quoted in OLD and NEW with a single backslash. If `&' appears in - NEW, it is replaced by OLD. A single backslash will quote the - `&'. The final delimiter is optional if it is the last character - on the input line. - -`&' - Repeat the previous substitution. - -`g' - Cause changes to be applied over the entire event line. Used in - conjunction with `s', as in `gs/OLD/NEW/', or with `&'. - - - -File: gdb.info, Node: Formatting Documentation, Next: Command Line Editing, Prev: GDB Bugs, Up: Top - -Formatting Documentation -************************ - -The GDB 4 release includes an already-formatted reference card, ready -for printing with PostScript or Ghostscript, in the `gdb' subdirectory -of the main source directory(1). If you can use PostScript or -Ghostscript with your printer, you can print the reference card -immediately with `refcard.ps'. - - The release also includes the source for the reference card. You -can format it, using TeX, by typing: - - make refcard.dvi - - The GDB reference card is designed to print in "landscape" mode on -US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches -high. You will need to specify this form of printing as an option to -your DVI output program. - - All the documentation for GDB comes as part of the machine-readable -distribution. The documentation is written in Texinfo format, which is -a documentation system that uses a single source file to produce both -on-line information and a printed manual. You can use one of the Info -formatting commands to create the on-line version of the documentation -and TeX (or `texi2roff') to typeset the printed version. - - GDB includes an already formatted copy of the on-line Info version -of this manual in the `gdb' subdirectory. The main Info file is -`gdb-6.1.1/gdb/gdb.info', and it refers to subordinate files matching -`gdb.info*' in the same directory. If necessary, you can print out -these files, or read them with any editor; but they are easier to read -using the `info' subsystem in GNU Emacs or the standalone `info' -program, available as part of the GNU Texinfo distribution. - - If you want to format these Info files yourself, you need one of the -Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. - - If you have `makeinfo' installed, and are in the top level GDB -source directory (`gdb-6.1.1', in the case of version 6.1.1), you can -make the Info file by typing: - - cd gdb - make gdb.info - - If you want to typeset and print copies of this manual, you need TeX, -a program to print its DVI output files, and `texinfo.tex', the Texinfo -definitions file. - - TeX is a typesetting program; it does not print files directly, but -produces output files called DVI files. To print a typeset document, -you need a program to print DVI files. If your system has TeX -installed, chances are it has such a program. The precise command to -use depends on your system; `lpr -d' is common; another (for PostScript -devices) is `dvips'. The DVI print command may require a file name -without any extension or a `.dvi' extension. - - TeX also requires a macro definitions file called `texinfo.tex'. -This file tells TeX how to typeset a document written in Texinfo -format. On its own, TeX cannot either read or typeset a Texinfo file. -`texinfo.tex' is distributed with GDB and is located in the -`gdb-VERSION-NUMBER/texinfo' directory. - - If you have TeX and a DVI printer program installed, you can typeset -and print this manual. First switch to the the `gdb' subdirectory of -the main source directory (for example, to `gdb-6.1.1/gdb') and type: - - make gdb.dvi - - Then give `gdb.dvi' to your DVI printing program. - - ---------- Footnotes ---------- - - (1) In `gdb-6.1.1/gdb/refcard.ps' of the version 6.1.1 release. - - -File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Using History Interactively, Up: Top - -Installing GDB -************** - -GDB comes with a `configure' script that automates the process of -preparing GDB for installation; you can then use `make' to build the -`gdb' program. - - The GDB distribution includes all the source code you need for GDB -in a single directory, whose name is usually composed by appending the -version number to `gdb'. - - For example, the GDB version 6.1.1 distribution is in the -`gdb-6.1.1' directory. That directory contains: - -`gdb-6.1.1/configure (and supporting files)' - script for configuring GDB and all its supporting libraries - -`gdb-6.1.1/gdb' - the source specific to GDB itself - -`gdb-6.1.1/bfd' - source for the Binary File Descriptor library - -`gdb-6.1.1/include' - GNU include files - -`gdb-6.1.1/libiberty' - source for the `-liberty' free software library - -`gdb-6.1.1/opcodes' - source for the library of opcode tables and disassemblers - -`gdb-6.1.1/readline' - source for the GNU command-line interface - -`gdb-6.1.1/glob' - source for the GNU filename pattern-matching subroutine - -`gdb-6.1.1/mmalloc' - source for the GNU memory-mapped malloc package - - The simplest way to configure and build GDB is to run `configure' -from the `gdb-VERSION-NUMBER' source directory, which in this example -is the `gdb-6.1.1' directory. - - First switch to the `gdb-VERSION-NUMBER' source directory if you are -not already in it; then run `configure'. Pass the identifier for the -platform on which GDB will run as an argument. - - For example: - - cd gdb-6.1.1 - ./configure HOST - make - -where HOST is an identifier such as `sun4' or `decstation', that -identifies the platform where GDB will run. (You can often leave off -HOST; `configure' tries to guess the correct value by examining your -system.) - - Running `configure HOST' and then running `make' builds the `bfd', -`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. -The configured source files, and the binaries, are left in the -corresponding source directories. - - `configure' is a Bourne-shell (`/bin/sh') script; if your system -does not recognize this automatically when you run a different shell, -you may need to run `sh' on it explicitly: - - sh configure HOST - - If you run `configure' from a directory that contains source -directories for multiple libraries or programs, such as the `gdb-6.1.1' -source directory for version 6.1.1, `configure' creates configuration -files for every directory level underneath (unless you tell it not to, -with the `--norecursion' option). - - You should run the `configure' script from the top directory in the -source tree, the `gdb-VERSION-NUMBER' directory. If you run -`configure' from one of the subdirectories, you will configure only -that subdirectory. That is usually not what you want. In particular, -if you run the first `configure' from the `gdb' subdirectory of the -`gdb-VERSION-NUMBER' directory, you will omit the configuration of -`bfd', `readline', and other sibling directories of the `gdb' -subdirectory. This leads to build errors about missing include files -such as `bfd/bfd.h'. - - You can install `gdb' anywhere; it has no hardwired paths. However, -you should make sure that the shell on your path (named by the `SHELL' -environment variable) is publicly readable. Remember that GDB uses the -shell to start your program--some systems refuse to let GDB debug child -processes whose programs are not readable. - -* Menu: - -* Separate Objdir:: Compiling GDB in another directory -* Config Names:: Specifying names for hosts and targets -* Configure Options:: Summary of options for configure - - -File: gdb.info, Node: Separate Objdir, Next: Config Names, Up: Installing GDB - -Compiling GDB in another directory -================================== - -If you want to run GDB versions for several host or target machines, -you need a different `gdb' compiled for each combination of host and -target. `configure' is designed to make this easy by allowing you to -generate each configuration in a separate subdirectory, rather than in -the source directory. If your `make' program handles the `VPATH' -feature (GNU `make' does), running `make' in each of these directories -builds the `gdb' program specified there. - - To build `gdb' in a separate directory, run `configure' with the -`--srcdir' option to specify where to find the source. (You also need -to specify a path to find `configure' itself from your working -directory. If the path to `configure' would be the same as the -argument to `--srcdir', you can leave out the `--srcdir' option; it is -assumed.) - - For example, with version 6.1.1, you can build GDB in a separate -directory for a Sun 4 like this: - - cd gdb-6.1.1 - mkdir ../gdb-sun4 - cd ../gdb-sun4 - ../gdb-6.1.1/configure sun4 - make - - When `configure' builds a configuration using a remote source -directory, it creates a tree for the binaries with the same structure -(and using the same names) as the tree under the source directory. In -the example, you'd find the Sun 4 library `libiberty.a' in the -directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. - - Make sure that your path to the `configure' script has just one -instance of `gdb' in it. If your path to `configure' looks like -`../gdb-6.1.1/gdb/configure', you are configuring only one subdirectory -of GDB, not the whole package. This leads to build errors about -missing include files such as `bfd/bfd.h'. - - One popular reason to build several GDB configurations in separate -directories is to configure GDB for cross-compiling (where GDB runs on -one machine--the "host"--while debugging programs that run on another -machine--the "target"). You specify a cross-debugging target by giving -the `--target=TARGET' option to `configure'. - - When you run `make' to build a program or library, you must run it -in a configured directory--whatever directory you were in when you -called `configure' (or one of its subdirectories). - - The `Makefile' that `configure' generates in each source directory -also runs recursively. If you type `make' in a source directory such -as `gdb-6.1.1' (or in a separate configured directory configured with -`--srcdir=DIRNAME/gdb-6.1.1'), you will build all the required -libraries, and then build GDB. - - When you have multiple hosts or targets configured in separate -directories, you can run `make' on them in parallel (for example, if -they are NFS-mounted on each of the hosts); they will not interfere -with each other. - - -File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB - -Specifying names for hosts and targets -====================================== - -The specifications used for hosts and targets in the `configure' script -are based on a three-part naming scheme, but some short predefined -aliases are also supported. The full naming scheme encodes three pieces -of information in the following pattern: - - ARCHITECTURE-VENDOR-OS - - For example, you can use the alias `sun4' as a HOST argument, or as -the value for TARGET in a `--target=TARGET' option. The equivalent -full name is `sparc-sun-sunos4'. - - The `configure' script accompanying GDB does not provide any query -facility to list all supported host and target names or aliases. -`configure' calls the Bourne shell script `config.sub' to map -abbreviations to full names; you can read the script, if you wish, or -you can use it to test your guesses on abbreviations--for example: - - % sh config.sub i386-linux - i386-pc-linux-gnu - % sh config.sub alpha-linux - alpha-unknown-linux-gnu - % sh config.sub hp9k700 - hppa1.1-hp-hpux - % sh config.sub sun4 - sparc-sun-sunos4.1.1 - % sh config.sub sun3 - m68k-sun-sunos4.1.1 - % sh config.sub i986v - Invalid configuration `i986v': machine `i986v' not recognized - -`config.sub' is also distributed in the GDB source directory -(`gdb-6.1.1', for version 6.1.1). - - -File: gdb.info, Node: Configure Options, Prev: Config Names, Up: Installing GDB - -`configure' options -=================== - -Here is a summary of the `configure' options and arguments that are -most often useful for building GDB. `configure' also has several other -options not listed here. *note (configure.info)What Configure Does::, -for a full explanation of `configure'. - - configure [--help] - [--prefix=DIR] - [--exec-prefix=DIR] - [--srcdir=DIRNAME] - [--norecursion] [--rm] - [--target=TARGET] - HOST - -You may introduce options with a single `-' rather than `--' if you -prefer; but you may abbreviate option names if you use `--'. - -`--help' - Display a quick summary of how to invoke `configure'. - -`--prefix=DIR' - Configure the source to install programs and files under directory - `DIR'. - -`--exec-prefix=DIR' - Configure the source to install programs under directory `DIR'. - -`--srcdir=DIRNAME' - *Warning: using this option requires GNU `make', or another `make' - that implements the `VPATH' feature.* - Use this option to make configurations in directories separate - from the GDB source directories. Among other things, you can use - this to build (or maintain) several configurations simultaneously, - in separate directories. `configure' writes configuration - specific files in the current directory, but arranges for them to - use the source in the directory DIRNAME. `configure' creates - directories under the working directory in parallel to the source - directories below DIRNAME. - -`--norecursion' - Configure only the directory level where `configure' is executed; - do not propagate configuration to subdirectories. - -`--target=TARGET' - Configure GDB for cross-debugging programs running on the specified - TARGET. Without this option, GDB is configured to debug programs - that run on the same machine (HOST) as GDB itself. - - There is no convenient way to generate a list of all available - targets. - -`HOST ...' - Configure GDB to run on the specified HOST. - - There is no convenient way to generate a list of all available - hosts. - - There are many other options available as well, but they are -generally needed for special purposes only. - - -File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top - -Maintenance Commands -******************** - -In addition to commands intended for GDB users, GDB includes a number -of commands intended for GDB developers. These commands are provided -here for reference. - -`maint info breakpoints' - Using the same format as `info breakpoints', display both the - breakpoints you've set explicitly, and those GDB is using for - internal purposes. Internal breakpoints are shown with negative - breakpoint numbers. The type column identifies what kind of - breakpoint is shown: - - `breakpoint' - Normal, explicitly set breakpoint. - - `watchpoint' - Normal, explicitly set watchpoint. - - `longjmp' - Internal breakpoint, used to handle correctly stepping through - `longjmp' calls. - - `longjmp resume' - Internal breakpoint at the target of a `longjmp'. - - `until' - Temporary internal breakpoint used by the GDB `until' command. - - `finish' - Temporary internal breakpoint used by the GDB `finish' - command. - - `shlib events' - Shared library events. - - -`maint internal-error' -`maint internal-warning' - Cause GDB to call the internal function `internal_error' or - `internal_warning' and hence behave as though an internal error or - internal warning has been detected. In addition to reporting the - internal problem, these functions give the user the opportunity to - either quit GDB or create a core file of the current GDB session. - - (gdb) maint internal-error testing, 1, 2 - .../maint.c:121: internal-error: testing, 1, 2 - A problem internal to GDB has been detected. Further - debugging may prove unreliable. - Quit this debugging session? (y or n) n - Create a core file? (y or n) n - (gdb) - - Takes an optional parameter that is used as the text of the error - or warning message. - -`maint print dummy-frames' - Prints the contents of GDB's internal dummy-frame stack. - - (gdb) b add - ... - (gdb) print add(2,3) - Breakpoint 2, add (a=2, b=3) at ... - 58 return (a + b); - The program being debugged stopped while in a function called from GDB. - ... - (gdb) maint print dummy-frames - 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 - top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} - call_lo=0x01014000 call_hi=0x01014001 - (gdb) - - Takes an optional file parameter. - -`maint print registers' -`maint print raw-registers' -`maint print cooked-registers' -`maint print register-groups' - Print GDB's internal register data structures. - - The command `maint print raw-registers' includes the contents of - the raw register cache; the command `maint print cooked-registers' - includes the (cooked) value of all registers; and the command - `maint print register-groups' includes the groups that each - register is a member of. *Note Registers: (gdbint)Registers. - - Takes an optional file parameter. - -`maint print reggroups' - Print GDB's internal register group data structures. - - Takes an optional file parameter. - - (gdb) maint print reggroups - Group Type - general user - float user - all user - vector user - system user - save internal - restore internal - -`maint set profile' -`maint show profile' - Control profiling of GDB. - - Profiling will be disabled until you use the `maint set profile' - command to enable it. When you enable profiling, the system will - begin collecting timing and execution count data; when you disable - profiling or exit GDB, the results will be written to a log file. - Remember that if you use profiling, GDB will overwrite the - profiling log file (often called `gmon.out'). If you have a - record of important profiling data in a `gmon.out' file, be sure - to move it to a safe location. - - Configuring with `--enable-profiling' arranges for GDB to be - compiled with the `-pg' compiler option. - - - -File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top - -GDB Remote Serial Protocol -************************** - -* Menu: - -* Overview:: -* Packets:: -* Stop Reply Packets:: -* General Query Packets:: -* Register Packet Format:: -* Examples:: -* File-I/O remote protocol extension:: - - -File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol - -Overview -======== - -There may be occasions when you need to know something about the -protocol--for example, if there is only one serial port to your target -machine, you might want your program to do something special if it -recognizes a packet meant for GDB. - - In the examples below, `->' and `<-' are used to indicate -transmitted and received data respectfully. - - All GDB commands and responses (other than acknowledgments) are sent -as a PACKET. A PACKET is introduced with the character `$', the actual -PACKET-DATA, and the terminating character `#' followed by a two-digit -CHECKSUM: - - `$'PACKET-DATA`#'CHECKSUM - -The two-digit CHECKSUM is computed as the modulo 256 sum of all -characters between the leading `$' and the trailing `#' (an eight bit -unsigned checksum). - - Implementors should note that prior to GDB 5.0 the protocol -specification also included an optional two-digit SEQUENCE-ID: - - `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM - -That SEQUENCE-ID was appended to the acknowledgment. GDB has never -output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 -must not accept SEQUENCE-ID. - - When either the host or the target machine receives a packet, the -first response expected is an acknowledgment: either `+' (to indicate -the package was received correctly) or `-' (to request retransmission): - - -> `$'PACKET-DATA`#'CHECKSUM - <- `+' - -The host (GDB) sends COMMANDs, and the target (the debugging stub -incorporated in your program) sends a RESPONSE. In the case of step -and continue COMMANDs, the response is only sent when the operation has -completed (the target has again stopped). - - PACKET-DATA consists of a sequence of characters with the exception -of `#' and `$' (see `X' packet for additional exceptions). - - Fields within the packet should be separated using `,' `;' or `:'. -Except where otherwise noted all numbers are represented in HEX with -leading zeros suppressed. - - Implementors should note that prior to GDB 5.0, the character `:' -could not appear as the third character in a packet (as it would -potentially conflict with the SEQUENCE-ID). - - Response DATA can be run-length encoded to save space. A `*' means -that the next character is an ASCII encoding giving a repeat count -which stands for that many repetitions of the character preceding the -`*'. The encoding is `n+29', yielding a printable character where `n ->=3' (which is where rle starts to win). The printable characters `$', -`#', `+' and `-' or with a numeric value greater than 126 should not be -used. - - So: - "`0* '" - -means the same as "0000". - - The error response returned for some packets includes a two character -error number. That number is not well defined. - - For any COMMAND not supported by the stub, an empty response -(`$#00') should be returned. That way it is possible to extend the -protocol. A newer GDB can tell if a packet is supported based on that -response. - - A stub is required to support the `g', `G', `m', `M', `c', and `s' -COMMANDs. All other COMMANDs are optional. - - -File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol - -Packets -======= - -The following table provides a complete list of all currently defined -COMMANDs and their corresponding response DATA. - -`!' -- extended mode - Enable extended mode. In extended mode, the remote server is made - persistent. The `R' packet is used to restart the program being - debugged. - - Reply: - `OK' - The remote target both supports and has enabled extended mode. - -`?' -- last signal - Indicate the reason the target halted. The reply is the same as - for step and continue. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`a' -- reserved - Reserved for future use. - -`A'ARGLEN`,'ARGNUM`,'ARG`,...' -- set program arguments *(reserved)* - Initialized `argv[]' array passed into program. ARGLEN specifies - the number of bytes in the hex encoded byte stream ARG. See - `gdbserver' for more details. - - Reply: - `OK' - - `ENN' - -`b'BAUD -- set baud *(deprecated)* - Change the serial line speed to BAUD. - - JTC: _When does the transport layer state change? When it's - received, or after the ACK is transmitted. In either case, there - are problems if the command or the acknowledgment packet is - dropped._ - - Stan: _If people really wanted to add something like this, and get - it working for the first time, they ought to modify ser-unix.c to - send some kind of out-of-band message to a specially-setup stub - and have the switch happen "in between" packets, so that from - remote protocol's point of view, nothing actually happened._ - -`B'ADDR,MODE -- set breakpoint *(deprecated)* - Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR. - - This packet has been replaced by the `Z' and `z' packets (*note - insert breakpoint or watchpoint packet::). - -`c'ADDR -- continue - ADDR is address to resume. If ADDR is omitted, resume at current - address. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`C'SIG`;'ADDR -- continue with signal - Continue with signal SIG (hex signal number). If `;'ADDR is - omitted, resume at same address. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`d' -- toggle debug *(deprecated)* - Toggle debug flag. - -`D' -- detach - Detach GDB from the remote system. Sent to the remote target - before GDB disconnects via the `detach' command. - - Reply: - `_no response_' - GDB does not check for any response after sending this packet. - -`e' -- reserved - Reserved for future use. - -`E' -- reserved - Reserved for future use. - -`f' -- reserved - Reserved for future use. - -`F'RC`,'EE`,'CF`;'XX -- Reply to target's F packet. - This packet is send by GDB as reply to a `F' request packet sent - by the target. This is part of the File-I/O protocol extension. - *Note File-I/O remote protocol extension::, for the specification. - -`g' -- read registers - Read general registers. - - Reply: - `XX...' - Each byte of register data is described by two hex digits. - The bytes with the register are transmitted in target byte - order. The size of each register and their position within - the `g' PACKET are determined by the GDB internal macros - DEPRECATED_REGISTER_RAW_SIZE and REGISTER_NAME macros. The - specification of several standard `g' packets is specified - below. - - `ENN' - for an error. - -`G'XX... -- write regs - *Note read registers packet::, for a description of the XX... - data. - - Reply: - `OK' - for success - - `ENN' - for an error - -`h' -- reserved - Reserved for future use. - -`H'CT... -- set thread - Set thread for subsequent operations (`m', `M', `g', `G', et.al.). - C depends on the operation to be performed: it should be `c' for - step and continue operations, `g' for other operations. The - thread designator T... may be -1, meaning all the threads, a - thread number, or zero which means pick any thread. - - Reply: - `OK' - for success - - `ENN' - for an error - -`i'ADDR`,'NNN -- cycle step *(draft)* - Step the remote target by a single clock cycle. If `,'NNN is - present, cycle step NNN cycles. If ADDR is present, cycle step - starting at that address. - -`I' -- signal then cycle step *(reserved)* - *Note step with signal packet::. *Note cycle step packet::. - -`j' -- reserved - Reserved for future use. - -`J' -- reserved - Reserved for future use. - -`k' -- kill request - FIXME: _There is no description of how to operate when a specific - thread context has been selected (i.e. does 'k' kill only that - thread?)_. - -`K' -- reserved - Reserved for future use. - -`l' -- reserved - Reserved for future use. - -`L' -- reserved - Reserved for future use. - -`m'ADDR`,'LENGTH -- read memory - Read LENGTH bytes of memory starting at address ADDR. Neither GDB - nor the stub assume that sized memory transfers are assumed using - word aligned accesses. FIXME: _A word aligned memory transfer - mechanism is needed._ - - Reply: - `XX...' - XX... is mem contents. Can be fewer bytes than requested if - able to read only part of the data. Neither GDB nor the stub - assume that sized memory transfers are assumed using word - aligned accesses. FIXME: _A word aligned memory transfer - mechanism is needed._ - - `ENN' - NN is errno - -`M'ADDR,LENGTH`:'XX... -- write mem - Write LENGTH bytes of memory starting at address ADDR. XX... is - the data. - - Reply: - `OK' - for success - - `ENN' - for an error (this includes the case where only part of the - data was written). - -`n' -- reserved - Reserved for future use. - -`N' -- reserved - Reserved for future use. - -`o' -- reserved - Reserved for future use. - -`O' -- reserved - Reserved for future use. - -`p'N... -- read reg *(reserved)* - *Note write register packet::. - - Reply: - `R....' - The hex encoded value of the register in target byte order. - -`P'N...`='R... -- write register - Write register N... with value R..., which contains two hex digits - for each byte in the register (target byte order). - - Reply: - `OK' - for success - - `ENN' - for an error - -`q'QUERY -- general query - Request info about QUERY. In general GDB queries have a leading - upper case letter. Custom vendor queries should use a company - prefix (in lower case) ex: `qfsf.var'. QUERY may optionally be - followed by a `,' or `;' separated list. Stubs must ensure that - they match the full QUERY name. - - Reply: - `XX...' - Hex encoded data from query. The reply can not be empty. - - `ENN' - error reply - - `' - Indicating an unrecognized QUERY. - -`Q'VAR`='VAL -- general set - Set value of VAR to VAL. - - *Note general query packet::, for a discussion of naming - conventions. - -`r' -- reset *(deprecated)* - Reset the entire system. - -`R'XX -- remote restart - Restart the program being debugged. XX, while needed, is ignored. - This packet is only available in extended mode. - - Reply: - `_no reply_' - The `R' packet has no reply. - -`s'ADDR -- step - ADDR is address to resume. If ADDR is omitted, resume at same - address. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`S'SIG`;'ADDR -- step with signal - Like `C' but step not continue. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`t'ADDR`:'PP`,'MM -- search - Search backwards starting at address ADDR for a match with pattern - PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 - digits. - -`T'XX -- thread alive - Find out if the thread XX is alive. - - Reply: - `OK' - thread is still alive - - `ENN' - thread is dead - -`u' -- reserved - Reserved for future use. - -`U' -- reserved - Reserved for future use. - -`v' -- verbose packet prefix - Packets starting with `v' are identified by a multi-letter name, - up to the first `;' or `?' (or the end of the packet). - -`vCont'[;ACTION[`:'TID]]... -- extended resume - Resume the inferior. Different actions may be specified for each - thread. If an action is specified with no TID, then it is applied - to any threads that don't have a specific action specified; if no - default action is specified then other threads should remain - stopped. Specifying multiple default actions is an error; - specifying no actions is also an error. Thread IDs are specified - in hexadecimal. Currently supported actions are: - - `c' - Continue. - - `CSIG' - Continue with signal SIG. SIG should be two hex digits. - - `s' - Step. - - `SSIG' - Step with signal SIG. SIG should be two hex digits. - - The optional ADDR argument normally associated with these packets - is not supported in `vCont'. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`vCont?' -- extended resume query - Query support for the `vCont' packet. - - Reply: - ``vCont'[;ACTION]...' - The `vCont' packet is supported. Each ACTION is a supported - command in the `vCont' packet. - - `' - The `vCont' packet is not supported. - -`V' -- reserved - Reserved for future use. - -`w' -- reserved - Reserved for future use. - -`W' -- reserved - Reserved for future use. - -`x' -- reserved - Reserved for future use. - -`X'ADDR`,'LENGTH:XX... -- write mem (binary) - ADDR is address, LENGTH is number of bytes, XX... is binary data. - The characters `$', `#', and `0x7d' are escaped using `0x7d'. - - Reply: - `OK' - for success - - `ENN' - for an error - -`y' -- reserved - Reserved for future use. - -`Y' reserved - Reserved for future use. - -`z'TYPE`,'ADDR`,'LENGTH -- remove breakpoint or watchpoint *(draft)* -`Z'TYPE`,'ADDR`,'LENGTH -- insert breakpoint or watchpoint *(draft)* - Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint - starting at address ADDRESS and covering the next LENGTH bytes. - - Each breakpoint and watchpoint packet TYPE is documented - separately. - - _Implementation notes: A remote target shall return an empty string - for an unrecognized breakpoint or watchpoint packet TYPE. A - remote target shall support either both or neither of a given - `Z'TYPE... and `z'TYPE... packet pair. To avoid potential - problems with duplicate packets, the operations should be - implemented in an idempotent way._ - -`z'`0'`,'ADDR`,'LENGTH -- remove memory breakpoint *(draft)* - -`Z'`0'`,'ADDR`,'LENGTH -- insert memory breakpoint *(draft)* - Insert (`Z0') or remove (`z0') a memory breakpoint at address - `addr' of size `length'. - - A memory breakpoint is implemented by replacing the instruction at - ADDR with a software breakpoint or trap instruction. The `length' - is used by targets that indicates the size of the breakpoint (in - bytes) that should be inserted (e.g., the ARM and MIPS can insert - either a 2 or 4 byte breakpoint). - - _Implementation note: It is possible for a target to copy or move - code that contains memory breakpoints (e.g., when implementing - overlays). The behavior of this packet, in the presence of such a - target, is not defined._ - - Reply: - `OK' - success - - `' - not supported - - `ENN' - for an error - -`z'`1'`,'ADDR`,'LENGTH -- remove hardware breakpoint *(draft)* - -`Z'`1'`,'ADDR`,'LENGTH -- insert hardware breakpoint *(draft)* - Insert (`Z1') or remove (`z1') a hardware breakpoint at address - `addr' of size `length'. - - A hardware breakpoint is implemented using a mechanism that is not - dependant on being able to modify the target's memory. - - _Implementation note: A hardware breakpoint is not affected by code - movement._ - - Reply: - `OK' - success - - `' - not supported - - `ENN' - for an error - -`z'`2'`,'ADDR`,'LENGTH -- remove write watchpoint *(draft)* - -`Z'`2'`,'ADDR`,'LENGTH -- insert write watchpoint *(draft)* - Insert (`Z2') or remove (`z2') a write watchpoint. - - Reply: - `OK' - success - - `' - not supported - - `ENN' - for an error - -`z'`3'`,'ADDR`,'LENGTH -- remove read watchpoint *(draft)* - -`Z'`3'`,'ADDR`,'LENGTH -- insert read watchpoint *(draft)* - Insert (`Z3') or remove (`z3') a read watchpoint. - - Reply: - `OK' - success - - `' - not supported - - `ENN' - for an error - -`z'`4'`,'ADDR`,'LENGTH -- remove access watchpoint *(draft)* - -`Z'`4'`,'ADDR`,'LENGTH -- insert access watchpoint *(draft)* - Insert (`Z4') or remove (`z4') an access watchpoint. - - Reply: - `OK' - success - - `' - not supported - - `ENN' - for an error - - - -File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol - -Stop Reply Packets -================== - -The `C', `c', `S', `s' and `?' packets can receive any of the below as -a reply. In the case of the `C', `c', `S' and `s' packets, that reply -is only returned when the target halts. In the below the exact meaning -of `signal number' is poorly defined. In general one of the UNIX -signal numbering conventions is used. - -`SAA' - AA is the signal number - -``T'AAN...`:'R...`;'N...`:'R...`;'N...`:'R...`;'' - AA = two hex digit signal number; N... = register number (hex), - R... = target byte ordered register contents, size defined by - `DEPRECATED_REGISTER_RAW_SIZE'; N... = `thread', R... = thread - process ID, this is a hex integer; N... = (`watch' | `rwatch' | - `awatch', R... = data address, this is a hex integer; N... = other - string not starting with valid hex digit. GDB should ignore this - N..., R... pair and go on to the next. This way we can extend the - protocol. - -`WAA' - The process exited, and AA is the exit status. This is only - applicable to certain targets. - -`XAA' - The process terminated with signal AA. - -`OXX...' - XX... is hex encoding of ASCII data. This can happen at any time - while the program is running and the debugger should continue to - wait for `W', `T', etc. - -`FCALL-ID`,'PARAMETER...' - CALL-ID is the identifier which says which host system call should - be called. This is just the name of the function. Translation - into the correct system call is only applicable as it's defined in - GDB. *Note File-I/O remote protocol extension::, for a list of - implemented system calls. - - PARAMETER... is a list of parameters as defined for this very - system call. - - The target replies with this packet when it expects GDB to call a - host system call on behalf of the target. GDB replies with an - appropriate `F' packet and keeps up waiting for the next reply - packet from the target. The latest `C', `c', `S' or `s' action is - expected to be continued. *Note File-I/O remote protocol - extension::, for more details. - - - -File: gdb.info, Node: General Query Packets, Next: Register Packet Format, Prev: Stop Reply Packets, Up: Remote Protocol - -General Query Packets -===================== - -The following set and query packets have already been defined. - -`q'`C' -- current thread - Return the current thread id. - - Reply: - ``QC'PID' - Where PID is a HEX encoded 16 bit process id. - - `*' - Any other reply implies the old pid. - -`q'`fThreadInfo' - all thread ids - `q'`sThreadInfo' - - Obtain a list of active thread ids from the target (OS). Since - there may be too many active threads to fit into one reply packet, - this query works iteratively: it may require more than one - query/reply sequence to obtain the entire list of threads. The - first query of the sequence will be the `qf'`ThreadInfo' query; - subsequent queries in the sequence will be the `qs'`ThreadInfo' - query. - - NOTE: replaces the `qL' query (see below). - - Reply: - ``m'ID' - A single thread id - - ``m'ID,ID...' - a comma-separated list of thread ids - - ``l'' - (lower case 'el') denotes end of list. - - In response to each query, the target will reply with a list of - one or more thread ids, in big-endian hex, separated by commas. - GDB will respond to each reply with a request for more thread ids - (using the `qs' form of the query), until the target responds with - `l' (lower-case el, for `'last''). - -`q'`ThreadExtraInfo'`,'ID -- extra thread info - Where ID is a thread-id in big-endian hex. Obtain a printable - string description of a thread's attributes from the target OS. - This string may contain anything that the target OS thinks is - interesting for GDB to tell the user about the thread. The string - is displayed in GDB's `info threads' display. Some examples of - possible thread extra info strings are "Runnable", or "Blocked on - Mutex". - - Reply: - `XX...' - Where XX... is a hex encoding of ASCII data, comprising the - printable string containing the extra information about the - thread's attributes. - -`q'`L'STARTFLAGTHREADCOUNTNEXTTHREAD -- query LIST or THREADLIST *(deprecated)* - Obtain thread information from RTOS. Where: STARTFLAG (one hex - digit) is one to indicate the first query and zero to indicate a - subsequent query; THREADCOUNT (two hex digits) is the maximum - number of threads the response packet can contain; and NEXTTHREAD - (eight hex digits), for subsequent queries (STARTFLAG is zero), is - returned in the response as ARGTHREAD. - - NOTE: this query is replaced by the `q'`fThreadInfo' query (see - above). - - Reply: - ``q'`M'COUNTDONEARGTHREADTHREAD...' - Where: COUNT (two hex digits) is the number of threads being - returned; DONE (one hex digit) is zero to indicate more - threads and one indicates no further threads; ARGTHREADID - (eight hex digits) is NEXTTHREAD from the request packet; - THREAD... is a sequence of thread IDs from the target. - THREADID (eight hex digits). See - `remote.c:parse_threadlist_response()'. - -`q'`CRC:'ADDR`,'LENGTH -- compute CRC of memory block - Reply: - ``E'NN' - An error (such as memory fault) - - ``C'CRC32' - A 32 bit cyclic redundancy check of the specified memory - region. - -`q'`Offsets' -- query sect offs - Get section offsets that the target used when re-locating the - downloaded image. _Note: while a `Bss' offset is included in the - response, GDB ignores this and instead applies the `Data' offset - to the `Bss' section._ - - Reply: - ``Text='XXX`;Data='YYY`;Bss='ZZZ' - -`q'`P'MODETHREADID -- thread info request - Returns information on THREADID. Where: MODE is a hex encoded 32 - bit mode; THREADID is a hex encoded 64 bit thread ID. - - Reply: - `*' - - See `remote.c:remote_unpack_thread_info_response()'. - -`q'`Rcmd,'COMMAND -- remote command - COMMAND (hex encoded) is passed to the local interpreter for - execution. Invalid commands should be reported using the output - string. Before the final result packet, the target may also - respond with a number of intermediate `O'OUTPUT console output - packets. _Implementors should note that providing access to a - stubs's interpreter may have security implications_. - - Reply: - `OK' - A command response with no output. - - `OUTPUT' - A command response with the hex encoded output string OUTPUT. - - ``E'NN' - Indicate a badly formed request. - - ``'' - When `q'`Rcmd' is not recognized. - -`qSymbol::' -- symbol lookup - Notify the target that GDB is prepared to serve symbol lookup - requests. Accept requests from the target for the values of - symbols. - - Reply: - ``OK'' - The target does not need to look up any (more) symbols. - - ``qSymbol:'SYM_NAME' - The target requests the value of symbol SYM_NAME (hex - encoded). GDB may provide the value by using the - `qSymbol:'SYM_VALUE:SYM_NAME message, described below. - -`qSymbol:'SYM_VALUE:SYM_NAME -- symbol value - Set the value of SYM_NAME to SYM_VALUE. - - SYM_NAME (hex encoded) is the name of a symbol whose value the - target has previously requested. - - SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot - supply a value for SYM_NAME, then this field will be empty. - - Reply: - ``OK'' - The target does not need to look up any (more) symbols. - - ``qSymbol:'SYM_NAME' - The target requests the value of a new symbol SYM_NAME (hex - encoded). GDB will continue to supply the values of symbols - (if available), until the target ceases to request them. - -`qPart':OBJECT:`read':ANNEX:OFFSET,LENGTH -- read special data - Read uninterpreted bytes from the target's special data area - identified by the keyword `object'. Request LENGTH bytes starting - at OFFSET bytes into the data. The content and encoding of ANNEX - is specific to the object; it can supply additional details about - what data to access. - - Here are the specific requests of this form defined so far. All - ``qPart':OBJECT:`read':...' requests use the same reply formats, - listed below. - - `qPart':`auxv':`read'::OFFSET,LENGTH - Access the target's "auxiliary vector". *Note Auxiliary - Vector::. Note ANNEX must be empty. - - Reply: - `OK' - The OFFSET in the request is at the end of the data. There - is no more data to be read. - - XX... - Hex encoded data bytes read. This may be fewer bytes than - the LENGTH in the request. - - `E00' - The request was malformed, or ANNEX was invalid. - - `E'NN - The offset was invalid, or there was an error encountered - reading the data. NN is a hex-encoded `errno' value. - - `""' (empty) - An empty reply indicates the OBJECT or ANNEX string was not - recognized by the stub. - -`qPart':OBJECT:`write':ANNEX:OFFSET:DATA... - Write uninterpreted bytes into the target's special data area - identified by the keyword `object', starting at OFFSET bytes into - the data. DATA... is the hex-encoded data to be written. The - content and encoding of ANNEX is specific to the object; it can - supply additional details about what data to access. - - No requests of this form are presently in use. This specification - serves as a placeholder to document the common format that new - specific request specifications ought to use. - - Reply: - NN - NN (hex encoded) is the number of bytes written. This may be - fewer bytes than supplied in the request. - - `E00' - The request was malformed, or ANNEX was invalid. - - `E'NN - The offset was invalid, or there was an error encountered - writing the data. NN is a hex-encoded `errno' value. - - `""' (empty) - An empty reply indicates the OBJECT or ANNEX string was not - recognized by the stub, or that the object does not support - writing. - -`qPart':OBJECT:OPERATION:... - Requests of this form may be added in the future. When a stub does - not recognize the OBJECT keyword, or its support for OBJECT does - not recognize the OPERATION keyword, the stub must respond with an - empty packet. - - -File: gdb.info, Node: Register Packet Format, Next: Examples, Prev: General Query Packets, Up: Remote Protocol - -Register Packet Format -====================== - -The following `g'/`G' packets have previously been defined. In the -below, some thirty-two bit registers are transferred as sixty-four -bits. Those registers should be zero/sign extended (which?) to fill -the space allocated. Register bytes are transfered in target byte -order. The two nibbles within a register byte are transfered -most-significant - least-significant. - -MIPS32 - All registers are transfered as thirty-two bit quantities in the - order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 - floating-point registers; fsr; fir; fp. - -MIPS64 - All registers are transfered as sixty-four bit quantities - (including thirty-two bit registers such as `sr'). The ordering - is the same as `MIPS32'. - - - -File: gdb.info, Node: Examples, Next: File-I/O remote protocol extension, Prev: Register Packet Format, Up: Remote Protocol - -Examples -======== - -Example sequence of a target being re-started. Notice how the restart -does not get any direct output: - - -> `R00' - <- `+' - _target restarts_ - -> `?' - <- `+' - <- `T001:1234123412341234' - -> `+' - - Example sequence of a target being stepped by a single instruction: - - -> `G1445...' - <- `+' - -> `s' - <- `+' - _time passes_ - <- `T001:1234123412341234' - -> `+' - -> `g' - <- `+' - <- `1455...' - -> `+' - - -File: gdb.info, Node: File-I/O remote protocol extension, Prev: Examples, Up: Remote Protocol - -File-I/O remote protocol extension -================================== - -* Menu: - -* File-I/O Overview:: -* Protocol basics:: -* The F request packet:: -* The F reply packet:: -* Memory transfer:: -* The Ctrl-C message:: -* Console I/O:: -* The isatty call:: -* The system call:: -* List of supported calls:: -* Protocol specific representation of datatypes:: -* Constants:: -* File-I/O Examples:: - - -File: gdb.info, Node: File-I/O Overview, Next: Protocol basics, Up: File-I/O remote protocol extension - -File-I/O Overview ------------------ - -The File I/O remote protocol extension (short: File-I/O) allows the -target to use the hosts file system and console I/O when calling various -system calls. System calls on the target system are translated into a -remote protocol packet to the host system which then performs the needed -actions and returns with an adequate response packet to the target -system. This simulates file system operations even on targets that -lack file systems. - - The protocol is defined host- and target-system independent. It uses -it's own independent representation of datatypes and values. Both, GDB -and the target's GDB stub are responsible for translating the system -dependent values into the unified protocol values when data is -transmitted. - - The communication is synchronous. A system call is possible only -when GDB is waiting for the `C', `c', `S' or `s' packets. While GDB -handles the request for a system call, the target is stopped to allow -deterministic access to the target's memory. Therefore File-I/O is not -interuptible by target signals. It is possible to interrupt File-I/O -by a user interrupt (Ctrl-C), though. - - The target's request to perform a host system call does not finish -the latest `C', `c', `S' or `s' action. That means, after finishing -the system call, the target returns to continuing the previous activity -(continue, step). No additional continue or step request from GDB is -required. - - (gdb) continue - <- target requests 'system call X' - target is stopped, GDB executes system call - -> GDB returns result - ... target continues, GDB returns to wait for the target - <- target hits breakpoint and sends a Txx packet - - The protocol is only used for files on the host file system and for -I/O on the console. Character or block special devices, pipes, named -pipes or sockets or any other communication method on the host system -are not supported by this protocol. - - -File: gdb.info, Node: Protocol basics, Next: The F request packet, Prev: File-I/O Overview, Up: File-I/O remote protocol extension - -Protocol basics ---------------- - -The File-I/O protocol uses the `F' packet, as request as well as as -reply packet. Since a File-I/O system call can only occur when GDB is -waiting for the continuing or stepping target, the File-I/O request is -a reply that GDB has to expect as a result of a former `C', `c', `S' or -`s' packet. This `F' packet contains all information needed to allow -GDB to call the appropriate host system call: - - * A unique identifier for the requested system call. - - * All parameters to the system call. Pointers are given as addresses - in the target memory address space. Pointers to strings are given - as pointer/length pair. Numerical values are given as they are. - Numerical control values are given in a protocol specific - representation. - - - At that point GDB has to perform the following actions. - - * If parameter pointer values are given, which point to data needed - as input to a system call, GDB requests this data from the target - with a standard `m' packet request. This additional communication - has to be expected by the target implementation and is handled as - any other `m' packet. - - * GDB translates all value from protocol representation to host - representation as needed. Datatypes are coerced into the host - types. - - * GDB calls the system call - - * It then coerces datatypes back to protocol representation. - - * If pointer parameters in the request packet point to buffer space - in which a system call is expected to copy data to, the data is - transmitted to the target using a `M' or `X' packet. This packet - has to be expected by the target implementation and is handled as - any other `M' or `X' packet. - - - Eventually GDB replies with another `F' packet which contains all -necessary information for the target to continue. This at least -contains - - * Return value. - - * `errno', if has been changed by the system call. - - * "Ctrl-C" flag. - - - After having done the needed type and value coercion, the target -continues the latest continue or step action. - - -File: gdb.info, Node: The F request packet, Next: The F reply packet, Prev: Protocol basics, Up: File-I/O remote protocol extension - -The `F' request packet ----------------------- - -The `F' request packet has the following format: - - `F'CALL-ID`,'PARAMETER... - - CALL-ID is the identifier to indicate the host system call to be - called. This is just the name of the function. - - PARAMETER... are the parameters to the system call. - - - Parameters are hexadecimal integer values, either the real values in -case of scalar datatypes, as pointers to target buffer space in case of -compound datatypes and unspecified memory areas or as pointer/length -pairs in case of string parameters. These are appended to the call-id, -each separated from its predecessor by a comma. All values are -transmitted in ASCII string representation, pointer/length pairs -separated by a slash. - - -File: gdb.info, Node: The F reply packet, Next: Memory transfer, Prev: The F request packet, Up: File-I/O remote protocol extension - -The `F' reply packet --------------------- - -The `F' reply packet has the following format: - - `F'RETCODE`,'ERRNO`,'CTRL-C FLAG`;'CALL SPECIFIC ATTACHMENT - - RETCODE is the return code of the system call as hexadecimal value. - - ERRNO is the errno set by the call, in protocol specific - representation. This parameter can be omitted if the call was - successful. - - CTRL-C FLAG is only send if the user requested a break. In this - case, ERRNO must be send as well, even if the call was successful. - The CTRL-C FLAG itself consists of the character 'C': - - F0,0,C - - or, if the call was interupted before the host call has been - performed: - - F-1,4,C - - assuming 4 is the protocol specific representation of `EINTR'. - - - -File: gdb.info, Node: Memory transfer, Next: The Ctrl-C message, Prev: The F reply packet, Up: File-I/O remote protocol extension - -Memory transfer ---------------- - -Structured data which is transferred using a memory read or write as -e.g. a `struct stat' is expected to be in a protocol specific format -with all scalar multibyte datatypes being big endian. This should be -done by the target before the `F' packet is sent resp. by GDB before it -transfers memory to the target. Transferred pointers to structured -data should point to the already coerced data at any time. - - -File: gdb.info, Node: The Ctrl-C message, Next: Console I/O, Prev: Memory transfer, Up: File-I/O remote protocol extension - -The Ctrl-C message ------------------- - -A special case is, if the CTRL-C FLAG is set in the GDB reply packet. -In this case the target should behave, as if it had gotten a break -message. The meaning for the target is "system call interupted by -`SIGINT'". Consequentially, the target should actually stop (as with a -break message) and return to GDB with a `T02' packet. In this case, -it's important for the target to know, in which state the system call -was interrupted. Since this action is by design not an atomic -operation, we have to differ between two cases: - - * The system call hasn't been performed on the host yet. - - * The system call on the host has been finished. - - - These two states can be distinguished by the target by the value of -the returned `errno'. If it's the protocol representation of `EINTR', -the system call hasn't been performed. This is equivalent to the -`EINTR' handling on POSIX systems. In any other case, the target may -presume that the system call has been finished -- successful or not -- -and should behave as if the break message arrived right after the -system call. - - GDB must behave reliable. If the system call has not been called -yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno' -in the packet. If the system call on the host has been finished before -the user requests a break, the full action must be finshed by GDB. -This requires sending `M' or `X' packets as they fit. The `F' packet -may only be send when either nothing has happened or the full action -has been completed. - - -File: gdb.info, Node: Console I/O, Next: The isatty call, Prev: The Ctrl-C message, Up: File-I/O remote protocol extension - -Console I/O ------------ - -By default and if not explicitely closed by the target system, the file -descriptors 0, 1 and 2 are connected to the GDB console. Output on the -GDB console is handled as any other file output operation (`write(1, -...)' or `write(2, ...)'). Console input is handled by GDB so that -after the target read request from file descriptor 0 all following -typing is buffered until either one of the following conditions is met: - - * The user presses `Ctrl-C'. The behaviour is as explained above, - the `read' system call is treated as finished. - - * The user presses `Enter'. This is treated as end of input with a - trailing line feed. - - * The user presses `Ctrl-D'. This is treated as end of input. No - trailing character, especially no Ctrl-D is appended to the input. - - - If the user has typed more characters as fit in the buffer given to -the read call, the trailing characters are buffered in GDB until either -another `read(0, ...)' is requested by the target or debugging is -stopped on users request. - - -File: gdb.info, Node: The isatty call, Next: The system call, Prev: Console I/O, Up: File-I/O remote protocol extension - -The isatty(3) call ------------------- - -A special case in this protocol is the library call `isatty' which is -implemented as it's own call inside of this protocol. It returns 1 to -the target if the file descriptor given as parameter is attached to the -GDB console, 0 otherwise. Implementing through system calls would -require implementing `ioctl' and would be more complex than needed. - - -File: gdb.info, Node: The system call, Next: List of supported calls, Prev: The isatty call, Up: File-I/O remote protocol extension - -The system(3) call ------------------- - -The other special case in this protocol is the `system' call which is -implemented as it's own call, too. GDB is taking over the full task of -calling the necessary host calls to perform the `system' call. The -return value of `system' is simplified before it's returned to the -target. Basically, the only signal transmitted back is `EINTR' in case -the user pressed `Ctrl-C'. Otherwise the return value consists -entirely of the exit status of the called command. - - Due to security concerns, the `system' call is refused to be called -by GDB by default. The user has to allow this call explicitly by -entering - -``set remote system-call-allowed 1'' - - Disabling the `system' call is done by - -``set remote system-call-allowed 0'' - - The current setting is shown by typing - -``show remote system-call-allowed'' - - -File: gdb.info, Node: List of supported calls, Next: Protocol specific representation of datatypes, Prev: The system call, Up: File-I/O remote protocol extension - -List of supported calls ------------------------ - -* Menu: - -* open:: -* close:: -* read:: -* write:: -* lseek:: -* rename:: -* unlink:: -* stat/fstat:: -* gettimeofday:: -* isatty:: -* system:: - - -File: gdb.info, Node: open, Next: close, Up: List of supported calls - -open -.... - -Synopsis: - int open(const char *pathname, int flags); - int open(const char *pathname, int flags, mode_t mode); - -Request: - Fopen,pathptr/len,flags,mode - -`flags' is the bitwise or of the following values: - -`O_CREAT' - If the file does not exist it will be created. The host rules - apply as far as file ownership and time stamps are concerned. - -`O_EXCL' - When used with O_CREAT, if the file already exists it is an error - and open() fails. - -`O_TRUNC' - If the file already exists and the open mode allows writing - (O_RDWR or O_WRONLY is given) it will be truncated to length 0. - -`O_APPEND' - The file is opened in append mode. - -`O_RDONLY' - The file is opened for reading only. - -`O_WRONLY' - The file is opened for writing only. - -`O_RDWR' - The file is opened for reading and writing. - - Each other bit is silently ignored. - - -`mode' is the bitwise or of the following values: - -`S_IRUSR' - User has read permission. - -`S_IWUSR' - User has write permission. - -`S_IRGRP' - Group has read permission. - -`S_IWGRP' - Group has write permission. - -`S_IROTH' - Others have read permission. - -`S_IWOTH' - Others have write permission. - - Each other bit is silently ignored. - - -Return value: - open returns the new file descriptor or -1 if an error - occured. - -Errors: - - -`EEXIST' - pathname already exists and O_CREAT and O_EXCL were used. - -`EISDIR' - pathname refers to a directory. - -`EACCES' - The requested access is not allowed. - -`ENAMETOOLONG' - pathname was too long. - -`ENOENT' - A directory component in pathname does not exist. - -`ENODEV' - pathname refers to a device, pipe, named pipe or socket. - -`EROFS' - pathname refers to a file on a read-only filesystem and write - access was requested. - -`EFAULT' - pathname is an invalid pointer value. - -`ENOSPC' - No space on device to create the file. - -`EMFILE' - The process already has the maximum number of files open. - -`ENFILE' - The limit on the total number of files open on the system has been - reached. - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: close, Next: read, Prev: open, Up: List of supported calls - -close -..... - -Synopsis: - int close(int fd); - -Request: - Fclose,fd - -Return value: - close returns zero on success, or -1 if an error occurred. - -Errors: - - -`EBADF' - fd isn't a valid open file descriptor. - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: read, Next: write, Prev: close, Up: List of supported calls - -read -.... - -Synopsis: - int read(int fd, void *buf, unsigned int count); - -Request: - Fread,fd,bufptr,count - -Return value: - On success, the number of bytes read is returned. - Zero indicates end of file. If count is zero, read - returns zero as well. On error, -1 is returned. - -Errors: - - -`EBADF' - fd is not a valid file descriptor or is not open for reading. - -`EFAULT' - buf is an invalid pointer value. - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of supported calls - -write -..... - -Synopsis: - int write(int fd, const void *buf, unsigned int count); - -Request: - Fwrite,fd,bufptr,count - -Return value: - On success, the number of bytes written are returned. - Zero indicates nothing was written. On error, -1 - is returned. - -Errors: - - -`EBADF' - fd is not a valid file descriptor or is not open for writing. - -`EFAULT' - buf is an invalid pointer value. - -`EFBIG' - An attempt was made to write a file that exceeds the host specific - maximum file size allowed. - -`ENOSPC' - No space on device to write the data. - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of supported calls - -lseek -..... - -Synopsis: - long lseek (int fd, long offset, int flag); - -Request: - Flseek,fd,offset,flag - - `flag' is one of: - -`SEEK_SET' - The offset is set to offset bytes. - -`SEEK_CUR' - The offset is set to its current location plus offset bytes. - -`SEEK_END' - The offset is set to the size of the file plus offset bytes. - -Return value: - On success, the resulting unsigned offset in bytes from - the beginning of the file is returned. Otherwise, a - value of -1 is returned. - -Errors: - - -`EBADF' - fd is not a valid open file descriptor. - -`ESPIPE' - fd is associated with the GDB console. - -`EINVAL' - flag is not a proper value. - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of supported calls - -rename -...... - -Synopsis: - int rename(const char *oldpath, const char *newpath); - -Request: - Frename,oldpathptr/len,newpathptr/len - -Return value: - On success, zero is returned. On error, -1 is returned. - -Errors: - - -`EISDIR' - newpath is an existing directory, but oldpath is not a directory. - -`EEXIST' - newpath is a non-empty directory. - -`EBUSY' - oldpath or newpath is a directory that is in use by some process. - -`EINVAL' - An attempt was made to make a directory a subdirectory of itself. - -`ENOTDIR' - A component used as a directory in oldpath or new path is not a - directory. Or oldpath is a directory and newpath exists but is - not a directory. - -`EFAULT' - oldpathptr or newpathptr are invalid pointer values. - -`EACCES' - No access to the file or the path of the file. - -`ENAMETOOLONG' - oldpath or newpath was too long. - -`ENOENT' - A directory component in oldpath or newpath does not exist. - -`EROFS' - The file is on a read-only filesystem. - -`ENOSPC' - The device containing the file has no room for the new directory - entry. - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of supported calls - -unlink -...... - -Synopsis: - int unlink(const char *pathname); - -Request: - Funlink,pathnameptr/len - -Return value: - On success, zero is returned. On error, -1 is returned. - -Errors: - - -`EACCES' - No access to the file or the path of the file. - -`EPERM' - The system does not allow unlinking of directories. - -`EBUSY' - The file pathname cannot be unlinked because it's being used by - another process. - -`EFAULT' - pathnameptr is an invalid pointer value. - -`ENAMETOOLONG' - pathname was too long. - -`ENOENT' - A directory component in pathname does not exist. - -`ENOTDIR' - A component of the path is not a directory. - -`EROFS' - The file is on a read-only filesystem. - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of supported calls - -stat/fstat -.......... - -Synopsis: - int stat(const char *pathname, struct stat *buf); - int fstat(int fd, struct stat *buf); - -Request: - Fstat,pathnameptr/len,bufptr - Ffstat,fd,bufptr - -Return value: - On success, zero is returned. On error, -1 is returned. - -Errors: - - -`EBADF' - fd is not a valid open file. - -`ENOENT' - A directory component in pathname does not exist or the path is an - empty string. - -`ENOTDIR' - A component of the path is not a directory. - -`EFAULT' - pathnameptr is an invalid pointer value. - -`EACCES' - No access to the file or the path of the file. - -`ENAMETOOLONG' - pathname was too long. - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of supported calls - -gettimeofday -............ - -Synopsis: - int gettimeofday(struct timeval *tv, void *tz); - -Request: - Fgettimeofday,tvptr,tzptr - -Return value: - On success, 0 is returned, -1 otherwise. - -Errors: - - -`EINVAL' - tz is a non-NULL pointer. - -`EFAULT' - tvptr and/or tzptr is an invalid pointer value. - - -File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of supported calls - -isatty -...... - -Synopsis: - int isatty(int fd); - -Request: - Fisatty,fd - -Return value: - Returns 1 if fd refers to the GDB console, 0 otherwise. - -Errors: - - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: system, Prev: isatty, Up: List of supported calls - -system -...... - -Synopsis: - int system(const char *command); - -Request: - Fsystem,commandptr/len - -Return value: - The value returned is -1 on error and the return status - of the command otherwise. Only the exit status of the - command is returned, which is extracted from the hosts - system return value by calling WEXITSTATUS(retval). - In case /bin/sh could not be executed, 127 is returned. - -Errors: - - -`EINTR' - The call was interrupted by the user. - - -File: gdb.info, Node: Protocol specific representation of datatypes, Next: Constants, Prev: List of supported calls, Up: File-I/O remote protocol extension - -Protocol specific representation of datatypes ---------------------------------------------- - -* Menu: - -* Integral datatypes:: -* Pointer values:: -* struct stat:: -* struct timeval:: - - -File: gdb.info, Node: Integral datatypes, Next: Pointer values, Up: Protocol specific representation of datatypes - -Integral datatypes -.................. - -The integral datatypes used in the system calls are - - int, unsigned int, long, unsigned long, mode_t and time_t - - `Int', `unsigned int', `mode_t' and `time_t' are implemented as 32 -bit values in this protocol. - - `Long' and `unsigned long' are implemented as 64 bit types. - - *Note Limits::, for corresponding MIN and MAX values (similar to -those in `limits.h') to allow range checking on host and target. - - `time_t' datatypes are defined as seconds since the Epoch. - - All integral datatypes transferred as part of a memory read or write -of a structured datatype e.g. a `struct stat' have to be given in big -endian byte order. - - -File: gdb.info, Node: Pointer values, Next: struct stat, Prev: Integral datatypes, Up: Protocol specific representation of datatypes - -Pointer values -.............. - -Pointers to target data are transmitted as they are. An exception is -made for pointers to buffers for which the length isn't transmitted as -part of the function call, namely strings. Strings are transmitted as -a pointer/length pair, both as hex values, e.g. - - `1aaf/12' - -which is a pointer to data of length 18 bytes at position 0x1aaf. The -length is defined as the full string length in bytes, including the -trailing null byte. Example: - - ``hello, world'' at address 0x123456 - -is transmitted as - - `123456/d' - - -File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Pointer values, Up: Protocol specific representation of datatypes - -struct stat -........... - -The buffer of type struct stat used by the target and GDB is defined as -follows: - - struct stat { - unsigned int st_dev; /* device */ - unsigned int st_ino; /* inode */ - mode_t st_mode; /* protection */ - unsigned int st_nlink; /* number of hard links */ - unsigned int st_uid; /* user ID of owner */ - unsigned int st_gid; /* group ID of owner */ - unsigned int st_rdev; /* device type (if inode device) */ - unsigned long st_size; /* total size, in bytes */ - unsigned long st_blksize; /* blocksize for filesystem I/O */ - unsigned long st_blocks; /* number of blocks allocated */ - time_t st_atime; /* time of last access */ - time_t st_mtime; /* time of last modification */ - time_t st_ctime; /* time of last change */ - }; - - The integral datatypes are conforming to the definitions given in the -approriate section (see *Note Integral datatypes::, for details) so this -structure is of size 64 bytes. - - The values of several fields have a restricted meaning and/or range -of values. - - st_dev: 0 file - 1 console - - st_ino: No valid meaning for the target. Transmitted unchanged. - - st_mode: Valid mode bits are described in Appendix C. Any other - bits have currently no meaning for the target. - - st_uid: No valid meaning for the target. Transmitted unchanged. - - st_gid: No valid meaning for the target. Transmitted unchanged. - - st_rdev: No valid meaning for the target. Transmitted unchanged. - - st_atime, st_mtime, st_ctime: - These values have a host and file system dependent - accuracy. Especially on Windows hosts the file systems - don't support exact timing values. - - The target gets a struct stat of the above representation and is -responsible to coerce it to the target representation before continuing. - - Note that due to size differences between the host and target -representation of stat members, these members could eventually get -truncated on the target. - - -File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol specific representation of datatypes - -struct timeval -.............. - -The buffer of type struct timeval used by the target and GDB is defined -as follows: - - struct timeval { - time_t tv_sec; /* second */ - long tv_usec; /* microsecond */ - }; - - The integral datatypes are conforming to the definitions given in the -approriate section (see *Note Integral datatypes::, for details) so this -structure is of size 8 bytes. - - -File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol specific representation of datatypes, Up: File-I/O remote protocol extension - -Constants ---------- - -The following values are used for the constants inside of the protocol. -GDB and target are resposible to translate these values before and -after the call as needed. - -* Menu: - -* Open flags:: -* mode_t values:: -* Errno values:: -* Lseek flags:: -* Limits:: - - -File: gdb.info, Node: Open flags, Next: mode_t values, Up: Constants - -Open flags -.......... - -All values are given in hexadecimal representation. - - O_RDONLY 0x0 - O_WRONLY 0x1 - O_RDWR 0x2 - O_APPEND 0x8 - O_CREAT 0x200 - O_TRUNC 0x400 - O_EXCL 0x800 - - -File: gdb.info, Node: mode_t values, Next: Errno values, Prev: Open flags, Up: Constants - -mode_t values -............. - -All values are given in octal representation. - - S_IFREG 0100000 - S_IFDIR 040000 - S_IRUSR 0400 - S_IWUSR 0200 - S_IXUSR 0100 - S_IRGRP 040 - S_IWGRP 020 - S_IXGRP 010 - S_IROTH 04 - S_IWOTH 02 - S_IXOTH 01 - - -File: gdb.info, Node: Errno values, Next: Lseek flags, Prev: mode_t values, Up: Constants - -Errno values -............ - -All values are given in decimal representation. - - EPERM 1 - ENOENT 2 - EINTR 4 - EBADF 9 - EACCES 13 - EFAULT 14 - EBUSY 16 - EEXIST 17 - ENODEV 19 - ENOTDIR 20 - EISDIR 21 - EINVAL 22 - ENFILE 23 - EMFILE 24 - EFBIG 27 - ENOSPC 28 - ESPIPE 29 - EROFS 30 - ENAMETOOLONG 91 - EUNKNOWN 9999 - - EUNKNOWN is used as a fallback error value if a host system returns -any error value not in the list of supported error numbers. - - -File: gdb.info, Node: Lseek flags, Next: Limits, Prev: Errno values, Up: Constants - -Lseek flags -........... - - SEEK_SET 0 - SEEK_CUR 1 - SEEK_END 2 - - -File: gdb.info, Node: Limits, Prev: Lseek flags, Up: Constants - -Limits -...... - -All values are given in decimal representation. - - INT_MIN -2147483648 - INT_MAX 2147483647 - UINT_MAX 4294967295 - LONG_MIN -9223372036854775808 - LONG_MAX 9223372036854775807 - ULONG_MAX 18446744073709551615 - - -File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O remote protocol extension - -File-I/O Examples ------------------ - -Example sequence of a write call, file descriptor 3, buffer is at target -address 0x1234, 6 bytes should be written: - - <- `Fwrite,3,1234,6' - _request memory read from target_ - -> `m1234,6' - <- XXXXXX - _return "6 bytes written"_ - -> `F6' - - Example sequence of a read call, file descriptor 3, buffer is at -target address 0x1234, 6 bytes should be read: - - <- `Fread,3,1234,6' - _request memory write to target_ - -> `X1234,6:XXXXXX' - _return "6 bytes read"_ - -> `F6' - - Example sequence of a read call, call fails on the host due to -invalid file descriptor (EBADF): - - <- `Fread,3,1234,6' - -> `F-1,9' - - Example sequence of a read call, user presses Ctrl-C before syscall -on host is called: - - <- `Fread,3,1234,6' - -> `F-1,4,C' - <- `T02' - - Example sequence of a read call, user presses Ctrl-C after syscall on -host is called: - - <- `Fread,3,1234,6' - -> `X1234,6:XXXXXX' - <- `T02' - - -File: gdb.info, Node: Agent Expressions, Next: Copying, Prev: Remote Protocol, Up: Top - -The GDB Agent Expression Mechanism -********************************** - -In some applications, it is not feasable for the debugger to interrupt -the program's execution long enough for the developer to learn anything -helpful about its behavior. If the program's correctness depends on its -real-time behavior, delays introduced by a debugger might cause the -program to fail, even when the code itself is correct. It is useful to -be able to observe the program's behavior without interrupting it. - - Using GDB's `trace' and `collect' commands, the user can specify -locations in the program, and arbitrary expressions to evaluate when -those locations are reached. Later, using the `tfind' command, she can -examine the values those expressions had when the program hit the trace -points. The expressions may also denote objects in memory -- -structures or arrays, for example -- whose values GDB should record; -while visiting a particular tracepoint, the user may inspect those -objects as if they were in memory at that moment. However, because GDB -records these values without interacting with the user, it can do so -quickly and unobtrusively, hopefully not disturbing the program's -behavior. - - When GDB is debugging a remote target, the GDB "agent" code running -on the target computes the values of the expressions itself. To avoid -having a full symbolic expression evaluator on the agent, GDB translates -expressions in the source language into a simpler bytecode language, and -then sends the bytecode to the agent; the agent then executes the -bytecode, and records the values for GDB to retrieve later. - - The bytecode language is simple; there are forty-odd opcodes, the -bulk of which are the usual vocabulary of C operands (addition, -subtraction, shifts, and so on) and various sizes of literals and -memory reference operations. The bytecode interpreter operates -strictly on machine-level values -- various sizes of integers and -floating point numbers -- and requires no information about types or -symbols; thus, the interpreter's internal data structures are simple, -and each bytecode requires only a few native machine instructions to -implement it. The interpreter is small, and strict limits on the -memory and time required to evaluate an expression are easy to -determine, making it suitable for use by the debugging agent in -real-time applications. - -* Menu: - -* General Bytecode Design:: Overview of the interpreter. -* Bytecode Descriptions:: What each one does. -* Using Agent Expressions:: How agent expressions fit into the big picture. -* Varying Target Capabilities:: How to discover what the target can do. -* Tracing on Symmetrix:: Special info for implementation on EMC's - boxes. -* Rationale:: Why we did it this way. - - -File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions - -General Bytecode Design -======================= - -The agent represents bytecode expressions as an array of bytes. Each -instruction is one byte long (thus the term "bytecode"). Some -instructions are followed by operand bytes; for example, the `goto' -instruction is followed by a destination for the jump. - - The bytecode interpreter is a stack-based machine; most instructions -pop their operands off the stack, perform some operation, and push the -result back on the stack for the next instruction to consume. Each -element of the stack may contain either a integer or a floating point -value; these values are as many bits wide as the largest integer that -can be directly manipulated in the source language. Stack elements -carry no record of their type; bytecode could push a value as an -integer, then pop it as a floating point value. However, GDB will not -generate code which does this. In C, one might define the type of a -stack element as follows: - union agent_val { - LONGEST l; - DOUBLEST d; - }; - -where `LONGEST' and `DOUBLEST' are `typedef' names for the largest -integer and floating point types on the machine. - - By the time the bytecode interpreter reaches the end of the -expression, the value of the expression should be the only value left -on the stack. For tracing applications, `trace' bytecodes in the -expression will have recorded the necessary data, and the value on the -stack may be discarded. For other applications, like conditional -breakpoints, the value may be useful. - - Separate from the stack, the interpreter has two registers: -`pc' - The address of the next bytecode to execute. - -`start' - The address of the start of the bytecode expression, necessary for - interpreting the `goto' and `if_goto' instructions. - - -Neither of these registers is directly visible to the bytecode language -itself, but they are useful for defining the meanings of the bytecode -operations. - - There are no instructions to perform side effects on the running -program, or call the program's functions; we assume that these -expressions are only used for unobtrusive debugging, not for patching -the running code. - - Most bytecode instructions do not distinguish between the various -sizes of values, and operate on full-width values; the upper bits of the -values are simply ignored, since they do not usually make a difference -to the value computed. The exceptions to this rule are: -memory reference instructions (`ref'N) - There are distinct instructions to fetch different word sizes from - memory. Once on the stack, however, the values are treated as - full-size integers. They may need to be sign-extended; the `ext' - instruction exists for this purpose. - -the sign-extension instruction (`ext' N) - These clearly need to know which portion of their operand is to be - extended to occupy the full length of the word. - - - If the interpreter is unable to evaluate an expression completely for -some reason (a memory location is inaccessible, or a divisor is zero, -for example), we say that interpretation "terminates with an error". -This means that the problem is reported back to the interpreter's caller -in some helpful way. In general, code using agent expressions should -assume that they may attempt to divide by zero, fetch arbitrary memory -locations, and misbehave in other ways. - - Even complicated C expressions compile to a few bytecode -instructions; for example, the expression `x + y * z' would typically -produce code like the following, assuming that `x' and `y' live in -registers, and `z' is a global variable holding a 32-bit `int': - reg 1 - reg 2 - const32 address of z - ref32 - ext 32 - mul - add - end - - In detail, these mean: -`reg 1' - Push the value of register 1 (presumably holding `x') onto the - stack. - -`reg 2' - Push the value of register 2 (holding `y'). - -`const32 address of z' - Push the address of `z' onto the stack. - -`ref32' - Fetch a 32-bit word from the address at the top of the stack; - replace the address on the stack with the value. Thus, we replace - the address of `z' with `z''s value. - -`ext 32' - Sign-extend the value on the top of the stack from 32 bits to full - length. This is necessary because `z' is a signed integer. - -`mul' - Pop the top two numbers on the stack, multiply them, and push their - product. Now the top of the stack contains the value of the - expression `y * z'. - -`add' - Pop the top two numbers, add them, and push the sum. Now the top - of the stack contains the value of `x + y * z'. - -`end' - Stop executing; the value left on the stack top is the value to be - recorded. - - - -File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions - -Bytecode Descriptions -===================== - -Each bytecode description has the following form: - -`add' (0x02): A B => A+B - Pop the top two stack items, A and B, as integers; push their sum, - as an integer. - - - In this example, `add' is the name of the bytecode, and `(0x02)' is -the one-byte value used to encode the bytecode, in hexidecimal. The -phrase "A B => A+B" shows the stack before and after the bytecode -executes. Beforehand, the stack must contain at least two values, A -and B; since the top of the stack is to the right, B is on the top of -the stack, and A is underneath it. After execution, the bytecode will -have popped A and B from the stack, and replaced them with a single -value, A+B. There may be other values on the stack below those shown, -but the bytecode affects only those shown. - - Here is another example: - -`const8' (0x22) N: => N - Push the 8-bit integer constant N on the stack, without sign - extension. - - - In this example, the bytecode `const8' takes an operand N directly -from the bytecode stream; the operand follows the `const8' bytecode -itself. We write any such operands immediately after the name of the -bytecode, before the colon, and describe the exact encoding of the -operand in the bytecode stream in the body of the bytecode description. - - For the `const8' bytecode, there are no stack items given before the -=>; this simply means that the bytecode consumes no values from the -stack. If a bytecode consumes no values, or produces no values, the -list on either side of the => may be empty. - - If a value is written as A, B, or N, then the bytecode treats it as -an integer. If a value is written is ADDR, then the bytecode treats it -as an address. - - We do not fully describe the floating point operations here; although -this design can be extended in a clean way to handle floating point -values, they are not of immediate interest to the customer, so we avoid -describing them, to save time. - -`float' (0x01): => - Prefix for floating-point bytecodes. Not implemented yet. - -`add' (0x02): A B => A+B - Pop two integers from the stack, and push their sum, as an integer. - -`sub' (0x03): A B => A-B - Pop two integers from the stack, subtract the top value from the - next-to-top value, and push the difference. - -`mul' (0x04): A B => A*B - Pop two integers from the stack, multiply them, and push the - product on the stack. Note that, when one multiplies two N-bit - numbers yielding another N-bit number, it is irrelevant whether the - numbers are signed or not; the results are the same. - -`div_signed' (0x05): A B => A/B - Pop two signed integers from the stack; divide the next-to-top - value by the top value, and push the quotient. If the divisor is - zero, terminate with an error. - -`div_unsigned' (0x06): A B => A/B - Pop two unsigned integers from the stack; divide the next-to-top - value by the top value, and push the quotient. If the divisor is - zero, terminate with an error. - -`rem_signed' (0x07): A B => A MODULO B - Pop two signed integers from the stack; divide the next-to-top - value by the top value, and push the remainder. If the divisor is - zero, terminate with an error. - -`rem_unsigned' (0x08): A B => A MODULO B - Pop two unsigned integers from the stack; divide the next-to-top - value by the top value, and push the remainder. If the divisor is - zero, terminate with an error. - -`lsh' (0x09): A B => A<<B - Pop two integers from the stack; let A be the next-to-top value, - and B be the top value. Shift A left by B bits, and push the - result. - -`rsh_signed' (0x0a): A B => `(signed)'A>>B - Pop two integers from the stack; let A be the next-to-top value, - and B be the top value. Shift A right by B bits, inserting copies - of the top bit at the high end, and push the result. - -`rsh_unsigned' (0x0b): A B => A>>B - Pop two integers from the stack; let A be the next-to-top value, - and B be the top value. Shift A right by B bits, inserting zero - bits at the high end, and push the result. - -`log_not' (0x0e): A => !A - Pop an integer from the stack; if it is zero, push the value one; - otherwise, push the value zero. - -`bit_and' (0x0f): A B => A&B - Pop two integers from the stack, and push their bitwise `and'. - -`bit_or' (0x10): A B => A|B - Pop two integers from the stack, and push their bitwise `or'. - -`bit_xor' (0x11): A B => A^B - Pop two integers from the stack, and push their bitwise - exclusive-`or'. - -`bit_not' (0x12): A => ~A - Pop an integer from the stack, and push its bitwise complement. - -`equal' (0x13): A B => A=B - Pop two integers from the stack; if they are equal, push the value - one; otherwise, push the value zero. - -`less_signed' (0x14): A B => A<B - Pop two signed integers from the stack; if the next-to-top value - is less than the top value, push the value one; otherwise, push - the value zero. - -`less_unsigned' (0x15): A B => A<B - Pop two unsigned integers from the stack; if the next-to-top value - is less than the top value, push the value one; otherwise, push - the value zero. - -`ext' (0x16) N: A => A, sign-extended from N bits - Pop an unsigned value from the stack; treating it as an N-bit - twos-complement value, extend it to full length. This means that - all bits to the left of bit N-1 (where the least significant bit - is bit 0) are set to the value of bit N-1. Note that N may be - larger than or equal to the width of the stack elements of the - bytecode engine; in this case, the bytecode should have no effect. - - The number of source bits to preserve, N, is encoded as a single - byte unsigned integer following the `ext' bytecode. - -`zero_ext' (0x2a) N: A => A, zero-extended from N bits - Pop an unsigned value from the stack; zero all but the bottom N - bits. This means that all bits to the left of bit N-1 (where the - least significant bit is bit 0) are set to the value of bit N-1. - - The number of source bits to preserve, N, is encoded as a single - byte unsigned integer following the `zero_ext' bytecode. - -`ref8' (0x17): ADDR => A -`ref16' (0x18): ADDR => A -`ref32' (0x19): ADDR => A -`ref64' (0x1a): ADDR => A - Pop an address ADDR from the stack. For bytecode `ref'N, fetch an - N-bit value from ADDR, using the natural target endianness. Push - the fetched value as an unsigned integer. - - Note that ADDR may not be aligned in any particular way; the - `refN' bytecodes should operate correctly for any address. - - If attempting to access memory at ADDR would cause a processor - exception of some sort, terminate with an error. - -`ref_float' (0x1b): ADDR => D -`ref_double' (0x1c): ADDR => D -`ref_long_double' (0x1d): ADDR => D -`l_to_d' (0x1e): A => D -`d_to_l' (0x1f): D => A - Not implemented yet. - -`dup' (0x28): A => A A - Push another copy of the stack's top element. - -`swap' (0x2b): A B => B A - Exchange the top two items on the stack. - -`pop' (0x29): A => - Discard the top value on the stack. - -`if_goto' (0x20) OFFSET: A => - Pop an integer off the stack; if it is non-zero, branch to the - given offset in the bytecode string. Otherwise, continue to the - next instruction in the bytecode stream. In other words, if A is - non-zero, set the `pc' register to `start' + OFFSET. Thus, an - offset of zero denotes the beginning of the expression. - - The OFFSET is stored as a sixteen-bit unsigned value, stored - immediately following the `if_goto' bytecode. It is always stored - most significant byte first, regardless of the target's normal - endianness. The offset is not guaranteed to fall at any particular - alignment within the bytecode stream; thus, on machines where - fetching a 16-bit on an unaligned address raises an exception, you - should fetch the offset one byte at a time. - -`goto' (0x21) OFFSET: => - Branch unconditionally to OFFSET; in other words, set the `pc' - register to `start' + OFFSET. - - The offset is stored in the same way as for the `if_goto' bytecode. - -`const8' (0x22) N: => N -`const16' (0x23) N: => N -`const32' (0x24) N: => N -`const64' (0x25) N: => N - Push the integer constant N on the stack, without sign extension. - To produce a small negative value, push a small twos-complement - value, and then sign-extend it using the `ext' bytecode. - - The constant N is stored in the appropriate number of bytes - following the `const'B bytecode. The constant N is always stored - most significant byte first, regardless of the target's normal - endianness. The constant is not guaranteed to fall at any - particular alignment within the bytecode stream; thus, on machines - where fetching a 16-bit on an unaligned address raises an - exception, you should fetch N one byte at a time. - -`reg' (0x26) N: => A - Push the value of register number N, without sign extension. The - registers are numbered following GDB's conventions. - - The register number N is encoded as a 16-bit unsigned integer - immediately following the `reg' bytecode. It is always stored most - significant byte first, regardless of the target's normal - endianness. The register number is not guaranteed to fall at any - particular alignment within the bytecode stream; thus, on machines - where fetching a 16-bit on an unaligned address raises an - exception, you should fetch the register number one byte at a time. - -`trace' (0x0c): ADDR SIZE => - Record the contents of the SIZE bytes at ADDR in a trace buffer, - for later retrieval by GDB. - -`trace_quick' (0x0d) SIZE: ADDR => ADDR - Record the contents of the SIZE bytes at ADDR in a trace buffer, - for later retrieval by GDB. SIZE is a single byte unsigned - integer following the `trace' opcode. - - This bytecode is equivalent to the sequence `dup const8 SIZE - trace', but we provide it anyway to save space in bytecode strings. - -`trace16' (0x30) SIZE: ADDR => ADDR - Identical to trace_quick, except that SIZE is a 16-bit big-endian - unsigned integer, not a single byte. This should probably have - been named `trace_quick16', for consistency. - -`end' (0x27): => - Stop executing bytecode; the result should be the top element of - the stack. If the purpose of the expression was to compute an - lvalue or a range of memory, then the next-to-top of the stack is - the lvalue's address, and the top of the stack is the lvalue's - size, in bytes. - - - -File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions - -Using Agent Expressions -======================= - -Here is a sketch of a full non-stop debugging cycle, showing how agent -expressions fit into the process. - - * The user selects trace points in the program's code at which GDB - should collect data. - - * The user specifies expressions to evaluate at each trace point. - These expressions may denote objects in memory, in which case - those objects' contents are recorded as the program runs, or - computed values, in which case the values themselves are recorded. - - * GDB transmits the tracepoints and their associated expressions to - the GDB agent, running on the debugging target. - - * The agent arranges to be notified when a trace point is hit. Note - that, on some systems, the target operating system is completely - responsible for collecting the data; see *Note Tracing on - Symmetrix::. - - * When execution on the target reaches a trace point, the agent - evaluates the expressions associated with that trace point, and - records the resulting values and memory ranges. - - * Later, when the user selects a given trace event and inspects the - objects and expression values recorded, GDB talks to the agent to - retrieve recorded data as necessary to meet the user's requests. - If the user asks to see an object whose contents have not been - recorded, GDB reports an error. - - - -File: gdb.info, Node: Varying Target Capabilities, Next: Tracing on Symmetrix, Prev: Using Agent Expressions, Up: Agent Expressions - -Varying Target Capabilities -=========================== - -Some targets don't support floating-point, and some would rather not -have to deal with `long long' operations. Also, different targets will -have different stack sizes, and different bytecode buffer lengths. - - Thus, GDB needs a way to ask the target about itself. We haven't -worked out the details yet, but in general, GDB should be able to send -the target a packet asking it to describe itself. The reply should be a -packet whose length is explicit, so we can add new information to the -packet in future revisions of the agent, without confusing old versions -of GDB, and it should contain a version number. It should contain at -least the following information: - - * whether floating point is supported - - * whether `long long' is supported - - * maximum acceptable size of bytecode stack - - * maximum acceptable length of bytecode expressions - - * which registers are actually available for collection - - * whether the target supports disabled tracepoints - - - -File: gdb.info, Node: Tracing on Symmetrix, Next: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions - -Tracing on Symmetrix -==================== - -This section documents the API used by the GDB agent to collect data on -Symmetrix systems. - - Cygnus originally implemented these tracing features to help EMC -Corporation debug their Symmetrix high-availability disk drives. The -Symmetrix application code already includes substantial tracing -facilities; the GDB agent for the Symmetrix system uses those facilities -for its own data collection, via the API described here. - - - Function: DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *FRAME, - char *ADDRESS, char **BUFFER, unsigned int *SIZE) - Search the trace frame FRAME for memory saved from ADDRESS. If - the memory is available, provide the address of the buffer holding - it; otherwise, provide the address of the next saved area. - - * If the memory at ADDRESS was saved in FRAME, set `*BUFFER' to - point to the buffer in which that memory was saved, set - `*SIZE' to the number of bytes from ADDRESS that are saved at - `*BUFFER', and return `OK_TARGET_RESPONSE'. (Clearly, in - this case, the function will always set `*SIZE' to a value - greater than zero.) - - * If FRAME does not record any memory at ADDRESS, set `*SIZE' - to the distance from ADDRESS to the start of the saved region - with the lowest address higher than ADDRESS. If there is no - memory saved from any higher address, set `*SIZE' to zero. - Return `NOT_FOUND_TARGET_RESPONSE'. - - These two possibilities allow the caller to either retrieve the - data, or walk the address space to the next saved area. - - This function allows the GDB agent to map the regions of memory -saved in a particular frame, and retrieve their contents efficiently. - - This function also provides a clean interface between the GDB agent -and the Symmetrix tracing structures, making it easier to adapt the GDB -agent to future versions of the Symmetrix system, and vice versa. This -function searches all data saved in FRAME, whether the data is there at -the request of a bytecode expression, or because it falls in one of the -format's memory ranges, or because it was saved from the top of the -stack. EMC can arbitrarily change and enhance the tracing mechanism, -but as long as this function works properly, all collected memory is -visible to GDB. - - The function itself is straightforward to implement. A single pass -over the trace frame's stack area, memory ranges, and expression blocks -can yield the address of the buffer (if the requested address was -saved), and also note the address of the next higher range of memory, -to be returned when the search fails. - - As an example, suppose the trace frame `f' has saved sixteen bytes -from address `0x8000' in a buffer at `0x1000', and thirty-two bytes -from address `0xc000' in a buffer at `0x1010'. Here are some sample -calls, and the effect each would have: - -`adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)' - This would set `buffer' to `0x1000', set `size' to sixteen, and - return `OK_TARGET_RESPONSE', since `f' saves sixteen bytes from - `0x8000' at `0x1000'. - -`adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)' - This would set `buffer' to `0x1004', set `size' to twelve, and - return `OK_TARGET_RESPONSE', since `f' saves the twelve bytes from - `0x8004' starting four bytes into the buffer at `0x1000'. This - shows that request addresses may fall in the middle of saved - areas; the function should return the address and size of the - remainder of the buffer. - -`adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)' - This would set `size' to `0x3f00' and return - `NOT_FOUND_TARGET_RESPONSE', since there is no memory saved in `f' - from the address `0x8100', and the next memory available is at - `0x8100 + 0x3f00', or `0xc000'. This shows that request addresses - may fall outside of all saved memory ranges; the function should - indicate the next saved area, if any. - -`adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)' - This would set `size' to `0x1000' and return - `NOT_FOUND_TARGET_RESPONSE', since the next saved memory is at - `0x7000 + 0x1000', or `0x8000'. - -`adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)' - This would set `size' to zero, and return - `NOT_FOUND_TARGET_RESPONSE'. This shows how the function tells the - caller that no further memory ranges have been saved. - - - As another example, here is a function which will print out the -addresses of all memory saved in the trace frame `frame' on the -Symmetrix INLINES console: - void - print_frame_addresses (FRAME_DEF *frame) - { - char *addr; - char *buffer; - unsigned long size; - - addr = 0; - for (;;) - { - /* Either find out how much memory we have here, or discover - where the next saved region is. */ - if (adbg_find_memory_in_frame (frame, addr, &buffer, &size) - == OK_TARGET_RESPONSE) - printp ("saved %x to %x\n", addr, addr + size); - if (size == 0) - break; - addr += size; - } - } - - Note that there is not necessarily any connection between the order -in which the data is saved in the trace frame, and the order in which -`adbg_find_memory_in_frame' will return those memory ranges. The code -above will always print the saved memory regions in order of increasing -address, while the underlying frame structure might store the data in a -random order. - - [[This section should cover the rest of the Symmetrix functions the -stub relies upon, too.]] - - -File: gdb.info, Node: Rationale, Prev: Tracing on Symmetrix, Up: Agent Expressions - -Rationale -========= - -Some of the design decisions apparent above are arguable. - -What about stack overflow/underflow? - GDB should be able to query the target to discover its stack size. - Given that information, GDB can determine at translation time - whether a given expression will overflow the stack. But this spec - isn't about what kinds of error-checking GDB ought to do. - -Why are you doing everything in LONGEST? - Speed isn't important, but agent code size is; using LONGEST - brings in a bunch of support code to do things like division, etc. - So this is a serious concern. - - First, note that you don't need different bytecodes for different - operand sizes. You can generate code without _knowing_ how big the - stack elements actually are on the target. If the target only - supports 32-bit ints, and you don't send any 64-bit bytecodes, - everything just works. The observation here is that the MIPS and - the Alpha have only fixed-size registers, and you can still get - C's semantics even though most instructions only operate on - full-sized words. You just need to make sure everything is - properly sign-extended at the right times. So there is no need - for 32- and 64-bit variants of the bytecodes. Just implement - everything using the largest size you support. - - GDB should certainly check to see what sizes the target supports, - so the user can get an error earlier, rather than later. But this - information is not necessary for correctness. - -Why don't you have `>' or `<=' operators? - I want to keep the interpreter small, and we don't need them. We - can combine the `less_' opcodes with `log_not', and swap the order - of the operands, yielding all four asymmetrical comparison - operators. For example, `(x <= y)' is `! (x > y)', which is `! (y - < x)'. - -Why do you have `log_not'? -Why do you have `ext'? -Why do you have `zero_ext'? - These are all easily synthesized from other instructions, but I - expect them to be used frequently, and they're simple, so I - include them to keep bytecode strings short. - - `log_not' is equivalent to `const8 0 equal'; it's used in half the - relational operators. - - `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed', - where S is the size of the stack elements; it follows `refM' and - REG bytecodes when the value should be signed. See the next - bulleted item. - - `zero_ext N' is equivalent to `constM MASK log_and'; it's used - whenever we push the value of a register, because we can't assume - the upper bits of the register aren't garbage. - -Why not have sign-extending variants of the `ref' operators? - Because that would double the number of `ref' operators, and we - need the `ext' bytecode anyway for accessing bitfields. - -Why not have constant-address variants of the `ref' operators? - Because that would double the number of `ref' operators again, and - `const32 ADDRESS ref32' is only one byte longer. - -Why do the `refN' operators have to support unaligned fetches? - GDB will generate bytecode that fetches multi-byte values at - unaligned addresses whenever the executable's debugging - information tells it to. Furthermore, GDB does not know the value - the pointer will have when GDB generates the bytecode, so it - cannot determine whether a particular fetch will be aligned or not. - - In particular, structure bitfields may be several bytes long, but - follow no alignment rules; members of packed structures are not - necessarily aligned either. - - In general, there are many cases where unaligned references occur - in correct C code, either at the programmer's explicit request, or - at the compiler's discretion. Thus, it is simpler to make the GDB - agent bytecodes work correctly in all circumstances than to make - GDB guess in each case whether the compiler did the usual thing. - -Why are there no side-effecting operators? - Because our current client doesn't want them? That's a cheap - answer. I think the real answer is that I'm afraid of - implementing function calls. We should re-visit this issue after - the present contract is delivered. - -Why aren't the `goto' ops PC-relative? - The interpreter has the base address around anyway for PC bounds - checking, and it seemed simpler. - -Why is there only one offset size for the `goto' ops? - Offsets are currently sixteen bits. I'm not happy with this - situation either: - - Suppose we have multiple branch ops with different offset sizes. - As I generate code left-to-right, all my jumps are forward jumps - (there are no loops in expressions), so I never know the target - when I emit the jump opcode. Thus, I have to either always assume - the largest offset size, or do jump relaxation on the code after I - generate it, which seems like a big waste of time. - - I can imagine a reasonable expression being longer than 256 bytes. - I can't imagine one being longer than 64k. Thus, we need 16-bit - offsets. This kind of reasoning is so bogus, but relaxation is - pathetic. - - The other approach would be to generate code right-to-left. Then - I'd always know my offset size. That might be fun. - -Where is the function call bytecode? - When we add side-effects, we should add this. - -Why does the `reg' bytecode take a 16-bit register number? - Intel's IA-64 architecture has 128 general-purpose registers, and - 128 floating-point registers, and I'm sure it has some random - control registers. - -Why do we need `trace' and `trace_quick'? - Because GDB needs to record all the memory contents and registers - an expression touches. If the user wants to evaluate an expression - `x->y->z', the agent must record the values of `x' and `x->y' as - well as the value of `x->y->z'. - -Don't the `trace' bytecodes make the interpreter less general? - They do mean that the interpreter contains special-purpose code, - but that doesn't mean the interpreter can only be used for that - purpose. If an expression doesn't use the `trace' bytecodes, they - don't get in its way. - -Why doesn't `trace_quick' consume its arguments the way everything else does? - In general, you do want your operators to consume their arguments; - it's consistent, and generally reduces the amount of stack - rearrangement necessary. However, `trace_quick' is a kludge to - save space; it only exists so we needn't write `dup const8 SIZE - trace' before every memory reference. Therefore, it's okay for it - not to consume its arguments; it's meant for a specific context in - which we know exactly what it should do with the stack. If we're - going to have a kludge, it should be an effective kludge. - -Why does `trace16' exist? - That opcode was added by the customer that contracted Cygnus for - the data tracing work. I personally think it is unnecessary; - objects that large will be quite rare, so it is okay to use `dup - const16 SIZE trace' in those cases. - - Whatever we decide to do with `trace16', we should at least leave - opcode 0x30 reserved, to remain compatible with the customer who - added it. - - - -File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Agent Expressions, Up: Top - -GNU GENERAL PUBLIC LICENSE -************************** - - Version 2, June 1991 - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - -Preamble -======== - -The licenses for most software are designed to take away your freedom -to share and change it. By contrast, the GNU General Public License is -intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it in -new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, -and (2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - 0. This License applies to any program or other work which contains a - notice placed by the copyright holder saying it may be distributed - under the terms of this General Public License. The "Program", - below, refers to any such program or work, and a "work based on - the Program" means either the Program or any derivative work under - copyright law: that is to say, a work containing the Program or a - portion of it, either verbatim or with modifications and/or - translated into another language. (Hereinafter, translation is - included without limitation in the term "modification".) Each - licensee is addressed as "you". - - Activities other than copying, distribution and modification are - not covered by this License; they are outside its scope. The act - of running the Program is not restricted, and the output from the - Program is covered only if its contents constitute a work based on - the Program (independent of having been made by running the - Program). Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's - source code as you receive it, in any medium, provided that you - conspicuously and appropriately publish on each copy an appropriate - copyright notice and disclaimer of warranty; keep intact all the - notices that refer to this License and to the absence of any - warranty; and give any other recipients of the Program a copy of - this License along with the Program. - - You may charge a fee for the physical act of transferring a copy, - and you may at your option offer warranty protection in exchange - for a fee. - - 2. You may modify your copy or copies of the Program or any portion - of it, thus forming a work based on the Program, and copy and - distribute such modifications or work under the terms of Section 1 - above, provided that you also meet all of these conditions: - - a. You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b. You must cause any work that you distribute or publish, that - in whole or in part contains or is derived from the Program - or any part thereof, to be licensed as a whole at no charge - to all third parties under the terms of this License. - - c. If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display - an announcement including an appropriate copyright notice and - a notice that there is no warranty (or else, saying that you - provide a warranty) and that users may redistribute the - program under these conditions, and telling the user how to - view a copy of this License. (Exception: if the Program - itself is interactive but does not normally print such an - announcement, your work based on the Program is not required - to print an announcement.) - - These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the - Program, and can be reasonably considered independent and separate - works in themselves, then this License, and its terms, do not - apply to those sections when you distribute them as separate - works. But when you distribute the same sections as part of a - whole which is a work based on the Program, the distribution of - the whole must be on the terms of this License, whose permissions - for other licensees extend to the entire whole, and thus to each - and every part regardless of who wrote it. - - Thus, it is not the intent of this section to claim rights or - contest your rights to work written entirely by you; rather, the - intent is to exercise the right to control the distribution of - derivative or collective works based on the Program. - - In addition, mere aggregation of another work not based on the - Program with the Program (or with a work based on the Program) on - a volume of a storage or distribution medium does not bring the - other work under the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, - under Section 2) in object code or executable form under the terms - of Sections 1 and 2 above provided that you also do one of the - following: - - a. Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of - Sections 1 and 2 above on a medium customarily used for - software interchange; or, - - b. Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a - medium customarily used for software interchange; or, - - c. Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with - such an offer, in accord with Subsection b above.) - - The source code for a work means the preferred form of the work for - making modifications to it. For an executable work, complete - source code means all the source code for all modules it contains, - plus any associated interface definition files, plus the scripts - used to control compilation and installation of the executable. - However, as a special exception, the source code distributed need - not include anything that is normally distributed (in either - source or binary form) with the major components (compiler, - kernel, and so on) of the operating system on which the executable - runs, unless that component itself accompanies the executable. - - If distribution of executable or object code is made by offering - access to copy from a designated place, then offering equivalent - access to copy the source code from the same place counts as - distribution of the source code, even though third parties are not - compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense or distribute the Program is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 5. You are not required to accept this License, since you have not - signed it. However, nothing else grants you permission to modify - or distribute the Program or its derivative works. These actions - are prohibited by law if you do not accept this License. - Therefore, by modifying or distributing the Program (or any work - based on the Program), you indicate your acceptance of this - License to do so, and all its terms and conditions for copying, - distributing or modifying the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the - Program), the recipient automatically receives a license from the - original licensor to copy, distribute or modify the Program - subject to these terms and conditions. You may not impose any - further restrictions on the recipients' exercise of the rights - granted herein. You are not responsible for enforcing compliance - by third parties to this License. - - 7. If, as a consequence of a court judgment or allegation of patent - infringement or for any other reason (not limited to patent - issues), conditions are imposed on you (whether by court order, - agreement or otherwise) that contradict the conditions of this - License, they do not excuse you from the conditions of this - License. If you cannot distribute so as to satisfy simultaneously - your obligations under this License and any other pertinent - obligations, then as a consequence you may not distribute the - Program at all. For example, if a patent license would not permit - royalty-free redistribution of the Program by all those who - receive copies directly or indirectly through you, then the only - way you could satisfy both it and this License would be to refrain - entirely from distribution of the Program. - - If any portion of this section is held invalid or unenforceable - under any particular circumstance, the balance of the section is - intended to apply and the section as a whole is intended to apply - in other circumstances. - - It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of - any such claims; this section has the sole purpose of protecting - the integrity of the free software distribution system, which is - implemented by public license practices. Many people have made - generous contributions to the wide range of software distributed - through that system in reliance on consistent application of that - system; it is up to the author/donor to decide if he or she is - willing to distribute software through any other system and a - licensee cannot impose that choice. - - This section is intended to make thoroughly clear what is believed - to be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in - certain countries either by patents or by copyrighted interfaces, - the original copyright holder who places the Program under this - License may add an explicit geographical distribution limitation - excluding those countries, so that distribution is permitted only - in or among countries not thus excluded. In such case, this - License incorporates the limitation as if written in the body of - this License. - - 9. The Free Software Foundation may publish revised and/or new - versions of the General Public License from time to time. Such - new versions will be similar in spirit to the present version, but - may differ in detail to address new problems or concerns. - - Each version is given a distinguishing version number. If the - Program specifies a version number of this License which applies - to it and "any later version", you have the option of following - the terms and conditions either of that version or of any later - version published by the Free Software Foundation. If the Program - does not specify a version number of this License, you may choose - any version ever published by the Free Software Foundation. - - 10. If you wish to incorporate parts of the Program into other free - programs whose distribution conditions are different, write to the - author to ask for permission. For software which is copyrighted - by the Free Software Foundation, write to the Free Software - Foundation; we sometimes make exceptions for this. Our decision - will be guided by the two goals of preserving the free status of - all derivatives of our free software and of promoting the sharing - and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO - WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE - LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT - HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT - WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT - NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE - QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE - PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY - SERVICING, REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY - MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE - LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, - INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR - INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF - DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU - OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY - OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - -How to Apply These Terms to Your New Programs -============================================= - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. - Copyright (C) YEAR NAME OF AUTHOR - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - - Also add information on how to contact you by electronic and paper -mail. - - If the program is interactive, make it output a short notice like -this when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details - type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - - The hypothetical commands `show w' and `show c' should show the -appropriate parts of the General Public License. Of course, the -commands you use may be called something other than `show w' and `show -c'; they could even be mouse-clicks or menu items--whatever suits your -program. - - You should also get your employer (if you work as a programmer) or -your school, if any, to sign a "copyright disclaimer" for the program, -if necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - SIGNATURE OF TY COON, 1 April 1989 - Ty Coon, President of Vice - - This General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use the -GNU Library General Public License instead of this License. - - -File: gdb.info, Node: GNU Free Documentation License, Next: Index, Prev: Copying, Up: Top - -GNU Free Documentation License -****************************** - - Version 1.2, November 2002 - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included in an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warranty Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover -Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, to -permit their use in free software. - - -File: gdb.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - -Index -***** - -* Menu: - -* ! packet: Packets. -* "No symbol "foo" in current context": Variables. -* # (a comment): Command Syntax. -* # in Modula-2: GDB/M2. -* $: Value History. -* $$: Value History. -* $_ and info breakpoints: Set Breaks. -* $_ and info line: Machine Code. -* $_, $__, and value history: Memory. -* $_, convenience variable: Convenience Vars. -* $__, convenience variable: Convenience Vars. -* $_exitcode, convenience variable: Convenience Vars. -* $bpnum, convenience variable: Set Breaks. -* $cdir, convenience variable: Source Path. -* $cwdr, convenience variable: Source Path. -* $tpnum: Create and Delete Tracepoints. -* $trace_file: Tracepoint Variables. -* $trace_frame: Tracepoint Variables. -* $trace_func: Tracepoint Variables. -* $trace_line: Tracepoint Variables. -* $tracepoint: Tracepoint Variables. -* --annotate: Mode Options. -* --args: Mode Options. -* --async: Mode Options. -* --batch: Mode Options. -* --baud: Mode Options. -* --cd: Mode Options. -* --command: File Options. -* --core: File Options. -* --directory: File Options. -* --epoch: Mode Options. -* --exec: File Options. -* --fullname: Mode Options. -* --interpreter: Mode Options. -* --mapped: File Options. -* --noasync: Mode Options. -* --nowindows: Mode Options. -* --nx: Mode Options. -* --pid: File Options. -* --quiet: Mode Options. -* --readnow: File Options. -* --se: File Options. -* --silent: Mode Options. -* --statistics: Mode Options. -* --symbols: File Options. -* --tty: Mode Options. -* --tui: Mode Options. -* --version: Mode Options. -* --windows: Mode Options. -* --write: Mode Options. -* -b: Mode Options. -* -break-after: GDB/MI Breakpoint Table Commands. -* -break-condition: GDB/MI Breakpoint Table Commands. -* -break-delete: GDB/MI Breakpoint Table Commands. -* -break-disable: GDB/MI Breakpoint Table Commands. -* -break-enable: GDB/MI Breakpoint Table Commands. -* -break-info: GDB/MI Breakpoint Table Commands. -* -break-insert: GDB/MI Breakpoint Table Commands. -* -break-list: GDB/MI Breakpoint Table Commands. -* -break-watch: GDB/MI Breakpoint Table Commands. -* -c: File Options. -* -d: File Options. -* -data-disassemble: GDB/MI Data Manipulation. -* -data-evaluate-expression: GDB/MI Data Manipulation. -* -data-list-changed-registers: GDB/MI Data Manipulation. -* -data-list-register-names: GDB/MI Data Manipulation. -* -data-list-register-values: GDB/MI Data Manipulation. -* -data-read-memory: GDB/MI Data Manipulation. -* -display-delete: GDB/MI Data Manipulation. -* -display-disable: GDB/MI Data Manipulation. -* -display-enable: GDB/MI Data Manipulation. -* -display-insert: GDB/MI Data Manipulation. -* -display-list: GDB/MI Data Manipulation. -* -e: File Options. -* -environment-cd: GDB/MI Data Manipulation. -* -environment-directory: GDB/MI Data Manipulation. -* -environment-path: GDB/MI Data Manipulation. -* -environment-pwd: GDB/MI Data Manipulation. -* -exec-abort: GDB/MI Program Control. -* -exec-arguments: GDB/MI Program Control. -* -exec-continue: GDB/MI Program Control. -* -exec-finish: GDB/MI Program Control. -* -exec-interrupt: GDB/MI Program Control. -* -exec-next: GDB/MI Program Control. -* -exec-next-instruction: GDB/MI Program Control. -* -exec-return: GDB/MI Program Control. -* -exec-run: GDB/MI Program Control. -* -exec-show-arguments: GDB/MI Program Control. -* -exec-step: GDB/MI Program Control. -* -exec-step-instruction: GDB/MI Program Control. -* -exec-until: GDB/MI Program Control. -* -f: Mode Options. -* -file-exec-and-symbols: GDB/MI Program Control. -* -file-exec-file: GDB/MI Program Control. -* -file-list-exec-sections: GDB/MI Program Control. -* -file-list-exec-source-file: GDB/MI Program Control. -* -file-list-exec-source-files: GDB/MI Program Control. -* -file-list-shared-libraries: GDB/MI Program Control. -* -file-list-symbol-files: GDB/MI Program Control. -* -file-symbol-file: GDB/MI Program Control. -* -gdb-exit: GDB/MI Miscellaneous Commands. -* -gdb-set: GDB/MI Miscellaneous Commands. -* -gdb-show: GDB/MI Miscellaneous Commands. -* -gdb-version: GDB/MI Miscellaneous Commands. -* -interpreter-exec: GDB/MI Miscellaneous Commands. -* -m: File Options. -* -n: Mode Options. -* -nw: Mode Options. -* -p: File Options. -* -q: Mode Options. -* -r: File Options. -* -s: File Options. -* -stack-info-depth: GDB/MI Stack Manipulation. -* -stack-info-frame: GDB/MI Stack Manipulation. -* -stack-list-arguments: GDB/MI Stack Manipulation. -* -stack-list-frames: GDB/MI Stack Manipulation. -* -stack-list-locals: GDB/MI Stack Manipulation. -* -stack-select-frame: GDB/MI Stack Manipulation. -* -symbol-info-address: GDB/MI Symbol Query. -* -symbol-info-file: GDB/MI Symbol Query. -* -symbol-info-function: GDB/MI Symbol Query. -* -symbol-info-line: GDB/MI Symbol Query. -* -symbol-info-symbol: GDB/MI Symbol Query. -* -symbol-list-functions: GDB/MI Symbol Query. -* -symbol-list-lines: GDB/MI Symbol Query. -* -symbol-list-types: GDB/MI Symbol Query. -* -symbol-list-variables: GDB/MI Symbol Query. -* -symbol-locate: GDB/MI Symbol Query. -* -symbol-type: GDB/MI Symbol Query. -* -t: Mode Options. -* -target-attach: GDB/MI Target Manipulation. -* -target-compare-sections: GDB/MI Target Manipulation. -* -target-detach: GDB/MI Target Manipulation. -* -target-disconnect: GDB/MI Target Manipulation. -* -target-download: GDB/MI Target Manipulation. -* -target-exec-status: GDB/MI Target Manipulation. -* -target-list-available-targets: GDB/MI Target Manipulation. -* -target-list-current-targets: GDB/MI Target Manipulation. -* -target-list-parameters: GDB/MI Target Manipulation. -* -target-select: GDB/MI Target Manipulation. -* -thread-info: GDB/MI Thread Commands. -* -thread-list-all-threads: GDB/MI Thread Commands. -* -thread-list-ids: GDB/MI Thread Commands. -* -thread-select: GDB/MI Thread Commands. -* -var-assign: GDB/MI Variable Objects. -* -var-create: GDB/MI Variable Objects. -* -var-delete: GDB/MI Variable Objects. -* -var-evaluate-expression: GDB/MI Variable Objects. -* -var-info-expression: GDB/MI Variable Objects. -* -var-info-num-children: GDB/MI Variable Objects. -* -var-info-type: GDB/MI Variable Objects. -* -var-list-children: GDB/MI Variable Objects. -* -var-set-format: GDB/MI Variable Objects. -* -var-show-attributes: GDB/MI Variable Objects. -* -var-show-format: GDB/MI Variable Objects. -* -var-update: GDB/MI Variable Objects. -* -w: Mode Options. -* -x: File Options. -* ., Modula-2 scope operator: M2 Scope. -* .debug subdirectories: Separate Debug Files. -* .esgdbinit: Command Files. -* .gdbinit: Command Files. -* .gnu_debuglink sections: Separate Debug Files. -* .o files, reading symbols from: Files. -* .os68gdbinit: Command Files. -* .vxgdbinit: Command Files. -* /proc: SVR4 Process Information. -* ? packet: Packets. -* @, referencing memory as an array: Arrays. -* ^done: GDB/MI Result Records. -* ^error: GDB/MI Result Records. -* ^running: GDB/MI Result Records. -* _NSPrintForDebugger, and printing Objective-C objects: The Print Command with Objective-C. -* A packet: Packets. -* abbreviation: Command Syntax. -* abort (C-g): Miscellaneous Commands. -* accept-line (Newline or Return): Commands For History. -* acknowledgment, for GDB remote: Overview. -* actions: Tracepoint Actions. -* active targets: Active Targets. -* adbg_find_memory_in_frame: Tracing on Symmetrix. -* add-shared-symbol-file: Files. -* add-symbol-file: Files. -* address of a symbol: Symbols. -* advance LOCATION: Continuing and Stepping. -* Alpha stack: MIPS. -* AMD 29K register stack: A29K. -* annotations: Annotations Overview. -* annotations for errors, warnings and interrupts: Errors. -* annotations for invalidation messages: Invalidation. -* annotations for prompts: Prompting. -* annotations for running programs: Annotations for Running. -* annotations for source display: Source Annotations. -* append: Dump/Restore Files. -* append data to a file: Dump/Restore Files. -* apropos: Help. -* arguments (to your program): Arguments. -* artificial array: Arrays. -* ASCII character set: Character Sets. -* assembly instructions: Machine Code. -* assignment: Assignment. -* async output in GDB/MI: GDB/MI Output Syntax. -* AT&T disassembly flavor: Machine Code. -* attach: Attach. -* attach to a program by name: Server. -* automatic display: Auto Display. -* automatic overlay debugging: Automatic Overlay Debugging. -* automatic thread selection: Threads. -* auxiliary vector: Auxiliary Vector. -* awatch: Set Watchpoints. -* b (break): Set Breaks. -* B packet: Packets. -* b packet: Packets. -* backtrace: Backtrace. -* backtrace limit: Backtrace. -* backtraces: Backtrace. -* backward-char (C-b): Commands For Moving. -* backward-delete-char (Rubout): Commands For Text. -* backward-kill-line (C-x Rubout): Commands For Killing. -* backward-kill-word (M-<DEL>): Commands For Killing. -* backward-word (M-b): Commands For Moving. -* beginning-of-history (M-<): Commands For History. -* beginning-of-line (C-a): Commands For Moving. -* bell-style: Readline Init File Syntax. -* break: Set Breaks. -* break ... thread THREADNO: Thread Stops. -* break in overloaded functions: Debugging C plus plus. -* break, and Objective-C: Method Names in Commands. -* breakpoint: Annotations for Running. -* breakpoint address adjusted: Breakpoint related warnings. -* breakpoint commands: Break Commands. -* breakpoint commands for GDB/MI: GDB/MI Breakpoint Table Commands. -* breakpoint conditions: Conditions. -* breakpoint numbers: Breakpoints. -* breakpoint on events: Breakpoints. -* breakpoint on memory address: Breakpoints. -* breakpoint on variable modification: Breakpoints. -* breakpoint ranges: Breakpoints. -* breakpoint subroutine, remote: Stub Contents. -* breakpoints: Breakpoints. -* breakpoints and threads: Thread Stops. -* breakpoints in overlays: Overlay Commands. -* breakpoints-invalid: Invalidation. -* bt (backtrace): Backtrace. -* bug criteria: Bug Criteria. -* bug reports: Bug Reporting. -* bugs in GDB: GDB Bugs. -* c (continue): Continuing and Stepping. -* c (SingleKey TUI key): TUI Single Key Mode. -* C and C++: C. -* C and C++ checks: C Checks. -* C and C++ constants: C Constants. -* C and C++ defaults: C Defaults. -* C and C++ operators: C Operators. -* C packet: Packets. -* c packet: Packets. -* C++: C. -* C++ compilers: C plus plus expressions. -* C++ exception handling: Debugging C plus plus. -* C++ scope resolution: Variables. -* C++ symbol decoding style: Print Settings. -* C++ symbol display: Debugging C plus plus. -* C-L: TUI Keys. -* C-o (operate-and-get-next): Command Syntax. -* C-x 1: TUI Keys. -* C-x 2: TUI Keys. -* C-x A: TUI Keys. -* C-x a: TUI Keys. -* C-x C-a: TUI Keys. -* C-x o: TUI Keys. -* C-x s: TUI Keys. -* call: Calling. -* call overloaded functions: C plus plus expressions. -* call stack: Stack. -* call-last-kbd-macro (C-x e): Keyboard Macros. -* calling functions: Calling. -* calling make: Shell Commands. -* capitalize-word (M-c): Commands For Text. -* casts, to view memory: Expressions. -* catch: Set Catchpoints. -* catch catch: Set Catchpoints. -* catch exceptions, list active handlers: Frame Info. -* catch exec: Set Catchpoints. -* catch fork: Set Catchpoints. -* catch load: Set Catchpoints. -* catch throw: Set Catchpoints. -* catch unload: Set Catchpoints. -* catch vfork: Set Catchpoints. -* catchpoints: Breakpoints. -* catchpoints, setting: Set Catchpoints. -* cd: Working Directory. -* cdir: Source Path. -* character sets: Character Sets. -* character-search (C-]): Miscellaneous Commands. -* character-search-backward (M-C-]): Miscellaneous Commands. -* charset: Character Sets. -* checks, range: Type Checking. -* checks, type: Checks. -* checksum, for GDB remote: Overview. -* choosing target byte order: Byte Order. -* clear: Delete Breaks. -* clear, and Objective-C: Method Names in Commands. -* clear-screen (C-l): Commands For Moving. -* clearing breakpoints, watchpoints, catchpoints: Delete Breaks. -* close, file-i/o system call: close. -* collect (tracepoints): Tracepoint Actions. -* collected data discarded: Starting and Stopping Trace Experiment. -* colon, doubled as scope operator: M2 Scope. -* colon-colon, context for variables/functions: Variables. -* colon-colon, in Modula-2: M2 Scope. -* command editing: Readline Bare Essentials. -* command files: Command Files. -* command hooks: Hooks. -* command interpreters: Interpreters. -* command line editing: Editing. -* commands <1>: Prompting. -* commands: Break Commands. -* commands for C++: Debugging C plus plus. -* commands to STDBUG (ST2000): ST2000. -* comment: Command Syntax. -* comment-begin: Readline Init File Syntax. -* compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI. -* compilation directory: Source Path. -* compiling, on Sparclet: Sparclet. -* complete: Help. -* complete (<TAB>): Commands For Completion. -* completion: Completion. -* completion of quoted strings: Completion. -* completion-query-items: Readline Init File Syntax. -* condition: Conditions. -* conditional breakpoints: Conditions. -* configuring GDB: Installing GDB. -* configuring GDB, and source tree subdirectories: Installing GDB. -* confirmation: Messages/Warnings. -* connect (to STDBUG): ST2000. -* console i/o as part of file-i/o: Console I/O. -* console interpreter: Interpreters. -* console output in GDB/MI: GDB/MI Output Syntax. -* constants, in file-i/o protocol: Constants. -* continue: Continuing and Stepping. -* continuing: Continuing and Stepping. -* continuing threads: Thread Stops. -* control C, and remote debugging: Bootstrapping. -* controlling terminal: Input/Output. -* convenience variables: Convenience Vars. -* convenience variables for tracepoints: Tracepoint Variables. -* convert-meta: Readline Init File Syntax. -* copy-backward-word (): Commands For Killing. -* copy-forward-word (): Commands For Killing. -* copy-region-as-kill (): Commands For Killing. -* core: Files. -* core dump file: Files. -* core-file: Files. -* crash of debugger: Bug Criteria. -* ctrl-c message, in file-i/o protocol: The Ctrl-C message. -* current directory: Source Path. -* current stack frame: Frames. -* current thread: Threads. -* cwd: Source Path. -* Cygwin-specific commands: Cygwin Native. -* d (delete): Delete Breaks. -* d (SingleKey TUI key): TUI Single Key Mode. -* D packet: Packets. -* d packet: Packets. -* data manipulation, in GDB/MI: GDB/MI Data Manipulation. -* debug formats and C++: C plus plus expressions. -* debug links: Separate Debug Files. -* debugger crash: Bug Criteria. -* debugging C++ programs: C plus plus expressions. -* debugging information directory, global: Separate Debug Files. -* debugging information in separate files: Separate Debug Files. -* debugging optimized code: Compilation. -* debugging stub, example: remote stub. -* debugging target: Targets. -* define: Define. -* defining macros interactively: Macros. -* definition, showing a macro's: Macros. -* delete: Delete Breaks. -* delete breakpoints: Delete Breaks. -* delete display: Auto Display. -* delete mem: Memory Region Attributes. -* delete tracepoint: Create and Delete Tracepoints. -* delete-char (C-d): Commands For Text. -* delete-char-or-list (): Commands For Completion. -* delete-horizontal-space (): Commands For Killing. -* deleting breakpoints, watchpoints, catchpoints: Delete Breaks. -* demangling: Print Settings. -* descriptor tables display: DJGPP Native. -* detach: Attach. -* detach (remote): Connecting. -* device: Renesas Boards. -* digit-argument (M-0, M-1, ... M--): Numeric Arguments. -* dir: Source Path. -* direct memory access (DMA) on MS-DOS: DJGPP Native. -* directories for source files: Source Path. -* directory: Source Path. -* directory, compilation: Source Path. -* directory, current: Source Path. -* dis (disable): Disabling. -* disable: Disabling. -* disable breakpoints: Disabling. -* disable display: Auto Display. -* disable mem: Memory Region Attributes. -* disable tracepoint: Enable and Disable Tracepoints. -* disable-completion: Readline Init File Syntax. -* disassemble: Machine Code. -* disconnect: Connecting. -* display: Auto Display. -* display of expressions: Auto Display. -* DJGPP debugging: DJGPP Native. -* dll-symbols: Cygwin Native. -* DLLs with no debugging symbols: Non-debug DLL symbols. -* do (down): Selection. -* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. -* document: Define. -* documentation: Formatting Documentation. -* Down: TUI Keys. -* down: Selection. -* down-silently: Selection. -* downcase-word (M-l): Commands For Text. -* download to H8/300 or H8/500: H8/300. -* download to Renesas SH: H8/300. -* download to Sparclet: Sparclet Download. -* download to VxWorks: VxWorks Download. -* dump: Dump/Restore Files. -* dump all data collected at tracepoint: tdump. -* dump data to a file: Dump/Restore Files. -* dump-functions (): Miscellaneous Commands. -* dump-macros (): Miscellaneous Commands. -* dump-variables (): Miscellaneous Commands. -* dump/restore files: Dump/Restore Files. -* dynamic linking: Files. -* e (edit): Edit. -* EBCDIC character set: Character Sets. -* echo: Output. -* edit: Edit. -* editing: Editing. -* editing command lines: Readline Bare Essentials. -* editing source files: Edit. -* editing-mode: Readline Init File Syntax. -* else: Define. -* Emacs: Emacs. -* enable: Disabling. -* enable breakpoints: Disabling. -* enable display: Auto Display. -* enable mem: Memory Region Attributes. -* enable tracepoint: Enable and Disable Tracepoints. -* enable-keypad: Readline Init File Syntax. -* end: Break Commands. -* end-kbd-macro (C-x )): Keyboard Macros. -* end-of-history (M->): Commands For History. -* end-of-line (C-e): Commands For Moving. -* entering numbers: Numbers. -* environment (of your program): Environment. -* errno values, in file-i/o protocol: Errno values. -* error: Errors. -* error on valid input: Bug Criteria. -* error-begin: Errors. -* event designators: Event Designators. -* event handling: Set Catchpoints. -* examining data: Data. -* examining memory: Memory. -* exception handlers: Set Catchpoints. -* exception handlers, how to list: Frame Info. -* exceptionHandler: Bootstrapping. -* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. -* exec-file: Files. -* executable file: Files. -* exited: Annotations for Running. -* exiting GDB: Quitting GDB. -* expand-tilde: Readline Init File Syntax. -* expanding preprocessor macros: Macros. -* expressions: Expressions. -* expressions in C or C++: C. -* expressions in C++: C plus plus expressions. -* expressions in Modula-2: Modula-2. -* f (frame): Selection. -* f (SingleKey TUI key): TUI Single Key Mode. -* F packet: Packets. -* F reply packet: The F reply packet. -* F request packet: The F request packet. -* fatal signal: Bug Criteria. -* fatal signals: Signals. -* FDL, GNU Free Documentation License: GNU Free Documentation License. -* fg (resume foreground execution): Continuing and Stepping. -* file: Files. -* file-i/o examples: File-I/O Examples. -* file-i/o overview: File-I/O Overview. -* File-I/O remote protocol extension: File-I/O remote protocol extension. -* file-i/o reply packet: The F reply packet. -* file-i/o request packet: The F request packet. -* find trace snapshot: tfind. -* finish: Continuing and Stepping. -* flinching: Messages/Warnings. -* float promotion: ABI. -* floating point: Floating Point Hardware. -* floating point registers: Registers. -* floating point, MIPS remote: MIPS Embedded. -* flush_i_cache: Bootstrapping. -* focus: TUI Commands. -* focus of debugging: Threads. -* foo: Symbol Errors. -* fork, debugging programs which call: Processes. -* format options: Print Settings. -* formatted output: Output Formats. -* Fortran: Summary. -* forward-backward-delete-char (): Commands For Text. -* forward-char (C-f): Commands For Moving. -* forward-search: Search. -* forward-search-history (C-s): Commands For History. -* forward-word (M-f): Commands For Moving. -* frame number: Frames. -* frame pointer: Frames. -* frame, command: Frames. -* frame, definition: Frames. -* frame, selecting: Selection. -* frameless execution: Frames. -* frames-invalid: Invalidation. -* free memory information (MS-DOS): DJGPP Native. -* fstat, file-i/o system call: stat/fstat. -* Fujitsu: remote stub. -* full symbol tables, listing GDB's internal: Symbols. -* functions without line info, and stepping: Continuing and Stepping. -* G packet: Packets. -* g packet: Packets. -* g++, GNU C++ compiler: C. -* garbled pointers: DJGPP Native. -* GCC and C++: C plus plus expressions. -* GDB bugs, reporting: Bug Reporting. -* GDB reference card: Formatting Documentation. -* gdb.ini: Command Files. -* GDB/MI, breakpoint commands: GDB/MI Breakpoint Table Commands. -* GDB/MI, compatibility with CLI: GDB/MI Compatibility with CLI. -* GDB/MI, data manipulation: GDB/MI Data Manipulation. -* GDB/MI, input syntax: GDB/MI Input Syntax. -* GDB/MI, its purpose: GDB/MI. -* GDB/MI, out-of-band records: GDB/MI Out-of-band Records. -* GDB/MI, output syntax: GDB/MI Output Syntax. -* GDB/MI, result records: GDB/MI Result Records. -* GDB/MI, simple examples: GDB/MI Simple Examples. -* GDB/MI, stream records: GDB/MI Stream Records. -* GDBHISTFILE: History. -* gdbserve.nlm: NetWare. -* gdbserver: Server. -* GDT: DJGPP Native. -* getDebugChar: Bootstrapping. -* gettimeofday, file-i/o system call: gettimeofday. -* global debugging information directory: Separate Debug Files. -* GNU C++: C. -* GNU Emacs: Emacs. -* gnu_debuglink_crc32: Separate Debug Files. -* h (help): Help. -* H packet: Packets. -* H8/300 or H8/500 download: H8/300. -* handle: Signals. -* handle_exception: Stub Contents. -* handling signals: Signals. -* hardware watchpoints: Set Watchpoints. -* hbreak: Set Breaks. -* help: Help. -* help target: Target Commands. -* help user-defined: Define. -* heuristic-fence-post (Alpha, MIPS): MIPS. -* history events: Event Designators. -* history expansion <1>: History Interaction. -* history expansion: History. -* history file: History. -* history number: Value History. -* history save: History. -* history size: History. -* history substitution: History. -* history-preserve-point: Readline Init File Syntax. -* history-search-backward (): Commands For History. -* history-search-forward (): Commands For History. -* hook: Hooks. -* hook-: Hooks. -* hookpost: Hooks. -* hookpost-: Hooks. -* hooks, for commands: Hooks. -* hooks, post-command: Hooks. -* hooks, pre-command: Hooks. -* horizontal-scroll-mode: Readline Init File Syntax. -* host character set: Character Sets. -* htrace disable: OpenRISC 1000. -* htrace enable: OpenRISC 1000. -* htrace info: OpenRISC 1000. -* htrace mode continuous: OpenRISC 1000. -* htrace mode suspend: OpenRISC 1000. -* htrace print: OpenRISC 1000. -* htrace qualifier: OpenRISC 1000. -* htrace record: OpenRISC 1000. -* htrace rewind: OpenRISC 1000. -* htrace stop: OpenRISC 1000. -* htrace trigger: OpenRISC 1000. -* hwatch: OpenRISC 1000. -* i (info): Help. -* I packet: Packets. -* i packet: Packets. -* i/o: Input/Output. -* i386: remote stub. -* i386-stub.c: remote stub. -* IBM1047 character set: Character Sets. -* IDT: DJGPP Native. -* if: Define. -* ignore: Conditions. -* ignore count (of breakpoint): Conditions. -* INCLUDE_RDB: VxWorks. -* info: Help. -* info address: Symbols. -* info all-registers: Registers. -* info args: Frame Info. -* info auxv: Auxiliary Vector. -* info breakpoints: Set Breaks. -* info catch: Frame Info. -* info cisco: KOD. -* info classes: Symbols. -* info display: Auto Display. -* info dll: Cygwin Native. -* info dos: DJGPP Native. -* info extensions: Show. -* info f (info frame): Frame Info. -* info files: Files. -* info float: Floating Point Hardware. -* info frame: Frame Info. -* info frame, show the source language: Show. -* info functions: Symbols. -* info line: Machine Code. -* info line, and Objective-C: Method Names in Commands. -* info locals: Frame Info. -* info macro: Macros. -* info mem: Memory Region Attributes. -* info or1k spr: OpenRISC 1000. -* info proc: SVR4 Process Information. -* info proc mappings: SVR4 Process Information. -* info program: Stopping. -* info registers: Registers. -* info s (info stack): Backtrace. -* info scope: Symbols. -* info selectors: Symbols. -* info set: Help. -* info share: Files. -* info sharedlibrary: Files. -* info signals: Signals. -* info source: Symbols. -* info source, show the source language: Show. -* info sources: Symbols. -* info stack: Backtrace. -* info symbol: Symbols. -* info target: Files. -* info terminal: Input/Output. -* info threads: Threads. -* info tracepoints: Listing Tracepoints. -* info types: Symbols. -* info variables: Symbols. -* info vector: Vector Unit. -* info w32: Cygwin Native. -* info watchpoints: Set Watchpoints. -* info win: TUI Commands. -* information about tracepoints: Listing Tracepoints. -* inheritance: Debugging C plus plus. -* init file: Command Files. -* init file name: Command Files. -* initial frame: Frames. -* initialization file, readline: Readline Init File. -* innermost frame: Frames. -* input syntax for GDB/MI: GDB/MI Input Syntax. -* input-meta: Readline Init File Syntax. -* insert-comment (M-#): Miscellaneous Commands. -* insert-completions (M-*): Commands For Completion. -* inspect: Data. -* installation: Installing GDB. -* instructions, assembly: Machine Code. -* integral datatypes, in file-i/o protocol: Integral datatypes. -* Intel: remote stub. -* Intel disassembly flavor: Machine Code. -* interaction, readline: Readline Interaction. -* internal commands: Maintenance Commands. -* internal GDB breakpoints: Set Breaks. -* interpreter-exec: Interpreters. -* interrupt: Quitting GDB. -* interrupting remote programs: Connecting. -* interrupting remote targets: Bootstrapping. -* invalid input: Bug Criteria. -* invoke another interpreter: Interpreters. -* isatty call, file-i/o protocol: The isatty call. -* isatty, file-i/o system call: isatty. -* isearch-terminators: Readline Init File Syntax. -* ISO 8859-1 character set: Character Sets. -* ISO Latin 1 character set: Character Sets. -* jump: Jumping. -* jump, and Objective-C: Method Names in Commands. -* k packet: Packets. -* kernel object display: KOD. -* keymap: Readline Init File Syntax. -* kill: Kill Process. -* kill ring: Readline Killing Commands. -* kill-line (C-k): Commands For Killing. -* kill-region (): Commands For Killing. -* kill-whole-line (): Commands For Killing. -* kill-word (M-d): Commands For Killing. -* killing text: Readline Killing Commands. -* KOD: KOD. -* l (list): List. -* languages: Languages. -* last tracepoint number: Create and Delete Tracepoints. -* latest breakpoint: Set Breaks. -* layout asm: TUI Commands. -* layout next: TUI Commands. -* layout prev: TUI Commands. -* layout regs: TUI Commands. -* layout split: TUI Commands. -* layout src: TUI Commands. -* LDT: DJGPP Native. -* leaving GDB: Quitting GDB. -* Left: TUI Keys. -* limits, in file-i/o protocol: Limits. -* linespec: List. -* list: List. -* list of supported file-i/o calls: List of supported calls. -* list output in GDB/MI: GDB/MI Output Syntax. -* list, and Objective-C: Method Names in Commands. -* listing GDB's internal symbol tables: Symbols. -* listing machine instructions: Machine Code. -* listing mapped overlays: Overlay Commands. -* load address, overlay's: How Overlays Work. -* load FILENAME: Target Commands. -* local variables: Symbols. -* locate address: Output Formats. -* log output in GDB/MI: GDB/MI Output Syntax. -* logging GDB output: Logging output. -* lseek flags, in file-i/o protocol: Lseek flags. -* lseek, file-i/o system call: lseek. -* M packet: Packets. -* m packet: Packets. -* m680x0: remote stub. -* m68k-stub.c: remote stub. -* machine instructions: Machine Code. -* macro define: Macros. -* macro definition, showing: Macros. -* macro expand: Macros. -* macro expand-once: Macros. -* macro expansion, showing the results of preprocessor: Macros. -* macro undef: Macros. -* macros, example of debugging with: Macros. -* macros, user-defined: Macros. -* maint info breakpoints: Maintenance Commands. -* maint info psymtabs: Symbols. -* maint info sections: Files. -* maint info symtabs: Symbols. -* maint internal-error: Maintenance Commands. -* maint internal-warning: Maintenance Commands. -* maint print cooked-registers: Maintenance Commands. -* maint print dummy-frames: Maintenance Commands. -* maint print psymbols: Symbols. -* maint print raw-registers: Maintenance Commands. -* maint print reggroups: Maintenance Commands. -* maint print register-groups: Maintenance Commands. -* maint print registers: Maintenance Commands. -* maint print symbols: Symbols. -* maint set profile: Maintenance Commands. -* maint show profile: Maintenance Commands. -* maintenance commands: Maintenance Commands. -* make: Shell Commands. -* manual overlay debugging: Overlay Commands. -* map an overlay: Overlay Commands. -* mapped: Files. -* mapped address: How Overlays Work. -* mapped overlays: How Overlays Work. -* mark-modified-lines: Readline Init File Syntax. -* mark-symlinked-directories: Readline Init File Syntax. -* match-hidden-files: Readline Init File Syntax. -* mem: Memory Region Attributes. -* member functions: C plus plus expressions. -* memory models, H8/500: H8/500. -* memory region attributes: Memory Region Attributes. -* memory tracing: Breakpoints. -* memory transfer, in file-i/o protocol: Memory transfer. -* memory, viewing as typed object: Expressions. -* memory-mapped symbol file: Files. -* memset: Bootstrapping. -* menu-complete (): Commands For Completion. -* meta-flag: Readline Init File Syntax. -* mi interpreter: Interpreters. -* mi1 interpreter: Interpreters. -* mi2 interpreter: Interpreters. -* minimal language: Unsupported languages. -* Minimal symbols and DLLs: Non-debug DLL symbols. -* MIPS boards: MIPS Embedded. -* MIPS remote floating point: MIPS Embedded. -* MIPS remotedebug protocol: MIPS Embedded. -* MIPS stack: MIPS. -* mode_t values, in file-i/o protocol: mode_t values. -* Modula-2: Summary. -* Modula-2 built-ins: Built-In Func/Proc. -* Modula-2 checks: M2 Checks. -* Modula-2 constants: Built-In Func/Proc. -* Modula-2 defaults: M2 Defaults. -* Modula-2 operators: M2 Operators. -* Modula-2, deviations from: Deviations. -* Modula-2, GDB support: Modula-2. -* Motorola 680x0: remote stub. -* MS Windows debugging: Cygwin Native. -* MS-DOS system info: DJGPP Native. -* MS-DOS-specific commands: DJGPP Native. -* multiple processes: Processes. -* multiple targets: Active Targets. -* multiple threads: Threads. -* n (next): Continuing and Stepping. -* n (SingleKey TUI key): TUI Single Key Mode. -* names of symbols: Symbols. -* namespace in C++: C plus plus expressions. -* native Cygwin debugging: Cygwin Native. -* native DJGPP debugging: DJGPP Native. -* negative breakpoint numbers: Set Breaks. -* New SYSTAG message: Threads. -* New SYSTAG message, on HP-UX: Threads. -* next: Continuing and Stepping. -* next-history (C-n): Commands For History. -* nexti: Continuing and Stepping. -* ni (nexti): Continuing and Stepping. -* non-incremental-forward-search-history (M-n): Commands For History. -* non-incremental-reverse-search-history (M-p): Commands For History. -* notation, readline: Readline Bare Essentials. -* notational conventions, for GDB/MI: GDB/MI. -* notify output in GDB/MI: GDB/MI Output Syntax. -* number representation: Numbers. -* numbers for breakpoints: Breakpoints. -* object files, relocatable, reading symbols from: Files. -* Objective-C: Objective-C. -* online documentation: Help. -* open flags, in file-i/o protocol: Open flags. -* open, file-i/o system call: open. -* OpenRISC 1000: OpenRISC 1000. -* OpenRISC 1000 htrace: OpenRISC 1000. -* operations allowed on pending breakpoints: Set Breaks. -* optimized code, debugging: Compilation. -* or1k boards: OpenRISC 1000. -* or1ksim: OpenRISC 1000. -* OS ABI: ABI. -* out-of-band records in GDB/MI: GDB/MI Out-of-band Records. -* outermost frame: Frames. -* output: Output. -* output formats: Output Formats. -* output syntax of GDB/MI: GDB/MI Output Syntax. -* output-meta: Readline Init File Syntax. -* overlay area: How Overlays Work. -* overlay auto: Overlay Commands. -* overlay example program: Overlay Sample Program. -* overlay load-target: Overlay Commands. -* overlay manual: Overlay Commands. -* overlay map-overlay: Overlay Commands. -* overlay off: Overlay Commands. -* overlay unmap-overlay: Overlay Commands. -* overlays: Overlays. -* overlays, setting breakpoints in: Overlay Commands. -* overload-choice: Prompting. -* overloaded functions, calling: C plus plus expressions. -* overloaded functions, overload resolution: Debugging C plus plus. -* overloading: Breakpoint Menus. -* overloading in C++: Debugging C plus plus. -* overwrite-mode (): Commands For Text. -* P packet: Packets. -* p packet: Packets. -* packets, reporting on stdout: Debugging Output. -* page tables display (MS-DOS): DJGPP Native. -* page-completions: Readline Init File Syntax. -* partial symbol dump: Symbols. -* partial symbol tables, listing GDB's internal: Symbols. -* Pascal: Summary. -* passcount: Tracepoint Passcounts. -* patching binaries: Patching. -* path: Environment. -* pauses in output: Screen Size. -* pending breakpoints: Set Breaks. -* PgDn: TUI Keys. -* PgUp: TUI Keys. -* physical address from linear address: DJGPP Native. -* pipes: Starting. -* po (print-object): The Print Command with Objective-C. -* pointer values, in file-i/o protocol: Pointer values. -* pointer, finding referent: Print Settings. -* possible-completions (M-?): Commands For Completion. -* post-commands: Prompting. -* post-overload-choice: Prompting. -* post-prompt: Prompting. -* post-prompt-for-continue: Prompting. -* post-query: Prompting. -* pre-commands: Prompting. -* pre-overload-choice: Prompting. -* pre-prompt: Prompting. -* pre-prompt-for-continue: Prompting. -* pre-query: Prompting. -* prefix-meta (<ESC>): Miscellaneous Commands. -* premature return from system calls: Thread Stops. -* preprocessor macro expansion, showing the results of: Macros. -* previous-history (C-p): Commands For History. -* print: Data. -* print an Objective-C object description: The Print Command with Objective-C. -* print settings: Print Settings. -* print-object: The Print Command with Objective-C. -* printf: Output. -* printing data: Data. -* process image: SVR4 Process Information. -* processes, multiple: Processes. -* profiling GDB: Maintenance Commands. -* prompt <1>: Prompting. -* prompt: Prompt. -* prompt-for-continue: Prompting. -* protocol basics, file-i/o: Protocol basics. -* protocol specific representation of datatypes, in file-i/o protocol: Protocol specific representation of datatypes. -* protocol, GDB remote serial: Overview. -* ptype: Symbols. -* putDebugChar: Bootstrapping. -* pwd: Working Directory. -* q (quit): Quitting GDB. -* q (SingleKey TUI key): TUI Single Key Mode. -* Q packet: Packets. -* q packet: Packets. -* query: Prompting. -* quit: Errors. -* quit [EXPRESSION]: Quitting GDB. -* quoted-insert (C-q or C-v): Commands For Text. -* quotes in commands: Completion. -* quoting names: Symbols. -* r (run): Starting. -* r (SingleKey TUI key): TUI Single Key Mode. -* R packet: Packets. -* r packet: Packets. -* raise exceptions: Set Catchpoints. -* range checking: Type Checking. -* ranges of breakpoints: Breakpoints. -* rbreak: Set Breaks. -* re-read-init-file (C-x C-r): Miscellaneous Commands. -* read, file-i/o system call: read. -* reading symbols from relocatable object files: Files. -* reading symbols immediately: Files. -* readline: Editing. -* readnow: Files. -* recent tracepoint number: Create and Delete Tracepoints. -* redirection: Input/Output. -* redraw-current-line (): Commands For Moving. -* reference card: Formatting Documentation. -* reference declarations: C plus plus expressions. -* refresh: TUI Commands. -* register stack, AMD29K: A29K. -* registers: Registers. -* regular expression: Set Breaks. -* reloading symbols: Symbols. -* reloading the overlay table: Overlay Commands. -* relocatable object files, reading symbols from: Files. -* remote connection without stubs: Server. -* remote debugging: Remote. -* remote programs, interrupting: Connecting. -* remote protocol, field separator: Overview. -* remote serial debugging summary: Debug Session. -* remote serial debugging, overview: remote stub. -* remote serial protocol: Overview. -* remote serial stub: Stub Contents. -* remote serial stub list: remote stub. -* remote serial stub, initialization: Stub Contents. -* remote serial stub, main routine: Stub Contents. -* remote stub, example: remote stub. -* remote stub, support routines: Bootstrapping. -* remotedebug, MIPS protocol: MIPS Embedded. -* remotetimeout: Sparclet. -* remove actions from a tracepoint: Tracepoint Actions. -* rename, file-i/o system call: rename. -* Renesas: remote stub. -* Renesas SH download: H8/300. -* repeating command sequences: Command Syntax. -* repeating commands: Command Syntax. -* reporting bugs in GDB: GDB Bugs. -* response time, MIPS debugging: MIPS. -* restore: Dump/Restore Files. -* restore data from a file: Dump/Restore Files. -* result records in GDB/MI: GDB/MI Result Records. -* resuming execution: Continuing and Stepping. -* RET (repeat last command): Command Syntax. -* retransmit-timeout, MIPS protocol: MIPS Embedded. -* return: Returning. -* returning from a function: Returning. -* reverse-search: Search. -* reverse-search-history (C-r): Commands For History. -* revert-line (M-r): Miscellaneous Commands. -* Right: TUI Keys. -* run: Starting. -* running: Starting. -* running and debugging Sparclet programs: Sparclet Execution. -* running VxWorks tasks: VxWorks Attach. -* running, on Sparclet: Sparclet. -* rwatch: Set Watchpoints. -* s (SingleKey TUI key): TUI Single Key Mode. -* s (step): Continuing and Stepping. -* S packet: Packets. -* s packet: Packets. -* save tracepoints for future sessions: save-tracepoints. -* save-tracepoints: save-tracepoints. -* saving symbol table: Files. -* scope: M2 Scope. -* search: Search. -* searching: Search. -* section: Files. -* segment descriptor tables: DJGPP Native. -* select trace snapshot: tfind. -* select-frame: Frames. -* selected frame: Stack. -* selecting frame silently: Frames. -* self-insert (a, b, A, 1, !, ...): Commands For Text. -* separate debugging information files: Separate Debug Files. -* sequence-id, for GDB remote: Overview. -* serial connections, debugging: Debugging Output. -* serial device, Renesas micros: Renesas Boards. -* serial line speed, Renesas micros: Renesas Boards. -* serial line, target remote: Connecting. -* serial protocol, GDB remote: Overview. -* server prefix for annotations: Server Prefix. -* set: Help. -* set args: Arguments. -* set auto-solib-add: Files. -* set auto-solib-limit: Files. -* set backtrace limit: Backtrace. -* set backtrace past-main: Backtrace. -* set breakpoint pending: Set Breaks. -* set charset: Character Sets. -* set check range: Range Checking. -* set check type: Type Checking. -* set check, range: Range Checking. -* set check, type: Type Checking. -* set coerce-float-to-double: ABI. -* set complaints: Messages/Warnings. -* set confirm: Messages/Warnings. -* set cp-abi: ABI. -* set debug arch: Debugging Output. -* set debug event: Debugging Output. -* set debug expression: Debugging Output. -* set debug frame: Debugging Output. -* set debug overload: Debugging Output. -* set debug remote: Debugging Output. -* set debug serial: Debugging Output. -* set debug target: Debugging Output. -* set debug varobj: Debugging Output. -* set debug-file-directory: Separate Debug Files. -* set debugevents: Cygwin Native. -* set debugexceptions: Cygwin Native. -* set debugexec: Cygwin Native. -* set debugmemory: Cygwin Native. -* set demangle-style: Print Settings. -* set disassembly-flavor: Machine Code. -* set editing: Editing. -* set endian auto: Byte Order. -* set endian big: Byte Order. -* set endian little: Byte Order. -* set environment: Environment. -* set extension-language: Show. -* set follow-fork-mode: Processes. -* set gnutarget: Target Commands. -* set height: Screen Size. -* set history expansion: History. -* set history filename: History. -* set history save: History. -* set history size: History. -* set host-charset: Character Sets. -* set input-radix: Numbers. -* set language: Manually. -* set listsize: List. -* set logging: Logging output. -* set machine: Renesas Special. -* set max-user-call-depth: Define. -* set memory MOD: H8/500. -* set mipsfpu: MIPS Embedded. -* set new-console: Cygwin Native. -* set new-group: Cygwin Native. -* set opaque-type-resolution: Symbols. -* set os: KOD. -* set osabi: ABI. -* set output-radix: Numbers. -* set overload-resolution: Debugging C plus plus. -* set print address: Print Settings. -* set print array: Print Settings. -* set print asm-demangle: Print Settings. -* set print demangle: Print Settings. -* set print elements: Print Settings. -* set print max-symbolic-offset: Print Settings. -* set print null-stop: Print Settings. -* set print object: Print Settings. -* set print pretty: Print Settings. -* set print sevenbit-strings: Print Settings. -* set print static-members: Print Settings. -* set print symbol-filename: Print Settings. -* set print union: Print Settings. -* set print vtbl: Print Settings. -* set processor ARGS: MIPS Embedded. -* set prompt: Prompt. -* set remote hardware-breakpoint-limit: Remote configuration. -* set remote hardware-watchpoint-limit: Remote configuration. -* set remote system-call-allowed 0: The system call. -* set remote system-call-allowed 1: The system call. -* set remotedebug, MIPS protocol: MIPS Embedded. -* set retransmit-timeout: MIPS Embedded. -* set rstack_high_address: A29K. -* set shell: Cygwin Native. -* set solib-absolute-prefix: Files. -* set solib-search-path: Files. -* set step-mode: Continuing and Stepping. -* set symbol-reloading: Symbols. -* set target-charset: Character Sets. -* set timeout: MIPS Embedded. -* set tracepoint: Create and Delete Tracepoints. -* set trust-readonly-sections: Files. -* set tui active-border-mode: TUI Configuration. -* set tui border-kind: TUI Configuration. -* set tui border-mode: TUI Configuration. -* set variable: Assignment. -* set verbose: Messages/Warnings. -* set width: Screen Size. -* set write: Patching. -* set-mark (C-@): Miscellaneous Commands. -* set_debug_traps: Stub Contents. -* setting variables: Assignment. -* setting watchpoints: Set Watchpoints. -* SH: remote stub. -* sh-stub.c: remote stub. -* share: Files. -* shared libraries: Files. -* sharedlibrary: Files. -* shell: Shell Commands. -* shell escape: Shell Commands. -* show: Help. -* show args: Arguments. -* show auto-solib-add: Files. -* show auto-solib-limit: Files. -* show backtrace limit: Backtrace. -* show backtrace past-main: Backtrace. -* show breakpoint pending: Set Breaks. -* show charset: Character Sets. -* show check range: Range Checking. -* show check type: Type Checking. -* show complaints: Messages/Warnings. -* show confirm: Messages/Warnings. -* show convenience: Convenience Vars. -* show copying: Help. -* show cp-abi: ABI. -* show debug arch: Debugging Output. -* show debug event: Debugging Output. -* show debug expression: Debugging Output. -* show debug frame: Debugging Output. -* show debug overload: Debugging Output. -* show debug remote: Debugging Output. -* show debug serial: Debugging Output. -* show debug target: Debugging Output. -* show debug varobj: Debugging Output. -* show debug-file-directory: Separate Debug Files. -* show demangle-style: Print Settings. -* show directories: Source Path. -* show editing: Editing. -* show environment: Environment. -* show gnutarget: Target Commands. -* show height: Screen Size. -* show history: History. -* show host-charset: Character Sets. -* show input-radix: Numbers. -* show language: Show. -* show listsize: List. -* show logging: Logging output. -* show machine: Renesas Special. -* show max-user-call-depth: Define. -* show mipsfpu: MIPS Embedded. -* show new-console: Cygwin Native. -* show new-group: Cygwin Native. -* show opaque-type-resolution: Symbols. -* show os: KOD. -* show osabi: ABI. -* show output-radix: Numbers. -* show paths: Environment. -* show print address: Print Settings. -* show print array: Print Settings. -* show print asm-demangle: Print Settings. -* show print demangle: Print Settings. -* show print elements: Print Settings. -* show print max-symbolic-offset: Print Settings. -* show print object: Print Settings. -* show print pretty: Print Settings. -* show print sevenbit-strings: Print Settings. -* show print static-members: Print Settings. -* show print symbol-filename: Print Settings. -* show print union: Print Settings. -* show print vtbl: Print Settings. -* show processor: MIPS Embedded. -* show prompt: Prompt. -* show remote system-call-allowed: The system call. -* show remotedebug, MIPS protocol: MIPS Embedded. -* show retransmit-timeout: MIPS Embedded. -* show rstack_high_address: A29K. -* show shell: Cygwin Native. -* show solib-absolute-prefix: Files. -* show solib-search-path: Files. -* show symbol-reloading: Symbols. -* show target-charset: Character Sets. -* show timeout: MIPS Embedded. -* show user: Define. -* show values: Value History. -* show verbose: Messages/Warnings. -* show version: Help. -* show warranty: Help. -* show width: Screen Size. -* show write: Patching. -* show-all-if-ambiguous: Readline Init File Syntax. -* shows: History. -* si (stepi): Continuing and Stepping. -* signal <1>: Annotations for Running. -* signal: Signaling. -* signal-name: Annotations for Running. -* signal-name-end: Annotations for Running. -* signal-string: Annotations for Running. -* signal-string-end: Annotations for Running. -* signalled: Annotations for Running. -* signals: Signals. -* silent: Break Commands. -* sim: Z8000. -* simulator, Z8000: Z8000. -* size of screen: Screen Size. -* software watchpoints: Set Watchpoints. -* source <1>: Source Annotations. -* source: Command Files. -* source path: Source Path. -* Sparc: remote stub. -* sparc-stub.c: remote stub. -* sparcl-stub.c: remote stub. -* Sparclet: Sparclet. -* SparcLite: remote stub. -* speed: Renesas Boards. -* spr: OpenRISC 1000. -* ST2000 auxiliary commands: ST2000. -* st2000 CMD: ST2000. -* stack frame: Frames. -* stack on Alpha: MIPS. -* stack on MIPS: MIPS. -* stack traces: Backtrace. -* stacking targets: Active Targets. -* start a new trace experiment: Starting and Stopping Trace Experiment. -* start-kbd-macro (C-x (): Keyboard Macros. -* starting <1>: Annotations for Running. -* starting: Starting. -* stat, file-i/o system call: stat/fstat. -* status of trace data collection: Starting and Stopping Trace Experiment. -* status output in GDB/MI: GDB/MI Output Syntax. -* STDBUG commands (ST2000): ST2000. -* step: Continuing and Stepping. -* stepi: Continuing and Stepping. -* stepping: Continuing and Stepping. -* stepping into functions with no line info: Continuing and Stepping. -* stop a running trace experiment: Starting and Stopping Trace Experiment. -* stop reply packets: Stop Reply Packets. -* stop, a pseudo-command: Hooks. -* stopped threads: Thread Stops. -* stopping: Annotations for Running. -* stream records in GDB/MI: GDB/MI Stream Records. -* struct stat, in file-i/o protocol: struct stat. -* struct timeval, in file-i/o protocol: struct timeval. -* stub example, remote debugging: remote stub. -* stupid questions: Messages/Warnings. -* switching threads: Threads. -* switching threads automatically: Threads. -* symbol decoding style, C++: Print Settings. -* symbol dump: Symbols. -* symbol from address: Symbols. -* symbol names: Symbols. -* symbol overloading: Breakpoint Menus. -* symbol table: Files. -* symbol tables, listing GDB's internal: Symbols. -* symbol-file: Files. -* symbols, reading from relocatable object files: Files. -* symbols, reading immediately: Files. -* sysinfo: DJGPP Native. -* system call, file-i/o protocol: The system call. -* system calls and thread breakpoints: Thread Stops. -* system, file-i/o system call: system. -* T packet: Packets. -* t packet: Packets. -* T packet reply: Stop Reply Packets. -* target: Targets. -* target abug: M68K. -* target array: MIPS Embedded. -* target byte order: Byte Order. -* target character set: Character Sets. -* target core: Target Commands. -* target cpu32bug: M68K. -* target dbug: M68K. -* target ddb PORT: MIPS Embedded. -* target dink32: PowerPC. -* target e7000, with H8/300: H8/300. -* target e7000, with Renesas ICE: Renesas ICE. -* target e7000, with Renesas SH: SH. -* target est: M68K. -* target exec: Target Commands. -* target hms, and serial protocol: Renesas Boards. -* target hms, with H8/300: H8/300. -* target hms, with Renesas SH: SH. -* target jtag: OpenRISC 1000. -* target lsi PORT: MIPS Embedded. -* target m32r: M32R/D. -* target m32rsdi: M32R/D. -* target mips PORT: MIPS Embedded. -* target nrom: Target Commands. -* target op50n: PA. -* target output in GDB/MI: GDB/MI Output Syntax. -* target pmon PORT: MIPS Embedded. -* target ppcbug: PowerPC. -* target ppcbug1: PowerPC. -* target r3900: MIPS Embedded. -* target rdi: ARM. -* target rdp: ARM. -* target remote: Target Commands. -* target rom68k: M68K. -* target rombug: M68K. -* target sds: PowerPC. -* target sh3, with H8/300: H8/300. -* target sh3, with SH: SH. -* target sh3e, with H8/300: H8/300. -* target sh3e, with SH: SH. -* target sim: Target Commands. -* target sim, with Z8000: Z8000. -* target sparclite: Sparclite. -* target vxworks: VxWorks. -* target w89k: PA. -* tbreak: Set Breaks. -* TCP port, target remote: Connecting. -* tdump: tdump. -* terminal: Input/Output. -* Text User Interface: TUI. -* tfind: tfind. -* thbreak: Set Breaks. -* this, inside C++ member functions: C plus plus expressions. -* thread apply: Threads. -* thread breakpoints: Thread Stops. -* thread breakpoints and system calls: Thread Stops. -* thread identifier (GDB): Threads. -* thread identifier (system): Threads. -* thread identifier (system), on HP-UX: Threads. -* thread number: Threads. -* thread THREADNO: Threads. -* threads and watchpoints: Set Watchpoints. -* threads of execution: Threads. -* threads, automatic switching: Threads. -* threads, continuing: Thread Stops. -* threads, stopped: Thread Stops. -* timeout, MIPS protocol: MIPS Embedded. -* trace: Create and Delete Tracepoints. -* trace experiment, status of: Starting and Stopping Trace Experiment. -* tracebacks: Backtrace. -* tracepoint actions: Tracepoint Actions. -* tracepoint data, display: tdump. -* tracepoint deletion: Create and Delete Tracepoints. -* tracepoint number: Create and Delete Tracepoints. -* tracepoint pass count: Tracepoint Passcounts. -* tracepoint variables: Tracepoint Variables. -* tracepoints: Tracepoints. -* translating between character sets: Character Sets. -* transpose-chars (C-t): Commands For Text. -* transpose-words (M-t): Commands For Text. -* tstart: Starting and Stopping Trace Experiment. -* tstatus: Starting and Stopping Trace Experiment. -* tstop: Starting and Stopping Trace Experiment. -* tty: Input/Output. -* TUI: TUI. -* TUI commands: TUI Commands. -* TUI configuration variables: TUI Configuration. -* TUI key bindings: TUI Keys. -* tui reg: TUI Commands. -* TUI single key mode: TUI Single Key Mode. -* type casting memory: Expressions. -* type checking: Checks. -* type conversions in C++: C plus plus expressions. -* u (SingleKey TUI key): TUI Single Key Mode. -* u (until): Continuing and Stepping. -* UDP port, target remote: Connecting. -* undisplay: Auto Display. -* undo (C-_ or C-x C-u): Miscellaneous Commands. -* universal-argument (): Numeric Arguments. -* unix-line-discard (C-u): Commands For Killing. -* unix-word-rubout (C-w): Commands For Killing. -* unknown address, locating: Output Formats. -* unlink, file-i/o system call: unlink. -* unmap an overlay: Overlay Commands. -* unmapped overlays: How Overlays Work. -* unset environment: Environment. -* unsupported languages: Unsupported languages. -* until: Continuing and Stepping. -* Up: TUI Keys. -* up: Selection. -* up-silently: Selection. -* upcase-word (M-u): Commands For Text. -* update: TUI Commands. -* user-defined command: Define. -* user-defined macros: Macros. -* v (SingleKey TUI key): TUI Single Key Mode. -* value history: Value History. -* variable name conflict: Variables. -* variable objects in GDB/MI: GDB/MI Variable Objects. -* variable values, wrong: Variables. -* variables, readline: Readline Init File Syntax. -* variables, setting: Assignment. -* vCont packet: Packets. -* vCont? packet: Packets. -* vector unit: Vector Unit. -* vector, auxiliary: Auxiliary Vector. -* version number: Help. -* visible-stats: Readline Init File Syntax. -* VxWorks: VxWorks. -* vxworks-timeout: VxWorks. -* w (SingleKey TUI key): TUI Single Key Mode. -* watch: Set Watchpoints. -* watchpoint: Annotations for Running. -* watchpoints: Breakpoints. -* watchpoints and threads: Set Watchpoints. -* whatis: Symbols. -* where: Backtrace. -* while: Define. -* while-stepping (tracepoints): Tracepoint Actions. -* wild pointer, interpreting: Print Settings. -* winheight: TUI Commands. -* word completion: Completion. -* working directory: Source Path. -* working directory (of your program): Working Directory. -* working language: Languages. -* write, file-i/o system call: write. -* writing into corefiles: Patching. -* writing into executables: Patching. -* wrong values: Variables. -* x (examine memory): Memory. -* X packet: Packets. -* x(examine), and info line: Machine Code. -* yank (C-y): Commands For Killing. -* yank-last-arg (M-. or M-_): Commands For History. -* yank-nth-arg (M-C-y): Commands For History. -* yank-pop (M-y): Commands For Killing. -* yanking text: Readline Killing Commands. -* z packet: Packets. -* Z packets: Packets. -* Z0 packet: Packets. -* z0 packet: Packets. -* Z1 packet: Packets. -* z1 packet: Packets. -* Z2 packet: Packets. -* z2 packet: Packets. -* Z3 packet: Packets. -* z3 packet: Packets. -* Z4 packet: Packets. -* z4 packet: Packets. -* Z8000: Z8000. -* Zilog Z8000 simulator: Z8000. -* {TYPE}: Expressions. - - diff --git a/contrib/gdb/gdb/doc/gdb.texinfo b/contrib/gdb/gdb/doc/gdb.texinfo deleted file mode 100644 index 772d1ebf128e..000000000000 --- a/contrib/gdb/gdb/doc/gdb.texinfo +++ /dev/null @@ -1,21780 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -@c 1999, 2000, 2001, 2002, 2003, 2004 -@c Free Software Foundation, Inc. -@c -@c %**start of header -@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use -@c of @set vars. However, you can override filename with makeinfo -o. -@setfilename gdb.info -@c -@include gdb-cfg.texi -@c -@settitle Debugging with @value{GDBN} -@setchapternewpage odd -@c %**end of header - -@iftex -@c @smallbook -@c @cropmarks -@end iftex - -@finalout -@syncodeindex ky cp - -@c readline appendices use @vindex, @findex and @ftable, -@c annotate.texi and gdbmi use @findex. -@syncodeindex vr cp -@syncodeindex fn cp - -@c !!set GDB manual's edition---not the same as GDB version! -@c This is updated by GNU Press. -@set EDITION Ninth - -@c !!set GDB edit command default editor -@set EDITOR /bin/ex - -@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER. - -@c This is a dir.info fragment to support semi-automated addition of -@c manuals to an info tree. -@dircategory Software development -@direntry -* Gdb: (gdb). The GNU debugger. -@end direntry - -@ifinfo -This file documents the @sc{gnu} debugger @value{GDBN}. - - -This is the @value{EDITION} Edition, of @cite{Debugging with -@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} -Version @value{GDBVN}. - -Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@* - 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``Free Software'' and ``Free Software Needs -Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. - -(a) The Free Software Foundation's Back-Cover Text is: ``You have -freedom to copy and modify this GNU Manual, like GNU software. Copies -published by the Free Software Foundation raise funds for GNU -development.'' -@end ifinfo - -@titlepage -@title Debugging with @value{GDBN} -@subtitle The @sc{gnu} Source-Level Debugger -@sp 1 -@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} -@author Richard Stallman, Roland Pesch, Stan Shebs, et al. -@page -@tex -{\parskip=0pt -\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par -\hfill {\it Debugging with @value{GDBN}}\par -\hfill \TeX{}info \texinfoversion\par -} -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, -1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. -@sp 2 -Published by the Free Software Foundation @* -59 Temple Place - Suite 330, @* -Boston, MA 02111-1307 USA @* -ISBN 1-882114-77-9 @* - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``Free Software'' and ``Free Software Needs -Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. - -(a) The Free Software Foundation's Back-Cover Text is: ``You have -freedom to copy and modify this GNU Manual, like GNU software. Copies -published by the Free Software Foundation raise funds for GNU -development.'' -@end titlepage -@page - -@ifnottex -@node Top, Summary, (dir), (dir) - -@top Debugging with @value{GDBN} - -This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. - -This is the @value{EDITION} Edition, for @value{GDBN} Version -@value{GDBVN}. - -Copyright (C) 1988-2004 Free Software Foundation, Inc. - -@menu -* Summary:: Summary of @value{GDBN} -* Sample Session:: A sample @value{GDBN} session - -* Invocation:: Getting in and out of @value{GDBN} -* Commands:: @value{GDBN} commands -* Running:: Running programs under @value{GDBN} -* Stopping:: Stopping and continuing -* Stack:: Examining the stack -* Source:: Examining source files -* Data:: Examining data -* Macros:: Preprocessor Macros -* Tracepoints:: Debugging remote targets non-intrusively -* Overlays:: Debugging programs that use overlays - -* Languages:: Using @value{GDBN} with different languages - -* Symbols:: Examining the symbol table -* Altering:: Altering execution -* GDB Files:: @value{GDBN} files -* Targets:: Specifying a debugging target -* Remote Debugging:: Debugging remote programs -* Configurations:: Configuration-specific information -* Controlling GDB:: Controlling @value{GDBN} -* Sequences:: Canned sequences of commands -* TUI:: @value{GDBN} Text User Interface -* Interpreters:: Command Interpreters -* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs -* Annotations:: @value{GDBN}'s annotation interface. -* GDB/MI:: @value{GDBN}'s Machine Interface. - -* GDB Bugs:: Reporting bugs in @value{GDBN} -* Formatting Documentation:: How to format and print @value{GDBN} documentation - -* Command Line Editing:: Command Line Editing -* Using History Interactively:: Using History Interactively -* Installing GDB:: Installing GDB -* Maintenance Commands:: Maintenance Commands -* Remote Protocol:: GDB Remote Serial Protocol -* Agent Expressions:: The GDB Agent Expression Mechanism -* Copying:: GNU General Public License says - how you can copy and share GDB -* GNU Free Documentation License:: The license for this documentation -* Index:: Index -@end menu - -@end ifnottex - -@contents - -@node Summary -@unnumbered Summary of @value{GDBN} - -The purpose of a debugger such as @value{GDBN} is to allow you to see what is -going on ``inside'' another program while it executes---or what another -program was doing at the moment it crashed. - -@value{GDBN} can do four main kinds of things (plus other things in support of -these) to help you catch bugs in the act: - -@itemize @bullet -@item -Start your program, specifying anything that might affect its behavior. - -@item -Make your program stop on specified conditions. - -@item -Examine what has happened, when your program has stopped. - -@item -Change things in your program, so you can experiment with correcting the -effects of one bug and go on to learn about another. -@end itemize - -You can use @value{GDBN} to debug programs written in C and C@t{++}. -For more information, see @ref{Support,,Supported languages}. -For more information, see @ref{C,,C and C++}. - -@cindex Modula-2 -Support for Modula-2 is partial. For information on Modula-2, see -@ref{Modula-2,,Modula-2}. - -@cindex Pascal -Debugging Pascal programs which use sets, subranges, file variables, or -nested functions does not currently work. @value{GDBN} does not support -entering expressions, printing values, or similar features using Pascal -syntax. - -@cindex Fortran -@value{GDBN} can be used to debug programs written in Fortran, although -it may be necessary to refer to some variables with a trailing -underscore. - -@value{GDBN} can be used to debug programs written in Objective-C, -using either the Apple/NeXT or the GNU Objective-C runtime. - -@menu -* Free Software:: Freely redistributable software -* Contributors:: Contributors to GDB -@end menu - -@node Free Software -@unnumberedsec Free software - -@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} -General Public License -(GPL). The GPL gives you the freedom to copy or adapt a licensed -program---but every person getting a copy also gets with it the -freedom to modify that copy (which means that they must get access to -the source code), and the freedom to distribute further copies. -Typical software companies use copyrights to limit your freedoms; the -Free Software Foundation uses the GPL to preserve these freedoms. - -Fundamentally, the General Public License is a license which says that -you have these freedoms and that you cannot take these freedoms away -from anyone else. - -@unnumberedsec Free Software Needs Free Documentation - -The biggest deficiency in the free software community today is not in -the software---it is the lack of good free documentation that we can -include with the free software. Many of our most important -programs do not come with free reference manuals and free introductory -texts. Documentation is an essential part of any software package; -when an important free software package does not come with a free -manual and a free tutorial, that is a major gap. We have many such -gaps today. - -Consider Perl, for instance. The tutorial manuals that people -normally use are non-free. How did this come about? Because the -authors of those manuals published them with restrictive terms---no -copying, no modification, source files not available---which exclude -them from the free software world. - -That wasn't the first time this sort of thing happened, and it was far -from the last. Many times we have heard a GNU user eagerly describe a -manual that he is writing, his intended contribution to the community, -only to learn that he had ruined everything by signing a publication -contract to make it non-free. - -Free documentation, like free software, is a matter of freedom, not -price. The problem with the non-free manual is not that publishers -charge a price for printed copies---that in itself is fine. (The Free -Software Foundation sells printed copies of manuals, too.) The -problem is the restrictions on the use of the manual. Free manuals -are available in source code form, and give you permission to copy and -modify. Non-free manuals do not allow this. - -The criteria of freedom for a free manual are roughly the same as for -free software. Redistribution (including the normal kinds of -commercial redistribution) must be permitted, so that the manual can -accompany every copy of the program, both on-line and on paper. - -Permission for modification of the technical content is crucial too. -When people modify the software, adding or changing features, if they -are conscientious they will change the manual too---so they can -provide accurate and clear documentation for the modified program. A -manual that leaves you no choice but to write a new manual to document -a changed version of the program is not really available to our -community. - -Some kinds of limits on the way modification is handled are -acceptable. For example, requirements to preserve the original -author's copyright notice, the distribution terms, or the list of -authors, are ok. It is also no problem to require modified versions -to include notice that they were modified. Even entire sections that -may not be deleted or changed are acceptable, as long as they deal -with nontechnical topics (like this one). These kinds of restrictions -are acceptable because they don't obstruct the community's normal use -of the manual. - -However, it must be possible to modify all the @emph{technical} -content of the manual, and then distribute the result in all the usual -media, through all the usual channels. Otherwise, the restrictions -obstruct the use of the manual, it is not free, and we need another -manual to replace it. - -Please spread the word about this issue. Our community continues to -lose manuals to proprietary publishing. If we spread the word that -free software needs free reference manuals and free tutorials, perhaps -the next person who wants to contribute by writing documentation will -realize, before it is too late, that only free manuals contribute to -the free software community. - -If you are writing documentation, please insist on publishing it under -the GNU Free Documentation License or another free documentation -license. Remember that this decision requires your approval---you -don't have to let the publisher decide. Some commercial publishers -will use a free license if you insist, but they will not propose the -option; it is up to you to raise the issue and say firmly that this is -what you want. If the publisher you are dealing with refuses, please -try other publishers. If you're not sure whether a proposed license -is free, write to @email{licensing@@gnu.org}. - -You can encourage commercial publishers to sell more free, copylefted -manuals and tutorials by buying them, and particularly by buying -copies from the publishers that paid for their writing or for major -improvements. Meanwhile, try to avoid buying non-free documentation -at all. Check the distribution terms of a manual before you buy it, -and insist that whoever seeks your business must respect your freedom. -Check the history of the book, and try to reward the publishers that -have paid or pay the authors to work on it. - -The Free Software Foundation maintains a list of free documentation -published by other publishers, at -@url{http://www.fsf.org/doc/other-free-books.html}. - -@node Contributors -@unnumberedsec Contributors to @value{GDBN} - -Richard Stallman was the original author of @value{GDBN}, and of many -other @sc{gnu} programs. Many others have contributed to its -development. This section attempts to credit major contributors. One -of the virtues of free software is that everyone is free to contribute -to it; with regret, we cannot actually acknowledge everyone here. The -file @file{ChangeLog} in the @value{GDBN} distribution approximates a -blow-by-blow account. - -Changes much prior to version 2.0 are lost in the mists of time. - -@quotation -@emph{Plea:} Additions to this section are particularly welcome. If you -or your friends (or enemies, to be evenhanded) have been unfairly -omitted from this list, we would like to add your names! -@end quotation - -So that they may not regard their many labors as thankless, we -particularly thank those who shepherded @value{GDBN} through major -releases: -Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); -Jim Blandy (release 4.18); -Jason Molenda (release 4.17); -Stan Shebs (release 4.14); -Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); -Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); -John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); -Jim Kingdon (releases 3.5, 3.4, and 3.3); -and Randy Smith (releases 3.2, 3.1, and 3.0). - -Richard Stallman, assisted at various times by Peter TerMaat, Chris -Hanson, and Richard Mlynarik, handled releases through 2.8. - -Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support -in @value{GDBN}, with significant additional contributions from Per -Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} -demangler. Early work on C@t{++} was by Peter TerMaat (who also did -much general update work leading to release 3.0). - -@value{GDBN} uses the BFD subroutine library to examine multiple -object-file formats; BFD was a joint project of David V. -Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. - -David Johnson wrote the original COFF support; Pace Willison did -the original support for encapsulated COFF. - -Brent Benson of Harris Computer Systems contributed DWARF 2 support. - -Adam de Boor and Bradley Davis contributed the ISI Optimum V support. -Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS -support. -Jean-Daniel Fekete contributed Sun 386i support. -Chris Hanson improved the HP9000 support. -Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. -David Johnson contributed Encore Umax support. -Jyrki Kuoppala contributed Altos 3068 support. -Jeff Law contributed HP PA and SOM support. -Keith Packard contributed NS32K support. -Doug Rabson contributed Acorn Risc Machine support. -Bob Rusk contributed Harris Nighthawk CX-UX support. -Chris Smith contributed Convex support (and Fortran debugging). -Jonathan Stone contributed Pyramid support. -Michael Tiemann contributed SPARC support. -Tim Tucker contributed support for the Gould NP1 and Gould Powernode. -Pace Willison contributed Intel 386 support. -Jay Vosburgh contributed Symmetry support. -Marko Mlinar contributed OpenRISC 1000 support. - -Andreas Schwab contributed M68K @sc{gnu}/Linux support. - -Rich Schaefer and Peter Schauer helped with support of SunOS shared -libraries. - -Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree -about several machine instruction sets. - -Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop -remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM -contributed remote debugging modules for the i960, VxWorks, A29K UDI, -and RDI targets, respectively. - -Brian Fox is the author of the readline libraries providing -command-line editing and command history. - -Andrew Beers of SUNY Buffalo wrote the language-switching code, the -Modula-2 support, and contributed the Languages chapter of this manual. - -Fred Fish wrote most of the support for Unix System Vr4. -He also enhanced the command-completion support to cover C@t{++} overloaded -symbols. - -Hitachi America (now Renesas America), Ltd. sponsored the support for -H8/300, H8/500, and Super-H processors. - -NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. - -Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D -processors. - -Toshiba sponsored the support for the TX39 Mips processor. - -Matsushita sponsored the support for the MN10200 and MN10300 processors. - -Fujitsu sponsored the support for SPARClite and FR30 processors. - -Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware -watchpoints. - -Michael Snyder added support for tracepoints. - -Stu Grossman wrote gdbserver. - -Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made -nearly innumerable bug fixes and cleanups throughout @value{GDBN}. - -The following people at the Hewlett-Packard Company contributed -support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 -(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} -compiler, and the Text User Interface (nee Terminal User Interface): -Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, -Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase -provided HP-specific information in this manual. - -DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. -Robert Hoehne made significant contributions to the DJGPP port. - -Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its -development since 1991. Cygnus engineers who have worked on @value{GDBN} -fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin -Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim -Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, -Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek -Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In -addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, -JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug -Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff -Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, -Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin -Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela -Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David -Zuhn have made contributions both large and small. - -Jim Blandy added support for preprocessor macros, while working for Red -Hat. - -@node Sample Session -@chapter A Sample @value{GDBN} Session - -You can use this manual at your leisure to read all about @value{GDBN}. -However, a handful of commands are enough to get started using the -debugger. This chapter illustrates those commands. - -@iftex -In this sample session, we emphasize user input like this: @b{input}, -to make it easier to pick out from the surrounding output. -@end iftex - -@c FIXME: this example may not be appropriate for some configs, where -@c FIXME...primary interest is in remote use. - -One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro -processor) exhibits the following bug: sometimes, when we change its -quote strings from the default, the commands used to capture one macro -definition within another stop working. In the following short @code{m4} -session, we define a macro @code{foo} which expands to @code{0000}; we -then use the @code{m4} built-in @code{defn} to define @code{bar} as the -same thing. However, when we change the open quote string to -@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same -procedure fails to define a new synonym @code{baz}: - -@smallexample -$ @b{cd gnu/m4} -$ @b{./m4} -@b{define(foo,0000)} - -@b{foo} -0000 -@b{define(bar,defn(`foo'))} - -@b{bar} -0000 -@b{changequote(<QUOTE>,<UNQUOTE>)} - -@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} -@b{baz} -@b{C-d} -m4: End of input: 0: fatal error: EOF in string -@end smallexample - -@noindent -Let us use @value{GDBN} to try to see what is going on. - -@smallexample -$ @b{@value{GDBP} m4} -@c FIXME: this falsifies the exact text played out, to permit smallbook -@c FIXME... format to come out better. -@value{GDBN} is free software and you are welcome to distribute copies - of it under certain conditions; type "show copying" to see - the conditions. -There is absolutely no warranty for @value{GDBN}; type "show warranty" - for details. - -@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... -(@value{GDBP}) -@end smallexample - -@noindent -@value{GDBN} reads only enough symbol data to know where to find the -rest when needed; as a result, the first prompt comes up very quickly. -We now tell @value{GDBN} to use a narrower display width than usual, so -that examples fit in this manual. - -@smallexample -(@value{GDBP}) @b{set width 70} -@end smallexample - -@noindent -We need to see how the @code{m4} built-in @code{changequote} works. -Having looked at the source, we know the relevant subroutine is -@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN} -@code{break} command. - -@smallexample -(@value{GDBP}) @b{break m4_changequote} -Breakpoint 1 at 0x62f4: file builtin.c, line 879. -@end smallexample - -@noindent -Using the @code{run} command, we start @code{m4} running under @value{GDBN} -control; as long as control does not reach the @code{m4_changequote} -subroutine, the program runs as usual: - -@smallexample -(@value{GDBP}) @b{run} -Starting program: /work/Editorial/gdb/gnu/m4/m4 -@b{define(foo,0000)} - -@b{foo} -0000 -@end smallexample - -@noindent -To trigger the breakpoint, we call @code{changequote}. @value{GDBN} -suspends execution of @code{m4}, displaying information about the -context where it stops. - -@smallexample -@b{changequote(<QUOTE>,<UNQUOTE>)} - -Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) - at builtin.c:879 -879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) -@end smallexample - -@noindent -Now we use the command @code{n} (@code{next}) to advance execution to -the next line of the current function. - -@smallexample -(@value{GDBP}) @b{n} -882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ - : nil, -@end smallexample - -@noindent -@code{set_quotes} looks like a promising subroutine. We can go into it -by using the command @code{s} (@code{step}) instead of @code{next}. -@code{step} goes to the next line to be executed in @emph{any} -subroutine, so it steps into @code{set_quotes}. - -@smallexample -(@value{GDBP}) @b{s} -set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") - at input.c:530 -530 if (lquote != def_lquote) -@end smallexample - -@noindent -The display that shows the subroutine where @code{m4} is now -suspended (and its arguments) is called a stack frame display. It -shows a summary of the stack. We can use the @code{backtrace} -command (which can also be spelled @code{bt}), to see where we are -in the stack as a whole: the @code{backtrace} command displays a -stack frame for each active subroutine. - -@smallexample -(@value{GDBP}) @b{bt} -#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") - at input.c:530 -#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) - at builtin.c:882 -#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 -#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) - at macro.c:71 -#4 0x79dc in expand_input () at macro.c:40 -#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 -@end smallexample - -@noindent -We step through a few more lines to see what happens. The first two -times, we can use @samp{s}; the next two times we use @code{n} to avoid -falling into the @code{xstrdup} subroutine. - -@smallexample -(@value{GDBP}) @b{s} -0x3b5c 532 if (rquote != def_rquote) -(@value{GDBP}) @b{s} -0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ -def_lquote : xstrdup(lq); -(@value{GDBP}) @b{n} -536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ - : xstrdup(rq); -(@value{GDBP}) @b{n} -538 len_lquote = strlen(rquote); -@end smallexample - -@noindent -The last line displayed looks a little odd; we can examine the variables -@code{lquote} and @code{rquote} to see if they are in fact the new left -and right quotes we specified. We use the command @code{p} -(@code{print}) to see their values. - -@smallexample -(@value{GDBP}) @b{p lquote} -$1 = 0x35d40 "<QUOTE>" -(@value{GDBP}) @b{p rquote} -$2 = 0x35d50 "<UNQUOTE>" -@end smallexample - -@noindent -@code{lquote} and @code{rquote} are indeed the new left and right quotes. -To look at some context, we can display ten lines of source -surrounding the current line with the @code{l} (@code{list}) command. - -@smallexample -(@value{GDBP}) @b{l} -533 xfree(rquote); -534 -535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ - : xstrdup (lq); -536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ - : xstrdup (rq); -537 -538 len_lquote = strlen(rquote); -539 len_rquote = strlen(lquote); -540 @} -541 -542 void -@end smallexample - -@noindent -Let us step past the two lines that set @code{len_lquote} and -@code{len_rquote}, and then examine the values of those variables. - -@smallexample -(@value{GDBP}) @b{n} -539 len_rquote = strlen(lquote); -(@value{GDBP}) @b{n} -540 @} -(@value{GDBP}) @b{p len_lquote} -$3 = 9 -(@value{GDBP}) @b{p len_rquote} -$4 = 7 -@end smallexample - -@noindent -That certainly looks wrong, assuming @code{len_lquote} and -@code{len_rquote} are meant to be the lengths of @code{lquote} and -@code{rquote} respectively. We can set them to better values using -the @code{p} command, since it can print the value of -any expression---and that expression can include subroutine calls and -assignments. - -@smallexample -(@value{GDBP}) @b{p len_lquote=strlen(lquote)} -$5 = 7 -(@value{GDBP}) @b{p len_rquote=strlen(rquote)} -$6 = 9 -@end smallexample - -@noindent -Is that enough to fix the problem of using the new quotes with the -@code{m4} built-in @code{defn}? We can allow @code{m4} to continue -executing with the @code{c} (@code{continue}) command, and then try the -example that caused trouble initially: - -@smallexample -(@value{GDBP}) @b{c} -Continuing. - -@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))} - -baz -0000 -@end smallexample - -@noindent -Success! The new quotes now work just as well as the default ones. The -problem seems to have been just the two typos defining the wrong -lengths. We allow @code{m4} exit by giving it an EOF as input: - -@smallexample -@b{C-d} -Program exited normally. -@end smallexample - -@noindent -The message @samp{Program exited normally.} is from @value{GDBN}; it -indicates @code{m4} has finished executing. We can end our @value{GDBN} -session with the @value{GDBN} @code{quit} command. - -@smallexample -(@value{GDBP}) @b{quit} -@end smallexample - -@node Invocation -@chapter Getting In and Out of @value{GDBN} - -This chapter discusses how to start @value{GDBN}, and how to get out of it. -The essentials are: -@itemize @bullet -@item -type @samp{@value{GDBP}} to start @value{GDBN}. -@item -type @kbd{quit} or @kbd{C-d} to exit. -@end itemize - -@menu -* Invoking GDB:: How to start @value{GDBN} -* Quitting GDB:: How to quit @value{GDBN} -* Shell Commands:: How to use shell commands inside @value{GDBN} -* Logging output:: How to log @value{GDBN}'s output to a file -@end menu - -@node Invoking GDB -@section Invoking @value{GDBN} - -Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, -@value{GDBN} reads commands from the terminal until you tell it to exit. - -You can also run @code{@value{GDBP}} with a variety of arguments and options, -to specify more of your debugging environment at the outset. - -The command-line options described here are designed -to cover a variety of situations; in some environments, some of these -options may effectively be unavailable. - -The most usual way to start @value{GDBN} is with one argument, -specifying an executable program: - -@smallexample -@value{GDBP} @var{program} -@end smallexample - -@noindent -You can also start with both an executable program and a core file -specified: - -@smallexample -@value{GDBP} @var{program} @var{core} -@end smallexample - -You can, instead, specify a process ID as a second argument, if you want -to debug a running process: - -@smallexample -@value{GDBP} @var{program} 1234 -@end smallexample - -@noindent -would attach @value{GDBN} to process @code{1234} (unless you also have a file -named @file{1234}; @value{GDBN} does check for a core file first). - -Taking advantage of the second command-line argument requires a fairly -complete operating system; when you use @value{GDBN} as a remote -debugger attached to a bare board, there may not be any notion of -``process'', and there is often no way to get a core dump. @value{GDBN} -will warn you if it is unable to attach or to read core dumps. - -You can optionally have @code{@value{GDBP}} pass any arguments after the -executable file to the inferior using @code{--args}. This option stops -option processing. -@smallexample -gdb --args gcc -O2 -c foo.c -@end smallexample -This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set -@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. - -You can run @code{@value{GDBP}} without printing the front material, which describes -@value{GDBN}'s non-warranty, by specifying @code{-silent}: - -@smallexample -@value{GDBP} -silent -@end smallexample - -@noindent -You can further control how @value{GDBN} starts up by using command-line -options. @value{GDBN} itself can remind you of the options available. - -@noindent -Type - -@smallexample -@value{GDBP} -help -@end smallexample - -@noindent -to display all available options and briefly describe their use -(@samp{@value{GDBP} -h} is a shorter equivalent). - -All options and command line arguments you give are processed -in sequential order. The order makes a difference when the -@samp{-x} option is used. - - -@menu -* File Options:: Choosing files -* Mode Options:: Choosing modes -@end menu - -@node File Options -@subsection Choosing files - -When @value{GDBN} starts, it reads any arguments other than options as -specifying an executable file and core file (or process ID). This is -the same as if the arguments were specified by the @samp{-se} and -@samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the -first argument that does not have an associated option flag as -equivalent to the @samp{-se} option followed by that argument; and the -second argument that does not have an associated option flag, if any, as -equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) -If the second argument begins with a decimal digit, @value{GDBN} will -first attempt to attach to it as a process, and if that fails, attempt -to open it as a corefile. If you have a corefile whose name begins with -a digit, you can prevent @value{GDBN} from treating it as a pid by -prefixing it with @file{./}, eg. @file{./12345}. - -If @value{GDBN} has not been configured to included core file support, -such as for most embedded targets, then it will complain about a second -argument and ignore it. - -Many options have both long and short forms; both are shown in the -following list. @value{GDBN} also recognizes the long forms if you truncate -them, so long as enough of the option is present to be unambiguous. -(If you prefer, you can flag option arguments with @samp{--} rather -than @samp{-}, though we illustrate the more usual convention.) - -@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This -@c way, both those who look for -foo and --foo in the index, will find -@c it. - -@table @code -@item -symbols @var{file} -@itemx -s @var{file} -@cindex @code{--symbols} -@cindex @code{-s} -Read symbol table from file @var{file}. - -@item -exec @var{file} -@itemx -e @var{file} -@cindex @code{--exec} -@cindex @code{-e} -Use file @var{file} as the executable file to execute when appropriate, -and for examining pure data in conjunction with a core dump. - -@item -se @var{file} -@cindex @code{--se} -Read symbol table from file @var{file} and use it as the executable -file. - -@item -core @var{file} -@itemx -c @var{file} -@cindex @code{--core} -@cindex @code{-c} -Use file @var{file} as a core dump to examine. - -@item -c @var{number} -@item -pid @var{number} -@itemx -p @var{number} -@cindex @code{--pid} -@cindex @code{-p} -Connect to process ID @var{number}, as with the @code{attach} command. -If there is no such process, @value{GDBN} will attempt to open a core -file named @var{number}. - -@item -command @var{file} -@itemx -x @var{file} -@cindex @code{--command} -@cindex @code{-x} -Execute @value{GDBN} commands from file @var{file}. @xref{Command -Files,, Command files}. - -@item -directory @var{directory} -@itemx -d @var{directory} -@cindex @code{--directory} -@cindex @code{-d} -Add @var{directory} to the path to search for source files. - -@item -m -@itemx -mapped -@cindex @code{--mapped} -@cindex @code{-m} -@emph{Warning: this option depends on operating system facilities that are not -supported on all systems.}@* -If memory-mapped files are available on your system through the @code{mmap} -system call, you can use this option -to have @value{GDBN} write the symbols from your -program into a reusable file in the current directory. If the program you are debugging is -called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}. -Future @value{GDBN} debugging sessions notice the presence of this file, -and can quickly map in symbol information from it, rather than reading -the symbol table from the executable program. - -The @file{.syms} file is specific to the host machine where @value{GDBN} -is run. It holds an exact image of the internal @value{GDBN} symbol -table. It cannot be shared across multiple host platforms. - -@item -r -@itemx -readnow -@cindex @code{--readnow} -@cindex @code{-r} -Read each symbol file's entire symbol table immediately, rather than -the default, which is to read it incrementally as it is needed. -This makes startup slower, but makes future operations faster. - -@end table - -You typically combine the @code{-mapped} and @code{-readnow} options in -order to build a @file{.syms} file that contains complete symbol -information. (@xref{Files,,Commands to specify files}, for information -on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing -but build a @file{.syms} file for future use is: - -@smallexample -gdb -batch -nx -mapped -readnow programname -@end smallexample - -@node Mode Options -@subsection Choosing modes - -You can run @value{GDBN} in various alternative modes---for example, in -batch mode or quiet mode. - -@table @code -@item -nx -@itemx -n -@cindex @code{--nx} -@cindex @code{-n} -Do not execute commands found in any initialization files. Normally, -@value{GDBN} executes the commands in these files after all the command -options and arguments have been processed. @xref{Command Files,,Command -files}. - -@item -quiet -@itemx -silent -@itemx -q -@cindex @code{--quiet} -@cindex @code{--silent} -@cindex @code{-q} -``Quiet''. Do not print the introductory and copyright messages. These -messages are also suppressed in batch mode. - -@item -batch -@cindex @code{--batch} -Run in batch mode. Exit with status @code{0} after processing all the -command files specified with @samp{-x} (and all commands from -initialization files, if not inhibited with @samp{-n}). Exit with -nonzero status if an error occurs in executing the @value{GDBN} commands -in the command files. - -Batch mode may be useful for running @value{GDBN} as a filter, for -example to download and run a program on another computer; in order to -make this more useful, the message - -@smallexample -Program exited normally. -@end smallexample - -@noindent -(which is ordinarily issued whenever a program running under -@value{GDBN} control terminates) is not issued when running in batch -mode. - -@item -nowindows -@itemx -nw -@cindex @code{--nowindows} -@cindex @code{-nw} -``No windows''. If @value{GDBN} comes with a graphical user interface -(GUI) built in, then this option tells @value{GDBN} to only use the command-line -interface. If no GUI is available, this option has no effect. - -@item -windows -@itemx -w -@cindex @code{--windows} -@cindex @code{-w} -If @value{GDBN} includes a GUI, then this option requires it to be -used if possible. - -@item -cd @var{directory} -@cindex @code{--cd} -Run @value{GDBN} using @var{directory} as its working directory, -instead of the current directory. - -@item -fullname -@itemx -f -@cindex @code{--fullname} -@cindex @code{-f} -@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a -subprocess. It tells @value{GDBN} to output the full file name and line -number in a standard, recognizable fashion each time a stack frame is -displayed (which includes each time your program stops). This -recognizable format looks like two @samp{\032} characters, followed by -the file name, line number and character position separated by colons, -and a newline. The Emacs-to-@value{GDBN} interface program uses the two -@samp{\032} characters as a signal to display the source code for the -frame. - -@item -epoch -@cindex @code{--epoch} -The Epoch Emacs-@value{GDBN} interface sets this option when it runs -@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print -routines so as to allow Epoch to display values of expressions in a -separate window. - -@item -annotate @var{level} -@cindex @code{--annotate} -This option sets the @dfn{annotation level} inside @value{GDBN}. Its -effect is identical to using @samp{set annotate @var{level}} -(@pxref{Annotations}). The annotation @var{level} controls how much -information @value{GDBN} prints together with its prompt, values of -expressions, source lines, and other types of output. Level 0 is the -normal, level 1 is for use when @value{GDBN} is run as a subprocess of -@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs -that control @value{GDBN}, and level 2 has been deprecated. - -The annotation mechanism has largely been superseeded by @sc{gdb/mi} -(@pxref{GDB/MI}). - -@item -async -@cindex @code{--async} -Use the asynchronous event loop for the command-line interface. -@value{GDBN} processes all events, such as user keyboard input, via a -special event loop. This allows @value{GDBN} to accept and process user -commands in parallel with the debugged process being -run@footnote{@value{GDBN} built with @sc{djgpp} tools for -MS-DOS/MS-Windows supports this mode of operation, but the event loop is -suspended when the debuggee runs.}, so you don't need to wait for -control to return to @value{GDBN} before you type the next command. -(@emph{Note:} as of version 5.1, the target side of the asynchronous -operation is not yet in place, so @samp{-async} does not work fully -yet.) -@c FIXME: when the target side of the event loop is done, the above NOTE -@c should be removed. - -When the standard input is connected to a terminal device, @value{GDBN} -uses the asynchronous event loop by default, unless disabled by the -@samp{-noasync} option. - -@item -noasync -@cindex @code{--noasync} -Disable the asynchronous event loop for the command-line interface. - -@item --args -@cindex @code{--args} -Change interpretation of command line so that arguments following the -executable file are passed as command line arguments to the inferior. -This option stops option processing. - -@item -baud @var{bps} -@itemx -b @var{bps} -@cindex @code{--baud} -@cindex @code{-b} -Set the line speed (baud rate or bits per second) of any serial -interface used by @value{GDBN} for remote debugging. - -@item -tty @var{device} -@itemx -t @var{device} -@cindex @code{--tty} -@cindex @code{-t} -Run using @var{device} for your program's standard input and output. -@c FIXME: kingdon thinks there is more to -tty. Investigate. - -@c resolve the situation of these eventually -@item -tui -@cindex @code{--tui} -Activate the @dfn{Text User Interface} when starting. The Text User -Interface manages several text windows on the terminal, showing -source, assembly, registers and @value{GDBN} command outputs -(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the -Text User Interface can be enabled by invoking the program -@samp{gdbtui}. Do not use this option if you run @value{GDBN} from -Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}). - -@c @item -xdb -@c @cindex @code{--xdb} -@c Run in XDB compatibility mode, allowing the use of certain XDB commands. -@c For information, see the file @file{xdb_trans.html}, which is usually -@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX -@c systems. - -@item -interpreter @var{interp} -@cindex @code{--interpreter} -Use the interpreter @var{interp} for interface with the controlling -program or device. This option is meant to be set by programs which -communicate with @value{GDBN} using it as a back end. -@xref{Interpreters, , Command Interpreters}. - -@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes -@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, , -The @sc{gdb/mi} Interface}) included since @var{GDBN} version 6.0. The -previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and -selected with @samp{--interpreter=mi1}, is deprecated. Earlier -@sc{gdb/mi} interfaces are no longer supported. - -@item -write -@cindex @code{--write} -Open the executable and core files for both reading and writing. This -is equivalent to the @samp{set write on} command inside @value{GDBN} -(@pxref{Patching}). - -@item -statistics -@cindex @code{--statistics} -This option causes @value{GDBN} to print statistics about time and -memory usage after it completes each command and returns to the prompt. - -@item -version -@cindex @code{--version} -This option causes @value{GDBN} to print its version number and -no-warranty blurb, and exit. - -@end table - -@node Quitting GDB -@section Quitting @value{GDBN} -@cindex exiting @value{GDBN} -@cindex leaving @value{GDBN} - -@table @code -@kindex quit @r{[}@var{expression}@r{]} -@kindex q @r{(@code{quit})} -@item quit @r{[}@var{expression}@r{]} -@itemx q -To exit @value{GDBN}, use the @code{quit} command (abbreviated -@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you -do not supply @var{expression}, @value{GDBN} will terminate normally; -otherwise it will terminate using the result of @var{expression} as the -error code. -@end table - -@cindex interrupt -An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather -terminates the action of any @value{GDBN} command that is in progress and -returns to @value{GDBN} command level. It is safe to type the interrupt -character at any time because @value{GDBN} does not allow it to take effect -until a time when it is safe. - -If you have been using @value{GDBN} to control an attached process or -device, you can release it with the @code{detach} command -(@pxref{Attach, ,Debugging an already-running process}). - -@node Shell Commands -@section Shell commands - -If you need to execute occasional shell commands during your -debugging session, there is no need to leave or suspend @value{GDBN}; you can -just use the @code{shell} command. - -@table @code -@kindex shell -@cindex shell escape -@item shell @var{command string} -Invoke a standard shell to execute @var{command string}. -If it exists, the environment variable @code{SHELL} determines which -shell to run. Otherwise @value{GDBN} uses the default shell -(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.). -@end table - -The utility @code{make} is often needed in development environments. -You do not have to use the @code{shell} command for this purpose in -@value{GDBN}: - -@table @code -@kindex make -@cindex calling make -@item make @var{make-args} -Execute the @code{make} program with the specified -arguments. This is equivalent to @samp{shell make @var{make-args}}. -@end table - -@node Logging output -@section Logging output -@cindex logging @value{GDBN} output - -You may want to save the output of @value{GDBN} commands to a file. -There are several commands to control @value{GDBN}'s logging. - -@table @code -@kindex set logging -@item set logging on -Enable logging. -@item set logging off -Disable logging. -@item set logging file @var{file} -Change the name of the current logfile. The default logfile is @file{gdb.txt}. -@item set logging overwrite [on|off] -By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if -you want @code{set logging on} to overwrite the logfile instead. -@item set logging redirect [on|off] -By default, @value{GDBN} output will go to both the terminal and the logfile. -Set @code{redirect} if you want output to go only to the log file. -@kindex show logging -@item show logging -Show the current values of the logging settings. -@end table - -@node Commands -@chapter @value{GDBN} Commands - -You can abbreviate a @value{GDBN} command to the first few letters of the command -name, if that abbreviation is unambiguous; and you can repeat certain -@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} -key to get @value{GDBN} to fill out the rest of a word in a command (or to -show you the alternatives available, if there is more than one possibility). - -@menu -* Command Syntax:: How to give commands to @value{GDBN} -* Completion:: Command completion -* Help:: How to ask @value{GDBN} for help -@end menu - -@node Command Syntax -@section Command syntax - -A @value{GDBN} command is a single line of input. There is no limit on -how long it can be. It starts with a command name, which is followed by -arguments whose meaning depends on the command name. For example, the -command @code{step} accepts an argument which is the number of times to -step, as in @samp{step 5}. You can also use the @code{step} command -with no arguments. Some commands do not allow any arguments. - -@cindex abbreviation -@value{GDBN} command names may always be truncated if that abbreviation is -unambiguous. Other possible command abbreviations are listed in the -documentation for individual commands. In some cases, even ambiguous -abbreviations are allowed; for example, @code{s} is specially defined as -equivalent to @code{step} even though there are other commands whose -names start with @code{s}. You can test abbreviations by using them as -arguments to the @code{help} command. - -@cindex repeating commands -@kindex RET @r{(repeat last command)} -A blank line as input to @value{GDBN} (typing just @key{RET}) means to -repeat the previous command. Certain commands (for example, @code{run}) -will not repeat this way; these are commands whose unintentional -repetition might cause trouble and which you are unlikely to want to -repeat. - -The @code{list} and @code{x} commands, when you repeat them with -@key{RET}, construct new arguments rather than repeating -exactly as typed. This permits easy scanning of source or memory. - -@value{GDBN} can also use @key{RET} in another way: to partition lengthy -output, in a way similar to the common utility @code{more} -(@pxref{Screen Size,,Screen size}). Since it is easy to press one -@key{RET} too many in this situation, @value{GDBN} disables command -repetition after any command that generates this sort of display. - -@kindex # @r{(a comment)} -@cindex comment -Any text from a @kbd{#} to the end of the line is a comment; it does -nothing. This is useful mainly in command files (@pxref{Command -Files,,Command files}). - -@cindex repeating command sequences -@kindex C-o @r{(operate-and-get-next)} -The @kbd{C-o} binding is useful for repeating a complex sequence of -commands. This command accepts the current line, like @kbd{RET}, and -then fetches the next line relative to the current line from the history -for editing. - -@node Completion -@section Command completion - -@cindex completion -@cindex word completion -@value{GDBN} can fill in the rest of a word in a command for you, if there is -only one possibility; it can also show you what the valid possibilities -are for the next word in a command, at any time. This works for @value{GDBN} -commands, @value{GDBN} subcommands, and the names of symbols in your program. - -Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest -of a word. If there is only one possibility, @value{GDBN} fills in the -word, and waits for you to finish the command (or press @key{RET} to -enter it). For example, if you type - -@c FIXME "@key" does not distinguish its argument sufficiently to permit -@c complete accuracy in these examples; space introduced for clarity. -@c If texinfo enhancements make it unnecessary, it would be nice to -@c replace " @key" by "@key" in the following... -@smallexample -(@value{GDBP}) info bre @key{TAB} -@end smallexample - -@noindent -@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is -the only @code{info} subcommand beginning with @samp{bre}: - -@smallexample -(@value{GDBP}) info breakpoints -@end smallexample - -@noindent -You can either press @key{RET} at this point, to run the @code{info -breakpoints} command, or backspace and enter something else, if -@samp{breakpoints} does not look like the command you expected. (If you -were sure you wanted @code{info breakpoints} in the first place, you -might as well just type @key{RET} immediately after @samp{info bre}, -to exploit command abbreviations rather than command completion). - -If there is more than one possibility for the next word when you press -@key{TAB}, @value{GDBN} sounds a bell. You can either supply more -characters and try again, or just press @key{TAB} a second time; -@value{GDBN} displays all the possible completions for that word. For -example, you might want to set a breakpoint on a subroutine whose name -begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} -just sounds the bell. Typing @key{TAB} again displays all the -function names in your program that begin with those characters, for -example: - -@smallexample -(@value{GDBP}) b make_ @key{TAB} -@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: -make_a_section_from_file make_environ -make_abs_section make_function_type -make_blockvector make_pointer_type -make_cleanup make_reference_type -make_command make_symbol_completion_list -(@value{GDBP}) b make_ -@end smallexample - -@noindent -After displaying the available possibilities, @value{GDBN} copies your -partial input (@samp{b make_} in the example) so you can finish the -command. - -If you just want to see the list of alternatives in the first place, you -can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} -means @kbd{@key{META} ?}. You can type this either by holding down a -key designated as the @key{META} shift on your keyboard (if there is -one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. - -@cindex quotes in commands -@cindex completion of quoted strings -Sometimes the string you need, while logically a ``word'', may contain -parentheses or other characters that @value{GDBN} normally excludes from -its notion of a word. To permit word completion to work in this -situation, you may enclose words in @code{'} (single quote marks) in -@value{GDBN} commands. - -The most likely situation where you might need this is in typing the -name of a C@t{++} function. This is because C@t{++} allows function -overloading (multiple definitions of the same function, distinguished -by argument type). For example, when you want to set a breakpoint you -may need to distinguish whether you mean the version of @code{name} -that takes an @code{int} parameter, @code{name(int)}, or the version -that takes a @code{float} parameter, @code{name(float)}. To use the -word-completion facilities in this situation, type a single quote -@code{'} at the beginning of the function name. This alerts -@value{GDBN} that it may need to consider more information than usual -when you press @key{TAB} or @kbd{M-?} to request word completion: - -@smallexample -(@value{GDBP}) b 'bubble( @kbd{M-?} -bubble(double,double) bubble(int,int) -(@value{GDBP}) b 'bubble( -@end smallexample - -In some cases, @value{GDBN} can tell that completing a name requires using -quotes. When this happens, @value{GDBN} inserts the quote for you (while -completing as much as it can) if you do not type the quote in the first -place: - -@smallexample -(@value{GDBP}) b bub @key{TAB} -@exdent @value{GDBN} alters your input line to the following, and rings a bell: -(@value{GDBP}) b 'bubble( -@end smallexample - -@noindent -In general, @value{GDBN} can tell that a quote is needed (and inserts it) if -you have not yet started typing the argument list when you ask for -completion on an overloaded symbol. - -For more information about overloaded functions, see @ref{C plus plus -expressions, ,C@t{++} expressions}. You can use the command @code{set -overload-resolution off} to disable overload resolution; -see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}. - - -@node Help -@section Getting help -@cindex online documentation -@kindex help - -You can always ask @value{GDBN} itself for information on its commands, -using the command @code{help}. - -@table @code -@kindex h @r{(@code{help})} -@item help -@itemx h -You can use @code{help} (abbreviated @code{h}) with no arguments to -display a short list of named classes of commands: - -@smallexample -(@value{GDBP}) help -List of classes of commands: - -aliases -- Aliases of other commands -breakpoints -- Making program stop at certain points -data -- Examining data -files -- Specifying and examining files -internals -- Maintenance commands -obscure -- Obscure features -running -- Running the program -stack -- Examining the stack -status -- Status inquiries -support -- Support facilities -tracepoints -- Tracing of program execution without@* - stopping the program -user-defined -- User-defined commands - -Type "help" followed by a class name for a list of -commands in that class. -Type "help" followed by command name for full -documentation. -Command name abbreviations are allowed if unambiguous. -(@value{GDBP}) -@end smallexample -@c the above line break eliminates huge line overfull... - -@item help @var{class} -Using one of the general help classes as an argument, you can get a -list of the individual commands in that class. For example, here is the -help display for the class @code{status}: - -@smallexample -(@value{GDBP}) help status -Status inquiries. - -List of commands: - -@c Line break in "show" line falsifies real output, but needed -@c to fit in smallbook page size. -info -- Generic command for showing things - about the program being debugged -show -- Generic command for showing things - about the debugger - -Type "help" followed by command name for full -documentation. -Command name abbreviations are allowed if unambiguous. -(@value{GDBP}) -@end smallexample - -@item help @var{command} -With a command name as @code{help} argument, @value{GDBN} displays a -short paragraph on how to use that command. - -@kindex apropos -@item apropos @var{args} -The @code{apropos @var{args}} command searches through all of the @value{GDBN} -commands, and their documentation, for the regular expression specified in -@var{args}. It prints out all matches found. For example: - -@smallexample -apropos reload -@end smallexample - -@noindent -results in: - -@smallexample -@c @group -set symbol-reloading -- Set dynamic symbol table reloading - multiple times in one run -show symbol-reloading -- Show dynamic symbol table reloading - multiple times in one run -@c @end group -@end smallexample - -@kindex complete -@item complete @var{args} -The @code{complete @var{args}} command lists all the possible completions -for the beginning of a command. Use @var{args} to specify the beginning of the -command you want completed. For example: - -@smallexample -complete i -@end smallexample - -@noindent results in: - -@smallexample -@group -if -ignore -info -inspect -@end group -@end smallexample - -@noindent This is intended for use by @sc{gnu} Emacs. -@end table - -In addition to @code{help}, you can use the @value{GDBN} commands @code{info} -and @code{show} to inquire about the state of your program, or the state -of @value{GDBN} itself. Each command supports many topics of inquiry; this -manual introduces each of them in the appropriate context. The listings -under @code{info} and under @code{show} in the Index point to -all the sub-commands. @xref{Index}. - -@c @group -@table @code -@kindex info -@kindex i @r{(@code{info})} -@item info -This command (abbreviated @code{i}) is for describing the state of your -program. For example, you can list the arguments given to your program -with @code{info args}, list the registers currently in use with @code{info -registers}, or list the breakpoints you have set with @code{info breakpoints}. -You can get a complete list of the @code{info} sub-commands with -@w{@code{help info}}. - -@kindex set -@item set -You can assign the result of an expression to an environment variable with -@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with -@code{set prompt $}. - -@kindex show -@item show -In contrast to @code{info}, @code{show} is for describing the state of -@value{GDBN} itself. -You can change most of the things you can @code{show}, by using the -related command @code{set}; for example, you can control what number -system is used for displays with @code{set radix}, or simply inquire -which is currently in use with @code{show radix}. - -@kindex info set -To display all the settable parameters and their current -values, you can use @code{show} with no arguments; you may also use -@code{info set}. Both commands produce the same display. -@c FIXME: "info set" violates the rule that "info" is for state of -@c FIXME...program. Ck w/ GNU: "info set" to be called something else, -@c FIXME...or change desc of rule---eg "state of prog and debugging session"? -@end table -@c @end group - -Here are three miscellaneous @code{show} subcommands, all of which are -exceptional in lacking corresponding @code{set} commands: - -@table @code -@kindex show version -@cindex version number -@item show version -Show what version of @value{GDBN} is running. You should include this -information in @value{GDBN} bug-reports. If multiple versions of -@value{GDBN} are in use at your site, you may need to determine which -version of @value{GDBN} you are running; as @value{GDBN} evolves, new -commands are introduced, and old ones may wither away. Also, many -system vendors ship variant versions of @value{GDBN}, and there are -variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. -The version number is the same as the one announced when you start -@value{GDBN}. - -@kindex show copying -@item show copying -Display information about permission for copying @value{GDBN}. - -@kindex show warranty -@item show warranty -Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, -if your version of @value{GDBN} comes with one. - -@end table - -@node Running -@chapter Running Programs Under @value{GDBN} - -When you run a program under @value{GDBN}, you must first generate -debugging information when you compile it. - -You may start @value{GDBN} with its arguments, if any, in an environment -of your choice. If you are doing native debugging, you may redirect -your program's input and output, debug an already running process, or -kill a child process. - -@menu -* Compilation:: Compiling for debugging -* Starting:: Starting your program -* Arguments:: Your program's arguments -* Environment:: Your program's environment - -* Working Directory:: Your program's working directory -* Input/Output:: Your program's input and output -* Attach:: Debugging an already-running process -* Kill Process:: Killing the child process - -* Threads:: Debugging programs with multiple threads -* Processes:: Debugging programs with multiple processes -@end menu - -@node Compilation -@section Compiling for debugging - -In order to debug a program effectively, you need to generate -debugging information when you compile it. This debugging information -is stored in the object file; it describes the data type of each -variable or function and the correspondence between source line numbers -and addresses in the executable code. - -To request debugging information, specify the @samp{-g} option when you run -the compiler. - -Most compilers do not include information about preprocessor macros in -the debugging information if you specify the @option{-g} flag alone, -because this information is rather large. Version 3.1 of @value{NGCC}, -the @sc{gnu} C compiler, provides macro information if you specify the -options @option{-gdwarf-2} and @option{-g3}; the former option requests -debugging information in the Dwarf 2 format, and the latter requests -``extra information''. In the future, we hope to find more compact ways -to represent macro information, so that it can be included with -@option{-g} alone. - -Many C compilers are unable to handle the @samp{-g} and @samp{-O} -options together. Using those compilers, you cannot generate optimized -executables containing debugging information. - -@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or -without @samp{-O}, making it possible to debug optimized code. We -recommend that you @emph{always} use @samp{-g} whenever you compile a -program. You may think your program is correct, but there is no sense -in pushing your luck. - -@cindex optimized code, debugging -@cindex debugging optimized code -When you debug a program compiled with @samp{-g -O}, remember that the -optimizer is rearranging your code; the debugger shows you what is -really there. Do not be too surprised when the execution path does not -exactly match your source file! An extreme example: if you define a -variable, but never use it, @value{GDBN} never sees that -variable---because the compiler optimizes it out of existence. - -Some things do not work as well with @samp{-g -O} as with just -@samp{-g}, particularly on machines with instruction scheduling. If in -doubt, recompile with @samp{-g} alone, and if this fixes the problem, -please report it to us as a bug (including a test case!). - -Older versions of the @sc{gnu} C compiler permitted a variant option -@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this -format; if your @sc{gnu} C compiler has this option, do not use it. - -@need 2000 -@node Starting -@section Starting your program -@cindex starting -@cindex running - -@table @code -@kindex run -@kindex r @r{(@code{run})} -@item run -@itemx r -Use the @code{run} command to start your program under @value{GDBN}. -You must first specify the program name (except on VxWorks) with an -argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of -@value{GDBN}}), or by using the @code{file} or @code{exec-file} command -(@pxref{Files, ,Commands to specify files}). - -@end table - -If you are running your program in an execution environment that -supports processes, @code{run} creates an inferior process and makes -that process run your program. (In environments without processes, -@code{run} jumps to the start of your program.) - -The execution of a program is affected by certain information it -receives from its superior. @value{GDBN} provides ways to specify this -information, which you must do @emph{before} starting your program. (You -can change it after starting your program, but such changes only affect -your program the next time you start it.) This information may be -divided into four categories: - -@table @asis -@item The @emph{arguments.} -Specify the arguments to give your program as the arguments of the -@code{run} command. If a shell is available on your target, the shell -is used to pass the arguments, so that you may use normal conventions -(such as wildcard expansion or variable substitution) in describing -the arguments. -In Unix systems, you can control which shell is used with the -@code{SHELL} environment variable. -@xref{Arguments, ,Your program's arguments}. - -@item The @emph{environment.} -Your program normally inherits its environment from @value{GDBN}, but you can -use the @value{GDBN} commands @code{set environment} and @code{unset -environment} to change parts of the environment that affect -your program. @xref{Environment, ,Your program's environment}. - -@item The @emph{working directory.} -Your program inherits its working directory from @value{GDBN}. You can set -the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}. -@xref{Working Directory, ,Your program's working directory}. - -@item The @emph{standard input and output.} -Your program normally uses the same device for standard input and -standard output as @value{GDBN} is using. You can redirect input and output -in the @code{run} command line, or you can use the @code{tty} command to -set a different device for your program. -@xref{Input/Output, ,Your program's input and output}. - -@cindex pipes -@emph{Warning:} While input and output redirection work, you cannot use -pipes to pass the output of the program you are debugging to another -program; if you attempt this, @value{GDBN} is likely to wind up debugging the -wrong program. -@end table - -When you issue the @code{run} command, your program begins to execute -immediately. @xref{Stopping, ,Stopping and continuing}, for discussion -of how to arrange for your program to stop. Once your program has -stopped, you may call functions in your program, using the @code{print} -or @code{call} commands. @xref{Data, ,Examining Data}. - -If the modification time of your symbol file has changed since the last -time @value{GDBN} read its symbols, @value{GDBN} discards its symbol -table, and reads it again. When it does this, @value{GDBN} tries to retain -your current breakpoints. - -@node Arguments -@section Your program's arguments - -@cindex arguments (to your program) -The arguments to your program can be specified by the arguments of the -@code{run} command. -They are passed to a shell, which expands wildcard characters and -performs redirection of I/O, and thence to your program. Your -@code{SHELL} environment variable (if it exists) specifies what shell -@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses -the default shell (@file{/bin/sh} on Unix). - -On non-Unix systems, the program is usually invoked directly by -@value{GDBN}, which emulates I/O redirection via the appropriate system -calls, and the wildcard characters are expanded by the startup code of -the program, not by the shell. - -@code{run} with no arguments uses the same arguments used by the previous -@code{run}, or those set by the @code{set args} command. - -@table @code -@kindex set args -@item set args -Specify the arguments to be used the next time your program is run. If -@code{set args} has no arguments, @code{run} executes your program -with no arguments. Once you have run your program with arguments, -using @code{set args} before the next @code{run} is the only way to run -it again without arguments. - -@kindex show args -@item show args -Show the arguments to give your program when it is started. -@end table - -@node Environment -@section Your program's environment - -@cindex environment (of your program) -The @dfn{environment} consists of a set of environment variables and -their values. Environment variables conventionally record such things as -your user name, your home directory, your terminal type, and your search -path for programs to run. Usually you set up environment variables with -the shell and they are inherited by all the other programs you run. When -debugging, it can be useful to try running your program with a modified -environment without having to start @value{GDBN} over again. - -@table @code -@kindex path -@item path @var{directory} -Add @var{directory} to the front of the @code{PATH} environment variable -(the search path for executables) that will be passed to your program. -The value of @code{PATH} used by @value{GDBN} does not change. -You may specify several directory names, separated by whitespace or by a -system-dependent separator character (@samp{:} on Unix, @samp{;} on -MS-DOS and MS-Windows). If @var{directory} is already in the path, it -is moved to the front, so it is searched sooner. - -You can use the string @samp{$cwd} to refer to whatever is the current -working directory at the time @value{GDBN} searches the path. If you -use @samp{.} instead, it refers to the directory where you executed the -@code{path} command. @value{GDBN} replaces @samp{.} in the -@var{directory} argument (with the current path) before adding -@var{directory} to the search path. -@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to -@c document that, since repeating it would be a no-op. - -@kindex show paths -@item show paths -Display the list of search paths for executables (the @code{PATH} -environment variable). - -@kindex show environment -@item show environment @r{[}@var{varname}@r{]} -Print the value of environment variable @var{varname} to be given to -your program when it starts. If you do not supply @var{varname}, -print the names and values of all environment variables to be given to -your program. You can abbreviate @code{environment} as @code{env}. - -@kindex set environment -@item set environment @var{varname} @r{[}=@var{value}@r{]} -Set environment variable @var{varname} to @var{value}. The value -changes for your program only, not for @value{GDBN} itself. @var{value} may -be any string; the values of environment variables are just strings, and -any interpretation is supplied by your program itself. The @var{value} -parameter is optional; if it is eliminated, the variable is set to a -null value. -@c "any string" here does not include leading, trailing -@c blanks. Gnu asks: does anyone care? - -For example, this command: - -@smallexample -set env USER = foo -@end smallexample - -@noindent -tells the debugged program, when subsequently run, that its user is named -@samp{foo}. (The spaces around @samp{=} are used for clarity here; they -are not actually required.) - -@kindex unset environment -@item unset environment @var{varname} -Remove variable @var{varname} from the environment to be passed to your -program. This is different from @samp{set env @var{varname} =}; -@code{unset environment} removes the variable from the environment, -rather than assigning it an empty value. -@end table - -@emph{Warning:} On Unix systems, @value{GDBN} runs your program using -the shell indicated -by your @code{SHELL} environment variable if it exists (or -@code{/bin/sh} if not). If your @code{SHELL} variable names a shell -that runs an initialization file---such as @file{.cshrc} for C-shell, or -@file{.bashrc} for BASH---any variables you set in that file affect -your program. You may wish to move setting of environment variables to -files that are only run when you sign on, such as @file{.login} or -@file{.profile}. - -@node Working Directory -@section Your program's working directory - -@cindex working directory (of your program) -Each time you start your program with @code{run}, it inherits its -working directory from the current working directory of @value{GDBN}. -The @value{GDBN} working directory is initially whatever it inherited -from its parent process (typically the shell), but you can specify a new -working directory in @value{GDBN} with the @code{cd} command. - -The @value{GDBN} working directory also serves as a default for the commands -that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to -specify files}. - -@table @code -@kindex cd -@item cd @var{directory} -Set the @value{GDBN} working directory to @var{directory}. - -@kindex pwd -@item pwd -Print the @value{GDBN} working directory. -@end table - -@node Input/Output -@section Your program's input and output - -@cindex redirection -@cindex i/o -@cindex terminal -By default, the program you run under @value{GDBN} does input and output to -the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal -to its own terminal modes to interact with you, but it records the terminal -modes your program was using and switches back to them when you continue -running your program. - -@table @code -@kindex info terminal -@item info terminal -Displays information recorded by @value{GDBN} about the terminal modes your -program is using. -@end table - -You can redirect your program's input and/or output using shell -redirection with the @code{run} command. For example, - -@smallexample -run > outfile -@end smallexample - -@noindent -starts your program, diverting its output to the file @file{outfile}. - -@kindex tty -@cindex controlling terminal -Another way to specify where your program should do input and output is -with the @code{tty} command. This command accepts a file name as -argument, and causes this file to be the default for future @code{run} -commands. It also resets the controlling terminal for the child -process, for future @code{run} commands. For example, - -@smallexample -tty /dev/ttyb -@end smallexample - -@noindent -directs that processes started with subsequent @code{run} commands -default to do input and output on the terminal @file{/dev/ttyb} and have -that as their controlling terminal. - -An explicit redirection in @code{run} overrides the @code{tty} command's -effect on the input/output device, but not its effect on the controlling -terminal. - -When you use the @code{tty} command or redirect input in the @code{run} -command, only the input @emph{for your program} is affected. The input -for @value{GDBN} still comes from your terminal. - -@node Attach -@section Debugging an already-running process -@kindex attach -@cindex attach - -@table @code -@item attach @var{process-id} -This command attaches to a running process---one that was started -outside @value{GDBN}. (@code{info files} shows your active -targets.) The command takes as argument a process ID. The usual way to -find out the process-id of a Unix process is with the @code{ps} utility, -or with the @samp{jobs -l} shell command. - -@code{attach} does not repeat if you press @key{RET} a second time after -executing the command. -@end table - -To use @code{attach}, your program must be running in an environment -which supports processes; for example, @code{attach} does not work for -programs on bare-board targets that lack an operating system. You must -also have permission to send the process a signal. - -When you use @code{attach}, the debugger finds the program running in -the process first by looking in the current working directory, then (if -the program is not found) by using the source file search path -(@pxref{Source Path, ,Specifying source directories}). You can also use -the @code{file} command to load the program. @xref{Files, ,Commands to -Specify Files}. - -The first thing @value{GDBN} does after arranging to debug the specified -process is to stop it. You can examine and modify an attached process -with all the @value{GDBN} commands that are ordinarily available when -you start processes with @code{run}. You can insert breakpoints; you -can step and continue; you can modify storage. If you would rather the -process continue running, you may use the @code{continue} command after -attaching @value{GDBN} to the process. - -@table @code -@kindex detach -@item detach -When you have finished debugging the attached process, you can use the -@code{detach} command to release it from @value{GDBN} control. Detaching -the process continues its execution. After the @code{detach} command, -that process and @value{GDBN} become completely independent once more, and you -are ready to @code{attach} another process or start one with @code{run}. -@code{detach} does not repeat if you press @key{RET} again after -executing the command. -@end table - -If you exit @value{GDBN} or use the @code{run} command while you have an -attached process, you kill that process. By default, @value{GDBN} asks -for confirmation if you try to do either of these things; you can -control whether or not you need to confirm by using the @code{set -confirm} command (@pxref{Messages/Warnings, ,Optional warnings and -messages}). - -@node Kill Process -@section Killing the child process - -@table @code -@kindex kill -@item kill -Kill the child process in which your program is running under @value{GDBN}. -@end table - -This command is useful if you wish to debug a core dump instead of a -running process. @value{GDBN} ignores any core dump file while your program -is running. - -On some operating systems, a program cannot be executed outside @value{GDBN} -while you have breakpoints set on it inside @value{GDBN}. You can use the -@code{kill} command in this situation to permit running your program -outside the debugger. - -The @code{kill} command is also useful if you wish to recompile and -relink your program, since on many systems it is impossible to modify an -executable file while it is running in a process. In this case, when you -next type @code{run}, @value{GDBN} notices that the file has changed, and -reads the symbol table again (while trying to preserve your current -breakpoint settings). - -@node Threads -@section Debugging programs with multiple threads - -@cindex threads of execution -@cindex multiple threads -@cindex switching threads -In some operating systems, such as HP-UX and Solaris, a single program -may have more than one @dfn{thread} of execution. The precise semantics -of threads differ from one operating system to another, but in general -the threads of a single program are akin to multiple processes---except -that they share one address space (that is, they can all examine and -modify the same variables). On the other hand, each thread has its own -registers and execution stack, and perhaps private memory. - -@value{GDBN} provides these facilities for debugging multi-thread -programs: - -@itemize @bullet -@item automatic notification of new threads -@item @samp{thread @var{threadno}}, a command to switch among threads -@item @samp{info threads}, a command to inquire about existing threads -@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}}, -a command to apply a command to a list of threads -@item thread-specific breakpoints -@end itemize - -@quotation -@emph{Warning:} These facilities are not yet available on every -@value{GDBN} configuration where the operating system supports threads. -If your @value{GDBN} does not support threads, these commands have no -effect. For example, a system without thread support shows no output -from @samp{info threads}, and always rejects the @code{thread} command, -like this: - -@smallexample -(@value{GDBP}) info threads -(@value{GDBP}) thread 1 -Thread ID 1 not known. Use the "info threads" command to -see the IDs of currently known threads. -@end smallexample -@c FIXME to implementors: how hard would it be to say "sorry, this GDB -@c doesn't support threads"? -@end quotation - -@cindex focus of debugging -@cindex current thread -The @value{GDBN} thread debugging facility allows you to observe all -threads while your program runs---but whenever @value{GDBN} takes -control, one thread in particular is always the focus of debugging. -This thread is called the @dfn{current thread}. Debugging commands show -program information from the perspective of the current thread. - -@cindex @code{New} @var{systag} message -@cindex thread identifier (system) -@c FIXME-implementors!! It would be more helpful if the [New...] message -@c included GDB's numeric thread handle, so you could just go to that -@c thread without first checking `info threads'. -Whenever @value{GDBN} detects a new thread in your program, it displays -the target system's identification for the thread with a message in the -form @samp{[New @var{systag}]}. @var{systag} is a thread identifier -whose form varies depending on the particular system. For example, on -LynxOS, you might see - -@smallexample -[New process 35 thread 27] -@end smallexample - -@noindent -when @value{GDBN} notices a new thread. In contrast, on an SGI system, -the @var{systag} is simply something like @samp{process 368}, with no -further qualifier. - -@c FIXME!! (1) Does the [New...] message appear even for the very first -@c thread of a program, or does it only appear for the -@c second---i.e.@: when it becomes obvious we have a multithread -@c program? -@c (2) *Is* there necessarily a first thread always? Or do some -@c multithread systems permit starting a program with multiple -@c threads ab initio? - -@cindex thread number -@cindex thread identifier (GDB) -For debugging purposes, @value{GDBN} associates its own thread -number---always a single integer---with each thread in your program. - -@table @code -@kindex info threads -@item info threads -Display a summary of all threads currently in your -program. @value{GDBN} displays for each thread (in this order): - -@enumerate -@item the thread number assigned by @value{GDBN} - -@item the target system's thread identifier (@var{systag}) - -@item the current stack frame summary for that thread -@end enumerate - -@noindent -An asterisk @samp{*} to the left of the @value{GDBN} thread number -indicates the current thread. - -For example, -@end table -@c end table here to get a little more width for example - -@smallexample -(@value{GDBP}) info threads - 3 process 35 thread 27 0x34e5 in sigpause () - 2 process 35 thread 23 0x34e5 in sigpause () -* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) - at threadtest.c:68 -@end smallexample - -On HP-UX systems: - -@cindex thread number -@cindex thread identifier (GDB) -For debugging purposes, @value{GDBN} associates its own thread -number---a small integer assigned in thread-creation order---with each -thread in your program. - -@cindex @code{New} @var{systag} message, on HP-UX -@cindex thread identifier (system), on HP-UX -@c FIXME-implementors!! It would be more helpful if the [New...] message -@c included GDB's numeric thread handle, so you could just go to that -@c thread without first checking `info threads'. -Whenever @value{GDBN} detects a new thread in your program, it displays -both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the -form @samp{[New @var{systag}]}. @var{systag} is a thread identifier -whose form varies depending on the particular system. For example, on -HP-UX, you see - -@smallexample -[New thread 2 (system thread 26594)] -@end smallexample - -@noindent -when @value{GDBN} notices a new thread. - -@table @code -@kindex info threads -@item info threads -Display a summary of all threads currently in your -program. @value{GDBN} displays for each thread (in this order): - -@enumerate -@item the thread number assigned by @value{GDBN} - -@item the target system's thread identifier (@var{systag}) - -@item the current stack frame summary for that thread -@end enumerate - -@noindent -An asterisk @samp{*} to the left of the @value{GDBN} thread number -indicates the current thread. - -For example, -@end table -@c end table here to get a little more width for example - -@smallexample -(@value{GDBP}) info threads - * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@* - at quicksort.c:137 - 2 system thread 26606 0x7b0030d8 in __ksleep () \@* - from /usr/lib/libc.2 - 1 system thread 27905 0x7b003498 in _brk () \@* - from /usr/lib/libc.2 -@end smallexample - -@table @code -@kindex thread @var{threadno} -@item thread @var{threadno} -Make thread number @var{threadno} the current thread. The command -argument @var{threadno} is the internal @value{GDBN} thread number, as -shown in the first field of the @samp{info threads} display. -@value{GDBN} responds by displaying the system identifier of the thread -you selected, and its current stack frame summary: - -@smallexample -@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one -(@value{GDBP}) thread 2 -[Switching to process 35 thread 23] -0x34e5 in sigpause () -@end smallexample - -@noindent -As with the @samp{[New @dots{}]} message, the form of the text after -@samp{Switching to} depends on your system's conventions for identifying -threads. - -@kindex thread apply -@item thread apply [@var{threadno}] [@var{all}] @var{args} -The @code{thread apply} command allows you to apply a command to one or -more threads. Specify the numbers of the threads that you want affected -with the command argument @var{threadno}. @var{threadno} is the internal -@value{GDBN} thread number, as shown in the first field of the @samp{info -threads} display. To apply a command to all threads, use -@code{thread apply all} @var{args}. -@end table - -@cindex automatic thread selection -@cindex switching threads automatically -@cindex threads, automatic switching -Whenever @value{GDBN} stops your program, due to a breakpoint or a -signal, it automatically selects the thread where that breakpoint or -signal happened. @value{GDBN} alerts you to the context switch with a -message of the form @samp{[Switching to @var{systag}]} to identify the -thread. - -@xref{Thread Stops,,Stopping and starting multi-thread programs}, for -more information about how @value{GDBN} behaves when you stop and start -programs with multiple threads. - -@xref{Set Watchpoints,,Setting watchpoints}, for information about -watchpoints in programs with multiple threads. - -@node Processes -@section Debugging programs with multiple processes - -@cindex fork, debugging programs which call -@cindex multiple processes -@cindex processes, multiple -On most systems, @value{GDBN} has no special support for debugging -programs which create additional processes using the @code{fork} -function. When a program forks, @value{GDBN} will continue to debug the -parent process and the child process will run unimpeded. If you have -set a breakpoint in any code which the child then executes, the child -will get a @code{SIGTRAP} signal which (unless it catches the signal) -will cause it to terminate. - -However, if you want to debug the child process there is a workaround -which isn't too painful. Put a call to @code{sleep} in the code which -the child process executes after the fork. It may be useful to sleep -only if a certain environment variable is set, or a certain file exists, -so that the delay need not occur when you don't want to run @value{GDBN} -on the child. While the child is sleeping, use the @code{ps} program to -get its process ID. Then tell @value{GDBN} (a new invocation of -@value{GDBN} if you are also debugging the parent process) to attach to -the child process (@pxref{Attach}). From that point on you can debug -the child process just like any other process which you attached to. - -On some systems, @value{GDBN} provides support for debugging programs that -create additional processes using the @code{fork} or @code{vfork} functions. -Currently, the only platforms with this feature are HP-UX (11.x and later -only?) and GNU/Linux (kernel version 2.5.60 and later). - -By default, when a program forks, @value{GDBN} will continue to debug -the parent process and the child process will run unimpeded. - -If you want to follow the child process instead of the parent process, -use the command @w{@code{set follow-fork-mode}}. - -@table @code -@kindex set follow-fork-mode -@item set follow-fork-mode @var{mode} -Set the debugger response to a program call of @code{fork} or -@code{vfork}. A call to @code{fork} or @code{vfork} creates a new -process. The @var{mode} can be: - -@table @code -@item parent -The original process is debugged after a fork. The child process runs -unimpeded. This is the default. - -@item child -The new process is debugged after a fork. The parent process runs -unimpeded. - -@end table - -@item show follow-fork-mode -Display the current debugger response to a @code{fork} or @code{vfork} call. -@end table - -If you ask to debug a child process and a @code{vfork} is followed by an -@code{exec}, @value{GDBN} executes the new target up to the first -breakpoint in the new target. If you have a breakpoint set on -@code{main} in your original program, the breakpoint will also be set on -the child process's @code{main}. - -When a child process is spawned by @code{vfork}, you cannot debug the -child or parent until an @code{exec} call completes. - -If you issue a @code{run} command to @value{GDBN} after an @code{exec} -call executes, the new target restarts. To restart the parent process, -use the @code{file} command with the parent executable name as its -argument. - -You can use the @code{catch} command to make @value{GDBN} stop whenever -a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set -Catchpoints, ,Setting catchpoints}. - -@node Stopping -@chapter Stopping and Continuing - -The principal purposes of using a debugger are so that you can stop your -program before it terminates; or so that, if your program runs into -trouble, you can investigate and find out why. - -Inside @value{GDBN}, your program may stop for any of several reasons, -such as a signal, a breakpoint, or reaching a new line after a -@value{GDBN} command such as @code{step}. You may then examine and -change variables, set new breakpoints or remove old ones, and then -continue execution. Usually, the messages shown by @value{GDBN} provide -ample explanation of the status of your program---but you can also -explicitly request this information at any time. - -@table @code -@kindex info program -@item info program -Display information about the status of your program: whether it is -running or not, what process it is, and why it stopped. -@end table - -@menu -* Breakpoints:: Breakpoints, watchpoints, and catchpoints -* Continuing and Stepping:: Resuming execution -* Signals:: Signals -* Thread Stops:: Stopping and starting multi-thread programs -@end menu - -@node Breakpoints -@section Breakpoints, watchpoints, and catchpoints - -@cindex breakpoints -A @dfn{breakpoint} makes your program stop whenever a certain point in -the program is reached. For each breakpoint, you can add conditions to -control in finer detail whether your program stops. You can set -breakpoints with the @code{break} command and its variants (@pxref{Set -Breaks, ,Setting breakpoints}), to specify the place where your program -should stop by line number, function name or exact address in the -program. - -In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set -breakpoints in shared libraries before the executable is run. There is -a minor limitation on HP-UX systems: you must wait until the executable -is run in order to set breakpoints in shared library routines that are -not called directly by the program (for example, routines that are -arguments in a @code{pthread_create} call). - -@cindex watchpoints -@cindex memory tracing -@cindex breakpoint on memory address -@cindex breakpoint on variable modification -A @dfn{watchpoint} is a special breakpoint that stops your program -when the value of an expression changes. You must use a different -command to set watchpoints (@pxref{Set Watchpoints, ,Setting -watchpoints}), but aside from that, you can manage a watchpoint like -any other breakpoint: you enable, disable, and delete both breakpoints -and watchpoints using the same commands. - -You can arrange to have values from your program displayed automatically -whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, -Automatic display}. - -@cindex catchpoints -@cindex breakpoint on events -A @dfn{catchpoint} is another special breakpoint that stops your program -when a certain kind of event occurs, such as the throwing of a C@t{++} -exception or the loading of a library. As with watchpoints, you use a -different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting -catchpoints}), but aside from that, you can manage a catchpoint like any -other breakpoint. (To stop when your program receives a signal, use the -@code{handle} command; see @ref{Signals, ,Signals}.) - -@cindex breakpoint numbers -@cindex numbers for breakpoints -@value{GDBN} assigns a number to each breakpoint, watchpoint, or -catchpoint when you create it; these numbers are successive integers -starting with one. In many of the commands for controlling various -features of breakpoints you use the breakpoint number to say which -breakpoint you want to change. Each breakpoint may be @dfn{enabled} or -@dfn{disabled}; if disabled, it has no effect on your program until you -enable it again. - -@cindex breakpoint ranges -@cindex ranges of breakpoints -Some @value{GDBN} commands accept a range of breakpoints on which to -operate. A breakpoint range is either a single breakpoint number, like -@samp{5}, or two such numbers, in increasing order, separated by a -hyphen, like @samp{5-7}. When a breakpoint range is given to a command, -all breakpoint in that range are operated on. - -@menu -* Set Breaks:: Setting breakpoints -* Set Watchpoints:: Setting watchpoints -* Set Catchpoints:: Setting catchpoints -* Delete Breaks:: Deleting breakpoints -* Disabling:: Disabling breakpoints -* Conditions:: Break conditions -* Break Commands:: Breakpoint command lists -* Breakpoint Menus:: Breakpoint menus -* Error in Breakpoints:: ``Cannot insert breakpoints'' -* Breakpoint related warnings:: ``Breakpoint address adjusted...'' -@end menu - -@node Set Breaks -@subsection Setting breakpoints - -@c FIXME LMB what does GDB do if no code on line of breakpt? -@c consider in particular declaration with/without initialization. -@c -@c FIXME 2 is there stuff on this already? break at fun start, already init? - -@kindex break -@kindex b @r{(@code{break})} -@vindex $bpnum@r{, convenience variable} -@cindex latest breakpoint -Breakpoints are set with the @code{break} command (abbreviated -@code{b}). The debugger convenience variable @samp{$bpnum} records the -number of the breakpoint you've set most recently; see @ref{Convenience -Vars,, Convenience variables}, for a discussion of what you can do with -convenience variables. - -You have several ways to say where the breakpoint should go. - -@table @code -@item break @var{function} -Set a breakpoint at entry to function @var{function}. -When using source languages that permit overloading of symbols, such as -C@t{++}, @var{function} may refer to more than one possible place to break. -@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation. - -@item break +@var{offset} -@itemx break -@var{offset} -Set a breakpoint some number of lines forward or back from the position -at which execution stopped in the currently selected @dfn{stack frame}. -(@xref{Frames, ,Frames}, for a description of stack frames.) - -@item break @var{linenum} -Set a breakpoint at line @var{linenum} in the current source file. -The current source file is the last file whose source text was printed. -The breakpoint will stop your program just before it executes any of the -code on that line. - -@item break @var{filename}:@var{linenum} -Set a breakpoint at line @var{linenum} in source file @var{filename}. - -@item break @var{filename}:@var{function} -Set a breakpoint at entry to function @var{function} found in file -@var{filename}. Specifying a file name as well as a function name is -superfluous except when multiple files contain similarly named -functions. - -@item break *@var{address} -Set a breakpoint at address @var{address}. You can use this to set -breakpoints in parts of your program which do not have debugging -information or source files. - -@item break -When called without any arguments, @code{break} sets a breakpoint at -the next instruction to be executed in the selected stack frame -(@pxref{Stack, ,Examining the Stack}). In any selected frame but the -innermost, this makes your program stop as soon as control -returns to that frame. This is similar to the effect of a -@code{finish} command in the frame inside the selected frame---except -that @code{finish} does not leave an active breakpoint. If you use -@code{break} without an argument in the innermost frame, @value{GDBN} stops -the next time it reaches the current location; this may be useful -inside loops. - -@value{GDBN} normally ignores breakpoints when it resumes execution, until at -least one instruction has been executed. If it did not do this, you -would be unable to proceed past a breakpoint without first disabling the -breakpoint. This rule applies whether or not the breakpoint already -existed when your program stopped. - -@item break @dots{} if @var{cond} -Set a breakpoint with condition @var{cond}; evaluate the expression -@var{cond} each time the breakpoint is reached, and stop only if the -value is nonzero---that is, if @var{cond} evaluates as true. -@samp{@dots{}} stands for one of the possible arguments described -above (or no argument) specifying where to break. @xref{Conditions, -,Break conditions}, for more information on breakpoint conditions. - -@kindex tbreak -@item tbreak @var{args} -Set a breakpoint enabled only for one stop. @var{args} are the -same as for the @code{break} command, and the breakpoint is set in the same -way, but the breakpoint is automatically deleted after the first time your -program stops there. @xref{Disabling, ,Disabling breakpoints}. - -@kindex hbreak -@item hbreak @var{args} -Set a hardware-assisted breakpoint. @var{args} are the same as for the -@code{break} command and the breakpoint is set in the same way, but the -breakpoint requires hardware support and some target hardware may not -have this support. The main purpose of this is EPROM/ROM code -debugging, so you can set a breakpoint at an instruction without -changing the instruction. This can be used with the new trap-generation -provided by SPARClite DSU and some x86-based targets. These targets -will generate traps when a program accesses some data or instruction -address that is assigned to the debug registers. However the hardware -breakpoint registers can take a limited number of breakpoints. For -example, on the DSU, only two data breakpoints can be set at a time, and -@value{GDBN} will reject this command if more than two are used. Delete -or disable unused hardware breakpoints before setting new ones -(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}. -@xref{set remote hardware-breakpoint-limit}. - - -@kindex thbreak -@item thbreak @var{args} -Set a hardware-assisted breakpoint enabled only for one stop. @var{args} -are the same as for the @code{hbreak} command and the breakpoint is set in -the same way. However, like the @code{tbreak} command, -the breakpoint is automatically deleted after the -first time your program stops there. Also, like the @code{hbreak} -command, the breakpoint requires hardware support and some target hardware -may not have this support. @xref{Disabling, ,Disabling breakpoints}. -See also @ref{Conditions, ,Break conditions}. - -@kindex rbreak -@cindex regular expression -@item rbreak @var{regex} -Set breakpoints on all functions matching the regular expression -@var{regex}. This command sets an unconditional breakpoint on all -matches, printing a list of all breakpoints it set. Once these -breakpoints are set, they are treated just like the breakpoints set with -the @code{break} command. You can delete them, disable them, or make -them conditional the same way as any other breakpoint. - -The syntax of the regular expression is the standard one used with tools -like @file{grep}. Note that this is different from the syntax used by -shells, so for instance @code{foo*} matches all functions that include -an @code{fo} followed by zero or more @code{o}s. There is an implicit -@code{.*} leading and trailing the regular expression you supply, so to -match only functions that begin with @code{foo}, use @code{^foo}. - -When debugging C@t{++} programs, @code{rbreak} is useful for setting -breakpoints on overloaded functions that are not members of any special -classes. - -@kindex info breakpoints -@cindex @code{$_} and @code{info breakpoints} -@item info breakpoints @r{[}@var{n}@r{]} -@itemx info break @r{[}@var{n}@r{]} -@itemx info watchpoints @r{[}@var{n}@r{]} -Print a table of all breakpoints, watchpoints, and catchpoints set and -not deleted, with the following columns for each breakpoint: - -@table @emph -@item Breakpoint Numbers -@item Type -Breakpoint, watchpoint, or catchpoint. -@item Disposition -Whether the breakpoint is marked to be disabled or deleted when hit. -@item Enabled or Disabled -Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints -that are not enabled. -@item Address -Where the breakpoint is in your program, as a memory address. If the -breakpoint is pending (see below for details) on a future load of a shared library, the address -will be listed as @samp{<PENDING>}. -@item What -Where the breakpoint is in the source for your program, as a file and -line number. For a pending breakpoint, the original string passed to -the breakpoint command will be listed as it cannot be resolved until -the appropriate shared library is loaded in the future. -@end table - -@noindent -If a breakpoint is conditional, @code{info break} shows the condition on -the line following the affected breakpoint; breakpoint commands, if any, -are listed after that. A pending breakpoint is allowed to have a condition -specified for it. The condition is not parsed for validity until a shared -library is loaded that allows the pending breakpoint to resolve to a -valid location. - -@noindent -@code{info break} with a breakpoint -number @var{n} as argument lists only that breakpoint. The -convenience variable @code{$_} and the default examining-address for -the @code{x} command are set to the address of the last breakpoint -listed (@pxref{Memory, ,Examining memory}). - -@noindent -@code{info break} displays a count of the number of times the breakpoint -has been hit. This is especially useful in conjunction with the -@code{ignore} command. You can ignore a large number of breakpoint -hits, look at the breakpoint info to see how many times the breakpoint -was hit, and then run again, ignoring one less than that number. This -will get you quickly to the last hit of that breakpoint. -@end table - -@value{GDBN} allows you to set any number of breakpoints at the same place in -your program. There is nothing silly or meaningless about this. When -the breakpoints are conditional, this is even useful -(@pxref{Conditions, ,Break conditions}). - -@cindex pending breakpoints -If a specified breakpoint location cannot be found, it may be due to the fact -that the location is in a shared library that is yet to be loaded. In such -a case, you may want @value{GDBN} to create a special breakpoint (known as -a @dfn{pending breakpoint}) that -attempts to resolve itself in the future when an appropriate shared library -gets loaded. - -Pending breakpoints are useful to set at the start of your -@value{GDBN} session for locations that you know will be dynamically loaded -later by the program being debugged. When shared libraries are loaded, -a check is made to see if the load resolves any pending breakpoint locations. -If a pending breakpoint location gets resolved, -a regular breakpoint is created and the original pending breakpoint is removed. - -@value{GDBN} provides some additional commands for controlling pending -breakpoint support: - -@kindex set breakpoint pending -@kindex show breakpoint pending -@table @code -@item set breakpoint pending auto -This is the default behavior. When @value{GDBN} cannot find the breakpoint -location, it queries you whether a pending breakpoint should be created. - -@item set breakpoint pending on -This indicates that an unrecognized breakpoint location should automatically -result in a pending breakpoint being created. - -@item set breakpoint pending off -This indicates that pending breakpoints are not to be created. Any -unrecognized breakpoint location results in an error. This setting does -not affect any pending breakpoints previously created. - -@item show breakpoint pending -Show the current behavior setting for creating pending breakpoints. -@end table - -@cindex operations allowed on pending breakpoints -Normal breakpoint operations apply to pending breakpoints as well. You may -specify a condition for a pending breakpoint and/or commands to run when the -breakpoint is reached. You can also enable or disable -the pending breakpoint. When you specify a condition for a pending breakpoint, -the parsing of the condition will be deferred until the point where the -pending breakpoint location is resolved. Disabling a pending breakpoint -tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent -shared library load. When a pending breakpoint is re-enabled, -@value{GDBN} checks to see if the location is already resolved. -This is done because any number of shared library loads could have -occurred since the time the breakpoint was disabled and one or more -of these loads could resolve the location. - -@cindex negative breakpoint numbers -@cindex internal @value{GDBN} breakpoints -@value{GDBN} itself sometimes sets breakpoints in your program for -special purposes, such as proper handling of @code{longjmp} (in C -programs). These internal breakpoints are assigned negative numbers, -starting with @code{-1}; @samp{info breakpoints} does not display them. -You can see these breakpoints with the @value{GDBN} maintenance command -@samp{maint info breakpoints} (@pxref{maint info breakpoints}). - - -@node Set Watchpoints -@subsection Setting watchpoints - -@cindex setting watchpoints -@cindex software watchpoints -@cindex hardware watchpoints -You can use a watchpoint to stop execution whenever the value of an -expression changes, without having to predict a particular place where -this may happen. - -Depending on your system, watchpoints may be implemented in software or -hardware. @value{GDBN} does software watchpointing by single-stepping your -program and testing the variable's value each time, which is hundreds of -times slower than normal execution. (But this may still be worth it, to -catch errors where you have no clue what part of your program is the -culprit.) - -On some systems, such as HP-UX, @sc{gnu}/Linux and some other x86-based targets, -@value{GDBN} includes support for -hardware watchpoints, which do not slow down the running of your -program. - -@table @code -@kindex watch -@item watch @var{expr} -Set a watchpoint for an expression. @value{GDBN} will break when @var{expr} -is written into by the program and its value changes. - -@kindex rwatch -@item rwatch @var{expr} -Set a watchpoint that will break when watch @var{expr} is read by the program. - -@kindex awatch -@item awatch @var{expr} -Set a watchpoint that will break when @var{expr} is either read or written into -by the program. - -@kindex info watchpoints -@item info watchpoints -This command prints a list of watchpoints, breakpoints, and catchpoints; -it is the same as @code{info break}. -@end table - -@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware -watchpoints execute very quickly, and the debugger reports a change in -value at the exact instruction where the change occurs. If @value{GDBN} -cannot set a hardware watchpoint, it sets a software watchpoint, which -executes more slowly and reports the change in value at the next -statement, not the instruction, after the change occurs. - -When you issue the @code{watch} command, @value{GDBN} reports - -@smallexample -Hardware watchpoint @var{num}: @var{expr} -@end smallexample - -@noindent -if it was able to set a hardware watchpoint. - -Currently, the @code{awatch} and @code{rwatch} commands can only set -hardware watchpoints, because accesses to data that don't change the -value of the watched expression cannot be detected without examining -every instruction as it is being executed, and @value{GDBN} does not do -that currently. If @value{GDBN} finds that it is unable to set a -hardware breakpoint with the @code{awatch} or @code{rwatch} command, it -will print a message like this: - -@smallexample -Expression cannot be implemented with read/access watchpoint. -@end smallexample - -Sometimes, @value{GDBN} cannot set a hardware watchpoint because the -data type of the watched expression is wider than what a hardware -watchpoint on the target machine can handle. For example, some systems -can only watch regions that are up to 4 bytes wide; on such systems you -cannot set hardware watchpoints for an expression that yields a -double-precision floating-point number (which is typically 8 bytes -wide). As a work-around, it might be possible to break the large region -into a series of smaller ones and watch them with separate watchpoints. - -If you set too many hardware watchpoints, @value{GDBN} might be unable -to insert all of them when you resume the execution of your program. -Since the precise number of active watchpoints is unknown until such -time as the program is about to be resumed, @value{GDBN} might not be -able to warn you about this when you set the watchpoints, and the -warning will be printed only when the program is resumed: - -@smallexample -Hardware watchpoint @var{num}: Could not insert watchpoint -@end smallexample - -@noindent -If this happens, delete or disable some of the watchpoints. - -The SPARClite DSU will generate traps when a program accesses some data -or instruction address that is assigned to the debug registers. For the -data addresses, DSU facilitates the @code{watch} command. However the -hardware breakpoint registers can only take two data watchpoints, and -both watchpoints must be the same kind. For example, you can set two -watchpoints with @code{watch} commands, two with @code{rwatch} commands, -@strong{or} two with @code{awatch} commands, but you cannot set one -watchpoint with one command and the other with a different command. -@value{GDBN} will reject the command if you try to mix watchpoints. -Delete or disable unused watchpoint commands before setting new ones. - -If you call a function interactively using @code{print} or @code{call}, -any watchpoints you have set will be inactive until @value{GDBN} reaches another -kind of breakpoint or the call completes. - -@value{GDBN} automatically deletes watchpoints that watch local -(automatic) variables, or expressions that involve such variables, when -they go out of scope, that is, when the execution leaves the block in -which these variables were defined. In particular, when the program -being debugged terminates, @emph{all} local variables go out of scope, -and so only watchpoints that watch global variables remain set. If you -rerun the program, you will need to set all such watchpoints again. One -way of doing that would be to set a code breakpoint at the entry to the -@code{main} function and when it breaks, set all the watchpoints. - -@quotation -@cindex watchpoints and threads -@cindex threads and watchpoints -@emph{Warning:} In multi-thread programs, watchpoints have only limited -usefulness. With the current watchpoint implementation, @value{GDBN} -can only watch the value of an expression @emph{in a single thread}. If -you are confident that the expression can only change due to the current -thread's activity (and if you are also confident that no other thread -can become current), then you can use watchpoints as usual. However, -@value{GDBN} may not notice when a non-current thread's activity changes -the expression. - -@c FIXME: this is almost identical to the previous paragraph. -@emph{HP-UX Warning:} In multi-thread programs, software watchpoints -have only limited usefulness. If @value{GDBN} creates a software -watchpoint, it can only watch the value of an expression @emph{in a -single thread}. If you are confident that the expression can only -change due to the current thread's activity (and if you are also -confident that no other thread can become current), then you can use -software watchpoints as usual. However, @value{GDBN} may not notice -when a non-current thread's activity changes the expression. (Hardware -watchpoints, in contrast, watch an expression in all threads.) -@end quotation - -@xref{set remote hardware-watchpoint-limit}. - -@node Set Catchpoints -@subsection Setting catchpoints -@cindex catchpoints, setting -@cindex exception handlers -@cindex event handling - -You can use @dfn{catchpoints} to cause the debugger to stop for certain -kinds of program events, such as C@t{++} exceptions or the loading of a -shared library. Use the @code{catch} command to set a catchpoint. - -@table @code -@kindex catch -@item catch @var{event} -Stop when @var{event} occurs. @var{event} can be any of the following: -@table @code -@item throw -@kindex catch throw -The throwing of a C@t{++} exception. - -@item catch -@kindex catch catch -The catching of a C@t{++} exception. - -@item exec -@kindex catch exec -A call to @code{exec}. This is currently only available for HP-UX. - -@item fork -@kindex catch fork -A call to @code{fork}. This is currently only available for HP-UX. - -@item vfork -@kindex catch vfork -A call to @code{vfork}. This is currently only available for HP-UX. - -@item load -@itemx load @var{libname} -@kindex catch load -The dynamic loading of any shared library, or the loading of the library -@var{libname}. This is currently only available for HP-UX. - -@item unload -@itemx unload @var{libname} -@kindex catch unload -The unloading of any dynamically loaded shared library, or the unloading -of the library @var{libname}. This is currently only available for HP-UX. -@end table - -@item tcatch @var{event} -Set a catchpoint that is enabled only for one stop. The catchpoint is -automatically deleted after the first time the event is caught. - -@end table - -Use the @code{info break} command to list the current catchpoints. - -There are currently some limitations to C@t{++} exception handling -(@code{catch throw} and @code{catch catch}) in @value{GDBN}: - -@itemize @bullet -@item -If you call a function interactively, @value{GDBN} normally returns -control to you when the function has finished executing. If the call -raises an exception, however, the call may bypass the mechanism that -returns control to you and cause your program either to abort or to -simply continue running until it hits a breakpoint, catches a signal -that @value{GDBN} is listening for, or exits. This is the case even if -you set a catchpoint for the exception; catchpoints on exceptions are -disabled within interactive calls. - -@item -You cannot raise an exception interactively. - -@item -You cannot install an exception handler interactively. -@end itemize - -@cindex raise exceptions -Sometimes @code{catch} is not the best way to debug exception handling: -if you need to know exactly where an exception is raised, it is better to -stop @emph{before} the exception handler is called, since that way you -can see the stack before any unwinding takes place. If you set a -breakpoint in an exception handler instead, it may not be easy to find -out where the exception was raised. - -To stop just before an exception handler is called, you need some -knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are -raised by calling a library function named @code{__raise_exception} -which has the following ANSI C interface: - -@smallexample - /* @var{addr} is where the exception identifier is stored. - @var{id} is the exception identifier. */ - void __raise_exception (void **addr, void *id); -@end smallexample - -@noindent -To make the debugger catch all exceptions before any stack -unwinding takes place, set a breakpoint on @code{__raise_exception} -(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}). - -With a conditional breakpoint (@pxref{Conditions, ,Break conditions}) -that depends on the value of @var{id}, you can stop your program when -a specific exception is raised. You can use multiple conditional -breakpoints to stop your program when any of a number of exceptions are -raised. - - -@node Delete Breaks -@subsection Deleting breakpoints - -@cindex clearing breakpoints, watchpoints, catchpoints -@cindex deleting breakpoints, watchpoints, catchpoints -It is often necessary to eliminate a breakpoint, watchpoint, or -catchpoint once it has done its job and you no longer want your program -to stop there. This is called @dfn{deleting} the breakpoint. A -breakpoint that has been deleted no longer exists; it is forgotten. - -With the @code{clear} command you can delete breakpoints according to -where they are in your program. With the @code{delete} command you can -delete individual breakpoints, watchpoints, or catchpoints by specifying -their breakpoint numbers. - -It is not necessary to delete a breakpoint to proceed past it. @value{GDBN} -automatically ignores breakpoints on the first instruction to be executed -when you continue execution without changing the execution address. - -@table @code -@kindex clear -@item clear -Delete any breakpoints at the next instruction to be executed in the -selected stack frame (@pxref{Selection, ,Selecting a frame}). When -the innermost frame is selected, this is a good way to delete a -breakpoint where your program just stopped. - -@item clear @var{function} -@itemx clear @var{filename}:@var{function} -Delete any breakpoints set at entry to the function @var{function}. - -@item clear @var{linenum} -@itemx clear @var{filename}:@var{linenum} -Delete any breakpoints set at or within the code of the specified line. - -@cindex delete breakpoints -@kindex delete -@kindex d @r{(@code{delete})} -@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} -Delete the breakpoints, watchpoints, or catchpoints of the breakpoint -ranges specified as arguments. If no argument is specified, delete all -breakpoints (@value{GDBN} asks confirmation, unless you have @code{set -confirm off}). You can abbreviate this command as @code{d}. -@end table - -@node Disabling -@subsection Disabling breakpoints - -@kindex disable breakpoints -@kindex enable breakpoints -Rather than deleting a breakpoint, watchpoint, or catchpoint, you might -prefer to @dfn{disable} it. This makes the breakpoint inoperative as if -it had been deleted, but remembers the information on the breakpoint so -that you can @dfn{enable} it again later. - -You disable and enable breakpoints, watchpoints, and catchpoints with -the @code{enable} and @code{disable} commands, optionally specifying one -or more breakpoint numbers as arguments. Use @code{info break} or -@code{info watch} to print a list of breakpoints, watchpoints, and -catchpoints if you do not know which numbers to use. - -A breakpoint, watchpoint, or catchpoint can have any of four different -states of enablement: - -@itemize @bullet -@item -Enabled. The breakpoint stops your program. A breakpoint set -with the @code{break} command starts out in this state. -@item -Disabled. The breakpoint has no effect on your program. -@item -Enabled once. The breakpoint stops your program, but then becomes -disabled. -@item -Enabled for deletion. The breakpoint stops your program, but -immediately after it does so it is deleted permanently. A breakpoint -set with the @code{tbreak} command starts out in this state. -@end itemize - -You can use the following commands to enable or disable breakpoints, -watchpoints, and catchpoints: - -@table @code -@kindex disable breakpoints -@kindex disable -@kindex dis @r{(@code{disable})} -@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} -Disable the specified breakpoints---or all breakpoints, if none are -listed. A disabled breakpoint has no effect but is not forgotten. All -options such as ignore-counts, conditions and commands are remembered in -case the breakpoint is enabled again later. You may abbreviate -@code{disable} as @code{dis}. - -@kindex enable breakpoints -@kindex enable -@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} -Enable the specified breakpoints (or all defined breakpoints). They -become effective once again in stopping your program. - -@item enable @r{[}breakpoints@r{]} once @var{range}@dots{} -Enable the specified breakpoints temporarily. @value{GDBN} disables any -of these breakpoints immediately after stopping your program. - -@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{} -Enable the specified breakpoints to work once, then die. @value{GDBN} -deletes any of these breakpoints as soon as your program stops there. -@end table - -@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is -@c confusing: tbreak is also initially enabled. -Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, -,Setting breakpoints}), breakpoints that you set are initially enabled; -subsequently, they become disabled or enabled only when you use one of -the commands above. (The command @code{until} can set and delete a -breakpoint of its own, but it does not change the state of your other -breakpoints; see @ref{Continuing and Stepping, ,Continuing and -stepping}.) - -@node Conditions -@subsection Break conditions -@cindex conditional breakpoints -@cindex breakpoint conditions - -@c FIXME what is scope of break condition expr? Context where wanted? -@c in particular for a watchpoint? -The simplest sort of breakpoint breaks every time your program reaches a -specified place. You can also specify a @dfn{condition} for a -breakpoint. A condition is just a Boolean expression in your -programming language (@pxref{Expressions, ,Expressions}). A breakpoint with -a condition evaluates the expression each time your program reaches it, -and your program stops only if the condition is @emph{true}. - -This is the converse of using assertions for program validation; in that -situation, you want to stop when the assertion is violated---that is, -when the condition is false. In C, if you want to test an assertion expressed -by the condition @var{assert}, you should set the condition -@samp{! @var{assert}} on the appropriate breakpoint. - -Conditions are also accepted for watchpoints; you may not need them, -since a watchpoint is inspecting the value of an expression anyhow---but -it might be simpler, say, to just set a watchpoint on a variable name, -and specify a condition that tests whether the new value is an interesting -one. - -Break conditions can have side effects, and may even call functions in -your program. This can be useful, for example, to activate functions -that log program progress, or to use your own print functions to -format special data structures. The effects are completely predictable -unless there is another enabled breakpoint at the same address. (In -that case, @value{GDBN} might see the other breakpoint first and stop your -program without checking the condition of this one.) Note that -breakpoint commands are usually more convenient and flexible than break -conditions for the -purpose of performing side effects when a breakpoint is reached -(@pxref{Break Commands, ,Breakpoint command lists}). - -Break conditions can be specified when a breakpoint is set, by using -@samp{if} in the arguments to the @code{break} command. @xref{Set -Breaks, ,Setting breakpoints}. They can also be changed at any time -with the @code{condition} command. - -You can also use the @code{if} keyword with the @code{watch} command. -The @code{catch} command does not recognize the @code{if} keyword; -@code{condition} is the only way to impose a further condition on a -catchpoint. - -@table @code -@kindex condition -@item condition @var{bnum} @var{expression} -Specify @var{expression} as the break condition for breakpoint, -watchpoint, or catchpoint number @var{bnum}. After you set a condition, -breakpoint @var{bnum} stops your program only if the value of -@var{expression} is true (nonzero, in C). When you use -@code{condition}, @value{GDBN} checks @var{expression} immediately for -syntactic correctness, and to determine whether symbols in it have -referents in the context of your breakpoint. If @var{expression} uses -symbols not referenced in the context of the breakpoint, @value{GDBN} -prints an error message: - -@smallexample -No symbol "foo" in current context. -@end smallexample - -@noindent -@value{GDBN} does -not actually evaluate @var{expression} at the time the @code{condition} -command (or a command that sets a breakpoint with a condition, like -@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}. - -@item condition @var{bnum} -Remove the condition from breakpoint number @var{bnum}. It becomes -an ordinary unconditional breakpoint. -@end table - -@cindex ignore count (of breakpoint) -A special case of a breakpoint condition is to stop only when the -breakpoint has been reached a certain number of times. This is so -useful that there is a special way to do it, using the @dfn{ignore -count} of the breakpoint. Every breakpoint has an ignore count, which -is an integer. Most of the time, the ignore count is zero, and -therefore has no effect. But if your program reaches a breakpoint whose -ignore count is positive, then instead of stopping, it just decrements -the ignore count by one and continues. As a result, if the ignore count -value is @var{n}, the breakpoint does not stop the next @var{n} times -your program reaches it. - -@table @code -@kindex ignore -@item ignore @var{bnum} @var{count} -Set the ignore count of breakpoint number @var{bnum} to @var{count}. -The next @var{count} times the breakpoint is reached, your program's -execution does not stop; other than to decrement the ignore count, @value{GDBN} -takes no action. - -To make the breakpoint stop the next time it is reached, specify -a count of zero. - -When you use @code{continue} to resume execution of your program from a -breakpoint, you can specify an ignore count directly as an argument to -@code{continue}, rather than using @code{ignore}. @xref{Continuing and -Stepping,,Continuing and stepping}. - -If a breakpoint has a positive ignore count and a condition, the -condition is not checked. Once the ignore count reaches zero, -@value{GDBN} resumes checking the condition. - -You could achieve the effect of the ignore count with a condition such -as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that -is decremented each time. @xref{Convenience Vars, ,Convenience -variables}. -@end table - -Ignore counts apply to breakpoints, watchpoints, and catchpoints. - - -@node Break Commands -@subsection Breakpoint command lists - -@cindex breakpoint commands -You can give any breakpoint (or watchpoint or catchpoint) a series of -commands to execute when your program stops due to that breakpoint. For -example, you might want to print the values of certain expressions, or -enable other breakpoints. - -@table @code -@kindex commands -@kindex end -@item commands @r{[}@var{bnum}@r{]} -@itemx @dots{} @var{command-list} @dots{} -@itemx end -Specify a list of commands for breakpoint number @var{bnum}. The commands -themselves appear on the following lines. Type a line containing just -@code{end} to terminate the commands. - -To remove all commands from a breakpoint, type @code{commands} and -follow it immediately with @code{end}; that is, give no commands. - -With no @var{bnum} argument, @code{commands} refers to the last -breakpoint, watchpoint, or catchpoint set (not to the breakpoint most -recently encountered). -@end table - -Pressing @key{RET} as a means of repeating the last @value{GDBN} command is -disabled within a @var{command-list}. - -You can use breakpoint commands to start your program up again. Simply -use the @code{continue} command, or @code{step}, or any other command -that resumes execution. - -Any other commands in the command list, after a command that resumes -execution, are ignored. This is because any time you resume execution -(even with a simple @code{next} or @code{step}), you may encounter -another breakpoint---which could have its own command list, leading to -ambiguities about which list to execute. - -@kindex silent -If the first command you specify in a command list is @code{silent}, the -usual message about stopping at a breakpoint is not printed. This may -be desirable for breakpoints that are to print a specific message and -then continue. If none of the remaining commands print anything, you -see no sign that the breakpoint was reached. @code{silent} is -meaningful only at the beginning of a breakpoint command list. - -The commands @code{echo}, @code{output}, and @code{printf} allow you to -print precisely controlled output, and are often useful in silent -breakpoints. @xref{Output, ,Commands for controlled output}. - -For example, here is how you could use breakpoint commands to print the -value of @code{x} at entry to @code{foo} whenever @code{x} is positive. - -@smallexample -break foo if x>0 -commands -silent -printf "x is %d\n",x -cont -end -@end smallexample - -One application for breakpoint commands is to compensate for one bug so -you can test for another. Put a breakpoint just after the erroneous line -of code, give it a condition to detect the case in which something -erroneous has been done, and give it commands to assign correct values -to any variables that need them. End with the @code{continue} command -so that your program does not stop, and start with the @code{silent} -command so that no output is produced. Here is an example: - -@smallexample -break 403 -commands -silent -set x = y + 4 -cont -end -@end smallexample - -@node Breakpoint Menus -@subsection Breakpoint menus -@cindex overloading -@cindex symbol overloading - -Some programming languages (notably C@t{++} and Objective-C) permit a -single function name -to be defined several times, for application in different contexts. -This is called @dfn{overloading}. When a function name is overloaded, -@samp{break @var{function}} is not enough to tell @value{GDBN} where you want -a breakpoint. If you realize this is a problem, you can use -something like @samp{break @var{function}(@var{types})} to specify which -particular version of the function you want. Otherwise, @value{GDBN} offers -you a menu of numbered choices for different possible breakpoints, and -waits for your selection with the prompt @samp{>}. The first two -options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1} -sets a breakpoint at each definition of @var{function}, and typing -@kbd{0} aborts the @code{break} command without setting any new -breakpoints. - -For example, the following session excerpt shows an attempt to set a -breakpoint at the overloaded symbol @code{String::after}. -We choose three particular definitions of that function name: - -@c FIXME! This is likely to change to show arg type lists, at least -@smallexample -@group -(@value{GDBP}) b String::after -[0] cancel -[1] all -[2] file:String.cc; line number:867 -[3] file:String.cc; line number:860 -[4] file:String.cc; line number:875 -[5] file:String.cc; line number:853 -[6] file:String.cc; line number:846 -[7] file:String.cc; line number:735 -> 2 4 6 -Breakpoint 1 at 0xb26c: file String.cc, line 867. -Breakpoint 2 at 0xb344: file String.cc, line 875. -Breakpoint 3 at 0xafcc: file String.cc, line 846. -Multiple breakpoints were set. -Use the "delete" command to delete unwanted - breakpoints. -(@value{GDBP}) -@end group -@end smallexample - -@c @ifclear BARETARGET -@node Error in Breakpoints -@subsection ``Cannot insert breakpoints'' -@c -@c FIXME!! 14/6/95 Is there a real example of this? Let's use it. -@c -Under some operating systems, breakpoints cannot be used in a program if -any other process is running that program. In this situation, -attempting to run or continue a program with a breakpoint causes -@value{GDBN} to print an error message: - -@smallexample -Cannot insert breakpoints. -The same program may be running in another process. -@end smallexample - -When this happens, you have three ways to proceed: - -@enumerate -@item -Remove or disable the breakpoints, then continue. - -@item -Suspend @value{GDBN}, and copy the file containing your program to a new -name. Resume @value{GDBN} and use the @code{exec-file} command to specify -that @value{GDBN} should run your program under that name. -Then start your program again. - -@item -Relink your program so that the text segment is nonsharable, using the -linker option @samp{-N}. The operating system limitation may not apply -to nonsharable executables. -@end enumerate -@c @end ifclear - -A similar message can be printed if you request too many active -hardware-assisted breakpoints and watchpoints: - -@c FIXME: the precise wording of this message may change; the relevant -@c source change is not committed yet (Sep 3, 1999). -@smallexample -Stopped; cannot insert breakpoints. -You may have requested too many hardware breakpoints and watchpoints. -@end smallexample - -@noindent -This message is printed when you attempt to resume the program, since -only then @value{GDBN} knows exactly how many hardware breakpoints and -watchpoints it needs to insert. - -When this message is printed, you need to disable or remove some of the -hardware-assisted breakpoints and watchpoints, and then continue. - -@node Breakpoint related warnings -@subsection ``Breakpoint address adjusted...'' -@cindex breakpoint address adjusted - -Some processor architectures place constraints on the addresses at -which breakpoints may be placed. For architectures thus constrained, -@value{GDBN} will attempt to adjust the breakpoint's address to comply -with the constraints dictated by the architecture. - -One example of such an architecture is the Fujitsu FR-V. The FR-V is -a VLIW architecture in which a number of RISC-like instructions may be -bundled together for parallel execution. The FR-V architecture -constrains the location of a breakpoint instruction within such a -bundle to the instruction with the lowest address. @value{GDBN} -honors this constraint by adjusting a breakpoint's address to the -first in the bundle. - -It is not uncommon for optimized code to have bundles which contain -instructions from different source statements, thus it may happen that -a breakpoint's address will be adjusted from one source statement to -another. Since this adjustment may significantly alter @value{GDBN}'s -breakpoint related behavior from what the user expects, a warning is -printed when the breakpoint is first set and also when the breakpoint -is hit. - -A warning like the one below is printed when setting a breakpoint -that's been subject to address adjustment: - -@smallexample -warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. -@end smallexample - -Such warnings are printed both for user settable and @value{GDBN}'s -internal breakpoints. If you see one of these warnings, you should -verify that a breakpoint set at the adjusted address will have the -desired affect. If not, the breakpoint in question may be removed and -other breakpoints may be set which will have the desired behavior. -E.g., it may be sufficient to place the breakpoint at a later -instruction. A conditional breakpoint may also be useful in some -cases to prevent the breakpoint from triggering too often. - -@value{GDBN} will also issue a warning when stopping at one of these -adjusted breakpoints: - -@smallexample -warning: Breakpoint 1 address previously adjusted from 0x00010414 -to 0x00010410. -@end smallexample - -When this warning is encountered, it may be too late to take remedial -action except in cases where the breakpoint is hit earlier or more -frequently than expected. - -@node Continuing and Stepping -@section Continuing and stepping - -@cindex stepping -@cindex continuing -@cindex resuming execution -@dfn{Continuing} means resuming program execution until your program -completes normally. In contrast, @dfn{stepping} means executing just -one more ``step'' of your program, where ``step'' may mean either one -line of source code, or one machine instruction (depending on what -particular command you use). Either when continuing or when stepping, -your program may stop even sooner, due to a breakpoint or a signal. (If -it stops due to a signal, you may want to use @code{handle}, or use -@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.) - -@table @code -@kindex continue -@kindex c @r{(@code{continue})} -@kindex fg @r{(resume foreground execution)} -@item continue @r{[}@var{ignore-count}@r{]} -@itemx c @r{[}@var{ignore-count}@r{]} -@itemx fg @r{[}@var{ignore-count}@r{]} -Resume program execution, at the address where your program last stopped; -any breakpoints set at that address are bypassed. The optional argument -@var{ignore-count} allows you to specify a further number of times to -ignore a breakpoint at this location; its effect is like that of -@code{ignore} (@pxref{Conditions, ,Break conditions}). - -The argument @var{ignore-count} is meaningful only when your program -stopped due to a breakpoint. At other times, the argument to -@code{continue} is ignored. - -The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the -debugged program is deemed to be the foreground program) are provided -purely for convenience, and have exactly the same behavior as -@code{continue}. -@end table - -To resume execution at a different place, you can use @code{return} -(@pxref{Returning, ,Returning from a function}) to go back to the -calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a -different address}) to go to an arbitrary location in your program. - -A typical technique for using stepping is to set a breakpoint -(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the -beginning of the function or the section of your program where a problem -is believed to lie, run your program until it stops at that breakpoint, -and then step through the suspect area, examining the variables that are -interesting, until you see the problem happen. - -@table @code -@kindex step -@kindex s @r{(@code{step})} -@item step -Continue running your program until control reaches a different source -line, then stop it and return control to @value{GDBN}. This command is -abbreviated @code{s}. - -@quotation -@c "without debugging information" is imprecise; actually "without line -@c numbers in the debugging information". (gcc -g1 has debugging info but -@c not line numbers). But it seems complex to try to make that -@c distinction here. -@emph{Warning:} If you use the @code{step} command while control is -within a function that was compiled without debugging information, -execution proceeds until control reaches a function that does have -debugging information. Likewise, it will not step into a function which -is compiled without debugging information. To step through functions -without debugging information, use the @code{stepi} command, described -below. -@end quotation - -The @code{step} command only stops at the first instruction of a source -line. This prevents the multiple stops that could otherwise occur in -@code{switch} statements, @code{for} loops, etc. @code{step} continues -to stop if a function that has debugging information is called within -the line. In other words, @code{step} @emph{steps inside} any functions -called within the line. - -Also, the @code{step} command only enters a function if there is line -number information for the function. Otherwise it acts like the -@code{next} command. This avoids problems when using @code{cc -gl} -on MIPS machines. Previously, @code{step} entered subroutines if there -was any debugging information about the routine. - -@item step @var{count} -Continue running as in @code{step}, but do so @var{count} times. If a -breakpoint is reached, or a signal not related to stepping occurs before -@var{count} steps, stepping stops right away. - -@kindex next -@kindex n @r{(@code{next})} -@item next @r{[}@var{count}@r{]} -Continue to the next source line in the current (innermost) stack frame. -This is similar to @code{step}, but function calls that appear within -the line of code are executed without stopping. Execution stops when -control reaches a different line of code at the original stack level -that was executing when you gave the @code{next} command. This command -is abbreviated @code{n}. - -An argument @var{count} is a repeat count, as for @code{step}. - - -@c FIX ME!! Do we delete this, or is there a way it fits in with -@c the following paragraph? --- Vctoria -@c -@c @code{next} within a function that lacks debugging information acts like -@c @code{step}, but any function calls appearing within the code of the -@c function are executed without stopping. - -The @code{next} command only stops at the first instruction of a -source line. This prevents multiple stops that could otherwise occur in -@code{switch} statements, @code{for} loops, etc. - -@kindex set step-mode -@item set step-mode -@cindex functions without line info, and stepping -@cindex stepping into functions with no line info -@itemx set step-mode on -The @code{set step-mode on} command causes the @code{step} command to -stop at the first instruction of a function which contains no debug line -information rather than stepping over it. - -This is useful in cases where you may be interested in inspecting the -machine instructions of a function which has no symbolic info and do not -want @value{GDBN} to automatically skip over this function. - -@item set step-mode off -Causes the @code{step} command to step over any functions which contains no -debug information. This is the default. - -@kindex finish -@item finish -Continue running until just after function in the selected stack frame -returns. Print the returned value (if any). - -Contrast this with the @code{return} command (@pxref{Returning, -,Returning from a function}). - -@kindex until -@kindex u @r{(@code{until})} -@item until -@itemx u -Continue running until a source line past the current line, in the -current stack frame, is reached. This command is used to avoid single -stepping through a loop more than once. It is like the @code{next} -command, except that when @code{until} encounters a jump, it -automatically continues execution until the program counter is greater -than the address of the jump. - -This means that when you reach the end of a loop after single stepping -though it, @code{until} makes your program continue execution until it -exits the loop. In contrast, a @code{next} command at the end of a loop -simply steps back to the beginning of the loop, which forces you to step -through the next iteration. - -@code{until} always stops your program if it attempts to exit the current -stack frame. - -@code{until} may produce somewhat counterintuitive results if the order -of machine code does not match the order of the source lines. For -example, in the following excerpt from a debugging session, the @code{f} -(@code{frame}) command shows that execution is stopped at line -@code{206}; yet when we use @code{until}, we get to line @code{195}: - -@smallexample -(@value{GDBP}) f -#0 main (argc=4, argv=0xf7fffae8) at m4.c:206 -206 expand_input(); -(@value{GDBP}) until -195 for ( ; argc > 0; NEXTARG) @{ -@end smallexample - -This happened because, for execution efficiency, the compiler had -generated code for the loop closure test at the end, rather than the -start, of the loop---even though the test in a C @code{for}-loop is -written before the body of the loop. The @code{until} command appeared -to step back to the beginning of the loop when it advanced to this -expression; however, it has not really gone to an earlier -statement---not in terms of the actual machine code. - -@code{until} with no argument works by means of single -instruction stepping, and hence is slower than @code{until} with an -argument. - -@item until @var{location} -@itemx u @var{location} -Continue running your program until either the specified location is -reached, or the current stack frame returns. @var{location} is any of -the forms of argument acceptable to @code{break} (@pxref{Set Breaks, -,Setting breakpoints}). This form of the command uses breakpoints, and -hence is quicker than @code{until} without an argument. The specified -location is actually reached only if it is in the current frame. This -implies that @code{until} can be used to skip over recursive function -invocations. For instance in the code below, if the current location is -line @code{96}, issuing @code{until 99} will execute the program up to -line @code{99} in the same invocation of factorial, i.e. after the inner -invocations have returned. - -@smallexample -94 int factorial (int value) -95 @{ -96 if (value > 1) @{ -97 value *= factorial (value - 1); -98 @} -99 return (value); -100 @} -@end smallexample - - -@kindex advance @var{location} -@itemx advance @var{location} -Continue running the program up to the given location. An argument is -required, anything of the same form as arguments for the @code{break} -command. Execution will also stop upon exit from the current stack -frame. This command is similar to @code{until}, but @code{advance} will -not skip over recursive function calls, and the target location doesn't -have to be in the same frame as the current one. - - -@kindex stepi -@kindex si @r{(@code{stepi})} -@item stepi -@itemx stepi @var{arg} -@itemx si -Execute one machine instruction, then stop and return to the debugger. - -It is often useful to do @samp{display/i $pc} when stepping by machine -instructions. This makes @value{GDBN} automatically display the next -instruction to be executed, each time your program stops. @xref{Auto -Display,, Automatic display}. - -An argument is a repeat count, as in @code{step}. - -@need 750 -@kindex nexti -@kindex ni @r{(@code{nexti})} -@item nexti -@itemx nexti @var{arg} -@itemx ni -Execute one machine instruction, but if it is a function call, -proceed until the function returns. - -An argument is a repeat count, as in @code{next}. -@end table - -@node Signals -@section Signals -@cindex signals - -A signal is an asynchronous event that can happen in a program. The -operating system defines the possible kinds of signals, and gives each -kind a name and a number. For example, in Unix @code{SIGINT} is the -signal a program gets when you type an interrupt character (often @kbd{C-c}); -@code{SIGSEGV} is the signal a program gets from referencing a place in -memory far away from all the areas in use; @code{SIGALRM} occurs when -the alarm clock timer goes off (which happens only if your program has -requested an alarm). - -@cindex fatal signals -Some signals, including @code{SIGALRM}, are a normal part of the -functioning of your program. Others, such as @code{SIGSEGV}, indicate -errors; these signals are @dfn{fatal} (they kill your program immediately) if the -program has not specified in advance some other way to handle the signal. -@code{SIGINT} does not indicate an error in your program, but it is normally -fatal so it can carry out the purpose of the interrupt: to kill the program. - -@value{GDBN} has the ability to detect any occurrence of a signal in your -program. You can tell @value{GDBN} in advance what to do for each kind of -signal. - -@cindex handling signals -Normally, @value{GDBN} is set up to let the non-erroneous signals like -@code{SIGALRM} be silently passed to your program -(so as not to interfere with their role in the program's functioning) -but to stop your program immediately whenever an error signal happens. -You can change these settings with the @code{handle} command. - -@table @code -@kindex info signals -@item info signals -@itemx info handle -Print a table of all the kinds of signals and how @value{GDBN} has been told to -handle each one. You can use this to see the signal numbers of all -the defined types of signals. - -@code{info handle} is an alias for @code{info signals}. - -@kindex handle -@item handle @var{signal} @var{keywords}@dots{} -Change the way @value{GDBN} handles signal @var{signal}. @var{signal} -can be the number of a signal or its name (with or without the -@samp{SIG} at the beginning); a list of signal numbers of the form -@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the -known signals. The @var{keywords} say what change to make. -@end table - -@c @group -The keywords allowed by the @code{handle} command can be abbreviated. -Their full names are: - -@table @code -@item nostop -@value{GDBN} should not stop your program when this signal happens. It may -still print a message telling you that the signal has come in. - -@item stop -@value{GDBN} should stop your program when this signal happens. This implies -the @code{print} keyword as well. - -@item print -@value{GDBN} should print a message when this signal happens. - -@item noprint -@value{GDBN} should not mention the occurrence of the signal at all. This -implies the @code{nostop} keyword as well. - -@item pass -@itemx noignore -@value{GDBN} should allow your program to see this signal; your program -can handle the signal, or else it may terminate if the signal is fatal -and not handled. @code{pass} and @code{noignore} are synonyms. - -@item nopass -@itemx ignore -@value{GDBN} should not allow your program to see this signal. -@code{nopass} and @code{ignore} are synonyms. -@end table -@c @end group - -When a signal stops your program, the signal is not visible to the -program until you -continue. Your program sees the signal then, if @code{pass} is in -effect for the signal in question @emph{at that time}. In other words, -after @value{GDBN} reports a signal, you can use the @code{handle} -command with @code{pass} or @code{nopass} to control whether your -program sees that signal when you continue. - -The default is set to @code{nostop}, @code{noprint}, @code{pass} for -non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and -@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the -erroneous signals. - -You can also use the @code{signal} command to prevent your program from -seeing a signal, or cause it to see a signal it normally would not see, -or to give it any signal at any time. For example, if your program stopped -due to some sort of memory reference error, you might store correct -values into the erroneous variables and continue, hoping to see more -execution; but your program would probably terminate immediately as -a result of the fatal signal once it saw the signal. To prevent this, -you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your -program a signal}. - -@node Thread Stops -@section Stopping and starting multi-thread programs - -When your program has multiple threads (@pxref{Threads,, Debugging -programs with multiple threads}), you can choose whether to set -breakpoints on all threads, or on a particular thread. - -@table @code -@cindex breakpoints and threads -@cindex thread breakpoints -@kindex break @dots{} thread @var{threadno} -@item break @var{linespec} thread @var{threadno} -@itemx break @var{linespec} thread @var{threadno} if @dots{} -@var{linespec} specifies source lines; there are several ways of -writing them, but the effect is always to specify some source line. - -Use the qualifier @samp{thread @var{threadno}} with a breakpoint command -to specify that you only want @value{GDBN} to stop the program when a -particular thread reaches this breakpoint. @var{threadno} is one of the -numeric thread identifiers assigned by @value{GDBN}, shown in the first -column of the @samp{info threads} display. - -If you do not specify @samp{thread @var{threadno}} when you set a -breakpoint, the breakpoint applies to @emph{all} threads of your -program. - -You can use the @code{thread} qualifier on conditional breakpoints as -well; in this case, place @samp{thread @var{threadno}} before the -breakpoint condition, like this: - -@smallexample -(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim -@end smallexample - -@end table - -@cindex stopped threads -@cindex threads, stopped -Whenever your program stops under @value{GDBN} for any reason, -@emph{all} threads of execution stop, not just the current thread. This -allows you to examine the overall state of the program, including -switching between threads, without worrying that things may change -underfoot. - -@cindex thread breakpoints and system calls -@cindex system calls and thread breakpoints -@cindex premature return from system calls -There is an unfortunate side effect. If one thread stops for a -breakpoint, or for some other reason, and another thread is blocked in a -system call, then the system call may return prematurely. This is a -consequence of the interaction between multiple threads and the signals -that @value{GDBN} uses to implement breakpoints and other events that -stop execution. - -To handle this problem, your program should check the return value of -each system call and react appropriately. This is good programming -style anyways. - -For example, do not write code like this: - -@smallexample - sleep (10); -@end smallexample - -The call to @code{sleep} will return early if a different thread stops -at a breakpoint or for some other reason. - -Instead, write this: - -@smallexample - int unslept = 10; - while (unslept > 0) - unslept = sleep (unslept); -@end smallexample - -A system call is allowed to return early, so the system is still -conforming to its specification. But @value{GDBN} does cause your -multi-threaded program to behave differently than it would without -@value{GDBN}. - -Also, @value{GDBN} uses internal breakpoints in the thread library to -monitor certain events such as thread creation and thread destruction. -When such an event happens, a system call in another thread may return -prematurely, even though your program does not appear to stop. - -@cindex continuing threads -@cindex threads, continuing -Conversely, whenever you restart the program, @emph{all} threads start -executing. @emph{This is true even when single-stepping} with commands -like @code{step} or @code{next}. - -In particular, @value{GDBN} cannot single-step all threads in lockstep. -Since thread scheduling is up to your debugging target's operating -system (not controlled by @value{GDBN}), other threads may -execute more than one statement while the current thread completes a -single step. Moreover, in general other threads stop in the middle of a -statement, rather than at a clean statement boundary, when the program -stops. - -You might even find your program stopped in another thread after -continuing or even single-stepping. This happens whenever some other -thread runs into a breakpoint, a signal, or an exception before the -first thread completes whatever you requested. - -On some OSes, you can lock the OS scheduler and thus allow only a single -thread to run. - -@table @code -@item set scheduler-locking @var{mode} -Set the scheduler locking mode. If it is @code{off}, then there is no -locking and any thread may run at any time. If @code{on}, then only the -current thread may run when the inferior is resumed. The @code{step} -mode optimizes for single-stepping. It stops other threads from -``seizing the prompt'' by preempting the current thread while you are -stepping. Other threads will only rarely (or never) get a chance to run -when you step. They are more likely to run when you @samp{next} over a -function call, and they are completely free to run when you use commands -like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another -thread hits a breakpoint during its timeslice, they will never steal the -@value{GDBN} prompt away from the thread that you are debugging. - -@item show scheduler-locking -Display the current scheduler locking mode. -@end table - - -@node Stack -@chapter Examining the Stack - -When your program has stopped, the first thing you need to know is where it -stopped and how it got there. - -@cindex call stack -Each time your program performs a function call, information about the call -is generated. -That information includes the location of the call in your program, -the arguments of the call, -and the local variables of the function being called. -The information is saved in a block of data called a @dfn{stack frame}. -The stack frames are allocated in a region of memory called the @dfn{call -stack}. - -When your program stops, the @value{GDBN} commands for examining the -stack allow you to see all of this information. - -@cindex selected frame -One of the stack frames is @dfn{selected} by @value{GDBN} and many -@value{GDBN} commands refer implicitly to the selected frame. In -particular, whenever you ask @value{GDBN} for the value of a variable in -your program, the value is found in the selected frame. There are -special @value{GDBN} commands to select whichever frame you are -interested in. @xref{Selection, ,Selecting a frame}. - -When your program stops, @value{GDBN} automatically selects the -currently executing frame and describes it briefly, similar to the -@code{frame} command (@pxref{Frame Info, ,Information about a frame}). - -@menu -* Frames:: Stack frames -* Backtrace:: Backtraces -* Selection:: Selecting a frame -* Frame Info:: Information on a frame - -@end menu - -@node Frames -@section Stack frames - -@cindex frame, definition -@cindex stack frame -The call stack is divided up into contiguous pieces called @dfn{stack -frames}, or @dfn{frames} for short; each frame is the data associated -with one call to one function. The frame contains the arguments given -to the function, the function's local variables, and the address at -which the function is executing. - -@cindex initial frame -@cindex outermost frame -@cindex innermost frame -When your program is started, the stack has only one frame, that of the -function @code{main}. This is called the @dfn{initial} frame or the -@dfn{outermost} frame. Each time a function is called, a new frame is -made. Each time a function returns, the frame for that function invocation -is eliminated. If a function is recursive, there can be many frames for -the same function. The frame for the function in which execution is -actually occurring is called the @dfn{innermost} frame. This is the most -recently created of all the stack frames that still exist. - -@cindex frame pointer -Inside your program, stack frames are identified by their addresses. A -stack frame consists of many bytes, each of which has its own address; each -kind of computer has a convention for choosing one byte whose -address serves as the address of the frame. Usually this address is kept -in a register called the @dfn{frame pointer register} while execution is -going on in that frame. - -@cindex frame number -@value{GDBN} assigns numbers to all existing stack frames, starting with -zero for the innermost frame, one for the frame that called it, -and so on upward. These numbers do not really exist in your program; -they are assigned by @value{GDBN} to give you a way of designating stack -frames in @value{GDBN} commands. - -@c The -fomit-frame-pointer below perennially causes hbox overflow -@c underflow problems. -@cindex frameless execution -Some compilers provide a way to compile functions so that they operate -without stack frames. (For example, the @value{GCC} option -@smallexample -@samp{-fomit-frame-pointer} -@end smallexample -generates functions without a frame.) -This is occasionally done with heavily used library functions to save -the frame setup time. @value{GDBN} has limited facilities for dealing -with these function invocations. If the innermost function invocation -has no stack frame, @value{GDBN} nevertheless regards it as though -it had a separate frame, which is numbered zero as usual, allowing -correct tracing of the function call chain. However, @value{GDBN} has -no provision for frameless functions elsewhere in the stack. - -@table @code -@kindex frame@r{, command} -@cindex current stack frame -@item frame @var{args} -The @code{frame} command allows you to move from one stack frame to another, -and to print the stack frame you select. @var{args} may be either the -address of the frame or the stack frame number. Without an argument, -@code{frame} prints the current stack frame. - -@kindex select-frame -@cindex selecting frame silently -@item select-frame -The @code{select-frame} command allows you to move from one stack frame -to another without printing the frame. This is the silent version of -@code{frame}. -@end table - -@node Backtrace -@section Backtraces - -@cindex backtraces -@cindex tracebacks -@cindex stack traces -A backtrace is a summary of how your program got where it is. It shows one -line per frame, for many frames, starting with the currently executing -frame (frame zero), followed by its caller (frame one), and on up the -stack. - -@table @code -@kindex backtrace -@kindex bt @r{(@code{backtrace})} -@item backtrace -@itemx bt -Print a backtrace of the entire stack: one line per frame for all -frames in the stack. - -You can stop the backtrace at any time by typing the system interrupt -character, normally @kbd{C-c}. - -@item backtrace @var{n} -@itemx bt @var{n} -Similar, but print only the innermost @var{n} frames. - -@item backtrace -@var{n} -@itemx bt -@var{n} -Similar, but print only the outermost @var{n} frames. -@end table - -@kindex where -@kindex info stack -@kindex info s @r{(@code{info stack})} -The names @code{where} and @code{info stack} (abbreviated @code{info s}) -are additional aliases for @code{backtrace}. - -Each line in the backtrace shows the frame number and the function name. -The program counter value is also shown---unless you use @code{set -print address off}. The backtrace also shows the source file name and -line number, as well as the arguments to the function. The program -counter value is omitted if it is at the beginning of the code for that -line number. - -Here is an example of a backtrace. It was made with the command -@samp{bt 3}, so it shows the innermost three frames. - -@smallexample -@group -#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) - at builtin.c:993 -#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 -#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) - at macro.c:71 -(More stack frames follow...) -@end group -@end smallexample - -@noindent -The display for frame zero does not begin with a program counter -value, indicating that your program has stopped at the beginning of the -code for line @code{993} of @code{builtin.c}. - -@kindex set backtrace past-main -@kindex show backtrace past-main -@kindex set backtrace limit -@kindex show backtrace limit - -Most programs have a standard user entry point---a place where system -libraries and startup code transition into user code. For C this is -@code{main}. When @value{GDBN} finds the entry function in a backtrace -it will terminate the backtrace, to avoid tracing into highly -system-specific (and generally uninteresting) code. - -If you need to examine the startup code, or limit the number of levels -in a backtrace, you can change this behavior: - -@table @code -@item set backtrace past-main -@itemx set backtrace past-main on -Backtraces will continue past the user entry point. - -@item set backtrace past-main off -Backtraces will stop when they encounter the user entry point. This is the -default. - -@item show backtrace past-main -Display the current user entry point backtrace policy. - -@item set backtrace limit @var{n} -@itemx set backtrace limit 0 -@cindex backtrace limit -Limit the backtrace to @var{n} levels. A value of zero means -unlimited. - -@item show backtrace limit -Display the current limit on backtrace levels. -@end table - -@node Selection -@section Selecting a frame - -Most commands for examining the stack and other data in your program work on -whichever stack frame is selected at the moment. Here are the commands for -selecting a stack frame; all of them finish by printing a brief description -of the stack frame just selected. - -@table @code -@kindex frame@r{, selecting} -@kindex f @r{(@code{frame})} -@item frame @var{n} -@itemx f @var{n} -Select frame number @var{n}. Recall that frame zero is the innermost -(currently executing) frame, frame one is the frame that called the -innermost one, and so on. The highest-numbered frame is the one for -@code{main}. - -@item frame @var{addr} -@itemx f @var{addr} -Select the frame at address @var{addr}. This is useful mainly if the -chaining of stack frames has been damaged by a bug, making it -impossible for @value{GDBN} to assign numbers properly to all frames. In -addition, this can be useful when your program has multiple stacks and -switches between them. - -On the SPARC architecture, @code{frame} needs two addresses to -select an arbitrary frame: a frame pointer and a stack pointer. - -On the MIPS and Alpha architecture, it needs two addresses: a stack -pointer and a program counter. - -On the 29k architecture, it needs three addresses: a register stack -pointer, a program counter, and a memory stack pointer. -@c note to future updaters: this is conditioned on a flag -@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date -@c as of 27 Jan 1994. - -@kindex up -@item up @var{n} -Move @var{n} frames up the stack. For positive numbers @var{n}, this -advances toward the outermost frame, to higher frame numbers, to frames -that have existed longer. @var{n} defaults to one. - -@kindex down -@kindex do @r{(@code{down})} -@item down @var{n} -Move @var{n} frames down the stack. For positive numbers @var{n}, this -advances toward the innermost frame, to lower frame numbers, to frames -that were created more recently. @var{n} defaults to one. You may -abbreviate @code{down} as @code{do}. -@end table - -All of these commands end by printing two lines of output describing the -frame. The first line shows the frame number, the function name, the -arguments, and the source file and line number of execution in that -frame. The second line shows the text of that source line. - -@need 1000 -For example: - -@smallexample -@group -(@value{GDBP}) up -#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) - at env.c:10 -10 read_input_file (argv[i]); -@end group -@end smallexample - -After such a printout, the @code{list} command with no arguments -prints ten lines centered on the point of execution in the frame. -You can also edit the program at the point of execution with your favorite -editing program by typing @code{edit}. -@xref{List, ,Printing source lines}, -for details. - -@table @code -@kindex down-silently -@kindex up-silently -@item up-silently @var{n} -@itemx down-silently @var{n} -These two commands are variants of @code{up} and @code{down}, -respectively; they differ in that they do their work silently, without -causing display of the new frame. They are intended primarily for use -in @value{GDBN} command scripts, where the output might be unnecessary and -distracting. -@end table - -@node Frame Info -@section Information about a frame - -There are several other commands to print information about the selected -stack frame. - -@table @code -@item frame -@itemx f -When used without any argument, this command does not change which -frame is selected, but prints a brief description of the currently -selected stack frame. It can be abbreviated @code{f}. With an -argument, this command is used to select a stack frame. -@xref{Selection, ,Selecting a frame}. - -@kindex info frame -@kindex info f @r{(@code{info frame})} -@item info frame -@itemx info f -This command prints a verbose description of the selected stack frame, -including: - -@itemize @bullet -@item -the address of the frame -@item -the address of the next frame down (called by this frame) -@item -the address of the next frame up (caller of this frame) -@item -the language in which the source code corresponding to this frame is written -@item -the address of the frame's arguments -@item -the address of the frame's local variables -@item -the program counter saved in it (the address of execution in the caller frame) -@item -which registers were saved in the frame -@end itemize - -@noindent The verbose description is useful when -something has gone wrong that has made the stack format fail to fit -the usual conventions. - -@item info frame @var{addr} -@itemx info f @var{addr} -Print a verbose description of the frame at address @var{addr}, without -selecting that frame. The selected frame remains unchanged by this -command. This requires the same kind of address (more than one for some -architectures) that you specify in the @code{frame} command. -@xref{Selection, ,Selecting a frame}. - -@kindex info args -@item info args -Print the arguments of the selected frame, each on a separate line. - -@item info locals -@kindex info locals -Print the local variables of the selected frame, each on a separate -line. These are all variables (declared either static or automatic) -accessible at the point of execution of the selected frame. - -@kindex info catch -@cindex catch exceptions, list active handlers -@cindex exception handlers, how to list -@item info catch -Print a list of all the exception handlers that are active in the -current stack frame at the current point of execution. To see other -exception handlers, visit the associated frame (using the @code{up}, -@code{down}, or @code{frame} commands); then type @code{info catch}. -@xref{Set Catchpoints, , Setting catchpoints}. - -@end table - - -@node Source -@chapter Examining Source Files - -@value{GDBN} can print parts of your program's source, since the debugging -information recorded in the program tells @value{GDBN} what source files were -used to build it. When your program stops, @value{GDBN} spontaneously prints -the line where it stopped. Likewise, when you select a stack frame -(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where -execution in that frame has stopped. You can print other portions of -source files by explicit command. - -If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may -prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using -@value{GDBN} under @sc{gnu} Emacs}. - -@menu -* List:: Printing source lines -* Edit:: Editing source files -* Search:: Searching source files -* Source Path:: Specifying source directories -* Machine Code:: Source and machine code -@end menu - -@node List -@section Printing source lines - -@kindex list -@kindex l @r{(@code{list})} -To print lines from a source file, use the @code{list} command -(abbreviated @code{l}). By default, ten lines are printed. -There are several ways to specify what part of the file you want to print. - -Here are the forms of the @code{list} command most commonly used: - -@table @code -@item list @var{linenum} -Print lines centered around line number @var{linenum} in the -current source file. - -@item list @var{function} -Print lines centered around the beginning of function -@var{function}. - -@item list -Print more lines. If the last lines printed were printed with a -@code{list} command, this prints lines following the last lines -printed; however, if the last line printed was a solitary line printed -as part of displaying a stack frame (@pxref{Stack, ,Examining the -Stack}), this prints lines centered around that line. - -@item list - -Print lines just before the lines last printed. -@end table - -By default, @value{GDBN} prints ten source lines with any of these forms of -the @code{list} command. You can change this using @code{set listsize}: - -@table @code -@kindex set listsize -@item set listsize @var{count} -Make the @code{list} command display @var{count} source lines (unless -the @code{list} argument explicitly specifies some other number). - -@kindex show listsize -@item show listsize -Display the number of lines that @code{list} prints. -@end table - -Repeating a @code{list} command with @key{RET} discards the argument, -so it is equivalent to typing just @code{list}. This is more useful -than listing the same lines again. An exception is made for an -argument of @samp{-}; that argument is preserved in repetition so that -each repetition moves up in the source file. - -@cindex linespec -In general, the @code{list} command expects you to supply zero, one or two -@dfn{linespecs}. Linespecs specify source lines; there are several ways -of writing them, but the effect is always to specify some source line. -Here is a complete description of the possible arguments for @code{list}: - -@table @code -@item list @var{linespec} -Print lines centered around the line specified by @var{linespec}. - -@item list @var{first},@var{last} -Print lines from @var{first} to @var{last}. Both arguments are -linespecs. - -@item list ,@var{last} -Print lines ending with @var{last}. - -@item list @var{first}, -Print lines starting with @var{first}. - -@item list + -Print lines just after the lines last printed. - -@item list - -Print lines just before the lines last printed. - -@item list -As described in the preceding table. -@end table - -Here are the ways of specifying a single source line---all the -kinds of linespec. - -@table @code -@item @var{number} -Specifies line @var{number} of the current source file. -When a @code{list} command has two linespecs, this refers to -the same source file as the first linespec. - -@item +@var{offset} -Specifies the line @var{offset} lines after the last line printed. -When used as the second linespec in a @code{list} command that has -two, this specifies the line @var{offset} lines down from the -first linespec. - -@item -@var{offset} -Specifies the line @var{offset} lines before the last line printed. - -@item @var{filename}:@var{number} -Specifies line @var{number} in the source file @var{filename}. - -@item @var{function} -Specifies the line that begins the body of the function @var{function}. -For example: in C, this is the line with the open brace. - -@item @var{filename}:@var{function} -Specifies the line of the open-brace that begins the body of the -function @var{function} in the file @var{filename}. You only need the -file name with a function name to avoid ambiguity when there are -identically named functions in different source files. - -@item *@var{address} -Specifies the line containing the program address @var{address}. -@var{address} may be any expression. -@end table - -@node Edit -@section Editing source files -@cindex editing source files - -@kindex edit -@kindex e @r{(@code{edit})} -To edit the lines in a source file, use the @code{edit} command. -The editing program of your choice -is invoked with the current line set to -the active line in the program. -Alternatively, there are several ways to specify what part of the file you -want to print if you want to see other parts of the program. - -Here are the forms of the @code{edit} command most commonly used: - -@table @code -@item edit -Edit the current source file at the active line number in the program. - -@item edit @var{number} -Edit the current source file with @var{number} as the active line number. - -@item edit @var{function} -Edit the file containing @var{function} at the beginning of its definition. - -@item edit @var{filename}:@var{number} -Specifies line @var{number} in the source file @var{filename}. - -@item edit @var{filename}:@var{function} -Specifies the line that begins the body of the -function @var{function} in the file @var{filename}. You only need the -file name with a function name to avoid ambiguity when there are -identically named functions in different source files. - -@item edit *@var{address} -Specifies the line containing the program address @var{address}. -@var{address} may be any expression. -@end table - -@subsection Choosing your editor -You can customize @value{GDBN} to use any editor you want -@footnote{ -The only restriction is that your editor (say @code{ex}), recognizes the -following command-line syntax: -@smallexample -ex +@var{number} file -@end smallexample -The optional numeric value +@var{number} designates the active line in -the file.}. By default, it is @value{EDITOR}, but you can change this -by setting the environment variable @code{EDITOR} before using -@value{GDBN}. For example, to configure @value{GDBN} to use the -@code{vi} editor, you could use these commands with the @code{sh} shell: -@smallexample -EDITOR=/usr/bin/vi -export EDITOR -gdb ... -@end smallexample -or in the @code{csh} shell, -@smallexample -setenv EDITOR /usr/bin/vi -gdb ... -@end smallexample - -@node Search -@section Searching source files -@cindex searching -@kindex reverse-search - -There are two commands for searching through the current source file for a -regular expression. - -@table @code -@kindex search -@kindex forward-search -@item forward-search @var{regexp} -@itemx search @var{regexp} -The command @samp{forward-search @var{regexp}} checks each line, -starting with the one following the last line listed, for a match for -@var{regexp}. It lists the line that is found. You can use the -synonym @samp{search @var{regexp}} or abbreviate the command name as -@code{fo}. - -@item reverse-search @var{regexp} -The command @samp{reverse-search @var{regexp}} checks each line, starting -with the one before the last line listed and going backward, for a match -for @var{regexp}. It lists the line that is found. You can abbreviate -this command as @code{rev}. -@end table - -@node Source Path -@section Specifying source directories - -@cindex source path -@cindex directories for source files -Executable programs sometimes do not record the directories of the source -files from which they were compiled, just the names. Even when they do, -the directories could be moved between the compilation and your debugging -session. @value{GDBN} has a list of directories to search for source files; -this is called the @dfn{source path}. Each time @value{GDBN} wants a source file, -it tries all the directories in the list, in the order they are present -in the list, until it finds a file with the desired name. Note that -the executable search path is @emph{not} used for this purpose. Neither is -the current working directory, unless it happens to be in the source -path. - -If @value{GDBN} cannot find a source file in the source path, and the -object program records a directory, @value{GDBN} tries that directory -too. If the source path is empty, and there is no record of the -compilation directory, @value{GDBN} looks in the current directory as a -last resort. - -Whenever you reset or rearrange the source path, @value{GDBN} clears out -any information it has cached about where source files are found and where -each line is in the file. - -@kindex directory -@kindex dir -When you start @value{GDBN}, its source path includes only @samp{cdir} -and @samp{cwd}, in that order. -To add other directories, use the @code{directory} command. - -@table @code -@item directory @var{dirname} @dots{} -@item dir @var{dirname} @dots{} -Add directory @var{dirname} to the front of the source path. Several -directory names may be given to this command, separated by @samp{:} -(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as -part of absolute file names) or -whitespace. You may specify a directory that is already in the source -path; this moves it forward, so @value{GDBN} searches it sooner. - -@kindex cdir -@kindex cwd -@vindex $cdir@r{, convenience variable} -@vindex $cwdr@r{, convenience variable} -@cindex compilation directory -@cindex current directory -@cindex working directory -@cindex directory, current -@cindex directory, compilation -You can use the string @samp{$cdir} to refer to the compilation -directory (if one is recorded), and @samp{$cwd} to refer to the current -working directory. @samp{$cwd} is not the same as @samp{.}---the former -tracks the current working directory as it changes during your @value{GDBN} -session, while the latter is immediately expanded to the current -directory at the time you add an entry to the source path. - -@item directory -Reset the source path to empty again. This requires confirmation. - -@c RET-repeat for @code{directory} is explicitly disabled, but since -@c repeating it would be a no-op we do not say that. (thanks to RMS) - -@item show directories -@kindex show directories -Print the source path: show which directories it contains. -@end table - -If your source path is cluttered with directories that are no longer of -interest, @value{GDBN} may sometimes cause confusion by finding the wrong -versions of source. You can correct the situation as follows: - -@enumerate -@item -Use @code{directory} with no argument to reset the source path to empty. - -@item -Use @code{directory} with suitable arguments to reinstall the -directories you want in the source path. You can add all the -directories in one command. -@end enumerate - -@node Machine Code -@section Source and machine code - -You can use the command @code{info line} to map source lines to program -addresses (and vice versa), and the command @code{disassemble} to display -a range of addresses as machine instructions. When run under @sc{gnu} Emacs -mode, the @code{info line} command causes the arrow to point to the -line specified. Also, @code{info line} prints addresses in symbolic form as -well as hex. - -@table @code -@kindex info line -@item info line @var{linespec} -Print the starting and ending addresses of the compiled code for -source line @var{linespec}. You can specify source lines in any of -the ways understood by the @code{list} command (@pxref{List, ,Printing -source lines}). -@end table - -For example, we can use @code{info line} to discover the location of -the object code for the first line of function -@code{m4_changequote}: - -@c FIXME: I think this example should also show the addresses in -@c symbolic form, as they usually would be displayed. -@smallexample -(@value{GDBP}) info line m4_changequote -Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. -@end smallexample - -@noindent -We can also inquire (using @code{*@var{addr}} as the form for -@var{linespec}) what source line covers a particular address: -@smallexample -(@value{GDBP}) info line *0x63ff -Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. -@end smallexample - -@cindex @code{$_} and @code{info line} -@kindex x@r{(examine), and} info line -After @code{info line}, the default address for the @code{x} command -is changed to the starting address of the line, so that @samp{x/i} is -sufficient to begin examining the machine code (@pxref{Memory, -,Examining memory}). Also, this address is saved as the value of the -convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience -variables}). - -@table @code -@kindex disassemble -@cindex assembly instructions -@cindex instructions, assembly -@cindex machine instructions -@cindex listing machine instructions -@item disassemble -This specialized command dumps a range of memory as machine -instructions. The default memory range is the function surrounding the -program counter of the selected frame. A single argument to this -command is a program counter value; @value{GDBN} dumps the function -surrounding this value. Two arguments specify a range of addresses -(first inclusive, second exclusive) to dump. -@end table - -The following example shows the disassembly of a range of addresses of -HP PA-RISC 2.0 code: - -@smallexample -(@value{GDBP}) disas 0x32c4 0x32e4 -Dump of assembler code from 0x32c4 to 0x32e4: -0x32c4 <main+204>: addil 0,dp -0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 -0x32cc <main+212>: ldil 0x3000,r31 -0x32d0 <main+216>: ble 0x3f8(sr4,r31) -0x32d4 <main+220>: ldo 0(r31),rp -0x32d8 <main+224>: addil -0x800,dp -0x32dc <main+228>: ldo 0x588(r1),r26 -0x32e0 <main+232>: ldil 0x3000,r31 -End of assembler dump. -@end smallexample - -Some architectures have more than one commonly-used set of instruction -mnemonics or other syntax. - -@table @code -@kindex set disassembly-flavor -@cindex assembly instructions -@cindex instructions, assembly -@cindex machine instructions -@cindex listing machine instructions -@cindex Intel disassembly flavor -@cindex AT&T disassembly flavor -@item set disassembly-flavor @var{instruction-set} -Select the instruction set to use when disassembling the -program via the @code{disassemble} or @code{x/i} commands. - -Currently this command is only defined for the Intel x86 family. You -can set @var{instruction-set} to either @code{intel} or @code{att}. -The default is @code{att}, the AT&T flavor used by default by Unix -assemblers for x86-based targets. -@end table - - -@node Data -@chapter Examining Data - -@cindex printing data -@cindex examining data -@kindex print -@kindex inspect -@c "inspect" is not quite a synonym if you are using Epoch, which we do not -@c document because it is nonstandard... Under Epoch it displays in a -@c different window or something like that. -The usual way to examine data in your program is with the @code{print} -command (abbreviated @code{p}), or its synonym @code{inspect}. It -evaluates and prints the value of an expression of the language your -program is written in (@pxref{Languages, ,Using @value{GDBN} with -Different Languages}). - -@table @code -@item print @var{expr} -@itemx print /@var{f} @var{expr} -@var{expr} is an expression (in the source language). By default the -value of @var{expr} is printed in a format appropriate to its data type; -you can choose a different format by specifying @samp{/@var{f}}, where -@var{f} is a letter specifying the format; see @ref{Output Formats,,Output -formats}. - -@item print -@itemx print /@var{f} -If you omit @var{expr}, @value{GDBN} displays the last value again (from the -@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to -conveniently inspect the same value in an alternative format. -@end table - -A more low-level way of examining data is with the @code{x} command. -It examines data in memory at a specified address and prints it in a -specified format. @xref{Memory, ,Examining memory}. - -If you are interested in information about types, or about how the -fields of a struct or a class are declared, use the @code{ptype @var{exp}} -command rather than @code{print}. @xref{Symbols, ,Examining the Symbol -Table}. - -@menu -* Expressions:: Expressions -* Variables:: Program variables -* Arrays:: Artificial arrays -* Output Formats:: Output formats -* Memory:: Examining memory -* Auto Display:: Automatic display -* Print Settings:: Print settings -* Value History:: Value history -* Convenience Vars:: Convenience variables -* Registers:: Registers -* Floating Point Hardware:: Floating point hardware -* Vector Unit:: Vector Unit -* Auxiliary Vector:: Auxiliary data provided by operating system -* Memory Region Attributes:: Memory region attributes -* Dump/Restore Files:: Copy between memory and a file -* Character Sets:: Debugging programs that use a different - character set than GDB does -@end menu - -@node Expressions -@section Expressions - -@cindex expressions -@code{print} and many other @value{GDBN} commands accept an expression and -compute its value. Any kind of constant, variable or operator defined -by the programming language you are using is valid in an expression in -@value{GDBN}. This includes conditional expressions, function calls, -casts, and string constants. It also includes preprocessor macros, if -you compiled your program to include this information; see -@ref{Compilation}. - -@value{GDBN} supports array constants in expressions input by -the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, -you can use the command @code{print @{1, 2, 3@}} to build up an array in -memory that is @code{malloc}ed in the target program. - -Because C is so widespread, most of the expressions shown in examples in -this manual are in C. @xref{Languages, , Using @value{GDBN} with Different -Languages}, for information on how to use expressions in other -languages. - -In this section, we discuss operators that you can use in @value{GDBN} -expressions regardless of your programming language. - -Casts are supported in all languages, not just in C, because it is so -useful to cast a number into a pointer in order to examine a structure -at that address in memory. -@c FIXME: casts supported---Mod2 true? - -@value{GDBN} supports these operators, in addition to those common -to programming languages: - -@table @code -@item @@ -@samp{@@} is a binary operator for treating parts of memory as arrays. -@xref{Arrays, ,Artificial arrays}, for more information. - -@item :: -@samp{::} allows you to specify a variable in terms of the file or -function where it is defined. @xref{Variables, ,Program variables}. - -@cindex @{@var{type}@} -@cindex type casting memory -@cindex memory, viewing as typed object -@cindex casts, to view memory -@item @{@var{type}@} @var{addr} -Refers to an object of type @var{type} stored at address @var{addr} in -memory. @var{addr} may be any expression whose value is an integer or -pointer (but parentheses are required around binary operators, just as in -a cast). This construct is allowed regardless of what kind of data is -normally supposed to reside at @var{addr}. -@end table - -@node Variables -@section Program variables - -The most common kind of expression to use is the name of a variable -in your program. - -Variables in expressions are understood in the selected stack frame -(@pxref{Selection, ,Selecting a frame}); they must be either: - -@itemize @bullet -@item -global (or file-static) -@end itemize - -@noindent or - -@itemize @bullet -@item -visible according to the scope rules of the -programming language from the point of execution in that frame -@end itemize - -@noindent This means that in the function - -@smallexample -foo (a) - int a; -@{ - bar (a); - @{ - int b = test (); - bar (b); - @} -@} -@end smallexample - -@noindent -you can examine and use the variable @code{a} whenever your program is -executing within the function @code{foo}, but you can only use or -examine the variable @code{b} while your program is executing inside -the block where @code{b} is declared. - -@cindex variable name conflict -There is an exception: you can refer to a variable or function whose -scope is a single source file even if the current execution point is not -in this file. But it is possible to have more than one such variable or -function with the same name (in different source files). If that -happens, referring to that name has unpredictable effects. If you wish, -you can specify a static variable in a particular function or file, -using the colon-colon notation: - -@cindex colon-colon, context for variables/functions -@iftex -@c info cannot cope with a :: index entry, but why deprive hard copy readers? -@cindex @code{::}, context for variables/functions -@end iftex -@smallexample -@var{file}::@var{variable} -@var{function}::@var{variable} -@end smallexample - -@noindent -Here @var{file} or @var{function} is the name of the context for the -static @var{variable}. In the case of file names, you can use quotes to -make sure @value{GDBN} parses the file name as a single word---for example, -to print a global value of @code{x} defined in @file{f2.c}: - -@smallexample -(@value{GDBP}) p 'f2.c'::x -@end smallexample - -@cindex C@t{++} scope resolution -This use of @samp{::} is very rarely in conflict with the very similar -use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++} -scope resolution operator in @value{GDBN} expressions. -@c FIXME: Um, so what happens in one of those rare cases where it's in -@c conflict?? --mew - -@cindex wrong values -@cindex variable values, wrong -@quotation -@emph{Warning:} Occasionally, a local variable may appear to have the -wrong value at certain points in a function---just after entry to a new -scope, and just before exit. -@end quotation -You may see this problem when you are stepping by machine instructions. -This is because, on most machines, it takes more than one instruction to -set up a stack frame (including local variable definitions); if you are -stepping by machine instructions, variables may appear to have the wrong -values until the stack frame is completely built. On exit, it usually -also takes more than one machine instruction to destroy a stack frame; -after you begin stepping through that group of instructions, local -variable definitions may be gone. - -This may also happen when the compiler does significant optimizations. -To be sure of always seeing accurate values, turn off all optimization -when compiling. - -@cindex ``No symbol "foo" in current context'' -Another possible effect of compiler optimizations is to optimize -unused variables out of existence, or assign variables to registers (as -opposed to memory addresses). Depending on the support for such cases -offered by the debug info format used by the compiler, @value{GDBN} -might not be able to display values for such local variables. If that -happens, @value{GDBN} will print a message like this: - -@smallexample -No symbol "foo" in current context. -@end smallexample - -To solve such problems, either recompile without optimizations, or use a -different debug info format, if the compiler supports several such -formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler -usually supports the @option{-gstabs+} option. @option{-gstabs+} -produces debug info in a format that is superior to formats such as -COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also -an effective form for debug info. @xref{Debugging Options,,Options -for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}. - - -@node Arrays -@section Artificial arrays - -@cindex artificial array -@kindex @@@r{, referencing memory as an array} -It is often useful to print out several successive objects of the -same type in memory; a section of an array, or an array of -dynamically determined size for which only a pointer exists in the -program. - -You can do this by referring to a contiguous span of memory as an -@dfn{artificial array}, using the binary operator @samp{@@}. The left -operand of @samp{@@} should be the first element of the desired array -and be an individual object. The right operand should be the desired length -of the array. The result is an array value whose elements are all of -the type of the left argument. The first element is actually the left -argument; the second element comes from bytes of memory immediately -following those that hold the first element, and so on. Here is an -example. If a program says - -@smallexample -int *array = (int *) malloc (len * sizeof (int)); -@end smallexample - -@noindent -you can print the contents of @code{array} with - -@smallexample -p *array@@len -@end smallexample - -The left operand of @samp{@@} must reside in memory. Array values made -with @samp{@@} in this way behave just like other arrays in terms of -subscripting, and are coerced to pointers when used in expressions. -Artificial arrays most often appear in expressions via the value history -(@pxref{Value History, ,Value history}), after printing one out. - -Another way to create an artificial array is to use a cast. -This re-interprets a value as if it were an array. -The value need not be in memory: -@smallexample -(@value{GDBP}) p/x (short[2])0x12345678 -$1 = @{0x1234, 0x5678@} -@end smallexample - -As a convenience, if you leave the array length out (as in -@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill -the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: -@smallexample -(@value{GDBP}) p/x (short[])0x12345678 -$2 = @{0x1234, 0x5678@} -@end smallexample - -Sometimes the artificial array mechanism is not quite enough; in -moderately complex data structures, the elements of interest may not -actually be adjacent---for example, if you are interested in the values -of pointers in an array. One useful work-around in this situation is -to use a convenience variable (@pxref{Convenience Vars, ,Convenience -variables}) as a counter in an expression that prints the first -interesting value, and then repeat that expression via @key{RET}. For -instance, suppose you have an array @code{dtab} of pointers to -structures, and you are interested in the values of a field @code{fv} -in each structure. Here is an example of what you might type: - -@smallexample -set $i = 0 -p dtab[$i++]->fv -@key{RET} -@key{RET} -@dots{} -@end smallexample - -@node Output Formats -@section Output formats - -@cindex formatted output -@cindex output formats -By default, @value{GDBN} prints a value according to its data type. Sometimes -this is not what you want. For example, you might want to print a number -in hex, or a pointer in decimal. Or you might want to view data in memory -at a certain address as a character string or as an instruction. To do -these things, specify an @dfn{output format} when you print a value. - -The simplest use of output formats is to say how to print a value -already computed. This is done by starting the arguments of the -@code{print} command with a slash and a format letter. The format -letters supported are: - -@table @code -@item x -Regard the bits of the value as an integer, and print the integer in -hexadecimal. - -@item d -Print as integer in signed decimal. - -@item u -Print as integer in unsigned decimal. - -@item o -Print as integer in octal. - -@item t -Print as integer in binary. The letter @samp{t} stands for ``two''. -@footnote{@samp{b} cannot be used because these format letters are also -used with the @code{x} command, where @samp{b} stands for ``byte''; -see @ref{Memory,,Examining memory}.} - -@item a -@cindex unknown address, locating -@cindex locate address -Print as an address, both absolute in hexadecimal and as an offset from -the nearest preceding symbol. You can use this format used to discover -where (in what function) an unknown address is located: - -@smallexample -(@value{GDBP}) p/a 0x54320 -$3 = 0x54320 <_initialize_vx+396> -@end smallexample - -@noindent -The command @code{info symbol 0x54320} yields similar results. -@xref{Symbols, info symbol}. - -@item c -Regard as an integer and print it as a character constant. - -@item f -Regard the bits of the value as a floating point number and print -using typical floating point syntax. -@end table - -For example, to print the program counter in hex (@pxref{Registers}), type - -@smallexample -p/x $pc -@end smallexample - -@noindent -Note that no space is required before the slash; this is because command -names in @value{GDBN} cannot contain a slash. - -To reprint the last value in the value history with a different format, -you can use the @code{print} command with just a format and no -expression. For example, @samp{p/x} reprints the last value in hex. - -@node Memory -@section Examining memory - -You can use the command @code{x} (for ``examine'') to examine memory in -any of several formats, independently of your program's data types. - -@cindex examining memory -@table @code -@kindex x @r{(examine memory)} -@item x/@var{nfu} @var{addr} -@itemx x @var{addr} -@itemx x -Use the @code{x} command to examine memory. -@end table - -@var{n}, @var{f}, and @var{u} are all optional parameters that specify how -much memory to display and how to format it; @var{addr} is an -expression giving the address where you want to start displaying memory. -If you use defaults for @var{nfu}, you need not type the slash @samp{/}. -Several commands set convenient defaults for @var{addr}. - -@table @r -@item @var{n}, the repeat count -The repeat count is a decimal integer; the default is 1. It specifies -how much memory (counting by units @var{u}) to display. -@c This really is **decimal**; unaffected by 'set radix' as of GDB -@c 4.1.2. - -@item @var{f}, the display format -The display format is one of the formats used by @code{print}, -@samp{s} (null-terminated string), or @samp{i} (machine instruction). -The default is @samp{x} (hexadecimal) initially. -The default changes each time you use either @code{x} or @code{print}. - -@item @var{u}, the unit size -The unit size is any of - -@table @code -@item b -Bytes. -@item h -Halfwords (two bytes). -@item w -Words (four bytes). This is the initial default. -@item g -Giant words (eight bytes). -@end table - -Each time you specify a unit size with @code{x}, that size becomes the -default unit the next time you use @code{x}. (For the @samp{s} and -@samp{i} formats, the unit size is ignored and is normally not written.) - -@item @var{addr}, starting display address -@var{addr} is the address where you want @value{GDBN} to begin displaying -memory. The expression need not have a pointer value (though it may); -it is always interpreted as an integer address of a byte of memory. -@xref{Expressions, ,Expressions}, for more information on expressions. The default for -@var{addr} is usually just after the last address examined---but several -other commands also set the default address: @code{info breakpoints} (to -the address of the last breakpoint listed), @code{info line} (to the -starting address of a line), and @code{print} (if you use it to display -a value from memory). -@end table - -For example, @samp{x/3uh 0x54320} is a request to display three halfwords -(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), -starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four -words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; -@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). - -Since the letters indicating unit sizes are all distinct from the -letters specifying output formats, you do not have to remember whether -unit size or format comes first; either order works. The output -specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. -(However, the count @var{n} must come first; @samp{wx4} does not work.) - -Even though the unit size @var{u} is ignored for the formats @samp{s} -and @samp{i}, you might still want to use a count @var{n}; for example, -@samp{3i} specifies that you want to see three machine instructions, -including any operands. The command @code{disassemble} gives an -alternative way of inspecting machine instructions; see @ref{Machine -Code,,Source and machine code}. - -All the defaults for the arguments to @code{x} are designed to make it -easy to continue scanning memory with minimal specifications each time -you use @code{x}. For example, after you have inspected three machine -instructions with @samp{x/3i @var{addr}}, you can inspect the next seven -with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, -the repeat count @var{n} is used again; the other arguments default as -for successive uses of @code{x}. - -@cindex @code{$_}, @code{$__}, and value history -The addresses and contents printed by the @code{x} command are not saved -in the value history because there is often too much of them and they -would get in the way. Instead, @value{GDBN} makes these values available for -subsequent use in expressions as values of the convenience variables -@code{$_} and @code{$__}. After an @code{x} command, the last address -examined is available for use in expressions in the convenience variable -@code{$_}. The contents of that address, as examined, are available in -the convenience variable @code{$__}. - -If the @code{x} command has a repeat count, the address and contents saved -are from the last memory unit printed; this is not the same as the last -address printed if several units were printed on the last line of output. - -@node Auto Display -@section Automatic display -@cindex automatic display -@cindex display of expressions - -If you find that you want to print the value of an expression frequently -(to see how it changes), you might want to add it to the @dfn{automatic -display list} so that @value{GDBN} prints its value each time your program stops. -Each expression added to the list is given a number to identify it; -to remove an expression from the list, you specify that number. -The automatic display looks like this: - -@smallexample -2: foo = 38 -3: bar[5] = (struct hack *) 0x3804 -@end smallexample - -@noindent -This display shows item numbers, expressions and their current values. As with -displays you request manually using @code{x} or @code{print}, you can -specify the output format you prefer; in fact, @code{display} decides -whether to use @code{print} or @code{x} depending on how elaborate your -format specification is---it uses @code{x} if you specify a unit size, -or one of the two formats (@samp{i} and @samp{s}) that are only -supported by @code{x}; otherwise it uses @code{print}. - -@table @code -@kindex display -@item display @var{expr} -Add the expression @var{expr} to the list of expressions to display -each time your program stops. @xref{Expressions, ,Expressions}. - -@code{display} does not repeat if you press @key{RET} again after using it. - -@item display/@var{fmt} @var{expr} -For @var{fmt} specifying only a display format and not a size or -count, add the expression @var{expr} to the auto-display list but -arrange to display it each time in the specified format @var{fmt}. -@xref{Output Formats,,Output formats}. - -@item display/@var{fmt} @var{addr} -For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a -number of units, add the expression @var{addr} as a memory address to -be examined each time your program stops. Examining means in effect -doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}. -@end table - -For example, @samp{display/i $pc} can be helpful, to see the machine -instruction about to be executed each time execution stops (@samp{$pc} -is a common name for the program counter; @pxref{Registers, ,Registers}). - -@table @code -@kindex delete display -@kindex undisplay -@item undisplay @var{dnums}@dots{} -@itemx delete display @var{dnums}@dots{} -Remove item numbers @var{dnums} from the list of expressions to display. - -@code{undisplay} does not repeat if you press @key{RET} after using it. -(Otherwise you would just get the error @samp{No display number @dots{}}.) - -@kindex disable display -@item disable display @var{dnums}@dots{} -Disable the display of item numbers @var{dnums}. A disabled display -item is not printed automatically, but is not forgotten. It may be -enabled again later. - -@kindex enable display -@item enable display @var{dnums}@dots{} -Enable display of item numbers @var{dnums}. It becomes effective once -again in auto display of its expression, until you specify otherwise. - -@item display -Display the current values of the expressions on the list, just as is -done when your program stops. - -@kindex info display -@item info display -Print the list of expressions previously set up to display -automatically, each one with its item number, but without showing the -values. This includes disabled expressions, which are marked as such. -It also includes expressions which would not be displayed right now -because they refer to automatic variables not currently available. -@end table - -If a display expression refers to local variables, then it does not make -sense outside the lexical context for which it was set up. Such an -expression is disabled when execution enters a context where one of its -variables is not defined. For example, if you give the command -@code{display last_char} while inside a function with an argument -@code{last_char}, @value{GDBN} displays this argument while your program -continues to stop inside that function. When it stops elsewhere---where -there is no variable @code{last_char}---the display is disabled -automatically. The next time your program stops where @code{last_char} -is meaningful, you can enable the display expression once again. - -@node Print Settings -@section Print settings - -@cindex format options -@cindex print settings -@value{GDBN} provides the following ways to control how arrays, structures, -and symbols are printed. - -@noindent -These settings are useful for debugging programs in any language: - -@table @code -@kindex set print address -@item set print address -@itemx set print address on -@value{GDBN} prints memory addresses showing the location of stack -traces, structure values, pointer values, breakpoints, and so forth, -even when it also displays the contents of those addresses. The default -is @code{on}. For example, this is what a stack frame display looks like with -@code{set print address on}: - -@smallexample -@group -(@value{GDBP}) f -#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") - at input.c:530 -530 if (lquote != def_lquote) -@end group -@end smallexample - -@item set print address off -Do not print addresses when displaying their contents. For example, -this is the same stack frame displayed with @code{set print address off}: - -@smallexample -@group -(@value{GDBP}) set print addr off -(@value{GDBP}) f -#0 set_quotes (lq="<<", rq=">>") at input.c:530 -530 if (lquote != def_lquote) -@end group -@end smallexample - -You can use @samp{set print address off} to eliminate all machine -dependent displays from the @value{GDBN} interface. For example, with -@code{print address off}, you should get the same text for backtraces on -all machines---whether or not they involve pointer arguments. - -@kindex show print address -@item show print address -Show whether or not addresses are to be printed. -@end table - -When @value{GDBN} prints a symbolic address, it normally prints the -closest earlier symbol plus an offset. If that symbol does not uniquely -identify the address (for example, it is a name whose scope is a single -source file), you may need to clarify. One way to do this is with -@code{info line}, for example @samp{info line *0x4537}. Alternately, -you can set @value{GDBN} to print the source file and line number when -it prints a symbolic address: - -@table @code -@kindex set print symbol-filename -@item set print symbol-filename on -Tell @value{GDBN} to print the source file name and line number of a -symbol in the symbolic form of an address. - -@item set print symbol-filename off -Do not print source file name and line number of a symbol. This is the -default. - -@kindex show print symbol-filename -@item show print symbol-filename -Show whether or not @value{GDBN} will print the source file name and -line number of a symbol in the symbolic form of an address. -@end table - -Another situation where it is helpful to show symbol filenames and line -numbers is when disassembling code; @value{GDBN} shows you the line -number and source file that corresponds to each instruction. - -Also, you may wish to see the symbolic form only if the address being -printed is reasonably close to the closest earlier symbol: - -@table @code -@kindex set print max-symbolic-offset -@item set print max-symbolic-offset @var{max-offset} -Tell @value{GDBN} to only display the symbolic form of an address if the -offset between the closest earlier symbol and the address is less than -@var{max-offset}. The default is 0, which tells @value{GDBN} -to always print the symbolic form of an address if any symbol precedes it. - -@kindex show print max-symbolic-offset -@item show print max-symbolic-offset -Ask how large the maximum offset is that @value{GDBN} prints in a -symbolic address. -@end table - -@cindex wild pointer, interpreting -@cindex pointer, finding referent -If you have a pointer and you are not sure where it points, try -@samp{set print symbol-filename on}. Then you can determine the name -and source file location of the variable where it points, using -@samp{p/a @var{pointer}}. This interprets the address in symbolic form. -For example, here @value{GDBN} shows that a variable @code{ptt} points -at another variable @code{t}, defined in @file{hi2.c}: - -@smallexample -(@value{GDBP}) set print symbol-filename on -(@value{GDBP}) p/a ptt -$4 = 0xe008 <t in hi2.c> -@end smallexample - -@quotation -@emph{Warning:} For pointers that point to a local variable, @samp{p/a} -does not show the symbol name and filename of the referent, even with -the appropriate @code{set print} options turned on. -@end quotation - -Other settings control how different kinds of objects are printed: - -@table @code -@kindex set print array -@item set print array -@itemx set print array on -Pretty print arrays. This format is more convenient to read, -but uses more space. The default is off. - -@item set print array off -Return to compressed format for arrays. - -@kindex show print array -@item show print array -Show whether compressed or pretty format is selected for displaying -arrays. - -@kindex set print elements -@item set print elements @var{number-of-elements} -Set a limit on how many elements of an array @value{GDBN} will print. -If @value{GDBN} is printing a large array, it stops printing after it has -printed the number of elements set by the @code{set print elements} command. -This limit also applies to the display of strings. -When @value{GDBN} starts, this limit is set to 200. -Setting @var{number-of-elements} to zero means that the printing is unlimited. - -@kindex show print elements -@item show print elements -Display the number of elements of a large array that @value{GDBN} will print. -If the number is 0, then the printing is unlimited. - -@kindex set print null-stop -@item set print null-stop -Cause @value{GDBN} to stop printing the characters of an array when the first -@sc{null} is encountered. This is useful when large arrays actually -contain only short strings. -The default is off. - -@kindex set print pretty -@item set print pretty on -Cause @value{GDBN} to print structures in an indented format with one member -per line, like this: - -@smallexample -@group -$1 = @{ - next = 0x0, - flags = @{ - sweet = 1, - sour = 1 - @}, - meat = 0x54 "Pork" -@} -@end group -@end smallexample - -@item set print pretty off -Cause @value{GDBN} to print structures in a compact format, like this: - -@smallexample -@group -$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \ -meat = 0x54 "Pork"@} -@end group -@end smallexample - -@noindent -This is the default format. - -@kindex show print pretty -@item show print pretty -Show which format @value{GDBN} is using to print structures. - -@kindex set print sevenbit-strings -@item set print sevenbit-strings on -Print using only seven-bit characters; if this option is set, -@value{GDBN} displays any eight-bit characters (in strings or -character values) using the notation @code{\}@var{nnn}. This setting is -best if you are working in English (@sc{ascii}) and you use the -high-order bit of characters as a marker or ``meta'' bit. - -@item set print sevenbit-strings off -Print full eight-bit characters. This allows the use of more -international character sets, and is the default. - -@kindex show print sevenbit-strings -@item show print sevenbit-strings -Show whether or not @value{GDBN} is printing only seven-bit characters. - -@kindex set print union -@item set print union on -Tell @value{GDBN} to print unions which are contained in structures. This -is the default setting. - -@item set print union off -Tell @value{GDBN} not to print unions which are contained in structures. - -@kindex show print union -@item show print union -Ask @value{GDBN} whether or not it will print unions which are contained in -structures. - -For example, given the declarations - -@smallexample -typedef enum @{Tree, Bug@} Species; -typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; -typedef enum @{Caterpillar, Cocoon, Butterfly@} - Bug_forms; - -struct thing @{ - Species it; - union @{ - Tree_forms tree; - Bug_forms bug; - @} form; -@}; - -struct thing foo = @{Tree, @{Acorn@}@}; -@end smallexample - -@noindent -with @code{set print union on} in effect @samp{p foo} would print - -@smallexample -$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} -@end smallexample - -@noindent -and with @code{set print union off} in effect it would print - -@smallexample -$1 = @{it = Tree, form = @{...@}@} -@end smallexample -@end table - -@need 1000 -@noindent -These settings are of interest when debugging C@t{++} programs: - -@table @code -@cindex demangling -@kindex set print demangle -@item set print demangle -@itemx set print demangle on -Print C@t{++} names in their source form rather than in the encoded -(``mangled'') form passed to the assembler and linker for type-safe -linkage. The default is on. - -@kindex show print demangle -@item show print demangle -Show whether C@t{++} names are printed in mangled or demangled form. - -@kindex set print asm-demangle -@item set print asm-demangle -@itemx set print asm-demangle on -Print C@t{++} names in their source form rather than their mangled form, even -in assembler code printouts such as instruction disassemblies. -The default is off. - -@kindex show print asm-demangle -@item show print asm-demangle -Show whether C@t{++} names in assembly listings are printed in mangled -or demangled form. - -@kindex set demangle-style -@cindex C@t{++} symbol decoding style -@cindex symbol decoding style, C@t{++} -@item set demangle-style @var{style} -Choose among several encoding schemes used by different compilers to -represent C@t{++} names. The choices for @var{style} are currently: - -@table @code -@item auto -Allow @value{GDBN} to choose a decoding style by inspecting your program. - -@item gnu -Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm. -This is the default. - -@item hp -Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm. - -@item lucid -Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm. - -@item arm -Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}. -@strong{Warning:} this setting alone is not sufficient to allow -debugging @code{cfront}-generated executables. @value{GDBN} would -require further enhancement to permit that. - -@end table -If you omit @var{style}, you will see a list of possible formats. - -@kindex show demangle-style -@item show demangle-style -Display the encoding style currently in use for decoding C@t{++} symbols. - -@kindex set print object -@item set print object -@itemx set print object on -When displaying a pointer to an object, identify the @emph{actual} -(derived) type of the object rather than the @emph{declared} type, using -the virtual function table. - -@item set print object off -Display only the declared type of objects, without reference to the -virtual function table. This is the default setting. - -@kindex show print object -@item show print object -Show whether actual, or declared, object types are displayed. - -@kindex set print static-members -@item set print static-members -@itemx set print static-members on -Print static members when displaying a C@t{++} object. The default is on. - -@item set print static-members off -Do not print static members when displaying a C@t{++} object. - -@kindex show print static-members -@item show print static-members -Show whether C@t{++} static members are printed, or not. - -@c These don't work with HP ANSI C++ yet. -@kindex set print vtbl -@item set print vtbl -@itemx set print vtbl on -Pretty print C@t{++} virtual function tables. The default is off. -(The @code{vtbl} commands do not work on programs compiled with the HP -ANSI C@t{++} compiler (@code{aCC}).) - -@item set print vtbl off -Do not pretty print C@t{++} virtual function tables. - -@kindex show print vtbl -@item show print vtbl -Show whether C@t{++} virtual function tables are pretty printed, or not. -@end table - -@node Value History -@section Value history - -@cindex value history -Values printed by the @code{print} command are saved in the @value{GDBN} -@dfn{value history}. This allows you to refer to them in other expressions. -Values are kept until the symbol table is re-read or discarded -(for example with the @code{file} or @code{symbol-file} commands). -When the symbol table changes, the value history is discarded, -since the values may contain pointers back to the types defined in the -symbol table. - -@cindex @code{$} -@cindex @code{$$} -@cindex history number -The values printed are given @dfn{history numbers} by which you can -refer to them. These are successive integers starting with one. -@code{print} shows you the history number assigned to a value by -printing @samp{$@var{num} = } before the value; here @var{num} is the -history number. - -To refer to any previous value, use @samp{$} followed by the value's -history number. The way @code{print} labels its output is designed to -remind you of this. Just @code{$} refers to the most recent value in -the history, and @code{$$} refers to the value before that. -@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2} -is the value just prior to @code{$$}, @code{$$1} is equivalent to -@code{$$}, and @code{$$0} is equivalent to @code{$}. - -For example, suppose you have just printed a pointer to a structure and -want to see the contents of the structure. It suffices to type - -@smallexample -p *$ -@end smallexample - -If you have a chain of structures where the component @code{next} points -to the next one, you can print the contents of the next one with this: - -@smallexample -p *$.next -@end smallexample - -@noindent -You can print successive links in the chain by repeating this -command---which you can do by just typing @key{RET}. - -Note that the history records values, not expressions. If the value of -@code{x} is 4 and you type these commands: - -@smallexample -print x -set x=5 -@end smallexample - -@noindent -then the value recorded in the value history by the @code{print} command -remains 4 even though the value of @code{x} has changed. - -@table @code -@kindex show values -@item show values -Print the last ten values in the value history, with their item numbers. -This is like @samp{p@ $$9} repeated ten times, except that @code{show -values} does not change the history. - -@item show values @var{n} -Print ten history values centered on history item number @var{n}. - -@item show values + -Print ten history values just after the values last printed. If no more -values are available, @code{show values +} produces no display. -@end table - -Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the -same effect as @samp{show values +}. - -@node Convenience Vars -@section Convenience variables - -@cindex convenience variables -@value{GDBN} provides @dfn{convenience variables} that you can use within -@value{GDBN} to hold on to a value and refer to it later. These variables -exist entirely within @value{GDBN}; they are not part of your program, and -setting a convenience variable has no direct effect on further execution -of your program. That is why you can use them freely. - -Convenience variables are prefixed with @samp{$}. Any name preceded by -@samp{$} can be used for a convenience variable, unless it is one of -the predefined machine-specific register names (@pxref{Registers, ,Registers}). -(Value history references, in contrast, are @emph{numbers} preceded -by @samp{$}. @xref{Value History, ,Value history}.) - -You can save a value in a convenience variable with an assignment -expression, just as you would set a variable in your program. -For example: - -@smallexample -set $foo = *object_ptr -@end smallexample - -@noindent -would save in @code{$foo} the value contained in the object pointed to by -@code{object_ptr}. - -Using a convenience variable for the first time creates it, but its -value is @code{void} until you assign a new value. You can alter the -value with another assignment at any time. - -Convenience variables have no fixed types. You can assign a convenience -variable any type of value, including structures and arrays, even if -that variable already has a value of a different type. The convenience -variable, when used as an expression, has the type of its current value. - -@table @code -@kindex show convenience -@item show convenience -Print a list of convenience variables used so far, and their values. -Abbreviated @code{show conv}. -@end table - -One of the ways to use a convenience variable is as a counter to be -incremented or a pointer to be advanced. For example, to print -a field from successive elements of an array of structures: - -@smallexample -set $i = 0 -print bar[$i++]->contents -@end smallexample - -@noindent -Repeat that command by typing @key{RET}. - -Some convenience variables are created automatically by @value{GDBN} and given -values likely to be useful. - -@table @code -@vindex $_@r{, convenience variable} -@item $_ -The variable @code{$_} is automatically set by the @code{x} command to -the last address examined (@pxref{Memory, ,Examining memory}). Other -commands which provide a default address for @code{x} to examine also -set @code{$_} to that address; these commands include @code{info line} -and @code{info breakpoint}. The type of @code{$_} is @code{void *} -except when set by the @code{x} command, in which case it is a pointer -to the type of @code{$__}. - -@vindex $__@r{, convenience variable} -@item $__ -The variable @code{$__} is automatically set by the @code{x} command -to the value found in the last address examined. Its type is chosen -to match the format in which the data was printed. - -@item $_exitcode -@vindex $_exitcode@r{, convenience variable} -The variable @code{$_exitcode} is automatically set to the exit code when -the program being debugged terminates. -@end table - -On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, @value{GDBN} searches for a user or system -name first, before it searches for a convenience variable. - -@node Registers -@section Registers - -@cindex registers -You can refer to machine register contents, in expressions, as variables -with names starting with @samp{$}. The names of registers are different -for each machine; use @code{info registers} to see the names used on -your machine. - -@table @code -@kindex info registers -@item info registers -Print the names and values of all registers except floating-point -and vector registers (in the selected stack frame). - -@kindex info all-registers -@cindex floating point registers -@item info all-registers -Print the names and values of all registers, including floating-point -and vector registers (in the selected stack frame). - -@item info registers @var{regname} @dots{} -Print the @dfn{relativized} value of each specified register @var{regname}. -As discussed in detail below, register values are normally relative to -the selected stack frame. @var{regname} may be any register name valid on -the machine you are using, with or without the initial @samp{$}. -@end table - -@value{GDBN} 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 -@code{$pc} and @code{$sp} are used for the program counter register and -the stack pointer. @code{$fp} is used for a register that contains a -pointer to the current stack frame, and @code{$ps} is used for a -register that contains the processor status. For example, -you could print the program counter in hex with - -@smallexample -p/x $pc -@end smallexample - -@noindent -or print the instruction to be executed next with - -@smallexample -x/i $pc -@end smallexample - -@noindent -or add four to the stack pointer@footnote{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 @code{$sp} is not allowed when other -stack frames are selected. To pop entire frames off the stack, -regardless of machine architecture, use @code{return}; -see @ref{Returning, ,Returning from a function}.} with - -@smallexample -set $sp += 4 -@end smallexample - -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 @code{info registers} command -shows the canonical names. For example, on the SPARC, @code{info -registers} displays the processor status register as @code{$psr} but you -can also refer to it as @code{$ps}; and on x86-based machines @code{$ps} -is an alias for the @sc{eflags} register. - -@value{GDBN} 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 @emph{print} it as a floating point value with -@samp{print/f $@var{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, @value{GDBN} normally works with the virtual format only (the format -that makes sense for your program), but the @code{info registers} command -prints the data in both formats. - -Normally, register values are relative to the selected stack frame -(@pxref{Selection, ,Selecting a frame}). 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 @samp{frame 0}). - -However, @value{GDBN} must deduce where registers are saved, from the machine -code generated by your compiler. If some registers are not saved, or if -@value{GDBN} is unable to locate the saved registers, the selected stack -frame makes no difference. - -@node Floating Point Hardware -@section Floating point hardware -@cindex floating point - -Depending on the configuration, @value{GDBN} may be able to give -you more information about the status of the floating point hardware. - -@table @code -@kindex info float -@item info float -Display hardware-dependent information about the floating -point unit. The exact contents and layout vary depending on the -floating point chip. Currently, @samp{info float} is supported on -the ARM and x86 machines. -@end table - -@node Vector Unit -@section Vector Unit -@cindex vector unit - -Depending on the configuration, @value{GDBN} may be able to give you -more information about the status of the vector unit. - -@table @code -@kindex info vector -@item info vector -Display information about the vector unit. The exact contents and -layout vary depending on the hardware. -@end table - -@node Auxiliary Vector -@section Operating system auxiliary vector -@cindex auxiliary vector -@cindex vector, auxiliary - -Some operating systems supply an @dfn{auxiliary vector} to programs at -startup. This is akin to the arguments and environment that you -specify for a program, but contains a system-dependent variety of -binary values that tell system libraries important details about the -hardware, operating system, and process. Each value's purpose is -identified by an integer tag; the meanings are well-known but system-specific. -Depending on the configuration and operating system facilities, -@value{GDBN} may be able to show you this information. - -@table @code -@kindex info auxv -@item info auxv -Display the auxiliary vector of the inferior, which can be either a -live process or a core dump file. @value{GDBN} prints each tag value -numerically, and also shows names and text descriptions for recognized -tags. Some values in the vector are numbers, some bit masks, and some -pointers to strings or other data. @value{GDBN} displays each value in the -most appropriate form for a recognized tag, and in hexadecimal for -an unrecognized tag. -@end table - -@node Memory Region Attributes -@section Memory region attributes -@cindex memory region attributes - -@dfn{Memory region attributes} allow you to describe special handling -required by regions of your target's memory. @value{GDBN} uses attributes -to determine whether to allow certain types of memory accesses; whether to -use specific width accesses; and whether to cache target memory. - -Defined memory regions can be individually enabled and disabled. When a -memory region is disabled, @value{GDBN} uses the default attributes when -accessing memory in that region. Similarly, if no memory regions have -been defined, @value{GDBN} uses the default attributes when accessing -all memory. - -When a memory region is defined, it is given a number to identify it; -to enable, disable, or remove a memory region, you specify that number. - -@table @code -@kindex mem -@item mem @var{lower} @var{upper} @var{attributes}@dots{} -Define memory region bounded by @var{lower} and @var{upper} with -attributes @var{attributes}@dots{}. Note that @var{upper} == 0 is a -special case: it is treated as the the target's maximum memory address. -(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.) - -@kindex delete mem -@item delete mem @var{nums}@dots{} -Remove memory regions @var{nums}@dots{}. - -@kindex disable mem -@item disable mem @var{nums}@dots{} -Disable memory regions @var{nums}@dots{}. -A disabled memory region is not forgotten. -It may be enabled again later. - -@kindex enable mem -@item enable mem @var{nums}@dots{} -Enable memory regions @var{nums}@dots{}. - -@kindex info mem -@item info mem -Print a table of all defined memory regions, with the following columns -for each region. - -@table @emph -@item Memory Region Number -@item Enabled or Disabled. -Enabled memory regions are marked with @samp{y}. -Disabled memory regions are marked with @samp{n}. - -@item Lo Address -The address defining the inclusive lower bound of the memory region. - -@item Hi Address -The address defining the exclusive upper bound of the memory region. - -@item Attributes -The list of attributes set for this memory region. -@end table -@end table - - -@subsection Attributes - -@subsubsection Memory Access Mode -The access mode attributes set whether @value{GDBN} may make read or -write accesses to a memory region. - -While these attributes prevent @value{GDBN} from performing invalid -memory accesses, they do nothing to prevent the target system, I/O DMA, -etc. from accessing memory. - -@table @code -@item ro -Memory is read only. -@item wo -Memory is write only. -@item rw -Memory is read/write. This is the default. -@end table - -@subsubsection Memory Access Size -The acccess size attributes tells @value{GDBN} to use specific sized -accesses in the memory region. Often memory mapped device registers -require specific sized accesses. If no access size attribute is -specified, @value{GDBN} may use accesses of any size. - -@table @code -@item 8 -Use 8 bit memory accesses. -@item 16 -Use 16 bit memory accesses. -@item 32 -Use 32 bit memory accesses. -@item 64 -Use 64 bit memory accesses. -@end table - -@c @subsubsection Hardware/Software Breakpoints -@c The hardware/software breakpoint attributes set whether @value{GDBN} -@c will use hardware or software breakpoints for the internal breakpoints -@c used by the step, next, finish, until, etc. commands. -@c -@c @table @code -@c @item hwbreak -@c Always use hardware breakpoints -@c @item swbreak (default) -@c @end table - -@subsubsection Data Cache -The data cache attributes set whether @value{GDBN} will cache target -memory. While this generally improves performance by reducing debug -protocol overhead, it can lead to incorrect results because @value{GDBN} -does not know about volatile variables or memory mapped device -registers. - -@table @code -@item cache -Enable @value{GDBN} to cache target memory. -@item nocache -Disable @value{GDBN} from caching target memory. This is the default. -@end table - -@c @subsubsection Memory Write Verification -@c The memory write verification attributes set whether @value{GDBN} -@c will re-reads data after each write to verify the write was successful. -@c -@c @table @code -@c @item verify -@c @item noverify (default) -@c @end table - -@node Dump/Restore Files -@section Copy between memory and a file -@cindex dump/restore files -@cindex append data to a file -@cindex dump data to a file -@cindex restore data from a file - -You can use the commands @code{dump}, @code{append}, and -@code{restore} to copy data between target memory and a file. The -@code{dump} and @code{append} commands write data to a file, and the -@code{restore} command reads data from a file back into the inferior's -memory. Files may be in binary, Motorola S-record, Intel hex, or -Tektronix Hex format; however, @value{GDBN} can only append to binary -files. - -@table @code - -@kindex dump -@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr} -@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr} -Dump the contents of memory from @var{start_addr} to @var{end_addr}, -or the value of @var{expr}, to @var{filename} in the given format. - -The @var{format} parameter may be any one of: -@table @code -@item binary -Raw binary form. -@item ihex -Intel hex format. -@item srec -Motorola S-record format. -@item tekhex -Tektronix Hex format. -@end table - -@value{GDBN} uses the same definitions of these formats as the -@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If -@var{format} is omitted, @value{GDBN} dumps the data in raw binary -form. - -@kindex append -@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr} -@itemx append @r{[}binary@r{]} value @var{filename} @var{expr} -Append the contents of memory from @var{start_addr} to @var{end_addr}, -or the value of @var{expr}, to @var{filename}, in raw binary form. -(@value{GDBN} can only append data to files in raw binary form.) - -@kindex restore -@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end} -Restore the contents of file @var{filename} into memory. The -@code{restore} command can automatically recognize any known @sc{bfd} -file format, except for raw binary. To restore a raw binary file you -must specify the optional keyword @code{binary} after the filename. - -If @var{bias} is non-zero, its value will be added to the addresses -contained in the file. Binary files always start at address zero, so -they will be restored at address @var{bias}. Other bfd files have -a built-in location; they will be restored at offset @var{bias} -from that location. - -If @var{start} and/or @var{end} are non-zero, then only data between -file offset @var{start} and file offset @var{end} will be restored. -These offsets are relative to the addresses in the file, before -the @var{bias} argument is applied. - -@end table - -@node Character Sets -@section Character Sets -@cindex character sets -@cindex charset -@cindex translating between character sets -@cindex host character set -@cindex target character set - -If the program you are debugging uses a different character set to -represent characters and strings than the one @value{GDBN} uses itself, -@value{GDBN} can automatically translate between the character sets for -you. The character set @value{GDBN} uses we call the @dfn{host -character set}; the one the inferior program uses we call the -@dfn{target character set}. - -For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which -uses the ISO Latin 1 character set, but you are using @value{GDBN}'s -remote protocol (@pxref{Remote,Remote Debugging}) to debug a program -running on an IBM mainframe, which uses the @sc{ebcdic} character set, -then the host character set is Latin-1, and the target character set is -@sc{ebcdic}. If you give @value{GDBN} the command @code{set -target-charset EBCDIC-US}, then @value{GDBN} translates between -@sc{ebcdic} and Latin 1 as you print character or string values, or use -character and string literals in expressions. - -@value{GDBN} has no way to automatically recognize which character set -the inferior program uses; you must tell it, using the @code{set -target-charset} command, described below. - -Here are the commands for controlling @value{GDBN}'s character set -support: - -@table @code -@item set target-charset @var{charset} -@kindex set target-charset -Set the current target character set to @var{charset}. We list the -character set names @value{GDBN} recognizes below, but if you type -@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will -list the target character sets it supports. -@end table - -@table @code -@item set host-charset @var{charset} -@kindex set host-charset -Set the current host character set to @var{charset}. - -By default, @value{GDBN} uses a host character set appropriate to the -system it is running on; you can override that default using the -@code{set host-charset} command. - -@value{GDBN} can only use certain character sets as its host character -set. We list the character set names @value{GDBN} recognizes below, and -indicate which can be host character sets, but if you type -@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will -list the host character sets it supports. - -@item set charset @var{charset} -@kindex set charset -Set the current host and target character sets to @var{charset}. As -above, if you type @code{set charset} followed by @key{TAB}@key{TAB}, -@value{GDBN} will list the name of the character sets that can be used -for both host and target. - - -@item show charset -@kindex show charset -Show the names of the current host and target charsets. - -@itemx show host-charset -@kindex show host-charset -Show the name of the current host charset. - -@itemx show target-charset -@kindex show target-charset -Show the name of the current target charset. - -@end table - -@value{GDBN} currently includes support for the following character -sets: - -@table @code - -@item ASCII -@cindex ASCII character set -Seven-bit U.S. @sc{ascii}. @value{GDBN} can use this as its host -character set. - -@item ISO-8859-1 -@cindex ISO 8859-1 character set -@cindex ISO Latin 1 character set -The ISO Latin 1 character set. This extends @sc{ascii} with accented -characters needed for French, German, and Spanish. @value{GDBN} can use -this as its host character set. - -@item EBCDIC-US -@itemx IBM1047 -@cindex EBCDIC character set -@cindex IBM1047 character set -Variants of the @sc{ebcdic} character set, used on some of IBM's -mainframe operating systems. (@sc{gnu}/Linux on the S/390 uses U.S. @sc{ascii}.) -@value{GDBN} cannot use these as its host character set. - -@end table - -Note that these are all single-byte character sets. More work inside -GDB is needed to support multi-byte or variable-width character -encodings, like the UTF-8 and UCS-2 encodings of Unicode. - -Here is an example of @value{GDBN}'s character set support in action. -Assume that the following source code has been placed in the file -@file{charset-test.c}: - -@smallexample -#include <stdio.h> - -char ascii_hello[] - = @{72, 101, 108, 108, 111, 44, 32, 119, - 111, 114, 108, 100, 33, 10, 0@}; -char ibm1047_hello[] - = @{200, 133, 147, 147, 150, 107, 64, 166, - 150, 153, 147, 132, 90, 37, 0@}; - -main () -@{ - printf ("Hello, world!\n"); -@} -@end smallexample - -In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays -containing the string @samp{Hello, world!} followed by a newline, -encoded in the @sc{ascii} and @sc{ibm1047} character sets. - -We compile the program, and invoke the debugger on it: - -@smallexample -$ gcc -g charset-test.c -o charset-test -$ gdb -nw charset-test -GNU gdb 2001-12-19-cvs -Copyright 2001 Free Software Foundation, Inc. -@dots{} -(gdb) -@end smallexample - -We can use the @code{show charset} command to see what character sets -@value{GDBN} is currently using to interpret and display characters and -strings: - -@smallexample -(gdb) show charset -The current host and target character set is `ISO-8859-1'. -(gdb) -@end smallexample - -For the sake of printing this manual, let's use @sc{ascii} as our -initial character set: -@smallexample -(gdb) set charset ASCII -(gdb) show charset -The current host and target character set is `ASCII'. -(gdb) -@end smallexample - -Let's assume that @sc{ascii} is indeed the correct character set for our -host system --- in other words, let's assume that if @value{GDBN} prints -characters using the @sc{ascii} character set, our terminal will display -them properly. Since our current target character set is also -@sc{ascii}, the contents of @code{ascii_hello} print legibly: - -@smallexample -(gdb) print ascii_hello -$1 = 0x401698 "Hello, world!\n" -(gdb) print ascii_hello[0] -$2 = 72 'H' -(gdb) -@end smallexample - -@value{GDBN} uses the target character set for character and string -literals you use in expressions: - -@smallexample -(gdb) print '+' -$3 = 43 '+' -(gdb) -@end smallexample - -The @sc{ascii} character set uses the number 43 to encode the @samp{+} -character. - -@value{GDBN} relies on the user to tell it which character set the -target program uses. If we print @code{ibm1047_hello} while our target -character set is still @sc{ascii}, we get jibberish: - -@smallexample -(gdb) print ibm1047_hello -$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" -(gdb) print ibm1047_hello[0] -$5 = 200 '\310' -(gdb) -@end smallexample - -If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, -@value{GDBN} tells us the character sets it supports: - -@smallexample -(gdb) set target-charset -ASCII EBCDIC-US IBM1047 ISO-8859-1 -(gdb) set target-charset -@end smallexample - -We can select @sc{ibm1047} as our target character set, and examine the -program's strings again. Now the @sc{ascii} string is wrong, but -@value{GDBN} translates the contents of @code{ibm1047_hello} from the -target character set, @sc{ibm1047}, to the host character set, -@sc{ascii}, and they display correctly: - -@smallexample -(gdb) set target-charset IBM1047 -(gdb) show charset -The current host character set is `ASCII'. -The current target character set is `IBM1047'. -(gdb) print ascii_hello -$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" -(gdb) print ascii_hello[0] -$7 = 72 '\110' -(gdb) print ibm1047_hello -$8 = 0x4016a8 "Hello, world!\n" -(gdb) print ibm1047_hello[0] -$9 = 200 'H' -(gdb) -@end smallexample - -As above, @value{GDBN} uses the target character set for character and -string literals you use in expressions: - -@smallexample -(gdb) print '+' -$10 = 78 '+' -(gdb) -@end smallexample - -The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} -character. - - -@node Macros -@chapter C Preprocessor Macros - -Some languages, such as C and C@t{++}, provide a way to define and invoke -``preprocessor macros'' which expand into strings of tokens. -@value{GDBN} can evaluate expressions containing macro invocations, show -the result of macro expansion, and show a macro's definition, including -where it was defined. - -You may need to compile your program specially to provide @value{GDBN} -with information about preprocessor macros. Most compilers do not -include macros in their debugging information, even when you compile -with the @option{-g} flag. @xref{Compilation}. - -A program may define a macro at one point, remove that definition later, -and then provide a different definition after that. Thus, at different -points in the program, a macro may have different definitions, or have -no definition at all. If there is a current stack frame, @value{GDBN} -uses the macros in scope at that frame's source code line. Otherwise, -@value{GDBN} uses the macros in scope at the current listing location; -see @ref{List}. - -At the moment, @value{GDBN} does not support the @code{##} -token-splicing operator, the @code{#} stringification operator, or -variable-arity macros. - -Whenever @value{GDBN} evaluates an expression, it always expands any -macro invocations present in the expression. @value{GDBN} also provides -the following commands for working with macros explicitly. - -@table @code - -@kindex macro expand -@cindex macro expansion, showing the results of preprocessor -@cindex preprocessor macro expansion, showing the results of -@cindex expanding preprocessor macros -@item macro expand @var{expression} -@itemx macro exp @var{expression} -Show the results of expanding all preprocessor macro invocations in -@var{expression}. Since @value{GDBN} simply expands macros, but does -not parse the result, @var{expression} need not be a valid expression; -it can be any string of tokens. - -@kindex macro expand-once -@item macro expand-once @var{expression} -@itemx macro exp1 @var{expression} -@i{(This command is not yet implemented.)} Show the results of -expanding those preprocessor macro invocations that appear explicitly in -@var{expression}. Macro invocations appearing in that expansion are -left unchanged. This command allows you to see the effect of a -particular macro more clearly, without being confused by further -expansions. Since @value{GDBN} simply expands macros, but does not -parse the result, @var{expression} need not be a valid expression; it -can be any string of tokens. - -@kindex info macro -@cindex macro definition, showing -@cindex definition, showing a macro's -@item info macro @var{macro} -Show the definition of the macro named @var{macro}, and describe the -source location where that definition was established. - -@kindex macro define -@cindex user-defined macros -@cindex defining macros interactively -@cindex macros, user-defined -@item macro define @var{macro} @var{replacement-list} -@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list} -@i{(This command is not yet implemented.)} Introduce a definition for a -preprocessor macro named @var{macro}, invocations of which are replaced -by the tokens given in @var{replacement-list}. The first form of this -command defines an ``object-like'' macro, which takes no arguments; the -second form defines a ``function-like'' macro, which takes the arguments -given in @var{arglist}. - -A definition introduced by this command is in scope in every expression -evaluated in @value{GDBN}, until it is removed with the @command{macro -undef} command, described below. The definition overrides all -definitions for @var{macro} present in the program being debugged, as -well as any previous user-supplied definition. - -@kindex macro undef -@item macro undef @var{macro} -@i{(This command is not yet implemented.)} Remove any user-supplied -definition for the macro named @var{macro}. This command only affects -definitions provided with the @command{macro define} command, described -above; it cannot remove definitions present in the program being -debugged. - -@end table - -@cindex macros, example of debugging with -Here is a transcript showing the above commands in action. First, we -show our source files: - -@smallexample -$ cat sample.c -#include <stdio.h> -#include "sample.h" - -#define M 42 -#define ADD(x) (M + x) - -main () -@{ -#define N 28 - printf ("Hello, world!\n"); -#undef N - printf ("We're so creative.\n"); -#define N 1729 - printf ("Goodbye, world!\n"); -@} -$ cat sample.h -#define Q < -$ -@end smallexample - -Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}. -We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the -compiler includes information about preprocessor macros in the debugging -information. - -@smallexample -$ gcc -gdwarf-2 -g3 sample.c -o sample -$ -@end smallexample - -Now, we start @value{GDBN} on our sample program: - -@smallexample -$ gdb -nw sample -GNU gdb 2002-05-06-cvs -Copyright 2002 Free Software Foundation, Inc. -GDB is free software, @dots{} -(gdb) -@end smallexample - -We can expand macros and examine their definitions, even when the -program is not running. @value{GDBN} uses the current listing position -to decide which macro definitions are in scope: - -@smallexample -(gdb) list main -3 -4 #define M 42 -5 #define ADD(x) (M + x) -6 -7 main () -8 @{ -9 #define N 28 -10 printf ("Hello, world!\n"); -11 #undef N -12 printf ("We're so creative.\n"); -(gdb) info macro ADD -Defined at /home/jimb/gdb/macros/play/sample.c:5 -#define ADD(x) (M + x) -(gdb) info macro Q -Defined at /home/jimb/gdb/macros/play/sample.h:1 - included at /home/jimb/gdb/macros/play/sample.c:2 -#define Q < -(gdb) macro expand ADD(1) -expands to: (42 + 1) -(gdb) macro expand-once ADD(1) -expands to: once (M + 1) -(gdb) -@end smallexample - -In the example above, note that @command{macro expand-once} expands only -the macro invocation explicit in the original text --- the invocation of -@code{ADD} --- but does not expand the invocation of the macro @code{M}, -which was introduced by @code{ADD}. - -Once the program is running, GDB uses the macro definitions in force at -the source line of the current stack frame: - -@smallexample -(gdb) break main -Breakpoint 1 at 0x8048370: file sample.c, line 10. -(gdb) run -Starting program: /home/jimb/gdb/macros/play/sample - -Breakpoint 1, main () at sample.c:10 -10 printf ("Hello, world!\n"); -(gdb) -@end smallexample - -At line 10, the definition of the macro @code{N} at line 9 is in force: - -@smallexample -(gdb) info macro N -Defined at /home/jimb/gdb/macros/play/sample.c:9 -#define N 28 -(gdb) macro expand N Q M -expands to: 28 < 42 -(gdb) print N Q M -$1 = 1 -(gdb) -@end smallexample - -As we step over directives that remove @code{N}'s definition, and then -give it a new definition, @value{GDBN} finds the definition (or lack -thereof) in force at each point: - -@smallexample -(gdb) next -Hello, world! -12 printf ("We're so creative.\n"); -(gdb) info macro N -The symbol `N' has no definition as a C/C++ preprocessor macro -at /home/jimb/gdb/macros/play/sample.c:12 -(gdb) next -We're so creative. -14 printf ("Goodbye, world!\n"); -(gdb) info macro N -Defined at /home/jimb/gdb/macros/play/sample.c:13 -#define N 1729 -(gdb) macro expand N Q M -expands to: 1729 < 42 -(gdb) print N Q M -$2 = 0 -(gdb) -@end smallexample - - -@node Tracepoints -@chapter Tracepoints -@c This chapter is based on the documentation written by Michael -@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. - -@cindex tracepoints -In some applications, it is not feasible for the debugger to interrupt -the program's execution long enough for the developer to learn -anything helpful about its behavior. If the program's correctness -depends on its real-time behavior, delays introduced by a debugger -might cause the program to change its behavior drastically, or perhaps -fail, even when the code itself is correct. It is useful to be able -to observe the program's behavior without interrupting it. - -Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can -specify locations in the program, called @dfn{tracepoints}, and -arbitrary expressions to evaluate when those tracepoints are reached. -Later, using the @code{tfind} command, you can examine the values -those expressions had when the program hit the tracepoints. The -expressions may also denote objects in memory---structures or arrays, -for example---whose values @value{GDBN} should record; while visiting -a particular tracepoint, you may inspect those objects as if they were -in memory at that moment. However, because @value{GDBN} records these -values without interacting with you, it can do so quickly and -unobtrusively, hopefully not disturbing the program's behavior. - -The tracepoint facility is currently available only for remote -targets. @xref{Targets}. In addition, your remote target must know how -to collect trace data. This functionality is implemented in the remote -stub; however, none of the stubs distributed with @value{GDBN} support -tracepoints as of this writing. - -This chapter describes the tracepoint commands and features. - -@menu -* Set Tracepoints:: -* Analyze Collected Data:: -* Tracepoint Variables:: -@end menu - -@node Set Tracepoints -@section Commands to Set Tracepoints - -Before running such a @dfn{trace experiment}, an arbitrary number of -tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a -tracepoint has a number assigned to it by @value{GDBN}. Like with -breakpoints, tracepoint numbers are successive integers starting from -one. Many of the commands associated with tracepoints take the -tracepoint number as their argument, to identify which tracepoint to -work on. - -For each tracepoint, you can specify, in advance, some arbitrary set -of data that you want the target to collect in the trace buffer when -it hits that tracepoint. The collected data can include registers, -local variables, or global data. Later, you can use @value{GDBN} -commands to examine the values these data had at the time the -tracepoint was hit. - -This section describes commands to set tracepoints and associated -conditions and actions. - -@menu -* Create and Delete Tracepoints:: -* Enable and Disable Tracepoints:: -* Tracepoint Passcounts:: -* Tracepoint Actions:: -* Listing Tracepoints:: -* Starting and Stopping Trace Experiment:: -@end menu - -@node Create and Delete Tracepoints -@subsection Create and Delete Tracepoints - -@table @code -@cindex set tracepoint -@kindex trace -@item trace -The @code{trace} command is very similar to the @code{break} command. -Its argument can be a source line, a function name, or an address in -the target program. @xref{Set Breaks}. The @code{trace} command -defines a tracepoint, which is a point in the target program where the -debugger will briefly stop, collect some data, and then allow the -program to continue. Setting a tracepoint or changing its commands -doesn't take effect until the next @code{tstart} command; thus, you -cannot change the tracepoint attributes once a trace experiment is -running. - -Here are some examples of using the @code{trace} command: - -@smallexample -(@value{GDBP}) @b{trace foo.c:121} // a source file and line number - -(@value{GDBP}) @b{trace +2} // 2 lines forward - -(@value{GDBP}) @b{trace my_function} // first source line of function - -(@value{GDBP}) @b{trace *my_function} // EXACT start address of function - -(@value{GDBP}) @b{trace *0x2117c4} // an address -@end smallexample - -@noindent -You can abbreviate @code{trace} as @code{tr}. - -@vindex $tpnum -@cindex last tracepoint number -@cindex recent tracepoint number -@cindex tracepoint number -The convenience variable @code{$tpnum} records the tracepoint number -of the most recently set tracepoint. - -@kindex delete tracepoint -@cindex tracepoint deletion -@item delete tracepoint @r{[}@var{num}@r{]} -Permanently delete one or more tracepoints. With no argument, the -default is to delete all tracepoints. - -Examples: - -@smallexample -(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints - -(@value{GDBP}) @b{delete trace} // remove all tracepoints -@end smallexample - -@noindent -You can abbreviate this command as @code{del tr}. -@end table - -@node Enable and Disable Tracepoints -@subsection Enable and Disable Tracepoints - -@table @code -@kindex disable tracepoint -@item disable tracepoint @r{[}@var{num}@r{]} -Disable tracepoint @var{num}, or all tracepoints if no argument -@var{num} is given. A disabled tracepoint will have no effect during -the next trace experiment, but it is not forgotten. You can re-enable -a disabled tracepoint using the @code{enable tracepoint} command. - -@kindex enable tracepoint -@item enable tracepoint @r{[}@var{num}@r{]} -Enable tracepoint @var{num}, or all tracepoints. The enabled -tracepoints will become effective the next time a trace experiment is -run. -@end table - -@node Tracepoint Passcounts -@subsection Tracepoint Passcounts - -@table @code -@kindex passcount -@cindex tracepoint pass count -@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} -Set the @dfn{passcount} of a tracepoint. The passcount is a way to -automatically stop a trace experiment. If a tracepoint's passcount is -@var{n}, then the trace experiment will be automatically stopped on -the @var{n}'th time that tracepoint is hit. If the tracepoint number -@var{num} is not specified, the @code{passcount} command sets the -passcount of the most recently defined tracepoint. If no passcount is -given, the trace experiment will run until stopped explicitly by the -user. - -Examples: - -@smallexample -(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of -@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} - -(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the -@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.} -(@value{GDBP}) @b{trace foo} -(@value{GDBP}) @b{pass 3} -(@value{GDBP}) @b{trace bar} -(@value{GDBP}) @b{pass 2} -(@value{GDBP}) @b{trace baz} -(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been -@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has} -@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times} -@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.} -@end smallexample -@end table - -@node Tracepoint Actions -@subsection Tracepoint Action Lists - -@table @code -@kindex actions -@cindex tracepoint actions -@item actions @r{[}@var{num}@r{]} -This command will prompt for a list of actions to be taken when the -tracepoint is hit. If the tracepoint number @var{num} is not -specified, this command sets the actions for the one that was most -recently defined (so that you can define a tracepoint and then say -@code{actions} without bothering about its number). You specify the -actions themselves on the following lines, one action at a time, and -terminate the actions list with a line containing just @code{end}. So -far, the only defined actions are @code{collect} and -@code{while-stepping}. - -@cindex remove actions from a tracepoint -To remove all actions from a tracepoint, type @samp{actions @var{num}} -and follow it immediately with @samp{end}. - -@smallexample -(@value{GDBP}) @b{collect @var{data}} // collect some data - -(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data - -(@value{GDBP}) @b{end} // signals the end of actions. -@end smallexample - -In the following example, the action list begins with @code{collect} -commands indicating the things to be collected when the tracepoint is -hit. Then, in order to single-step and collect additional data -following the tracepoint, a @code{while-stepping} command is used, -followed by the list of things to be collected while stepping. The -@code{while-stepping} command is terminated by its own separate -@code{end} command. Lastly, the action list is terminated by an -@code{end} command. - -@smallexample -(@value{GDBP}) @b{trace foo} -(@value{GDBP}) @b{actions} -Enter actions for tracepoint 1, one per line: -> collect bar,baz -> collect $regs -> while-stepping 12 - > collect $fp, $sp - > end -end -@end smallexample - -@kindex collect @r{(tracepoints)} -@item collect @var{expr1}, @var{expr2}, @dots{} -Collect values of the given expressions when the tracepoint is hit. -This command accepts a comma-separated list of any valid expressions. -In addition to global, static, or local variables, the following -special arguments are supported: - -@table @code -@item $regs -collect all registers - -@item $args -collect all function arguments - -@item $locals -collect all local variables. -@end table - -You can give several consecutive @code{collect} commands, each one -with a single argument, or one @code{collect} command with several -arguments separated by commas: the effect is the same. - -The command @code{info scope} (@pxref{Symbols, info scope}) is -particularly useful for figuring out what data to collect. - -@kindex while-stepping @r{(tracepoints)} -@item while-stepping @var{n} -Perform @var{n} single-step traces after the tracepoint, collecting -new data at each step. The @code{while-stepping} command is -followed by the list of what to collect while stepping (followed by -its own @code{end} command): - -@smallexample -> while-stepping 12 - > collect $regs, myglobal - > end -> -@end smallexample - -@noindent -You may abbreviate @code{while-stepping} as @code{ws} or -@code{stepping}. -@end table - -@node Listing Tracepoints -@subsection Listing Tracepoints - -@table @code -@kindex info tracepoints -@cindex information about tracepoints -@item info tracepoints @r{[}@var{num}@r{]} -Display information about the tracepoint @var{num}. If you don't specify -a tracepoint number, displays information about all the tracepoints -defined so far. For each tracepoint, the following information is -shown: - -@itemize @bullet -@item -its number -@item -whether it is enabled or disabled -@item -its address -@item -its passcount as given by the @code{passcount @var{n}} command -@item -its step count as given by the @code{while-stepping @var{n}} command -@item -where in the source files is the tracepoint set -@item -its action list as given by the @code{actions} command -@end itemize - -@smallexample -(@value{GDBP}) @b{info trace} -Num Enb Address PassC StepC What -1 y 0x002117c4 0 0 <gdb_asm> -2 y 0x0020dc64 0 0 in g_test at g_test.c:1375 -3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41 -(@value{GDBP}) -@end smallexample - -@noindent -This command can be abbreviated @code{info tp}. -@end table - -@node Starting and Stopping Trace Experiment -@subsection Starting and Stopping Trace Experiment - -@table @code -@kindex tstart -@cindex start a new trace experiment -@cindex collected data discarded -@item tstart -This command takes no arguments. It starts the trace experiment, and -begins collecting data. This has the side effect of discarding all -the data collected in the trace buffer during the previous trace -experiment. - -@kindex tstop -@cindex stop a running trace experiment -@item tstop -This command takes no arguments. It ends the trace experiment, and -stops collecting data. - -@strong{Note:} a trace experiment and data collection may stop -automatically if any tracepoint's passcount is reached -(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. - -@kindex tstatus -@cindex status of trace data collection -@cindex trace experiment, status of -@item tstatus -This command displays the status of the current trace data -collection. -@end table - -Here is an example of the commands we described so far: - -@smallexample -(@value{GDBP}) @b{trace gdb_c_test} -(@value{GDBP}) @b{actions} -Enter actions for tracepoint #1, one per line. -> collect $regs,$locals,$args -> while-stepping 11 - > collect $regs - > end -> end -(@value{GDBP}) @b{tstart} - [time passes @dots{}] -(@value{GDBP}) @b{tstop} -@end smallexample - - -@node Analyze Collected Data -@section Using the collected data - -After the tracepoint experiment ends, you use @value{GDBN} commands -for examining the trace data. The basic idea is that each tracepoint -collects a trace @dfn{snapshot} every time it is hit and another -snapshot every time it single-steps. All these snapshots are -consecutively numbered from zero and go into a buffer, and you can -examine them later. The way you examine them is to @dfn{focus} on a -specific trace snapshot. When the remote stub is focused on a trace -snapshot, it will respond to all @value{GDBN} requests for memory and -registers by reading from the buffer which belongs to that snapshot, -rather than from @emph{real} memory or registers of the program being -debugged. This means that @strong{all} @value{GDBN} commands -(@code{print}, @code{info registers}, @code{backtrace}, etc.) will -behave as if we were currently debugging the program state as it was -when the tracepoint occurred. Any requests for data that are not in -the buffer will fail. - -@menu -* tfind:: How to select a trace snapshot -* tdump:: How to display all data for a snapshot -* save-tracepoints:: How to save tracepoints for a future run -@end menu - -@node tfind -@subsection @code{tfind @var{n}} - -@kindex tfind -@cindex select trace snapshot -@cindex find trace snapshot -The basic command for selecting a trace snapshot from the buffer is -@code{tfind @var{n}}, which finds trace snapshot number @var{n}, -counting from zero. If no argument @var{n} is given, the next -snapshot is selected. - -Here are the various forms of using the @code{tfind} command. - -@table @code -@item tfind start -Find the first snapshot in the buffer. This is a synonym for -@code{tfind 0} (since 0 is the number of the first snapshot). - -@item tfind none -Stop debugging trace snapshots, resume @emph{live} debugging. - -@item tfind end -Same as @samp{tfind none}. - -@item tfind -No argument means find the next trace snapshot. - -@item tfind - -Find the previous trace snapshot before the current one. This permits -retracing earlier steps. - -@item tfind tracepoint @var{num} -Find the next snapshot associated with tracepoint @var{num}. Search -proceeds forward from the last examined trace snapshot. If no -argument @var{num} is given, it means find the next snapshot collected -for the same tracepoint as the current snapshot. - -@item tfind pc @var{addr} -Find the next snapshot associated with the value @var{addr} of the -program counter. Search proceeds forward from the last examined trace -snapshot. If no argument @var{addr} is given, it means find the next -snapshot with the same value of PC as the current snapshot. - -@item tfind outside @var{addr1}, @var{addr2} -Find the next snapshot whose PC is outside the given range of -addresses. - -@item tfind range @var{addr1}, @var{addr2} -Find the next snapshot whose PC is between @var{addr1} and -@var{addr2}. @c FIXME: Is the range inclusive or exclusive? - -@item tfind line @r{[}@var{file}:@r{]}@var{n} -Find the next snapshot associated with the source line @var{n}. If -the optional argument @var{file} is given, refer to line @var{n} in -that source file. Search proceeds forward from the last examined -trace snapshot. If no argument @var{n} is given, it means find the -next line other than the one currently being examined; thus saying -@code{tfind line} repeatedly can appear to have the same effect as -stepping from line to line in a @emph{live} debugging session. -@end table - -The default arguments for the @code{tfind} commands are specifically -designed to make it easy to scan through the trace buffer. For -instance, @code{tfind} with no argument selects the next trace -snapshot, and @code{tfind -} with no argument selects the previous -trace snapshot. So, by giving one @code{tfind} command, and then -simply hitting @key{RET} repeatedly you can examine all the trace -snapshots in order. Or, by saying @code{tfind -} and then hitting -@key{RET} repeatedly you can examine the snapshots in reverse order. -The @code{tfind line} command with no argument selects the snapshot -for the next source line executed. The @code{tfind pc} command with -no argument selects the next snapshot with the same program counter -(PC) as the current frame. The @code{tfind tracepoint} command with -no argument selects the next trace snapshot collected by the same -tracepoint as the current one. - -In addition to letting you scan through the trace buffer manually, -these commands make it easy to construct @value{GDBN} scripts that -scan through the trace buffer and print out whatever collected data -you are interested in. Thus, if we want to examine the PC, FP, and SP -registers from each trace frame in the buffer, we can say this: - -@smallexample -(@value{GDBP}) @b{tfind start} -(@value{GDBP}) @b{while ($trace_frame != -1)} -> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ - $trace_frame, $pc, $sp, $fp -> tfind -> end - -Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 -Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 -Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 -Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 -Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 -Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 -Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 -Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 -Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 -Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 -Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 -@end smallexample - -Or, if we want to examine the variable @code{X} at each source line in -the buffer: - -@smallexample -(@value{GDBP}) @b{tfind start} -(@value{GDBP}) @b{while ($trace_frame != -1)} -> printf "Frame %d, X == %d\n", $trace_frame, X -> tfind line -> end - -Frame 0, X = 1 -Frame 7, X = 2 -Frame 13, X = 255 -@end smallexample - -@node tdump -@subsection @code{tdump} -@kindex tdump -@cindex dump all data collected at tracepoint -@cindex tracepoint data, display - -This command takes no arguments. It prints all the data collected at -the current trace snapshot. - -@smallexample -(@value{GDBP}) @b{trace 444} -(@value{GDBP}) @b{actions} -Enter actions for tracepoint #2, one per line: -> collect $regs, $locals, $args, gdb_long_test -> end - -(@value{GDBP}) @b{tstart} - -(@value{GDBP}) @b{tfind line 444} -#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) -at gdb_test.c:444 -444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) - -(@value{GDBP}) @b{tdump} -Data collected at tracepoint 2, trace frame 1: -d0 0xc4aa0085 -995491707 -d1 0x18 24 -d2 0x80 128 -d3 0x33 51 -d4 0x71aea3d 119204413 -d5 0x22 34 -d6 0xe0 224 -d7 0x380035 3670069 -a0 0x19e24a 1696330 -a1 0x3000668 50333288 -a2 0x100 256 -a3 0x322000 3284992 -a4 0x3000698 50333336 -a5 0x1ad3cc 1758156 -fp 0x30bf3c 0x30bf3c -sp 0x30bf34 0x30bf34 -ps 0x0 0 -pc 0x20b2c8 0x20b2c8 -fpcontrol 0x0 0 -fpstatus 0x0 0 -fpiaddr 0x0 0 -p = 0x20e5b4 "gdb-test" -p1 = (void *) 0x11 -p2 = (void *) 0x22 -p3 = (void *) 0x33 -p4 = (void *) 0x44 -p5 = (void *) 0x55 -p6 = (void *) 0x66 -gdb_long_test = 17 '\021' - -(@value{GDBP}) -@end smallexample - -@node save-tracepoints -@subsection @code{save-tracepoints @var{filename}} -@kindex save-tracepoints -@cindex save tracepoints for future sessions - -This command saves all current tracepoint definitions together with -their actions and passcounts, into a file @file{@var{filename}} -suitable for use in a later debugging session. To read the saved -tracepoint definitions, use the @code{source} command (@pxref{Command -Files}). - -@node Tracepoint Variables -@section Convenience Variables for Tracepoints -@cindex tracepoint variables -@cindex convenience variables for tracepoints - -@table @code -@vindex $trace_frame -@item (int) $trace_frame -The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no -snapshot is selected. - -@vindex $tracepoint -@item (int) $tracepoint -The tracepoint for the current trace snapshot. - -@vindex $trace_line -@item (int) $trace_line -The line number for the current trace snapshot. - -@vindex $trace_file -@item (char []) $trace_file -The source file for the current trace snapshot. - -@vindex $trace_func -@item (char []) $trace_func -The name of the function containing @code{$tracepoint}. -@end table - -Note: @code{$trace_file} is not suitable for use in @code{printf}, -use @code{output} instead. - -Here's a simple example of using these convenience variables for -stepping through all the trace snapshots and printing some of their -data. - -@smallexample -(@value{GDBP}) @b{tfind start} - -(@value{GDBP}) @b{while $trace_frame != -1} -> output $trace_file -> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint -> tfind -> end -@end smallexample - -@node Overlays -@chapter Debugging Programs That Use Overlays -@cindex overlays - -If your program is too large to fit completely in your target system's -memory, you can sometimes use @dfn{overlays} to work around this -problem. @value{GDBN} provides some support for debugging programs that -use overlays. - -@menu -* How Overlays Work:: A general explanation of overlays. -* Overlay Commands:: Managing overlays in @value{GDBN}. -* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are - mapped by asking the inferior. -* Overlay Sample Program:: A sample program using overlays. -@end menu - -@node How Overlays Work -@section How Overlays Work -@cindex mapped overlays -@cindex unmapped overlays -@cindex load address, overlay's -@cindex mapped address -@cindex overlay area - -Suppose you have a computer whose instruction address space is only 64 -kilobytes long, but which has much more memory which can be accessed by -other means: special instructions, segment registers, or memory -management hardware, for example. Suppose further that you want to -adapt a program which is larger than 64 kilobytes to run on this system. - -One solution is to identify modules of your program which are relatively -independent, and need not call each other directly; call these modules -@dfn{overlays}. Separate the overlays from the main program, and place -their machine code in the larger memory. Place your main program in -instruction memory, but leave at least enough space there to hold the -largest overlay as well. - -Now, to call a function located in an overlay, you must first copy that -overlay's machine code from the large memory into the space set aside -for it in the instruction memory, and then jump to its entry point -there. - -@c NB: In the below the mapped area's size is greater or equal to the -@c size of all overlays. This is intentional to remind the developer -@c that overlays don't necessarily need to be the same size. - -@smallexample -@group - Data Instruction Larger -Address Space Address Space Address Space -+-----------+ +-----------+ +-----------+ -| | | | | | -+-----------+ +-----------+ +-----------+<-- overlay 1 -| program | | main | .----| overlay 1 | load address -| variables | | program | | +-----------+ -| and heap | | | | | | -+-----------+ | | | +-----------+<-- overlay 2 -| | +-----------+ | | | load address -+-----------+ | | | .-| overlay 2 | - | | | | | | - mapped --->+-----------+ | | +-----------+ - address | | | | | | - | overlay | <-' | | | - | area | <---' +-----------+<-- overlay 3 - | | <---. | | load address - +-----------+ `--| overlay 3 | - | | | | - +-----------+ | | - +-----------+ - | | - +-----------+ - - @anchor{A code overlay}A code overlay -@end group -@end smallexample - -The diagram (@pxref{A code overlay}) shows a system with separate data -and instruction address spaces. To map an overlay, the program copies -its code from the larger address space to the instruction address space. -Since the overlays shown here all use the same mapped address, only one -may be mapped at a time. For a system with a single address space for -data and instructions, the diagram would be similar, except that the -program variables and heap would share an address space with the main -program and the overlay area. - -An overlay loaded into instruction memory and ready for use is called a -@dfn{mapped} overlay; its @dfn{mapped address} is its address in the -instruction memory. An overlay not present (or only partially present) -in instruction memory is called @dfn{unmapped}; its @dfn{load address} -is its address in the larger memory. The mapped address is also called -the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also -called the @dfn{load memory address}, or @dfn{LMA}. - -Unfortunately, overlays are not a completely transparent way to adapt a -program to limited instruction memory. They introduce a new set of -global constraints you must keep in mind as you design your program: - -@itemize @bullet - -@item -Before calling or returning to a function in an overlay, your program -must make sure that overlay is actually mapped. Otherwise, the call or -return will transfer control to the right address, but in the wrong -overlay, and your program will probably crash. - -@item -If the process of mapping an overlay is expensive on your system, you -will need to choose your overlays carefully to minimize their effect on -your program's performance. - -@item -The executable file you load onto your system must contain each -overlay's instructions, appearing at the overlay's load address, not its -mapped address. However, each overlay's instructions must be relocated -and its symbols defined as if the overlay were at its mapped address. -You can use GNU linker scripts to specify different load and relocation -addresses for pieces of your program; see @ref{Overlay Description,,, -ld.info, Using ld: the GNU linker}. - -@item -The procedure for loading executable files onto your system must be able -to load their contents into the larger address space as well as the -instruction and data spaces. - -@end itemize - -The overlay system described above is rather simple, and could be -improved in many ways: - -@itemize @bullet - -@item -If your system has suitable bank switch registers or memory management -hardware, you could use those facilities to make an overlay's load area -contents simply appear at their mapped address in instruction space. -This would probably be faster than copying the overlay to its mapped -area in the usual way. - -@item -If your overlays are small enough, you could set aside more than one -overlay area, and have more than one overlay mapped at a time. - -@item -You can use overlays to manage data, as well as instructions. In -general, data overlays are even less transparent to your design than -code overlays: whereas code overlays only require care when you call or -return to functions, data overlays require care every time you access -the data. Also, if you change the contents of a data overlay, you -must copy its contents back out to its load address before you can copy a -different data overlay into the same mapped area. - -@end itemize - - -@node Overlay Commands -@section Overlay Commands - -To use @value{GDBN}'s overlay support, each overlay in your program must -correspond to a separate section of the executable file. The section's -virtual memory address and load memory address must be the overlay's -mapped and load addresses. Identifying overlays with sections allows -@value{GDBN} to determine the appropriate address of a function or -variable, depending on whether the overlay is mapped or not. - -@value{GDBN}'s overlay commands all start with the word @code{overlay}; -you can abbreviate this as @code{ov} or @code{ovly}. The commands are: - -@table @code -@item overlay off -@kindex overlay off -Disable @value{GDBN}'s overlay support. When overlay support is -disabled, @value{GDBN} assumes that all functions and variables are -always present at their mapped addresses. By default, @value{GDBN}'s -overlay support is disabled. - -@item overlay manual -@kindex overlay manual -@cindex manual overlay debugging -Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} -relies on you to tell it which overlays are mapped, and which are not, -using the @code{overlay map-overlay} and @code{overlay unmap-overlay} -commands described below. - -@item overlay map-overlay @var{overlay} -@itemx overlay map @var{overlay} -@kindex overlay map-overlay -@cindex map an overlay -Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must -be the name of the object file section containing the overlay. When an -overlay is mapped, @value{GDBN} assumes it can find the overlay's -functions and variables at their mapped addresses. @value{GDBN} assumes -that any other overlays whose mapped ranges overlap that of -@var{overlay} are now unmapped. - -@item overlay unmap-overlay @var{overlay} -@itemx overlay unmap @var{overlay} -@kindex overlay unmap-overlay -@cindex unmap an overlay -Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} -must be the name of the object file section containing the overlay. -When an overlay is unmapped, @value{GDBN} assumes it can find the -overlay's functions and variables at their load addresses. - -@item overlay auto -@kindex overlay auto -Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} -consults a data structure the overlay manager maintains in the inferior -to see which overlays are mapped. For details, see @ref{Automatic -Overlay Debugging}. - -@item overlay load-target -@itemx overlay load -@kindex overlay load-target -@cindex reloading the overlay table -Re-read the overlay table from the inferior. Normally, @value{GDBN} -re-reads the table @value{GDBN} automatically each time the inferior -stops, so this command should only be necessary if you have changed the -overlay mapping yourself using @value{GDBN}. This command is only -useful when using automatic overlay debugging. - -@item overlay list-overlays -@itemx overlay list -@cindex listing mapped overlays -Display a list of the overlays currently mapped, along with their mapped -addresses, load addresses, and sizes. - -@end table - -Normally, when @value{GDBN} prints a code address, it includes the name -of the function the address falls in: - -@smallexample -(gdb) print main -$3 = @{int ()@} 0x11a0 <main> -@end smallexample -@noindent -When overlay debugging is enabled, @value{GDBN} recognizes code in -unmapped overlays, and prints the names of unmapped functions with -asterisks around them. For example, if @code{foo} is a function in an -unmapped overlay, @value{GDBN} prints it this way: - -@smallexample -(gdb) overlay list -No sections are mapped. -(gdb) print foo -$5 = @{int (int)@} 0x100000 <*foo*> -@end smallexample -@noindent -When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's -name normally: - -@smallexample -(gdb) overlay list -Section .ov.foo.text, loaded at 0x100000 - 0x100034, - mapped at 0x1016 - 0x104a -(gdb) print foo -$6 = @{int (int)@} 0x1016 <foo> -@end smallexample - -When overlay debugging is enabled, @value{GDBN} can find the correct -address for functions and variables in an overlay, whether or not the -overlay is mapped. This allows most @value{GDBN} commands, like -@code{break} and @code{disassemble}, to work normally, even on unmapped -code. However, @value{GDBN}'s breakpoint support has some limitations: - -@itemize @bullet -@item -@cindex breakpoints in overlays -@cindex overlays, setting breakpoints in -You can set breakpoints in functions in unmapped overlays, as long as -@value{GDBN} can write to the overlay at its load address. -@item -@value{GDBN} can not set hardware or simulator-based breakpoints in -unmapped overlays. However, if you set a breakpoint at the end of your -overlay manager (and tell @value{GDBN} which overlays are now mapped, if -you are using manual overlay management), @value{GDBN} will re-set its -breakpoints properly. -@end itemize - - -@node Automatic Overlay Debugging -@section Automatic Overlay Debugging -@cindex automatic overlay debugging - -@value{GDBN} can automatically track which overlays are mapped and which -are not, given some simple co-operation from the overlay manager in the -inferior. If you enable automatic overlay debugging with the -@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN} -looks in the inferior's memory for certain variables describing the -current state of the overlays. - -Here are the variables your overlay manager must define to support -@value{GDBN}'s automatic overlay debugging: - -@table @asis - -@item @code{_ovly_table}: -This variable must be an array of the following structures: - -@smallexample -struct -@{ - /* The overlay's mapped address. */ - unsigned long vma; - - /* The size of the overlay, in bytes. */ - unsigned long size; - - /* The overlay's load address. */ - unsigned long lma; - - /* Non-zero if the overlay is currently mapped; - zero otherwise. */ - unsigned long mapped; -@} -@end smallexample - -@item @code{_novlys}: -This variable must be a four-byte signed integer, holding the total -number of elements in @code{_ovly_table}. - -@end table - -To decide whether a particular overlay is mapped or not, @value{GDBN} -looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and -@code{lma} members equal the VMA and LMA of the overlay's section in the -executable file. When @value{GDBN} finds a matching entry, it consults -the entry's @code{mapped} member to determine whether the overlay is -currently mapped. - -In addition, your overlay manager may define a function called -@code{_ovly_debug_event}. If this function is defined, @value{GDBN} -will silently set a breakpoint there. If the overlay manager then -calls this function whenever it has changed the overlay table, this -will enable @value{GDBN} to accurately keep track of which overlays -are in program memory, and update any breakpoints that may be set -in overlays. This will allow breakpoints to work even if the -overlays are kept in ROM or other non-writable memory while they -are not being executed. - -@node Overlay Sample Program -@section Overlay Sample Program -@cindex overlay example program - -When linking a program which uses overlays, you must place the overlays -at their load addresses, while relocating them to run at their mapped -addresses. To do this, you must write a linker script (@pxref{Overlay -Description,,, ld.info, Using ld: the GNU linker}). Unfortunately, -since linker scripts are specific to a particular host system, target -architecture, and target memory layout, this manual cannot provide -portable sample code demonstrating @value{GDBN}'s overlay support. - -However, the @value{GDBN} source distribution does contain an overlaid -program, with linker scripts for a few systems, as part of its test -suite. The program consists of the following files from -@file{gdb/testsuite/gdb.base}: - -@table @file -@item overlays.c -The main program file. -@item ovlymgr.c -A simple overlay manager, used by @file{overlays.c}. -@item foo.c -@itemx bar.c -@itemx baz.c -@itemx grbx.c -Overlay modules, loaded and used by @file{overlays.c}. -@item d10v.ld -@itemx m32r.ld -Linker scripts for linking the test program on the @code{d10v-elf} -and @code{m32r-elf} targets. -@end table - -You can build the test program using the @code{d10v-elf} GCC -cross-compiler like this: - -@smallexample -$ d10v-elf-gcc -g -c overlays.c -$ d10v-elf-gcc -g -c ovlymgr.c -$ d10v-elf-gcc -g -c foo.c -$ d10v-elf-gcc -g -c bar.c -$ d10v-elf-gcc -g -c baz.c -$ d10v-elf-gcc -g -c grbx.c -$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ - baz.o grbx.o -Wl,-Td10v.ld -o overlays -@end smallexample - -The build process is identical for any other architecture, except that -you must substitute the appropriate compiler and linker script for the -target system for @code{d10v-elf-gcc} and @code{d10v.ld}. - - -@node Languages -@chapter Using @value{GDBN} with Different Languages -@cindex languages - -Although programming languages generally have common aspects, they are -rarely expressed in the same manner. For instance, in ANSI C, -dereferencing a pointer @code{p} is accomplished by @code{*p}, but in -Modula-2, it is accomplished by @code{p^}. Values can also be -represented (and displayed) differently. Hex numbers in C appear as -@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. - -@cindex working language -Language-specific information is built into @value{GDBN} for some languages, -allowing you to express operations like the above in your program's -native language, and allowing @value{GDBN} to output values in a manner -consistent with the syntax of your program's native language. The -language you use to build expressions is called the @dfn{working -language}. - -@menu -* Setting:: Switching between source languages -* Show:: Displaying the language -* Checks:: Type and range checks -* Support:: Supported languages -* Unsupported languages:: Unsupported languages -@end menu - -@node Setting -@section Switching between source languages - -There are two ways to control the working language---either have @value{GDBN} -set it automatically, or select it manually yourself. You can use the -@code{set language} command for either purpose. On startup, @value{GDBN} -defaults to setting the language automatically. The working language is -used to determine how expressions you type are interpreted, how values -are printed, etc. - -In addition to the working language, every source file that -@value{GDBN} knows about has its own working language. For some object -file formats, the compiler might indicate which language a particular -source file is in. However, most of the time @value{GDBN} infers the -language from the name of the file. The language of a source file -controls whether C@t{++} names are demangled---this way @code{backtrace} can -show each frame appropriately for its own language. There is no way to -set the language of a source file from within @value{GDBN}, but you can -set the language associated with a filename extension. @xref{Show, , -Displaying the language}. - -This is most commonly a problem when you use a program, such -as @code{cfront} or @code{f2c}, that generates C but is written in -another language. In that case, make the -program use @code{#line} directives in its C output; that way -@value{GDBN} will know the correct language of the source code of the original -program, and will display that source code, not the generated C code. - -@menu -* Filenames:: Filename extensions and languages. -* Manually:: Setting the working language manually -* Automatically:: Having @value{GDBN} infer the source language -@end menu - -@node Filenames -@subsection List of filename extensions and languages - -If a source file name ends in one of the following extensions, then -@value{GDBN} infers that its language is the one indicated. - -@table @file - -@item .c -C source file - -@item .C -@itemx .cc -@itemx .cp -@itemx .cpp -@itemx .cxx -@itemx .c++ -C@t{++} source file - -@item .m -Objective-C source file - -@item .f -@itemx .F -Fortran source file - -@item .mod -Modula-2 source file - -@item .s -@itemx .S -Assembler source file. This actually behaves almost like C, but -@value{GDBN} does not skip over function prologues when stepping. -@end table - -In addition, you may set the language associated with a filename -extension. @xref{Show, , Displaying the language}. - -@node Manually -@subsection Setting the working language - -If you allow @value{GDBN} to set the language automatically, -expressions are interpreted the same way in your debugging session and -your program. - -@kindex set language -If you wish, you may set the language manually. To do this, issue the -command @samp{set language @var{lang}}, where @var{lang} is the name of -a language, such as -@code{c} or @code{modula-2}. -For a list of the supported languages, type @samp{set language}. - -Setting the language manually prevents @value{GDBN} 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 @value{GDBN} was parsing Modula-2, a -command such as: - -@smallexample -print a = b + c -@end smallexample - -@noindent -might not have the effect you intended. In C, this means to add -@code{b} and @code{c} and place the result in @code{a}. The result -printed would be the value of @code{a}. In Modula-2, this means to compare -@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. - -@node Automatically -@subsection Having @value{GDBN} infer the source language - -To have @value{GDBN} set the working language automatically, use -@samp{set language local} or @samp{set language auto}. @value{GDBN} -then infers the working language. That is, when your program stops in a -frame (usually by encountering a breakpoint), @value{GDBN} 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 @value{GDBN} 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 @samp{set language auto} in this -case frees you from having to set the working language manually. - -@node Show -@section Displaying the language - -The following commands help you find out which language is the -working language, and also what language source files were written in. - -@kindex show language -@kindex info frame@r{, show the source language} -@kindex info source@r{, show the source language} -@table @code -@item show language -Display the current working language. This is the -language you can use with commands such as @code{print} to -build and compute expressions that may involve variables in your program. - -@item info frame -Display the source language for this frame. This language becomes the -working language if you use an identifier from this frame. -@xref{Frame Info, ,Information about a frame}, to identify the other -information listed here. - -@item info source -Display the source language of this source file. -@xref{Symbols, ,Examining the Symbol Table}, to identify the other -information listed here. -@end table - -In unusual circumstances, you may have source files with extensions -not in the standard list. You can then set the extension associated -with a language explicitly: - -@kindex set extension-language -@kindex info extensions -@table @code -@item set extension-language @var{.ext} @var{language} -Set source files with extension @var{.ext} to be assumed to be in -the source language @var{language}. - -@item info extensions -List all the filename extensions and the associated languages. -@end table - -@node Checks -@section Type and range checking - -@quotation -@emph{Warning:} In this release, the @value{GDBN} commands for type and range -checking are included, but they do not yet have any effect. This -section documents the intended facilities. -@end quotation -@c FIXME remove warning when type/range code added - -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. - -@value{GDBN} can check for conditions like the above if you wish. -Although @value{GDBN} does not check the statements in your program, it -can check expressions entered directly into @value{GDBN} for evaluation via -the @code{print} command, for example. As with the working language, -@value{GDBN} can also decide whether or not to check automatically based on -your program's source language. @xref{Support, ,Supported languages}, -for the default settings of supported languages. - -@menu -* Type Checking:: An overview of type checking -* Range Checking:: An overview of range checking -@end menu - -@cindex type checking -@cindex checks, type -@node Type Checking -@subsection 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, - -@smallexample -1 + 2 @result{} 3 -@exdent but -@error{} 1 + 2.3 -@end smallexample - -The second example fails because the @code{CARDINAL} 1 is not -type-compatible with the @code{REAL} 2.3. - -For the expressions you use in @value{GDBN} commands, you can tell the -@value{GDBN} type checker to skip checking; -to treat any mismatches as errors and abandon the expression; -or to only issue warnings when type mismatches occur, -but evaluate the expression anyway. When you choose the last of -these, @value{GDBN} evaluates expressions like the second example above, but -also issues a warning. - -Even if you turn type checking off, there may be other reasons -related to type that prevent @value{GDBN} from evaluating an expression. -For instance, @value{GDBN} does not know how to add an @code{int} and -a @code{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. @xref{Support, ,Supported languages}, for further -details on specific languages. - -@value{GDBN} provides some additional commands for controlling the type checker: - -@kindex set check@r{, type} -@kindex set check type -@kindex show check type -@table @code -@item set check type auto -Set type checking on or off based on the current working language. -@xref{Support, ,Supported languages}, for the default settings for -each language. - -@item set check type on -@itemx 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 type checking is on, @value{GDBN} prints a -message and aborts evaluation of the expression. - -@item 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, @value{GDBN} cannot add -numbers and structures. - -@item show type -Show the current setting of the type checker, and whether or not @value{GDBN} -is setting it automatically. -@end table - -@cindex range checking -@cindex checks, range -@node Range Checking -@subsection 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 @value{GDBN} commands, you can tell -@value{GDBN} 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 @var{m} is -the largest integer value, and @var{s} is the smallest, then - -@smallexample -@var{m} + 1 @result{} @var{s} -@end smallexample - -This, too, is specific to individual languages, and in some cases -specific to individual compilers or machines. @xref{Support, , -Supported languages}, for further details on specific languages. - -@value{GDBN} provides some additional commands for controlling the range checker: - -@kindex set check@r{, range} -@kindex set check range -@kindex show check range -@table @code -@item set check range auto -Set range checking on or off based on the current working language. -@xref{Support, ,Supported languages}, for the default settings for -each language. - -@item set check range on -@itemx set check range off -Set range checking on or off, overriding the default setting for the -current working language. A warning is issued if the setting does not -match the language default. If a range error occurs and range checking is on, -then a message is printed and evaluation of the expression is aborted. - -@item set check range warn -Output messages when the @value{GDBN} 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). - -@item show range -Show the current setting of the range checker, and whether or not it is -being set automatically by @value{GDBN}. -@end table - -@node Support -@section Supported languages - -@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, and Modula-2. -@c This is false ... -Some @value{GDBN} features may be used in expressions regardless of the -language you use: the @value{GDBN} @code{@@} and @code{::} operators, -and the @samp{@{type@}addr} construct (@pxref{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 @value{GDBN}. These sections are not meant to be language -tutorials or references, but serve only as a reference guide to what the -@value{GDBN} expression parser accepts, and what input and output -formats should look like for different languages. There are many good -books written on each of these languages; please look to these for a -language reference or tutorial. - -@menu -* C:: C and C@t{++} -* Objective-C:: Objective-C -* Modula-2:: Modula-2 -@end menu - -@node C -@subsection C and C@t{++} - -@cindex C and C@t{++} -@cindex expressions in C or C@t{++} - -Since C and C@t{++} are so closely related, many features of @value{GDBN} apply -to both languages. Whenever this is the case, we discuss those languages -together. - -@cindex C@t{++} -@cindex @code{g++}, @sc{gnu} C@t{++} compiler -@cindex @sc{gnu} C@t{++} -The C@t{++} debugging facilities are jointly implemented by the C@t{++} -compiler and @value{GDBN}. Therefore, to debug your C@t{++} code -effectively, you must compile your C@t{++} programs with a supported -C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} -compiler (@code{aCC}). - -For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging -format; if it doesn't work on your system, try the stabs+ debugging -format. You can select those formats explicitly with the @code{g++} -command-line options @option{-gdwarf-2} and @option{-gstabs+}. -@xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu} -CC, gcc.info, Using @sc{gnu} CC}. - -@menu -* C Operators:: C and C@t{++} operators -* C Constants:: C and C@t{++} constants -* C plus plus expressions:: C@t{++} expressions -* C Defaults:: Default settings for C and C@t{++} -* C Checks:: C and C@t{++} type and range checks -* Debugging C:: @value{GDBN} and C -* Debugging C plus plus:: @value{GDBN} features for C@t{++} -@end menu - -@node C Operators -@subsubsection C and C@t{++} operators - -@cindex C and C@t{++} operators - -Operators must be defined on values of specific types. For instance, -@code{+} is defined on numbers, but not on structures. Operators are -often defined on groups of types. - -For the purposes of C and C@t{++}, the following definitions hold: - -@itemize @bullet - -@item -@emph{Integral types} include @code{int} with any of its storage-class -specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. - -@item -@emph{Floating-point types} include @code{float}, @code{double}, and -@code{long double} (if supported by the target platform). - -@item -@emph{Pointer types} include all types defined as @code{(@var{type} *)}. - -@item -@emph{Scalar types} include all of the above. - -@end itemize - -@noindent -The following operators are supported. They are listed here -in order of increasing precedence: - -@table @code -@item , -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. - -@item = -Assignment. The value of an assignment expression is the value -assigned. Defined on scalar types. - -@item @var{op}= -Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, -and translated to @w{@code{@var{a} = @var{a op b}}}. -@w{@code{@var{op}=}} and @code{=} have the same precedence. -@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, -@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. - -@item ?: -The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought -of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an -integral type. - -@item || -Logical @sc{or}. Defined on integral types. - -@item && -Logical @sc{and}. Defined on integral types. - -@item | -Bitwise @sc{or}. Defined on integral types. - -@item ^ -Bitwise exclusive-@sc{or}. Defined on integral types. - -@item & -Bitwise @sc{and}. Defined on integral types. - -@item ==@r{, }!= -Equality and inequality. Defined on scalar types. The value of these -expressions is 0 for false and non-zero for true. - -@item <@r{, }>@r{, }<=@r{, }>= -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. - -@item <<@r{, }>> -left shift, and right shift. Defined on integral types. - -@item @@ -The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). - -@item +@r{, }- -Addition and subtraction. Defined on integral types, floating-point types and -pointer types. - -@item *@r{, }/@r{, }% -Multiplication, division, and modulus. Multiplication and division are -defined on integral and floating-point types. Modulus is defined on -integral types. - -@item ++@r{, }-- -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. - -@item * -Pointer dereferencing. Defined on pointer types. Same precedence as -@code{++}. - -@item & -Address operator. Defined on variables. Same precedence as @code{++}. - -For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is -allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} -(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address -where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is -stored. - -@item - -Negative. Defined on integral and floating-point types. Same -precedence as @code{++}. - -@item ! -Logical negation. Defined on integral types. Same precedence as -@code{++}. - -@item ~ -Bitwise complement operator. Defined on integral types. Same precedence as -@code{++}. - - -@item .@r{, }-> -Structure member, and pointer-to-structure member. For convenience, -@value{GDBN} regards the two as equivalent, choosing whether to dereference a -pointer based on the stored type information. -Defined on @code{struct} and @code{union} data. - -@item .*@r{, }->* -Dereferences of pointers to members. - -@item [] -Array indexing. @code{@var{a}[@var{i}]} is defined as -@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. - -@item () -Function parameter list. Same precedence as @code{->}. - -@item :: -C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, -and @code{class} types. - -@item :: -Doubled colons also represent the @value{GDBN} scope operator -(@pxref{Expressions, ,Expressions}). Same precedence as @code{::}, -above. -@end table - -If an operator is redefined in the user code, @value{GDBN} usually -attempts to invoke the redefined version instead of using the operator's -predefined meaning. - -@menu -* C Constants:: -@end menu - -@node C Constants -@subsubsection C and C@t{++} constants - -@cindex C and C@t{++} constants - -@value{GDBN} allows you to express the constants of C and C@t{++} in the -following ways: - -@itemize @bullet -@item -Integer constants are a sequence of digits. Octal constants are -specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants -by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter -@samp{l}, specifying that the constant should be treated as a -@code{long} value. - -@item -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: -@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another -sequence of digits. The @samp{+} is optional for positive exponents. -A floating-point constant may also end with a letter @samp{f} or -@samp{F}, specifying that the constant should be treated as being of -the @code{float} (as opposed to the default @code{double}) type; or with -a letter @samp{l} or @samp{L}, which specifies a @code{long double} -constant. - -@item -Enumerated constants consist of enumerated identifiers, or their -integral equivalents. - -@item -Character constants are a single character surrounded by single quotes -(@code{'}), or a number---the ordinal value of the corresponding character -(usually its @sc{ascii} value). Within quotes, the single character may -be represented by a letter or by @dfn{escape sequences}, which are of -the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation -of the character's ordinal value; or of the form @samp{\@var{x}}, where -@samp{@var{x}} is a predefined special character---for example, -@samp{\n} for newline. - -@item -String constants are a sequence of character constants surrounded by -double quotes (@code{"}). Any valid character constant (as described -above) may appear. Double quotes within the string must be preceded by -a backslash, so for instance @samp{"a\"b'c"} is a string of five -characters. - -@item -Pointer constants are an integral value. You can also write pointers -to constants using the C operator @samp{&}. - -@item -Array constants are comma-separated lists surrounded by braces @samp{@{} -and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of -integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, -and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. -@end itemize - -@menu -* C plus plus expressions:: -* C Defaults:: -* C Checks:: - -* Debugging C:: -@end menu - -@node C plus plus expressions -@subsubsection C@t{++} expressions - -@cindex expressions in C@t{++} -@value{GDBN} expression handling can interpret most C@t{++} expressions. - -@cindex debugging C@t{++} programs -@cindex C@t{++} compilers -@cindex debug formats and C@t{++} -@cindex @value{NGCC} and C@t{++} -@quotation -@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the -proper compiler and the proper debug format. Currently, @value{GDBN} -works best when debugging C@t{++} code that is compiled with -@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options -@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over -stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or -stabs+ as their default debug format, so you usually don't need to -specify a debug format explicitly. Other compilers and/or debug formats -are likely to work badly or not at all when using @value{GDBN} to debug -C@t{++} code. -@end quotation - -@enumerate - -@cindex member functions -@item -Member function calls are allowed; you can use expressions like - -@smallexample -count = aml->GetOriginal(x, y) -@end smallexample - -@vindex this@r{, inside C@t{++} member functions} -@cindex namespace in C@t{++} -@item -While a member function is active (in the selected stack frame), your -expressions have the same namespace available as the member function; -that is, @value{GDBN} allows implicit references to the class instance -pointer @code{this} following the same rules as C@t{++}. - -@cindex call overloaded functions -@cindex overloaded functions, calling -@cindex type conversions in C@t{++} -@item -You can call overloaded functions; @value{GDBN} resolves the function -call to the right definition, with some restrictions. @value{GDBN} does not -perform overload resolution involving user-defined type conversions, -calls to constructors, or instantiations of templates that do not exist -in the program. It also cannot handle ellipsis argument lists or -default arguments. - -It does perform integral conversions and promotions, floating-point -promotions, arithmetic conversions, pointer conversions, conversions of -class objects to base classes, and standard conversions such as those of -functions or arrays to pointers; it requires an exact match on the -number of function arguments. - -Overload resolution is always performed, unless you have specified -@code{set overload-resolution off}. @xref{Debugging C plus plus, -,@value{GDBN} features for C@t{++}}. - -You must specify @code{set overload-resolution off} in order to use an -explicit function signature to call an overloaded function, as in -@smallexample -p 'foo(char,int)'('x', 13) -@end smallexample - -The @value{GDBN} command-completion facility can simplify this; -see @ref{Completion, ,Command completion}. - -@cindex reference declarations -@item -@value{GDBN} understands variables declared as C@t{++} references; you can use -them in expressions just as you do in C@t{++} source---they are automatically -dereferenced. - -In the parameter list shown when @value{GDBN} 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 @emph{address} of a reference variable is always shown, unless -you have specified @samp{set print address off}. - -@item -@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your -expressions can use it just as expressions in your program do. Since -one scope may be defined in another, you can use @code{::} repeatedly if -necessary, for example in an expression like -@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows -resolving name scope by reference to source files, in both C and C@t{++} -debugging (@pxref{Variables, ,Program variables}). -@end enumerate - -In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports -calling virtual functions correctly, printing out virtual bases of -objects, calling functions in a base subobject, casting objects, and -invoking user-defined operators. - -@node C Defaults -@subsubsection C and C@t{++} defaults - -@cindex C and C@t{++} defaults - -If you allow @value{GDBN} to set type and range checking automatically, they -both default to @code{off} whenever the working language changes to -C or C@t{++}. This happens regardless of whether you or @value{GDBN} -selects the working language. - -If you allow @value{GDBN} to set the language automatically, it -recognizes source files whose names end with @file{.c}, @file{.C}, or -@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of -these files, it sets the working language to C or C@t{++}. -@xref{Automatically, ,Having @value{GDBN} infer the source language}, -for further details. - -@c Type checking is (a) primarily motivated by Modula-2, and (b) -@c unimplemented. If (b) changes, it might make sense to let this node -@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93. - -@node C Checks -@subsubsection C and C@t{++} type and range checks - -@cindex C and C@t{++} checks - -By default, when @value{GDBN} parses C or C@t{++} expressions, type checking -is not used. However, if you turn type checking on, @value{GDBN} -considers two variables type equivalent if: - -@itemize @bullet -@item -The two variables are structured and have the same structure, union, or -enumerated tag. - -@item -The two variables have the same type name, or types that have been -declared equivalent through @code{typedef}. - -@ignore -@c leaving this out because neither J Gilmore nor R Pesch understand it. -@c FIXME--beers? -@item -The two @code{struct}, @code{union}, or @code{enum} variables are -declared in the same declaration. (Note: this may not be true for all C -compilers.) -@end ignore -@end itemize - -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. - -@node Debugging C -@subsubsection @value{GDBN} and C - -The @code{set print union} and @code{show print union} commands apply to -the @code{union} type. When set to @samp{on}, any @code{union} that is -inside a @code{struct} or @code{class} is also printed. Otherwise, it -appears as @samp{@{...@}}. - -The @code{@@} operator aids in the debugging of dynamic arrays, formed -with pointers and a memory allocation function. @xref{Expressions, -,Expressions}. - -@menu -* Debugging C plus plus:: -@end menu - -@node Debugging C plus plus -@subsubsection @value{GDBN} features for C@t{++} - -@cindex commands for C@t{++} - -Some @value{GDBN} commands are particularly useful with C@t{++}, and some are -designed specifically for use with C@t{++}. Here is a summary: - -@table @code -@cindex break in overloaded functions -@item @r{breakpoint menus} -When you want a breakpoint in a function whose name is overloaded, -@value{GDBN} breakpoint menus help you specify which function definition -you want. @xref{Breakpoint Menus,,Breakpoint menus}. - -@cindex overloading in C@t{++} -@item rbreak @var{regex} -Setting breakpoints using regular expressions is helpful for setting -breakpoints on overloaded functions that are not members of any special -classes. -@xref{Set Breaks, ,Setting breakpoints}. - -@cindex C@t{++} exception handling -@item catch throw -@itemx catch catch -Debug C@t{++} exception handling using these commands. @xref{Set -Catchpoints, , Setting catchpoints}. - -@cindex inheritance -@item ptype @var{typename} -Print inheritance relationships as well as other information for type -@var{typename}. -@xref{Symbols, ,Examining the Symbol Table}. - -@cindex C@t{++} symbol display -@item set print demangle -@itemx show print demangle -@itemx set print asm-demangle -@itemx show print asm-demangle -Control whether C@t{++} symbols display in their source form, both when -displaying code as C@t{++} source and when displaying disassemblies. -@xref{Print Settings, ,Print settings}. - -@item set print object -@itemx show print object -Choose whether to print derived (actual) or declared types of objects. -@xref{Print Settings, ,Print settings}. - -@item set print vtbl -@itemx show print vtbl -Control the format for printing virtual function tables. -@xref{Print Settings, ,Print settings}. -(The @code{vtbl} commands do not work on programs compiled with the HP -ANSI C@t{++} compiler (@code{aCC}).) - -@kindex set overload-resolution -@cindex overloaded functions, overload resolution -@item set overload-resolution on -Enable overload resolution for C@t{++} expression evaluation. The default -is on. For overloaded functions, @value{GDBN} evaluates the arguments -and searches for a function whose signature matches the argument types, -using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++} -expressions}, for details). If it cannot find a match, it emits a -message. - -@item set overload-resolution off -Disable overload resolution for C@t{++} expression evaluation. For -overloaded functions that are not class member functions, @value{GDBN} -chooses the first function of the specified name that it finds in the -symbol table, whether or not its arguments are of the correct type. For -overloaded functions that are class member functions, @value{GDBN} -searches for a function whose signature @emph{exactly} matches the -argument types. - -@item @r{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@t{++}: type -@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can -also use the @value{GDBN} command-line word completion facilities to list the -available choices, or to finish the type list for you. -@xref{Completion,, Command completion}, for details on how to do this. -@end table - -@node Objective-C -@subsection Objective-C - -@cindex Objective-C -This section provides information about some commands and command -options that are useful for debugging Objective-C code. - -@menu -* Method Names in Commands:: -* The Print Command with Objective-C:: -@end menu - -@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C -@subsubsection Method Names in Commands - -The following commands have been extended to accept Objective-C method -names as line specifications: - -@kindex clear@r{, and Objective-C} -@kindex break@r{, and Objective-C} -@kindex info line@r{, and Objective-C} -@kindex jump@r{, and Objective-C} -@kindex list@r{, and Objective-C} -@itemize -@item @code{clear} -@item @code{break} -@item @code{info line} -@item @code{jump} -@item @code{list} -@end itemize - -A fully qualified Objective-C method name is specified as - -@smallexample --[@var{Class} @var{methodName}] -@end smallexample - -where the minus sign is used to indicate an instance method and a -plus sign (not shown) is used to indicate a class method. The class -name @var{Class} and method name @var{methodName} are enclosed in -brackets, similar to the way messages are specified in Objective-C -source code. For example, to set a breakpoint at the @code{create} -instance method of class @code{Fruit} in the program currently being -debugged, enter: - -@smallexample -break -[Fruit create] -@end smallexample - -To list ten program lines around the @code{initialize} class method, -enter: - -@smallexample -list +[NSText initialize] -@end smallexample - -In the current version of @value{GDBN}, the plus or minus sign is -required. In future versions of @value{GDBN}, the plus or minus -sign will be optional, but you can use it to narrow the search. It -is also possible to specify just a method name: - -@smallexample -break create -@end smallexample - -You must specify the complete method name, including any colons. If -your program's source files contain more than one @code{create} method, -you'll be presented with a numbered list of classes that implement that -method. Indicate your choice by number, or type @samp{0} to exit if -none apply. - -As another example, to clear a breakpoint established at the -@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter: - -@smallexample -clear -[NSWindow makeKeyAndOrderFront:] -@end smallexample - -@node The Print Command with Objective-C -@subsubsection The Print Command With Objective-C -@kindex print-object -@kindex po @r{(@code{print-object})} - -The print command has also been extended to accept methods. For example: - -@smallexample -print -[@var{object} hash] -@end smallexample - -@cindex print an Objective-C object description -@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects -@noindent -will tell @value{GDBN} to send the @code{hash} message to @var{object} -and print the result. Also, an additional command has been added, -@code{print-object} or @code{po} for short, which is meant to print -the description of an object. However, this command may only work -with certain Objective-C libraries that have a particular hook -function, @code{_NSPrintForDebugger}, defined. - -@node Modula-2, , Objective-C, Support -@subsection Modula-2 - -@cindex Modula-2, @value{GDBN} support - -The extensions made to @value{GDBN} to support Modula-2 only support -output from the @sc{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 @value{GDBN} reads in the executable's symbol -table. - -@cindex expressions in Modula-2 -@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 @code{::} and @code{.} -* GDB/M2:: @value{GDBN} and Modula-2 -@end menu - -@node M2 Operators -@subsubsection Operators -@cindex Modula-2 operators - -Operators must be defined on values of specific types. For instance, -@code{+} 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: - -@itemize @bullet - -@item -@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and -their subranges. - -@item -@emph{Character types} consist of @code{CHAR} and its subranges. - -@item -@emph{Floating-point types} consist of @code{REAL}. - -@item -@emph{Pointer types} consist of anything declared as @code{POINTER TO -@var{type}}. - -@item -@emph{Scalar types} consist of all of the above. - -@item -@emph{Set types} consist of @code{SET} and @code{BITSET} types. - -@item -@emph{Boolean types} consist of @code{BOOLEAN}. -@end itemize - -@noindent -The following operators are supported, and appear in order of -increasing precedence: - -@table @code -@item , -Function argument or array index separator. - -@item := -Assignment. The value of @var{var} @code{:=} @var{value} is -@var{value}. - -@item <@r{, }> -Less than, greater than on integral, floating-point, or enumerated -types. - -@item <=@r{, }>= -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 @code{<}. - -@item =@r{, }<>@r{, }# -Equality and two ways of expressing inequality, valid on scalar types. -Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is -available for inequality, since @code{#} conflicts with the script -comment character. - -@item IN -Set membership. Defined on set types and the types of their members. -Same precedence as @code{<}. - -@item OR -Boolean disjunction. Defined on boolean types. - -@item AND@r{, }& -Boolean conjunction. Defined on boolean types. - -@item @@ -The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). - -@item +@r{, }- -Addition and subtraction on integral and floating-point types, or union -and difference on set types. - -@item * -Multiplication on integral and floating-point types, or set intersection -on set types. - -@item / -Division on floating-point types, or symmetric set difference on set -types. Same precedence as @code{*}. - -@item DIV@r{, }MOD -Integer division and remainder. Defined on integral types. Same -precedence as @code{*}. - -@item - -Negative. Defined on @code{INTEGER} and @code{REAL} data. - -@item ^ -Pointer dereferencing. Defined on pointer types. - -@item NOT -Boolean negation. Defined on boolean types. Same precedence as -@code{^}. - -@item . -@code{RECORD} field selector. Defined on @code{RECORD} data. Same -precedence as @code{^}. - -@item [] -Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}. - -@item () -Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence -as @code{^}. - -@item ::@r{, }. -@value{GDBN} and Modula-2 scope operators. -@end table - -@quotation -@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN} -treats the use of the operator @code{IN}, or the use of operators -@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, -@code{<=}, and @code{>=} on sets as an error. -@end quotation - - -@node Built-In Func/Proc -@subsubsection Built-in functions and procedures -@cindex Modula-2 built-ins - -Modula-2 also makes available several built-in procedures and functions. -In describing these, the following metavariables are used: - -@table @var - -@item a -represents an @code{ARRAY} variable. - -@item c -represents a @code{CHAR} constant or variable. - -@item i -represents a variable or constant of integral type. - -@item m -represents an identifier that belongs to a set. Generally used in the -same function with the metavariable @var{s}. The type of @var{s} should -be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}). - -@item n -represents a variable or constant of integral or floating-point type. - -@item r -represents a variable or constant of floating-point type. - -@item t -represents a type. - -@item v -represents a variable. - -@item x -represents a variable or constant of one of many types. See the -explanation of the function for details. -@end table - -All Modula-2 built-in procedures also return a result, described below. - -@table @code -@item ABS(@var{n}) -Returns the absolute value of @var{n}. - -@item CAP(@var{c}) -If @var{c} is a lower case letter, it returns its upper case -equivalent, otherwise it returns its argument. - -@item CHR(@var{i}) -Returns the character whose ordinal value is @var{i}. - -@item DEC(@var{v}) -Decrements the value in the variable @var{v} by one. Returns the new value. - -@item DEC(@var{v},@var{i}) -Decrements the value in the variable @var{v} by @var{i}. Returns the -new value. - -@item EXCL(@var{m},@var{s}) -Removes the element @var{m} from the set @var{s}. Returns the new -set. - -@item FLOAT(@var{i}) -Returns the floating point equivalent of the integer @var{i}. - -@item HIGH(@var{a}) -Returns the index of the last member of @var{a}. - -@item INC(@var{v}) -Increments the value in the variable @var{v} by one. Returns the new value. - -@item INC(@var{v},@var{i}) -Increments the value in the variable @var{v} by @var{i}. Returns the -new value. - -@item INCL(@var{m},@var{s}) -Adds the element @var{m} to the set @var{s} if it is not already -there. Returns the new set. - -@item MAX(@var{t}) -Returns the maximum value of the type @var{t}. - -@item MIN(@var{t}) -Returns the minimum value of the type @var{t}. - -@item ODD(@var{i}) -Returns boolean TRUE if @var{i} is an odd number. - -@item ORD(@var{x}) -Returns the ordinal value of its argument. For example, the ordinal -value of a character is its @sc{ascii} value (on machines supporting the -@sc{ascii} character set). @var{x} must be of an ordered type, which include -integral, character and enumerated types. - -@item SIZE(@var{x}) -Returns the size of its argument. @var{x} can be a variable or a type. - -@item TRUNC(@var{r}) -Returns the integral part of @var{r}. - -@item VAL(@var{t},@var{i}) -Returns the member of the type @var{t} whose ordinal value is @var{i}. -@end table - -@quotation -@emph{Warning:} Sets and their operations are not yet supported, so -@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as -an error. -@end quotation - -@cindex Modula-2 constants -@node M2 Constants -@subsubsection Constants - -@value{GDBN} allows you to express the constants of Modula-2 in the following -ways: - -@itemize @bullet - -@item -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 @samp{H}, and octal integers by a trailing @samp{B}. - -@item -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 @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where -@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the -digits of the floating point constant must be valid decimal (base 10) -digits. - -@item -Character constants consist of a single character enclosed by a pair of -like quotes, either single (@code{'}) or double (@code{"}). They may -also be expressed by their ordinal value (their @sc{ascii} value, usually) -followed by a @samp{C}. - -@item -String constants consist of a sequence of characters enclosed by a -pair of like quotes, either single (@code{'}) or double (@code{"}). -Escape sequences in the style of C are also allowed. @xref{C -Constants, ,C and C@t{++} constants}, for a brief explanation of escape -sequences. - -@item -Enumerated constants consist of an enumerated identifier. - -@item -Boolean constants consist of the identifiers @code{TRUE} and -@code{FALSE}. - -@item -Pointer constants consist of integral values only. - -@item -Set constants are not yet supported. -@end itemize - -@node M2 Defaults -@subsubsection Modula-2 defaults -@cindex Modula-2 defaults - -If type and range checking are set automatically by @value{GDBN}, they -both default to @code{on} whenever the working language changes to -Modula-2. This happens regardless of whether you or @value{GDBN} -selected the working language. - -If you allow @value{GDBN} to set the language automatically, then entering -code compiled from a file whose name ends with @file{.mod} sets the -working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set -the language automatically}, for further details. - -@node Deviations -@subsubsection Deviations from standard Modula-2 -@cindex Modula-2, deviations from - -A few changes have been made to make Modula-2 programs easier to debug. -This is done primarily via loosening its type strictness: - -@itemize @bullet -@item -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.) - -@item -C escape sequences can be used in strings and characters to represent -non-printable characters. @value{GDBN} prints out strings with these -escape sequences embedded. Single non-printable characters are -printed using the @samp{CHR(@var{nnn})} format. - -@item -The assignment operator (@code{:=}) returns the value of its right-hand -argument. - -@item -All built-in procedures both modify @emph{and} return their argument. -@end itemize - -@node M2 Checks -@subsubsection Modula-2 type and range checks -@cindex Modula-2 checks - -@quotation -@emph{Warning:} in this release, @value{GDBN} does not yet perform type or -range checking. -@end quotation -@c FIXME remove warning when type/range checks added - -@value{GDBN} considers two Modula-2 variables type equivalent if: - -@itemize @bullet -@item -They are of types that have been declared equivalent via a @code{TYPE -@var{t1} = @var{t2}} statement - -@item -They have been declared on the same line. (Note: This is true of the -@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.) -@end itemize - -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. - -@node M2 Scope -@subsubsection The scope operators @code{::} and @code{.} -@cindex scope -@cindex @code{.}, Modula-2 scope operator -@cindex colon, doubled as scope operator -@ifinfo -@vindex colon-colon@r{, in Modula-2} -@c Info cannot handle :: but TeX can. -@end ifinfo -@iftex -@vindex ::@r{, in Modula-2} -@end iftex - -There are a few subtle differences between the Modula-2 scope operator -(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have -similar syntax: - -@smallexample - -@var{module} . @var{id} -@var{scope} :: @var{id} -@end smallexample - -@noindent -where @var{scope} is the name of a module or a procedure, -@var{module} the name of a module, and @var{id} is any declared -identifier within your program, except another module. - -Using the @code{::} operator makes @value{GDBN} search the scope -specified by @var{scope} for the identifier @var{id}. If it is not -found in the specified scope, then @value{GDBN} searches all scopes -enclosing the one specified by @var{scope}. - -Using the @code{.} operator makes @value{GDBN} search the current scope for -the identifier specified by @var{id} that was imported from the -definition module specified by @var{module}. With this operator, it is -an error if the identifier @var{id} was not imported from definition -module @var{module}, or if @var{id} is not an identifier in -@var{module}. - -@node GDB/M2 -@subsubsection @value{GDBN} and Modula-2 - -Some @value{GDBN} commands have little use when debugging Modula-2 programs. -Five subcommands of @code{set print} and @code{show print} apply -specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, -@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four -apply to C@t{++}, and the last to the C @code{union} type, which has no direct -analogue in Modula-2. - -The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available -with any language, is not useful with Modula-2. Its -intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be -created in Modula-2 as they can in C or C@t{++}. However, because an -address can be specified by an integral constant, the construct -@samp{@{@var{type}@}@var{adrexp}} is still useful. - -@cindex @code{#} in Modula-2 -In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is -interpreted as the beginning of a comment. Use @code{<>} instead. - -@node Unsupported languages -@section Unsupported languages - -@cindex unsupported languages -@cindex minimal language -In addition to the other fully-supported programming languages, -@value{GDBN} also provides a pseudo-language, called @code{minimal}. -It does not represent a real programming language, but provides a set -of capabilities close to what the C or assembly languages provide. -This should allow most simple operations to be performed while debugging -an application that uses a language currently not supported by @value{GDBN}. - -If the language is set to @code{auto}, @value{GDBN} will automatically -select this language if the current frame corresponds to an unsupported -language. - -@node Symbols -@chapter Examining the Symbol Table - -The commands described in this chapter 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. @value{GDBN} finds it in your -program's symbol table, in the file indicated when you started @value{GDBN} -(@pxref{File Options, ,Choosing files}), or by one of the -file-management commands (@pxref{Files, ,Commands to specify files}). - -@cindex symbol names -@cindex names of symbols -@cindex quoting names -Occasionally, you may need to refer to symbols that contain unusual -characters, which @value{GDBN} ordinarily treats as word delimiters. The -most frequent case is in referring to static variables in other -source files (@pxref{Variables,,Program variables}). File names -are recorded in object files as debugging symbols, but @value{GDBN} would -ordinarily parse a typical file name, like @file{foo.c}, as the three words -@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize -@samp{foo.c} as a single symbol, enclose it in single quotes; for example, - -@smallexample -p 'foo.c'::x -@end smallexample - -@noindent -looks up the value of @code{x} in the scope of the file @file{foo.c}. - -@table @code -@kindex info address -@cindex address of a symbol -@item info address @var{symbol} -Describe where the data for @var{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 @samp{print &@var{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. - -@kindex info symbol -@cindex symbol from address -@item info symbol @var{addr} -Print the name of a symbol which is stored at the address @var{addr}. -If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the -nearest symbol and an offset from it: - -@smallexample -(@value{GDBP}) info symbol 0x54320 -_initialize_vx + 396 in section .text -@end smallexample - -@noindent -This is the opposite of the @code{info address} command. You can use -it to find out the name of a variable or a function given its address. - -@kindex whatis -@item whatis @var{expr} -Print the data type of expression @var{expr}. @var{expr} is not -actually evaluated, and any side-effecting operations (such as -assignments or function calls) inside it do not take place. -@xref{Expressions, ,Expressions}. - -@item whatis -Print the data type of @code{$}, the last value in the value history. - -@kindex ptype -@item ptype @var{typename} -Print a description of data type @var{typename}. @var{typename} may be -the name of a type, or for C code it may have the form @samp{class -@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union -@var{union-tag}} or @samp{enum @var{enum-tag}}. - -@item ptype @var{expr} -@itemx ptype -Print a description of the type of expression @var{expr}. @code{ptype} -differs from @code{whatis} by printing a detailed description, instead -of just the name of the type. - -For example, for this variable declaration: - -@smallexample -struct complex @{double real; double imag;@} v; -@end smallexample - -@noindent -the two commands give this output: - -@smallexample -@group -(@value{GDBP}) whatis v -type = struct complex -(@value{GDBP}) ptype v -type = struct complex @{ - double real; - double imag; -@} -@end group -@end smallexample - -@noindent -As with @code{whatis}, using @code{ptype} without an argument refers to -the type of @code{$}, the last value in the value history. - -@kindex info types -@item info types @var{regexp} -@itemx info types -Print a brief description of all types whose names match @var{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, -@samp{i type value} gives information on all types in your program whose -names include the string @code{value}, but @samp{i type ^value$} gives -information only on types whose complete name is @code{value}. - -This command differs from @code{ptype} in two ways: first, like -@code{whatis}, it does not print a detailed description; second, it -lists all source files where a type is defined. - -@kindex info scope -@cindex local variables -@item info scope @var{addr} -List all the variables local to a particular scope. This command -accepts a location---a function name, a source line, or an address -preceded by a @samp{*}, and prints all the variables local to the -scope defined by that location. For example: - -@smallexample -(@value{GDBP}) @b{info scope command_line_handler} -Scope for command_line_handler: -Symbol rl is an argument at stack/frame offset 8, length 4. -Symbol linebuffer is in static storage at address 0x150a18, length 4. -Symbol linelength is in static storage at address 0x150a1c, length 4. -Symbol p is a local variable in register $esi, length 4. -Symbol p1 is a local variable in register $ebx, length 4. -Symbol nline is a local variable in register $edx, length 4. -Symbol repeat is a local variable at frame offset -8, length 4. -@end smallexample - -@noindent -This command is especially useful for determining what data to collect -during a @dfn{trace experiment}, see @ref{Tracepoint Actions, -collect}. - -@kindex info source -@item info source -Show information about the current source file---that is, the source file for -the function containing the current point of execution: -@itemize @bullet -@item -the name of the source file, and the directory containing it, -@item -the directory it was compiled in, -@item -its length, in lines, -@item -which programming language it is written in, -@item -whether the executable includes debugging information for that file, and -if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and -@item -whether the debugging information includes information about -preprocessor macros. -@end itemize - - -@kindex info sources -@item 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. - -@kindex info functions -@item info functions -Print the names and data types of all defined functions. - -@item info functions @var{regexp} -Print the names and data types of all defined functions -whose names contain a match for regular expression @var{regexp}. -Thus, @samp{info fun step} finds all functions whose names -include @code{step}; @samp{info fun ^step} finds those whose names -start with @code{step}. If a function name contains characters -that conflict with the regular expression language (eg. -@samp{operator*()}), they may be quoted with a backslash. - -@kindex info variables -@item info variables -Print the names and data types of all variables that are declared -outside of functions (i.e.@: excluding local variables). - -@item info variables @var{regexp} -Print the names and data types of all variables (except for local -variables) whose names contain a match for regular expression -@var{regexp}. - -@kindex info classes -@item info classes -@itemx info classes @var{regexp} -Display all Objective-C classes in your program, or -(with the @var{regexp} argument) all those matching a particular regular -expression. - -@kindex info selectors -@item info selectors -@itemx info selectors @var{regexp} -Display all Objective-C selectors in your program, or -(with the @var{regexp} argument) all those matching a particular regular -expression. - -@ignore -This was never implemented. -@kindex info methods -@item info methods -@itemx info methods @var{regexp} -The @code{info methods} command permits the user to examine all defined -methods within C@t{++} program, or (with the @var{regexp} argument) a -specific set of methods found in the various C@t{++} classes. Many -C@t{++} classes provide a large number of methods. Thus, the output -from the @code{ptype} command can be overwhelming and hard to use. The -@code{info-methods} command filters the methods, printing only those -which match the regular-expression @var{regexp}. -@end ignore - -@cindex reloading symbols -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 -@value{GDBN} to reload the symbols for automatically relinked modules: - -@table @code -@kindex set symbol-reloading -@item set symbol-reloading on -Replace symbol definitions for the corresponding source file when an -object file with a particular name is seen again. - -@item set symbol-reloading off -Do not replace symbol definitions when encountering object files of the -same name more than once. This is the default state; if you are not -running on a system that permits automatic relinking of modules, you -should leave @code{symbol-reloading} off, since otherwise @value{GDBN} -may discard symbols when linking large programs, that may contain -several modules (from different directories or libraries) with the same -name. - -@kindex show symbol-reloading -@item show symbol-reloading -Show the current @code{on} or @code{off} setting. -@end table - -@kindex set opaque-type-resolution -@item set opaque-type-resolution on -Tell @value{GDBN} to resolve opaque types. An opaque type is a type -declared as a pointer to a @code{struct}, @code{class}, or -@code{union}---for example, @code{struct MyType *}---that is used in one -source file although the full declaration of @code{struct MyType} is in -another source file. The default is on. - -A change in the setting of this subcommand will not take effect until -the next time symbols for a file are loaded. - -@item set opaque-type-resolution off -Tell @value{GDBN} not to resolve opaque types. In this case, the type -is printed as follows: -@smallexample -@{<no data fields>@} -@end smallexample - -@kindex show opaque-type-resolution -@item show opaque-type-resolution -Show whether opaque types are resolved or not. - -@kindex maint print symbols -@cindex symbol dump -@kindex maint print psymbols -@cindex partial symbol dump -@item maint print symbols @var{filename} -@itemx maint print psymbols @var{filename} -@itemx maint print msymbols @var{filename} -Write a dump of debugging symbol data into the file @var{filename}. -These commands are used to debug the @value{GDBN} symbol-reading code. Only -symbols with debugging data are included. If you use @samp{maint print -symbols}, @value{GDBN} includes all the symbols for which it has already -collected full details: that is, @var{filename} reflects symbols for -only those files whose symbols @value{GDBN} has read. You can use the -command @code{info sources} to find out which files these are. If you -use @samp{maint print psymbols} instead, the dump shows information about -symbols that @value{GDBN} only knows partially---that is, symbols defined in -files that @value{GDBN} has skimmed, but not yet read completely. Finally, -@samp{maint print msymbols} dumps just the minimal symbol information -required for each object file from which @value{GDBN} has read some symbols. -@xref{Files, ,Commands to specify files}, for a discussion of how -@value{GDBN} reads symbols (in the description of @code{symbol-file}). - -@kindex maint info symtabs -@kindex maint info psymtabs -@cindex listing @value{GDBN}'s internal symbol tables -@cindex symbol tables, listing @value{GDBN}'s internal -@cindex full symbol tables, listing @value{GDBN}'s internal -@cindex partial symbol tables, listing @value{GDBN}'s internal -@item maint info symtabs @r{[} @var{regexp} @r{]} -@itemx maint info psymtabs @r{[} @var{regexp} @r{]} - -List the @code{struct symtab} or @code{struct partial_symtab} -structures whose names match @var{regexp}. If @var{regexp} is not -given, list them all. The output includes expressions which you can -copy into a @value{GDBN} debugging this one to examine a particular -structure in more detail. For example: - -@smallexample -(@value{GDBP}) maint info psymtabs dwarf2read -@{ objfile /home/gnu/build/gdb/gdb - ((struct objfile *) 0x82e69d0) - @{ psymtab /home/gnu/src/gdb/dwarf2read.c - ((struct partial_symtab *) 0x8474b10) - readin no - fullname (null) - text addresses 0x814d3c8 -- 0x8158074 - globals (* (struct partial_symbol **) 0x8507a08 @@ 9) - statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882) - dependencies (none) - @} -@} -(@value{GDBP}) maint info symtabs -(@value{GDBP}) -@end smallexample -@noindent -We see that there is one partial symbol table whose filename contains -the string @samp{dwarf2read}, belonging to the @samp{gdb} executable; -and we see that @value{GDBN} has not read in any symtabs yet at all. -If we set a breakpoint on a function, that will cause @value{GDBN} to -read the symtab for the compilation unit containing that function: - -@smallexample -(@value{GDBP}) break dwarf2_psymtab_to_symtab -Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, -line 1574. -(@value{GDBP}) maint info symtabs -@{ objfile /home/gnu/build/gdb/gdb - ((struct objfile *) 0x82e69d0) - @{ symtab /home/gnu/src/gdb/dwarf2read.c - ((struct symtab *) 0x86c1f38) - dirname (null) - fullname (null) - blockvector ((struct blockvector *) 0x86c1bd0) (primary) - debugformat DWARF 2 - @} -@} -(@value{GDBP}) -@end smallexample -@end table - - -@node Altering -@chapter 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 @value{GDBN} 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 -@end menu - -@node Assignment -@section Assignment to variables - -@cindex assignment -@cindex setting variables -To alter the value of a variable, evaluate an assignment expression. -@xref{Expressions, ,Expressions}. For example, - -@smallexample -print x=4 -@end smallexample - -@noindent -stores the value 4 into the variable @code{x}, and then prints the -value of the assignment expression (which is 4). -@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more -information on operators in supported languages. - -@kindex set variable -@cindex variables, setting -If you are not interested in seeing the value of the assignment, use the -@code{set} command instead of the @code{print} command. @code{set} is -really the same as @code{print} except that the expression's value is -not printed and is not put in the value history (@pxref{Value History, -,Value history}). The expression is evaluated only for its effects. - -If the beginning of the argument string of the @code{set} command -appears identical to a @code{set} subcommand, use the @code{set -variable} command instead of just @code{set}. This command is identical -to @code{set} except for its lack of subcommands. For example, if your -program has a variable @code{width}, you get an error if you try to set -a new value with just @samp{set width=13}, because @value{GDBN} has the -command @code{set width}: - -@smallexample -(@value{GDBP}) whatis width -type = double -(@value{GDBP}) p width -$4 = 13 -(@value{GDBP}) set width=47 -Invalid syntax in expression. -@end smallexample - -@noindent -The invalid expression, of course, is @samp{=47}. In -order to actually set the program's variable @code{width}, use - -@smallexample -(@value{GDBP}) set var width=47 -@end smallexample - -Because the @code{set} command has many subcommands that can conflict -with the names of program variables, it is a good idea to use the -@code{set variable} command instead of just @code{set}. For example, if -your program has a variable @code{g}, you run into problems if you try -to set a new value with just @samp{set g=4}, because @value{GDBN} has -the command @code{set gnutarget}, abbreviated @code{set g}: - -@smallexample -@group -(@value{GDBP}) whatis g -type = double -(@value{GDBP}) p g -$1 = 1 -(@value{GDBP}) set g=4 -(@value{GDBP}) p g -$2 = 1 -(@value{GDBP}) r -The program being debugged has been started already. -Start it from the beginning? (y or n) y -Starting program: /home/smith/cc_progs/a.out -"/home/smith/cc_progs/a.out": can't open to read symbols: - Invalid bfd target. -(@value{GDBP}) show g -The current BFD target is "=4". -@end group -@end smallexample - -@noindent -The program variable @code{g} did not change, and you silently set the -@code{gnutarget} to an invalid value. In order to set the variable -@code{g}, use - -@smallexample -(@value{GDBP}) set var g=4 -@end smallexample - -@value{GDBN} 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. -@comment FIXME: how do structs align/pad in these conversions? -@comment /doc@cygnus.com 18dec1990 - -To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} -construct to generate a value of specified type at a specified address -(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers -to memory location @code{0x83040} as an integer (which implies a certain size -and representation in memory), and - -@smallexample -set @{int@}0x83040 = 4 -@end smallexample - -@noindent -stores the value 4 into that memory location. - -@node Jumping -@section Continuing at a different address - -Ordinarily, when you continue your program, you do so at the place where -it stopped, with the @code{continue} command. You can instead continue at -an address of your own choosing, with the following commands: - -@table @code -@kindex jump -@item jump @var{linespec} -Resume execution at line @var{linespec}. Execution stops again -immediately if there is a breakpoint there. @xref{List, ,Printing -source lines}, for a description of the different forms of -@var{linespec}. It is common practice to use the @code{tbreak} command -in conjunction with @code{jump}. @xref{Set Breaks, ,Setting -breakpoints}. - -The @code{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 @var{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 @code{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. - -@item jump *@var{address} -Resume execution at the instruction at address @var{address}. -@end table - -@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt. -On many systems, you can get much the same effect as the @code{jump} -command by storing a new value into the register @code{$pc}. The -difference is that this does not start your program running; it only -changes the address of where it @emph{will} run when you continue. For -example, - -@smallexample -set $pc = 0x485 -@end smallexample - -@noindent -makes the next @code{continue} command or stepping command execute at -address @code{0x485}, rather than at the address where your program stopped. -@xref{Continuing and Stepping, ,Continuing and stepping}. - -The most common occasion to use the @code{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. - -@c @group -@node Signaling -@section Giving your program a signal - -@table @code -@kindex signal -@item signal @var{signal} -Resume execution where your program stopped, but immediately give it the -signal @var{signal}. @var{signal} can be the name or the number of a -signal. For example, on many systems @code{signal 2} and @code{signal -SIGINT} are both ways of sending an interrupt signal. - -Alternatively, if @var{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 -@code{continue} command; @samp{signal 0} causes it to resume without a -signal. - -@code{signal} does not repeat when you press @key{RET} a second time -after executing the command. -@end table -@c @end group - -Invoking the @code{signal} command is not the same as invoking the -@code{kill} utility from the shell. Sending a signal with @code{kill} -causes @value{GDBN} to decide what to do with the signal depending on -the signal handling tables (@pxref{Signals}). The @code{signal} command -passes the signal directly to your program. - - -@node Returning -@section Returning from a function - -@table @code -@cindex returning from a function -@kindex return -@item return -@itemx return @var{expression} -You can cancel execution of a function call with the @code{return} -command. If you give an -@var{expression} argument, its value is used as the function's return -value. -@end table - -When you use @code{return}, @value{GDBN} 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 @code{return}. - -This pops the selected stack frame (@pxref{Selection, ,Selecting a -frame}), 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 @code{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 @code{finish} command (@pxref{Continuing -and Stepping, ,Continuing and stepping}) resumes execution until the -selected stack frame returns naturally. - -@node Calling -@section Calling program functions - -@cindex calling functions -@kindex call -@table @code -@item call @var{expr} -Evaluate the expression @var{expr} without displaying @code{void} -returned values. -@end table - -You can use this variant of the @code{print} command if you want to -execute a function from your program, but without cluttering the output -with @code{void} returned values. If the result is not void, it -is printed and saved in the value history. - -@node Patching -@section Patching programs - -@cindex patching binaries -@cindex writing into executables -@cindex writing into corefiles - -By default, @value{GDBN} 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 @code{set write} command. For example, you might -want to turn on internal debugging flags, or even to make emergency -repairs. - -@table @code -@kindex set write -@item set write on -@itemx set write off -If you specify @samp{set write on}, @value{GDBN} opens executable and -core files for both reading and writing; if you specify @samp{set write -off} (the default), @value{GDBN} opens them read-only. - -If you have already loaded a file, you must load it again (using the -@code{exec-file} or @code{core-file} command) after changing @code{set -write}, for your new setting to take effect. - -@item show write -@kindex show write -Display whether executable files and core files are opened for writing -as well as reading. -@end table - -@node GDB Files -@chapter @value{GDBN} Files - -@value{GDBN} 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 -@value{GDBN} the name of the core dump file. - -@menu -* Files:: Commands to specify files -* Separate Debug Files:: Debugging information in separate files -* Symbol Errors:: Errors reading symbol files -@end menu - -@node Files -@section Commands to specify files - -@cindex symbol table -@cindex core dump file - -You may want to specify executable and core dump file names. The usual -way to do this is at start-up time, using the arguments to -@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and -Out of @value{GDBN}}). - -Occasionally it is necessary to change to a different file during a -@value{GDBN} session. Or you may run @value{GDBN} and forget to specify -a file you want to use. In these situations the @value{GDBN} commands -to specify new files are useful. - -@table @code -@cindex executable file -@kindex file -@item file @var{filename} -Use @var{filename} as the program to be debugged. It is read for its -symbols and for the contents of pure memory. It is also the program -executed when you use the @code{run} command. If you do not specify a -directory and the file is not found in the @value{GDBN} working directory, -@value{GDBN} uses the environment variable @code{PATH} as a list of -directories to search, just as the shell does when looking for a program -to run. You can change the value of this variable, for both @value{GDBN} -and your program, using the @code{path} command. - -On systems with memory-mapped files, an auxiliary file named -@file{@var{filename}.syms} may hold symbol table information for -@var{filename}. If so, @value{GDBN} maps in the symbol table from -@file{@var{filename}.syms}, starting up more quickly. See the -descriptions of the file options @samp{-mapped} and @samp{-readnow} -(available on the command line, and with the commands @code{file}, -@code{symbol-file}, or @code{add-symbol-file}, described below), -for more information. - -@item file -@code{file} with no argument makes @value{GDBN} discard any information it -has on both executable file and the symbol table. - -@kindex exec-file -@item exec-file @r{[} @var{filename} @r{]} -Specify that the program to be run (but not the symbol table) is found -in @var{filename}. @value{GDBN} searches the environment variable @code{PATH} -if necessary to locate your program. Omitting @var{filename} means to -discard information on the executable file. - -@kindex symbol-file -@item symbol-file @r{[} @var{filename} @r{]} -Read symbol table information from file @var{filename}. @code{PATH} is -searched when necessary. Use the @code{file} command to get both symbol -table and program to run from the same file. - -@code{symbol-file} with no argument clears out @value{GDBN} information on your -program's symbol table. - -The @code{symbol-file} command causes @value{GDBN} to forget the contents -of its convenience variables, the value history, and all breakpoints and -auto-display expressions. This is because they may contain pointers to -the internal data recording symbols and data types, which are part of -the old symbol table data being discarded inside @value{GDBN}. - -@code{symbol-file} does not repeat if you press @key{RET} again after -executing it once. - -When @value{GDBN} is configured for a particular environment, it -understands debugging information in whatever format is the standard -generated for that environment; you may use either a @sc{gnu} compiler, or -other compilers that adhere to the local conventions. -Best results are usually obtained from @sc{gnu} compilers; for example, -using @code{@value{GCC}} you can generate debugging information for -optimized code. - -For most kinds of object files, with the exception of old SVR3 systems -using COFF, the @code{symbol-file} command does not normally read the -symbol table in full right away. Instead, it scans the symbol table -quickly to find which source files and which symbols are present. The -details are read later, one source file at a time, as they are needed. - -The purpose of this two-stage reading strategy is to make @value{GDBN} -start up faster. For the most part, it is invisible except for -occasional pauses while the symbol table details for a particular source -file are being read. (The @code{set verbose} command can turn these -pauses into messages if desired. @xref{Messages/Warnings, ,Optional -warnings and messages}.) - -We have not implemented the two-stage strategy for COFF yet. When the -symbol table is stored in COFF format, @code{symbol-file} reads the -symbol table data in full right away. Note that ``stabs-in-COFF'' -still does the two-stage strategy, since the debug info is actually -in stabs format. - -@kindex readnow -@cindex reading symbols immediately -@cindex symbols, reading immediately -@kindex mapped -@cindex memory-mapped symbol file -@cindex saving symbol table -@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]} -@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]} -You can override the @value{GDBN} two-stage strategy for reading symbol -tables by using the @samp{-readnow} option with any of the commands that -load symbol table information, if you want to be sure @value{GDBN} has the -entire symbol table available. - -If memory-mapped files are available on your system through the -@code{mmap} system call, you can use another option, @samp{-mapped}, to -cause @value{GDBN} to write the symbols for your program into a reusable -file. Future @value{GDBN} debugging sessions map in symbol information -from this auxiliary symbol file (if the program has not changed), rather -than spending time reading the symbol table from the executable -program. Using the @samp{-mapped} option has the same effect as -starting @value{GDBN} with the @samp{-mapped} command-line option. - -You can use both options together, to make sure the auxiliary symbol -file has all the symbol information for your program. - -The auxiliary symbol file for a program called @var{myprog} is called -@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer -than the corresponding executable), @value{GDBN} always attempts to use -it when you debug @var{myprog}; no special options or commands are -needed. - -The @file{.syms} file is specific to the host machine where you run -@value{GDBN}. It holds an exact image of the internal @value{GDBN} -symbol table. It cannot be shared across multiple host platforms. - -@c FIXME: for now no mention of directories, since this seems to be in -@c flux. 13mar1992 status is that in theory GDB would look either in -@c current dir or in same dir as myprog; but issues like competing -@c GDB's, or clutter in system dirs, mean that in practice right now -@c only current dir is used. FFish says maybe a special GDB hierarchy -@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol -@c files. - -@kindex core -@kindex core-file -@item core-file @r{[} @var{filename} @r{]} -Specify the whereabouts of a core dump file to be used as the ``contents -of memory''. Traditionally, core files contain only some parts of the -address space of the process that generated them; @value{GDBN} can access the -executable file itself for other parts. - -@code{core-file} with no argument specifies that no core file is -to be used. - -Note that the core file is ignored when your program is actually running -under @value{GDBN}. So, if you have been running your program and you -wish to debug a core file instead, you must kill the subprocess in which -the program is running. To do this, use the @code{kill} command -(@pxref{Kill Process, ,Killing the child process}). - -@kindex add-symbol-file -@cindex dynamic linking -@item add-symbol-file @var{filename} @var{address} -@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]} -@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{} -The @code{add-symbol-file} command reads additional symbol table -information from the file @var{filename}. You would use this command -when @var{filename} has been dynamically loaded (by some other means) -into the program that is running. @var{address} should be the memory -address at which the file has been loaded; @value{GDBN} cannot figure -this out for itself. You can additionally specify an arbitrary number -of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit -section name and base address for that section. You can specify any -@var{address} as an expression. - -The symbol table of the file @var{filename} is added to the symbol table -originally read with the @code{symbol-file} command. You can use the -@code{add-symbol-file} command any number of times; the new symbol data -thus read keeps adding to the old. To discard all old symbol data -instead, use the @code{symbol-file} command without any arguments. - -@cindex relocatable object files, reading symbols from -@cindex object files, relocatable, reading symbols from -@cindex reading symbols from relocatable object files -@cindex symbols, reading from relocatable object files -@cindex @file{.o} files, reading symbols from -Although @var{filename} is typically a shared library file, an -executable file, or some other object file which has been fully -relocated for loading into a process, you can also load symbolic -information from relocatable @file{.o} files, as long as: - -@itemize @bullet -@item -the file's symbolic information refers only to linker symbols defined in -that file, not to symbols defined by other object files, -@item -every section the file's symbolic information refers to has actually -been loaded into the inferior, as it appears in the file, and -@item -you can determine the address at which every section was loaded, and -provide these to the @code{add-symbol-file} command. -@end itemize - -@noindent -Some embedded operating systems, like Sun Chorus and VxWorks, can load -relocatable files into an already running program; such systems -typically make the requirements above easy to meet. However, it's -important to recognize that many native systems use complex link -procedures (@code{.linkonce} section factoring and C@t{++} constructor table -assembly, for example) that make the requirements difficult to meet. In -general, one cannot assume that using @code{add-symbol-file} to read a -relocatable object file's symbolic information will have the same effect -as linking the relocatable object file into the program in the normal -way. - -@code{add-symbol-file} does not repeat if you press @key{RET} after using it. - -You can use the @samp{-mapped} and @samp{-readnow} options just as with -the @code{symbol-file} command, to change how @value{GDBN} manages the symbol -table information for @var{filename}. - -@kindex add-shared-symbol-file -@item add-shared-symbol-file -The @code{add-shared-symbol-file} command can be used only under Harris' CXUX -operating system for the Motorola 88k. @value{GDBN} automatically looks for -shared libraries, however if @value{GDBN} does not find yours, you can run -@code{add-shared-symbol-file}. It takes no arguments. - -@kindex section -@item section -The @code{section} command changes the base address of section SECTION of -the exec file to ADDR. This can be used if the exec file does not contain -section addresses, (such as in the a.out format), or when the addresses -specified in the file itself are wrong. Each section must be changed -separately. The @code{info files} command, described below, lists all -the sections and their addresses. - -@kindex info files -@kindex info target -@item info files -@itemx info target -@code{info files} and @code{info target} are synonymous; both print the -current target (@pxref{Targets, ,Specifying a Debugging Target}), -including the names of the executable and core dump files currently in -use by @value{GDBN}, and the files from which symbols were loaded. The -command @code{help target} lists all possible targets rather than -current ones. - -@kindex maint info sections -@item maint info sections -Another command that can give you extra information about program sections -is @code{maint info sections}. In addition to the section information -displayed by @code{info files}, this command displays the flags and file -offset of each section in the executable and core dump files. In addition, -@code{maint info sections} provides the following command options (which -may be arbitrarily combined): - -@table @code -@item ALLOBJ -Display sections for all loaded object files, including shared libraries. -@item @var{sections} -Display info only for named @var{sections}. -@item @var{section-flags} -Display info only for sections for which @var{section-flags} are true. -The section flags that @value{GDBN} currently knows about are: -@table @code -@item ALLOC -Section will have space allocated in the process when loaded. -Set for all sections except those containing debug information. -@item LOAD -Section will be loaded from the file into the child process memory. -Set for pre-initialized code and data, clear for @code{.bss} sections. -@item RELOC -Section needs to be relocated before loading. -@item READONLY -Section cannot be modified by the child process. -@item CODE -Section contains executable code only. -@item DATA -Section contains data only (no executable code). -@item ROM -Section will reside in ROM. -@item CONSTRUCTOR -Section contains data for constructor/destructor lists. -@item HAS_CONTENTS -Section is not empty. -@item NEVER_LOAD -An instruction to the linker to not output the section. -@item COFF_SHARED_LIBRARY -A notification to the linker that the section contains -COFF shared library information. -@item IS_COMMON -Section contains common symbols. -@end table -@end table -@kindex set trust-readonly-sections -@item set trust-readonly-sections on -Tell @value{GDBN} that readonly sections in your object file -really are read-only (i.e.@: that their contents will not change). -In that case, @value{GDBN} can fetch values from these sections -out of the object file, rather than from the target program. -For some targets (notably embedded ones), this can be a significant -enhancement to debugging performance. - -The default is off. - -@item set trust-readonly-sections off -Tell @value{GDBN} not to trust readonly sections. This means that -the contents of the section might change while the program is running, -and must therefore be fetched from the target when needed. -@end table - -All file-specifying commands allow both absolute and relative file names -as arguments. @value{GDBN} always converts the file name to an absolute file -name and remembers it that way. - -@cindex shared libraries -@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared -libraries. - -@value{GDBN} automatically loads symbol definitions from shared libraries -when you use the @code{run} command, or when you examine a core file. -(Before you issue the @code{run} command, @value{GDBN} does not understand -references to a function in a shared library, however---unless you are -debugging a core file). - -On HP-UX, if the program loads a library explicitly, @value{GDBN} -automatically loads the symbols at the time of the @code{shl_load} call. - -@c FIXME: some @value{GDBN} release may permit some refs to undef -@c FIXME...symbols---eg in a break cmd---assuming they are from a shared -@c FIXME...lib; check this from time to time when updating manual - -There are times, however, when you may wish to not automatically load -symbol definitions from shared libraries, such as when they are -particularly large or there are many of them. - -To control the automatic loading of shared library symbols, use the -commands: - -@table @code -@kindex set auto-solib-add -@item set auto-solib-add @var{mode} -If @var{mode} is @code{on}, symbols from all shared object libraries -will be loaded automatically when the inferior begins execution, you -attach to an independently started inferior, or when the dynamic linker -informs @value{GDBN} that a new library has been loaded. If @var{mode} -is @code{off}, symbols must be loaded manually, using the -@code{sharedlibrary} command. The default value is @code{on}. - -@kindex show auto-solib-add -@item show auto-solib-add -Display the current autoloading mode. -@end table - -To explicitly load shared library symbols, use the @code{sharedlibrary} -command: - -@table @code -@kindex info sharedlibrary -@kindex info share -@item info share -@itemx info sharedlibrary -Print the names of the shared libraries which are currently loaded. - -@kindex sharedlibrary -@kindex share -@item sharedlibrary @var{regex} -@itemx share @var{regex} -Load shared object library symbols for files matching a -Unix regular expression. -As with files loaded automatically, it only loads shared libraries -required by your program for a core file or after typing @code{run}. If -@var{regex} is omitted all shared libraries required by your program are -loaded. -@end table - -On some systems, such as HP-UX systems, @value{GDBN} supports -autoloading shared library symbols until a limiting threshold size is -reached. This provides the benefit of allowing autoloading to remain on -by default, but avoids autoloading excessively large shared libraries, -up to a threshold that is initially set, but which you can modify if you -wish. - -Beyond that threshold, symbols from shared libraries must be explicitly -loaded. To load these symbols, use the command @code{sharedlibrary -@var{filename}}. The base address of the shared library is determined -automatically by @value{GDBN} and need not be specified. - -To display or set the threshold, use the commands: - -@table @code -@kindex set auto-solib-limit -@item set auto-solib-limit @var{threshold} -Set the autoloading size threshold, in an integral number of megabytes. -If @var{threshold} is nonzero and shared library autoloading is enabled, -symbols from all shared object libraries will be loaded until the total -size of the loaded shared library symbols exceeds this threshold. -Otherwise, symbols must be loaded manually, using the -@code{sharedlibrary} command. The default threshold is 100 (i.e.@: 100 -Mb). - -@kindex show auto-solib-limit -@item show auto-solib-limit -Display the current autoloading size threshold, in megabytes. -@end table - -Shared libraries are also supported in many cross or remote debugging -configurations. A copy of the target's libraries need to be present on the -host system; they need to be the same as the target libraries, although the -copies on the target can be stripped as long as the copies on the host are -not. - -You need to tell @value{GDBN} where the target libraries are, so that it can -load the correct copies---otherwise, it may try to load the host's libraries. -@value{GDBN} has two variables to specify the search directories for target -libraries. - -@table @code -@kindex set solib-absolute-prefix -@item set solib-absolute-prefix @var{path} -If this variable is set, @var{path} will be used as a prefix for any -absolute shared library paths; many runtime loaders store the absolute -paths to the shared library in the target program's memory. If you use -@samp{solib-absolute-prefix} to find shared libraries, they need to be laid -out in the same way that they are on the target, with e.g.@: a -@file{/usr/lib} hierarchy under @var{path}. - -You can set the default value of @samp{solib-absolute-prefix} by using the -configure-time @samp{--with-sysroot} option. - -@kindex show solib-absolute-prefix -@item show solib-absolute-prefix -Display the current shared library prefix. - -@kindex set solib-search-path -@item set solib-search-path @var{path} -If this variable is set, @var{path} is a colon-separated list of directories -to search for shared libraries. @samp{solib-search-path} is used after -@samp{solib-absolute-prefix} fails to locate the library, or if the path to -the library is relative instead of absolute. If you want to use -@samp{solib-search-path} instead of @samp{solib-absolute-prefix}, be sure to -set @samp{solib-absolute-prefix} to a nonexistant directory to prevent -@value{GDBN} from finding your host's libraries. - -@kindex show solib-search-path -@item show solib-search-path -Display the current shared library search path. -@end table - - -@node Separate Debug Files -@section Debugging Information in Separate Files -@cindex separate debugging information files -@cindex debugging information in separate files -@cindex @file{.debug} subdirectories -@cindex debugging information directory, global -@cindex global debugging information directory - -@value{GDBN} allows you to put a program's debugging information in a -file separate from the executable itself, in a way that allows -@value{GDBN} to find and load the debugging information automatically. -Since debugging information can be very large --- sometimes larger -than the executable code itself --- some systems distribute debugging -information for their executables in separate files, which users can -install only when they need to debug a problem. - -If an executable's debugging information has been extracted to a -separate file, the executable should contain a @dfn{debug link} giving -the name of the debugging information file (with no directory -components), and a checksum of its contents. (The exact form of a -debug link is described below.) If the full name of the directory -containing the executable is @var{execdir}, and the executable has a -debug link that specifies the name @var{debugfile}, then @value{GDBN} -will automatically search for the debugging information file in three -places: - -@itemize @bullet -@item -the directory containing the executable file (that is, it will look -for a file named @file{@var{execdir}/@var{debugfile}}, -@item -a subdirectory of that directory named @file{.debug} (that is, the -file @file{@var{execdir}/.debug/@var{debugfile}}, and -@item -a subdirectory of the global debug file directory that includes the -executable's full path, and the name from the link (that is, the file -@file{@var{globaldebugdir}/@var{execdir}/@var{debugfile}}, where -@var{globaldebugdir} is the global debug file directory, and -@var{execdir} has been turned into a relative path). -@end itemize -@noindent -@value{GDBN} checks under each of these names for a debugging -information file whose checksum matches that given in the link, and -reads the debugging information from the first one it finds. - -So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls}, -which has a link containing the name @file{ls.debug}, and the global -debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look -for debug information in @file{/usr/bin/ls.debug}, -@file{/usr/bin/.debug/ls.debug}, and -@file{/usr/lib/debug/usr/bin/ls.debug}. - -You can set the global debugging info directory's name, and view the -name @value{GDBN} is currently using. - -@table @code - -@kindex set debug-file-directory -@item set debug-file-directory @var{directory} -Set the directory which @value{GDBN} searches for separate debugging -information files to @var{directory}. - -@kindex show debug-file-directory -@item show debug-file-directory -Show the directory @value{GDBN} searches for separate debugging -information files. - -@end table - -@cindex @code{.gnu_debuglink} sections -@cindex debug links -A debug link is a special section of the executable file named -@code{.gnu_debuglink}. The section must contain: - -@itemize -@item -A filename, with any leading directory components removed, followed by -a zero byte, -@item -zero to three bytes of padding, as needed to reach the next four-byte -boundary within the section, and -@item -a four-byte CRC checksum, stored in the same endianness used for the -executable file itself. The checksum is computed on the debugging -information file's full contents by the function given below, passing -zero as the @var{crc} argument. -@end itemize - -Any executable file format can carry a debug link, as long as it can -contain a section named @code{.gnu_debuglink} with the contents -described above. - -The debugging information file itself should be an ordinary -executable, containing a full set of linker symbols, sections, and -debugging information. The sections of the debugging information file -should have the same names, addresses and sizes as the original file, -but they need not contain any data --- much like a @code{.bss} section -in an ordinary executable. - -As of December 2002, there is no standard GNU utility to produce -separated executable / debugging information file pairs. Ulrich -Drepper's @file{elfutils} package, starting with version 0.53, -contains a version of the @code{strip} command such that the command -@kbd{strip foo -f foo.debug} removes the debugging information from -the executable file @file{foo}, places it in the file -@file{foo.debug}, and leaves behind a debug link in @file{foo}. - -Since there are many different ways to compute CRC's (different -polynomials, reversals, byte ordering, etc.), the simplest way to -describe the CRC used in @code{.gnu_debuglink} sections is to give the -complete code for a function that computes it: - -@kindex @code{gnu_debuglink_crc32} -@smallexample -unsigned long -gnu_debuglink_crc32 (unsigned long crc, - unsigned char *buf, size_t len) -@{ - static const unsigned long crc32_table[256] = - @{ - 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, - 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, - 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, - 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, - 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, - 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, - 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, - 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, - 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, - 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, - 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, - 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, - 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, - 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, - 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, - 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, - 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, - 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, - 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, - 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, - 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, - 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, - 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, - 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, - 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, - 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, - 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, - 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, - 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, - 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, - 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, - 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, - 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, - 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, - 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, - 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, - 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, - 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, - 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, - 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, - 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, - 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, - 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, - 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, - 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, - 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, - 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, - 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, - 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, - 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, - 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, - 0x2d02ef8d - @}; - unsigned char *end; - - crc = ~crc & 0xffffffff; - for (end = buf + len; buf < end; ++buf) - crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); - return ~crc & 0xffffffff; -@} -@end smallexample - - -@node Symbol Errors -@section Errors reading symbol files - -While reading a symbol file, @value{GDBN} occasionally encounters problems, -such as symbol types it does not recognize, or known bugs in compiler -output. By default, @value{GDBN} does not notify you of such problems, since -they are relatively common and primarily of interest to people -debugging compilers. If you are interested in seeing information -about ill-constructed symbol tables, you can either ask @value{GDBN} to print -only one message about each such type of problem, no matter how many -times the problem occurs; or you can ask @value{GDBN} to print more messages, -to see how many times the problems occur, with the @code{set -complaints} command (@pxref{Messages/Warnings, ,Optional warnings and -messages}). - -The messages currently printed, and their meanings, include: - -@table @code -@item inner block not inside outer block in @var{symbol} - -The symbol information shows where symbol scopes begin and end -(such as at the start of a function or a block of statements). This -error indicates that an inner scope block is not fully contained -in its outer scope blocks. - -@value{GDBN} circumvents the problem by treating the inner block as if it had -the same scope as the outer block. In the error message, @var{symbol} -may be shown as ``@code{(don't know)}'' if the outer block is not a -function. - -@item block at @var{address} out of order - -The symbol information for symbol scope blocks should occur in -order of increasing addresses. This error indicates that it does not -do so. - -@value{GDBN} does not circumvent this problem, and has trouble -locating symbols in the source file whose symbols it is reading. (You -can often determine what source file is affected by specifying -@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and -messages}.) - -@item bad block start address patched - -The symbol information for a symbol scope block has a start address -smaller than the address of the preceding source line. This is known -to occur in the SunOS 4.1.1 (and earlier) C compiler. - -@value{GDBN} circumvents the problem by treating the symbol scope block as -starting on the previous source line. - -@item bad string table offset in symbol @var{n} - -@cindex foo -Symbol number @var{n} contains a pointer into the string table which is -larger than the size of the string table. - -@value{GDBN} circumvents the problem by considering the symbol to have the -name @code{foo}, which may cause other problems if many symbols end up -with this name. - -@item unknown symbol type @code{0x@var{nn}} - -The symbol information contains new data types that @value{GDBN} does -not yet know how to read. @code{0x@var{nn}} is the symbol type of the -uncomprehended information, in hexadecimal. - -@value{GDBN} circumvents the error by ignoring this symbol information. -This usually allows you to debug your program, though certain symbols -are not accessible. If you encounter such a problem and feel like -debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint -on @code{complain}, then go up to the function @code{read_dbx_symtab} -and examine @code{*bufp} to see the symbol. - -@item stub type has NULL name - -@value{GDBN} could not find the full definition for a struct or class. - -@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} -The symbol information for a C@t{++} member function is missing some -information that recent versions of the compiler should have output for -it. - -@item info mismatch between compiler and debugger - -@value{GDBN} could not parse a type specification output by the compiler. - -@end table - -@node Targets -@chapter Specifying a Debugging Target - -@cindex debugging target -@kindex target - -A @dfn{target} is the execution environment occupied by your program. - -Often, @value{GDBN} runs in the same host environment as your program; -in that case, the debugging target is specified as a side effect when -you use the @code{file} or @code{core} commands. When you need more -flexibility---for example, running @value{GDBN} on a physically separate -host, or controlling a standalone system over a serial port or a -realtime system over a TCP/IP connection---you can use the @code{target} -command to specify one of the target types configured for @value{GDBN} -(@pxref{Target Commands, ,Commands for managing targets}). - -@menu -* Active Targets:: Active targets -* Target Commands:: Commands for managing targets -* Byte Order:: Choosing target byte order -* Remote:: Remote debugging -* KOD:: Kernel Object Display - -@end menu - -@node Active Targets -@section Active targets - -@cindex stacking targets -@cindex active targets -@cindex multiple targets - -There are three classes of targets: processes, core files, and -executable files. @value{GDBN} can work concurrently on up to three -active targets, one in each class. This allows you to (for example) -start a process and inspect its activity without abandoning your work on -a core file. - -For example, if you execute @samp{gdb a.out}, then the executable file -@code{a.out} is the only active target. If you designate a core file as -well---presumably from a prior run that crashed and coredumped---then -@value{GDBN} has two active targets and uses them in tandem, looking -first in the corefile target, then in the executable file, to satisfy -requests for memory addresses. (Typically, these two classes of target -are complementary, since core files contain only a program's -read-write memory---variables and so on---plus machine status, while -executable files contain only the program text and initialized data.) - -When you type @code{run}, your executable file becomes an active process -target as well. When a process target is active, all @value{GDBN} -commands requesting memory addresses refer to that target; addresses in -an active core file or executable file target are obscured while the -process target is active. - -Use the @code{core-file} and @code{exec-file} commands to select a new -core file or executable target (@pxref{Files, ,Commands to specify -files}). To specify as a target a process that is already running, use -the @code{attach} command (@pxref{Attach, ,Debugging an already-running -process}). - -@node Target Commands -@section Commands for managing targets - -@table @code -@item target @var{type} @var{parameters} -Connects the @value{GDBN} host environment to a target machine or -process. A target is typically a protocol for talking to debugging -facilities. You use the argument @var{type} to specify the type or -protocol of the target machine. - -Further @var{parameters} are interpreted by the target protocol, but -typically include things like device names or host names to connect -with, process numbers, and baud rates. - -The @code{target} command does not repeat if you press @key{RET} again -after executing the command. - -@kindex help target -@item help target -Displays the names of all targets available. To display targets -currently selected, use either @code{info target} or @code{info files} -(@pxref{Files, ,Commands to specify files}). - -@item help target @var{name} -Describe a particular target, including any parameters necessary to -select it. - -@kindex set gnutarget -@item set gnutarget @var{args} -@value{GDBN} uses its own library BFD to read your files. @value{GDBN} -knows whether it is reading an @dfn{executable}, -a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format -with the @code{set gnutarget} command. Unlike most @code{target} commands, -with @code{gnutarget} the @code{target} refers to a program, not a machine. - -@quotation -@emph{Warning:} To specify a file format with @code{set gnutarget}, -you must know the actual BFD name. -@end quotation - -@noindent -@xref{Files, , Commands to specify files}. - -@kindex show gnutarget -@item show gnutarget -Use the @code{show gnutarget} command to display what file format -@code{gnutarget} is set to read. If you have not set @code{gnutarget}, -@value{GDBN} will determine the file format for each file automatically, -and @code{show gnutarget} displays @samp{The current BDF target is "auto"}. -@end table - -Here are some common targets (available, or not, depending on the GDB -configuration): - -@table @code -@kindex target exec -@item target exec @var{program} -An executable file. @samp{target exec @var{program}} is the same as -@samp{exec-file @var{program}}. - -@kindex target core -@item target core @var{filename} -A core dump file. @samp{target core @var{filename}} is the same as -@samp{core-file @var{filename}}. - -@kindex target remote -@item target remote @var{dev} -Remote serial target in GDB-specific protocol. The argument @var{dev} -specifies what serial device to use for the connection (e.g. -@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote} -supports the @code{load} command. This is only useful if you have -some other way of getting the stub to the target system, and you can put -it somewhere in memory where it won't get clobbered by the download. - -@kindex target sim -@item target sim -Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. -In general, -@smallexample - target sim - load - run -@end smallexample -@noindent -works; however, you cannot assume that a specific memory map, device -drivers, or even basic I/O is available, although some simulators do -provide these. For info about any processor-specific simulator details, -see the appropriate section in @ref{Embedded Processors, ,Embedded -Processors}. - -@end table - -Some configurations may include these targets as well: - -@table @code - -@kindex target nrom -@item target nrom @var{dev} -NetROM ROM emulator. This target only supports downloading. - -@end table - -Different targets are available on different configurations of @value{GDBN}; -your configuration may have more or fewer targets. - -Many remote targets require you to download the executable's code -once you've successfully established a connection. - -@table @code - -@kindex load @var{filename} -@item load @var{filename} -Depending on what remote debugging facilities are configured into -@value{GDBN}, the @code{load} command may be available. Where it exists, it -is meant to make @var{filename} (an executable) available for debugging -on the remote system---by downloading, or dynamic linking, for example. -@code{load} also records the @var{filename} symbol table in @value{GDBN}, like -the @code{add-symbol-file} command. - -If your @value{GDBN} does not have a @code{load} command, attempting to -execute it gets the error message ``@code{You can't do that when your -target is @dots{}}'' - -The file is loaded at whatever address is specified in the executable. -For some object file formats, you can specify the load address when you -link the program; for other formats, like a.out, the object file format -specifies a fixed address. -@c FIXME! This would be a good place for an xref to the GNU linker doc. - -@code{load} does not repeat if you press @key{RET} again after using it. -@end table - -@node Byte Order -@section Choosing target byte order - -@cindex choosing target byte order -@cindex target byte order - -Some types of processors, such as the MIPS, PowerPC, and Renesas SH, -offer the ability to run either big-endian or little-endian byte -orders. Usually the executable or symbol will include a bit to -designate the endian-ness, and you will not need to worry about -which to use. However, you may still find it useful to adjust -@value{GDBN}'s idea of processor endian-ness manually. - -@table @code -@kindex set endian big -@item set endian big -Instruct @value{GDBN} to assume the target is big-endian. - -@kindex set endian little -@item set endian little -Instruct @value{GDBN} to assume the target is little-endian. - -@kindex set endian auto -@item set endian auto -Instruct @value{GDBN} to use the byte order associated with the -executable. - -@item show endian -Display @value{GDBN}'s current idea of the target byte order. - -@end table - -Note that these commands merely adjust interpretation of symbolic -data on the host, and that they have absolutely no effect on the -target system. - -@node Remote -@section Remote debugging -@cindex remote debugging - -If you are trying to debug a program running on a machine that cannot run -@value{GDBN} in the usual way, it is often useful to use remote debugging. -For example, you might use remote debugging on an operating system kernel, -or on a small system which does not have a general purpose operating system -powerful enough to run a full-featured debugger. - -Some configurations of @value{GDBN} have special serial or TCP/IP interfaces -to make this work with particular debugging targets. In addition, -@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, -but not specific to any particular target system) which you can use if you -write the remote stubs---the code that runs on the remote system to -communicate with @value{GDBN}. - -Other remote targets may be available in your -configuration of @value{GDBN}; use @code{help target} to list them. - -@node KOD -@section Kernel Object Display -@cindex kernel object display -@cindex KOD - -Some targets support kernel object display. Using this facility, -@value{GDBN} communicates specially with the underlying operating system -and can display information about operating system-level objects such as -mutexes and other synchronization objects. Exactly which objects can be -displayed is determined on a per-OS basis. - -@kindex set os -Use the @code{set os} command to set the operating system. This tells -@value{GDBN} which kernel object display module to initialize: - -@smallexample -(@value{GDBP}) set os cisco -@end smallexample - -@kindex show os -The associated command @code{show os} displays the operating system -set with the @code{set os} command; if no operating system has been -set, @code{show os} will display an empty string @samp{""}. - -If @code{set os} succeeds, @value{GDBN} will display some information -about the operating system, and will create a new @code{info} command -which can be used to query the target. The @code{info} command is named -after the operating system: - -@kindex info cisco -@smallexample -(@value{GDBP}) info cisco -List of Cisco Kernel Objects -Object Description -any Any and all objects -@end smallexample - -Further subcommands can be used to query about particular objects known -by the kernel. - -There is currently no way to determine whether a given operating -system is supported other than to try setting it with @kbd{set os -@var{name}}, where @var{name} is the name of the operating system you -want to try. - - -@node Remote Debugging -@chapter Debugging remote programs - -@menu -* Connecting:: Connecting to a remote target -* Server:: Using the gdbserver program -* NetWare:: Using the gdbserve.nlm program -* Remote configuration:: Remote configuration -* remote stub:: Implementing a remote stub -@end menu - -@node Connecting -@section Connecting to a remote target - -On the @value{GDBN} host machine, you will need an unstripped copy of -your program, since @value{GDBN} needs symobl and debugging information. -Start up @value{GDBN} as usual, using the name of the local copy of your -program as the first argument. - -@cindex serial line, @code{target remote} -If you're using a serial line, you may want to give @value{GDBN} the -@w{@samp{--baud}} option, or use the @code{set remotebaud} command -before the @code{target} command. - -After that, use @code{target remote} to establish communications with -the target machine. Its argument specifies how to communicate---either -via a devicename attached to a direct serial line, or a TCP or UDP port -(possibly to a terminal server which in turn has a serial line to the -target). For example, to use a serial line connected to the device -named @file{/dev/ttyb}: - -@smallexample -target remote /dev/ttyb -@end smallexample - -@cindex TCP port, @code{target remote} -To use a TCP connection, use an argument of the form -@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}. -For example, to connect to port 2828 on a -terminal server named @code{manyfarms}: - -@smallexample -target remote manyfarms:2828 -@end smallexample - -If your remote target is actually running on the same machine as -your debugger session (e.g.@: a simulator of your target running on -the same host), you can omit the hostname. For example, to connect -to port 1234 on your local machine: - -@smallexample -target remote :1234 -@end smallexample -@noindent - -Note that the colon is still required here. - -@cindex UDP port, @code{target remote} -To use a UDP connection, use an argument of the form -@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828 -on a terminal server named @code{manyfarms}: - -@smallexample -target remote udp:manyfarms:2828 -@end smallexample - -When using a UDP connection for remote debugging, you should keep in mind -that the `U' stands for ``Unreliable''. UDP can silently drop packets on -busy or unreliable networks, which will cause havoc with your debugging -session. - -Now you can use all the usual commands to examine and change data and to -step and continue the remote program. - -@cindex interrupting remote programs -@cindex remote programs, interrupting -Whenever @value{GDBN} is waiting for the remote program, if you type the -interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the -program. This may or may not succeed, depending in part on the hardware -and the serial drivers the remote system uses. If you type the -interrupt character once again, @value{GDBN} displays this prompt: - -@smallexample -Interrupted while waiting for the program. -Give up (and stop debugging it)? (y or n) -@end smallexample - -If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. -(If you decide you want to try again later, you can use @samp{target -remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} -goes back to waiting. - -@table @code -@kindex detach (remote) -@item detach -When you have finished debugging the remote program, you can use the -@code{detach} command to release it from @value{GDBN} control. -Detaching from the target normally resumes its execution, but the results -will depend on your particular remote stub. After the @code{detach} -command, @value{GDBN} is free to connect to another target. - -@kindex disconnect -@item disconnect -The @code{disconnect} command behaves like @code{detach}, except that -the target is generally not resumed. It will wait for @value{GDBN} -(this instance or another one) to connect and continue debugging. After -the @code{disconnect} command, @value{GDBN} is again free to connect to -another target. -@end table - -@node Server -@section Using the @code{gdbserver} program - -@kindex gdbserver -@cindex remote connection without stubs -@code{gdbserver} is a control program for Unix-like systems, which -allows you to connect your program with a remote @value{GDBN} via -@code{target remote}---but without linking in the usual debugging stub. - -@code{gdbserver} is not a complete replacement for the debugging stubs, -because it requires essentially the same operating-system facilities -that @value{GDBN} itself does. In fact, a system that can run -@code{gdbserver} to connect to a remote @value{GDBN} could also run -@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, -because it is a much smaller program than @value{GDBN} itself. It is -also easier to port than all of @value{GDBN}, so you may be able to get -started more quickly on a new system by using @code{gdbserver}. -Finally, if you develop code for real-time systems, you may find that -the tradeoffs involved in real-time operation make it more convenient to -do as much development work as possible on another system, for example -by cross-compiling. You can use @code{gdbserver} to make a similar -choice for debugging. - -@value{GDBN} and @code{gdbserver} communicate via either a serial line -or a TCP connection, using the standard @value{GDBN} remote serial -protocol. - -@table @emph -@item On the target machine, -you need to have a copy of the program you want to debug. -@code{gdbserver} does not need your program's symbol table, so you can -strip the program if necessary to save space. @value{GDBN} on the host -system does all the symbol handling. - -To use the server, you must tell it how to communicate with @value{GDBN}; -the name of your program; and the arguments for your program. The usual -syntax is: - -@smallexample -target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] -@end smallexample - -@var{comm} is either a device name (to use a serial line) or a TCP -hostname and portnumber. For example, to debug Emacs with the argument -@samp{foo.txt} and communicate with @value{GDBN} over the serial port -@file{/dev/com1}: - -@smallexample -target> gdbserver /dev/com1 emacs foo.txt -@end smallexample - -@code{gdbserver} waits passively for the host @value{GDBN} to communicate -with it. - -To use a TCP connection instead of a serial line: - -@smallexample -target> gdbserver host:2345 emacs foo.txt -@end smallexample - -The only difference from the previous example is the first argument, -specifying that you are communicating with the host @value{GDBN} via -TCP. The @samp{host:2345} argument means that @code{gdbserver} is to -expect a TCP connection from machine @samp{host} to local TCP port 2345. -(Currently, the @samp{host} part is ignored.) You can choose any number -you want for the port number as long as it does not conflict with any -TCP ports already in use on the target system (for example, @code{23} is -reserved for @code{telnet}).@footnote{If you choose a port number that -conflicts with another service, @code{gdbserver} prints an error message -and exits.} You must use the same port number with the host @value{GDBN} -@code{target remote} command. - -On some targets, @code{gdbserver} can also attach to running programs. -This is accomplished via the @code{--attach} argument. The syntax is: - -@smallexample -target> gdbserver @var{comm} --attach @var{pid} -@end smallexample - -@var{pid} is the process ID of a currently running process. It isn't necessary -to point @code{gdbserver} at a binary for the running process. - -@pindex pidof -@cindex attach to a program by name -You can debug processes by name instead of process ID if your target has the -@code{pidof} utility: - -@smallexample -target> gdbserver @var{comm} --attach `pidof @var{PROGRAM}` -@end smallexample - -In case more than one copy of @var{PROGRAM} is running, or @var{PROGRAM} -has multiple threads, most versions of @code{pidof} support the -@code{-s} option to only return the first process ID. - -@item On the host machine, -connect to your target (@pxref{Connecting,,Connecting to a remote target}). -For TCP connections, you must start up @code{gdbserver} prior to using -the @code{target remote} command. Otherwise you may get an error whose -text depends on the host system, but which usually looks something like -@samp{Connection refused}. You don't need to use the @code{load} -command in @value{GDBN} when using gdbserver, since the program is -already on the target. - -@end table - -@node NetWare -@section Using the @code{gdbserve.nlm} program - -@kindex gdbserve.nlm -@code{gdbserve.nlm} is a control program for NetWare systems, which -allows you to connect your program with a remote @value{GDBN} via -@code{target remote}. - -@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line, -using the standard @value{GDBN} remote serial protocol. - -@table @emph -@item On the target machine, -you need to have a copy of the program you want to debug. -@code{gdbserve.nlm} does not need your program's symbol table, so you -can strip the program if necessary to save space. @value{GDBN} on the -host system does all the symbol handling. - -To use the server, you must tell it how to communicate with -@value{GDBN}; the name of your program; and the arguments for your -program. The syntax is: - -@smallexample -load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ] - [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ] -@end smallexample - -@var{board} and @var{port} specify the serial line; @var{baud} specifies -the baud rate used by the connection. @var{port} and @var{node} default -to 0, @var{baud} defaults to 9600@dmn{bps}. - -For example, to debug Emacs with the argument @samp{foo.txt}and -communicate with @value{GDBN} over serial port number 2 or board 1 -using a 19200@dmn{bps} connection: - -@smallexample -load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt -@end smallexample - -@item -On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,, -Connecting to a remote target}). - -@end table - -@node Remote configuration -@section Remote configuration - -The following configuration options are available when debugging remote -programs: - -@table @code -@kindex set remote hardware-watchpoint-limit -@kindex set remote hardware-breakpoint-limit -@anchor{set remote hardware-watchpoint-limit} -@anchor{set remote hardware-breakpoint-limit} -@item set remote hardware-watchpoint-limit @var{limit} -@itemx set remote hardware-breakpoint-limit @var{limit} -Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or -watchpoints. A limit of -1, the default, is treated as unlimited. -@end table - -@node remote stub -@section Implementing a remote stub - -@cindex debugging stub, example -@cindex remote stub, example -@cindex stub example, remote debugging -The stub files provided with @value{GDBN} implement the target side of the -communication protocol, and the @value{GDBN} side is implemented in the -@value{GDBN} source file @file{remote.c}. Normally, you can simply allow -these subroutines to communicate, and ignore the details. (If you're -implementing your own stub file, you can still ignore the details: start -with one of the existing stub files. @file{sparc-stub.c} is the best -organized, and therefore the easiest to read.) - -@cindex remote serial debugging, overview -To debug a program running on another machine (the debugging -@dfn{target} machine), you must first arrange for all the usual -prerequisites for the program to run by itself. For example, for a C -program, you need: - -@enumerate -@item -A startup routine to set up the C runtime environment; these usually -have a name like @file{crt0}. The startup routine may be supplied by -your hardware supplier, or you may have to write your own. - -@item -A C subroutine library to support your program's -subroutine calls, notably managing input and output. - -@item -A way of getting your program to the other machine---for example, a -download program. These are often supplied by the hardware -manufacturer, but you may have to write your own from hardware -documentation. -@end enumerate - -The next step is to arrange for your program to use a serial port to -communicate with the machine where @value{GDBN} is running (the @dfn{host} -machine). In general terms, the scheme looks like this: - -@table @emph -@item On the host, -@value{GDBN} already understands how to use this protocol; when everything -else is set up, you can simply use the @samp{target remote} command -(@pxref{Targets,,Specifying a Debugging Target}). - -@item On the target, -you must link with your program a few special-purpose subroutines that -implement the @value{GDBN} remote serial protocol. The file containing these -subroutines is called a @dfn{debugging stub}. - -On certain remote targets, you can use an auxiliary program -@code{gdbserver} instead of linking a stub into your program. -@xref{Server,,Using the @code{gdbserver} program}, for details. -@end table - -The debugging stub is specific to the architecture of the remote -machine; for example, use @file{sparc-stub.c} to debug programs on -@sc{sparc} boards. - -@cindex remote serial stub list -These working remote stubs are distributed with @value{GDBN}: - -@table @code - -@item i386-stub.c -@cindex @file{i386-stub.c} -@cindex Intel -@cindex i386 -For Intel 386 and compatible architectures. - -@item m68k-stub.c -@cindex @file{m68k-stub.c} -@cindex Motorola 680x0 -@cindex m680x0 -For Motorola 680x0 architectures. - -@item sh-stub.c -@cindex @file{sh-stub.c} -@cindex Renesas -@cindex SH -For Renesas SH architectures. - -@item sparc-stub.c -@cindex @file{sparc-stub.c} -@cindex Sparc -For @sc{sparc} architectures. - -@item sparcl-stub.c -@cindex @file{sparcl-stub.c} -@cindex Fujitsu -@cindex SparcLite -For Fujitsu @sc{sparclite} architectures. - -@end table - -The @file{README} file in the @value{GDBN} distribution may list other -recently added stubs. - -@menu -* Stub Contents:: What the stub can do for you -* Bootstrapping:: What you must do for the stub -* Debug Session:: Putting it all together -@end menu - -@node Stub Contents -@subsection What the stub can do for you - -@cindex remote serial stub -The debugging stub for your architecture supplies these three -subroutines: - -@table @code -@item set_debug_traps -@kindex set_debug_traps -@cindex remote serial stub, initialization -This routine arranges for @code{handle_exception} to run when your -program stops. You must call this subroutine explicitly near the -beginning of your program. - -@item handle_exception -@kindex handle_exception -@cindex remote serial stub, main routine -This is the central workhorse, but your program never calls it -explicitly---the setup code arranges for @code{handle_exception} to -run when a trap is triggered. - -@code{handle_exception} takes control when your program stops during -execution (for example, on a breakpoint), and mediates communications -with @value{GDBN} on the host machine. This is where the communications -protocol is implemented; @code{handle_exception} acts as the @value{GDBN} -representative on the target machine. It begins by sending summary -information on the state of your program, then continues to execute, -retrieving and transmitting any information @value{GDBN} needs, until you -execute a @value{GDBN} command that makes your program resume; at that point, -@code{handle_exception} returns control to your own code on the target -machine. - -@item breakpoint -@cindex @code{breakpoint} subroutine, remote -Use this auxiliary subroutine to make your program contain a -breakpoint. Depending on the particular situation, this may be the only -way for @value{GDBN} to get control. For instance, if your target -machine has some sort of interrupt button, you won't need to call this; -pressing the interrupt button transfers control to -@code{handle_exception}---in effect, to @value{GDBN}. On some machines, -simply receiving characters on the serial port may also trigger a trap; -again, in that situation, you don't need to call @code{breakpoint} from -your own program---simply running @samp{target remote} from the host -@value{GDBN} session gets control. - -Call @code{breakpoint} if none of these is true, or if you simply want -to make certain your program stops at a predetermined point for the -start of your debugging session. -@end table - -@node Bootstrapping -@subsection What you must do for the stub - -@cindex remote stub, support routines -The debugging stubs that come with @value{GDBN} are set up for a particular -chip architecture, but they have no information about the rest of your -debugging target machine. - -First of all you need to tell the stub how to communicate with the -serial port. - -@table @code -@item int getDebugChar() -@kindex getDebugChar -Write this subroutine to read a single character from the serial port. -It may be identical to @code{getchar} for your target system; a -different name is used to allow you to distinguish the two if you wish. - -@item void putDebugChar(int) -@kindex putDebugChar -Write this subroutine to write a single character to the serial port. -It may be identical to @code{putchar} for your target system; a -different name is used to allow you to distinguish the two if you wish. -@end table - -@cindex control C, and remote debugging -@cindex interrupting remote targets -If you want @value{GDBN} to be able to stop your program while it is -running, you need to use an interrupt-driven serial driver, and arrange -for it to stop when it receives a @code{^C} (@samp{\003}, the control-C -character). That is the character which @value{GDBN} uses to tell the -remote system to stop. - -Getting the debugging target to return the proper status to @value{GDBN} -probably requires changes to the standard stub; one quick and dirty way -is to just execute a breakpoint instruction (the ``dirty'' part is that -@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). - -Other routines you need to supply are: - -@table @code -@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) -@kindex exceptionHandler -Write this function to install @var{exception_address} in the exception -handling tables. You need to do this because the stub does not have any -way of knowing what the exception handling tables on your target system -are like (for example, the processor's table might be in @sc{rom}, -containing entries which point to a table in @sc{ram}). -@var{exception_number} is the exception number which should be changed; -its meaning is architecture-dependent (for example, different numbers -might represent divide by zero, misaligned access, etc). When this -exception occurs, control should be transferred directly to -@var{exception_address}, and the processor state (stack, registers, -and so on) should be just as it is when a processor exception occurs. So if -you want to use a jump instruction to reach @var{exception_address}, it -should be a simple jump, not a jump to subroutine. - -For the 386, @var{exception_address} should be installed as an interrupt -gate so that interrupts are masked while the handler runs. The gate -should be at privilege level 0 (the most privileged level). The -@sc{sparc} and 68k stubs are able to mask interrupts themselves without -help from @code{exceptionHandler}. - -@item void flush_i_cache() -@kindex flush_i_cache -On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the -instruction cache, if any, on your target machine. If there is no -instruction cache, this subroutine may be a no-op. - -On target machines that have instruction caches, @value{GDBN} requires this -function to make certain that the state of your program is stable. -@end table - -@noindent -You must also make sure this library routine is available: - -@table @code -@item void *memset(void *, int, int) -@kindex memset -This is the standard library function @code{memset} that sets an area of -memory to a known value. If you have one of the free versions of -@code{libc.a}, @code{memset} can be found there; otherwise, you must -either obtain it from your hardware manufacturer, or write your own. -@end table - -If you do not use the GNU C compiler, you may need other standard -library subroutines as well; this varies from one stub to another, -but in general the stubs are likely to use any of the common library -subroutines which @code{@value{GCC}} generates as inline code. - - -@node Debug Session -@subsection Putting it all together - -@cindex remote serial debugging summary -In summary, when your program is ready to debug, you must follow these -steps. - -@enumerate -@item -Make sure you have defined the supporting low-level routines -(@pxref{Bootstrapping,,What you must do for the stub}): -@display -@code{getDebugChar}, @code{putDebugChar}, -@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. -@end display - -@item -Insert these lines near the top of your program: - -@smallexample -set_debug_traps(); -breakpoint(); -@end smallexample - -@item -For the 680x0 stub only, you need to provide a variable called -@code{exceptionHook}. Normally you just use: - -@smallexample -void (*exceptionHook)() = 0; -@end smallexample - -@noindent -but if before calling @code{set_debug_traps}, you set it to point to a -function in your program, that function is called when -@code{@value{GDBN}} continues after stopping on a trap (for example, bus -error). The function indicated by @code{exceptionHook} is called with -one parameter: an @code{int} which is the exception number. - -@item -Compile and link together: your program, the @value{GDBN} debugging stub for -your target architecture, and the supporting subroutines. - -@item -Make sure you have a serial connection between your target machine and -the @value{GDBN} host, and identify the serial port on the host. - -@item -@c The "remote" target now provides a `load' command, so we should -@c document that. FIXME. -Download your program to your target machine (or get it there by -whatever means the manufacturer provides), and start it. - -@item -Start @value{GDBN} on the host, and connect to the target -(@pxref{Connecting,,Connecting to a remote target}). - -@end enumerate - -@node Configurations -@chapter Configuration-Specific Information - -While nearly all @value{GDBN} commands are available for all native and -cross versions of the debugger, there are some exceptions. This chapter -describes things that are only available in certain configurations. - -There are three major categories of configurations: native -configurations, where the host and target are the same, embedded -operating system configurations, which are usually the same for several -different processor architectures, and bare embedded processors, which -are quite different from each other. - -@menu -* Native:: -* Embedded OS:: -* Embedded Processors:: -* Architectures:: -@end menu - -@node Native -@section Native - -This section describes details specific to particular native -configurations. - -@menu -* HP-UX:: HP-UX -* SVR4 Process Information:: SVR4 process information -* DJGPP Native:: Features specific to the DJGPP port -* Cygwin Native:: Features specific to the Cygwin port -@end menu - -@node HP-UX -@subsection HP-UX - -On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, @value{GDBN} searches for a user or system -name first, before it searches for a convenience variable. - -@node SVR4 Process Information -@subsection SVR4 process information - -@kindex /proc -@cindex process image - -Many versions of SVR4 provide a facility called @samp{/proc} that can be -used to examine the image of a running process using file-system -subroutines. If @value{GDBN} is configured for an operating system with -this facility, the command @code{info proc} is available to report on -several kinds of information about the process running your program. -@code{info proc} works only on SVR4 systems that include the -@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix, -and Unixware, but not HP-UX or @sc{gnu}/Linux, for example. - -@table @code -@kindex info proc -@item info proc -Summarize available information about the process. - -@kindex info proc mappings -@item info proc mappings -Report on the address ranges accessible in the program, with information -on whether your program may read, write, or execute each range. -@ignore -@comment These sub-options of 'info proc' were not included when -@comment procfs.c was re-written. Keep their descriptions around -@comment against the day when someone finds the time to put them back in. -@kindex info proc times -@item info proc times -Starting time, user CPU time, and system CPU time for your program and -its children. - -@kindex info proc id -@item info proc id -Report on the process IDs related to your program: its own process ID, -the ID of its parent, the process group ID, and the session ID. - -@kindex info proc status -@item info proc status -General information on the state of the process. If the process is -stopped, this report includes the reason for stopping, and any signal -received. - -@item info proc all -Show all the above information about the process. -@end ignore -@end table - -@node DJGPP Native -@subsection Features for Debugging @sc{djgpp} Programs -@cindex @sc{djgpp} debugging -@cindex native @sc{djgpp} debugging -@cindex MS-DOS-specific commands - -@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and -MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs -that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on -top of real-mode DOS systems and their emulations. - -@value{GDBN} supports native debugging of @sc{djgpp} programs, and -defines a few commands specific to the @sc{djgpp} port. This -subsection describes those commands. - -@table @code -@kindex info dos -@item info dos -This is a prefix of @sc{djgpp}-specific commands which print -information about the target system and important OS structures. - -@kindex sysinfo -@cindex MS-DOS system info -@cindex free memory information (MS-DOS) -@item info dos sysinfo -This command displays assorted information about the underlying -platform: the CPU type and features, the OS version and flavor, the -DPMI version, and the available conventional and DPMI memory. - -@cindex GDT -@cindex LDT -@cindex IDT -@cindex segment descriptor tables -@cindex descriptor tables display -@item info dos gdt -@itemx info dos ldt -@itemx info dos idt -These 3 commands display entries from, respectively, Global, Local, -and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor -tables are data structures which store a descriptor for each segment -that is currently in use. The segment's selector is an index into a -descriptor table; the table entry for that index holds the -descriptor's base address and limit, and its attributes and access -rights. - -A typical @sc{djgpp} program uses 3 segments: a code segment, a data -segment (used for both data and the stack), and a DOS segment (which -allows access to DOS/BIOS data structures and absolute addresses in -conventional memory). However, the DPMI host will usually define -additional segments in order to support the DPMI environment. - -@cindex garbled pointers -These commands allow to display entries from the descriptor tables. -Without an argument, all entries from the specified table are -displayed. An argument, which should be an integer expression, means -display a single entry whose index is given by the argument. For -example, here's a convenient way to display information about the -debugged program's data segment: - -@smallexample -@exdent @code{(@value{GDBP}) info dos ldt $ds} -@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} -@end smallexample - -@noindent -This comes in handy when you want to see whether a pointer is outside -the data segment's limit (i.e.@: @dfn{garbled}). - -@cindex page tables display (MS-DOS) -@item info dos pde -@itemx info dos pte -These two commands display entries from, respectively, the Page -Directory and the Page Tables. Page Directories and Page Tables are -data structures which control how virtual memory addresses are mapped -into physical addresses. A Page Table includes an entry for every -page of memory that is mapped into the program's address space; there -may be several Page Tables, each one holding up to 4096 entries. A -Page Directory has up to 4096 entries, one each for every Page Table -that is currently in use. - -Without an argument, @kbd{info dos pde} displays the entire Page -Directory, and @kbd{info dos pte} displays all the entries in all of -the Page Tables. An argument, an integer expression, given to the -@kbd{info dos pde} command means display only that entry from the Page -Directory table. An argument given to the @kbd{info dos pte} command -means display entries from a single Page Table, the one pointed to by -the specified entry in the Page Directory. - -@cindex direct memory access (DMA) on MS-DOS -These commands are useful when your program uses @dfn{DMA} (Direct -Memory Access), which needs physical addresses to program the DMA -controller. - -These commands are supported only with some DPMI servers. - -@cindex physical address from linear address -@item info dos address-pte @var{addr} -This command displays the Page Table entry for a specified linear -address. The argument linear address @var{addr} should already have the -appropriate segment's base address added to it, because this command -accepts addresses which may belong to @emph{any} segment. For -example, here's how to display the Page Table entry for the page where -the variable @code{i} is stored: - -@smallexample -@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} -@exdent @code{Page Table entry for address 0x11a00d30:} -@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} -@end smallexample - -@noindent -This says that @code{i} is stored at offset @code{0xd30} from the page -whose physical base address is @code{0x02698000}, and prints all the -attributes of that page. - -Note that you must cast the addresses of variables to a @code{char *}, -since otherwise the value of @code{__djgpp_base_address}, the base -address of all variables and functions in a @sc{djgpp} program, will -be added using the rules of C pointer arithmetics: if @code{i} is -declared an @code{int}, @value{GDBN} will add 4 times the value of -@code{__djgpp_base_address} to the address of @code{i}. - -Here's another example, it displays the Page Table entry for the -transfer buffer: - -@smallexample -@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} -@exdent @code{Page Table entry for address 0x29110:} -@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} -@end smallexample - -@noindent -(The @code{+ 3} offset is because the transfer buffer's address is the -3rd member of the @code{_go32_info_block} structure.) The output of -this command clearly shows that addresses in conventional memory are -mapped 1:1, i.e.@: the physical and linear addresses are identical. - -This command is supported only with some DPMI servers. -@end table - -@node Cygwin Native -@subsection Features for Debugging MS Windows PE executables -@cindex MS Windows debugging -@cindex native Cygwin debugging -@cindex Cygwin-specific commands - -@value{GDBN} supports native debugging of MS Windows programs, including -DLLs with and without symbolic debugging information. There are various -additional Cygwin-specific commands, described in this subsection. The -subsubsection @pxref{Non-debug DLL symbols} describes working with DLLs -that have no debugging symbols. - - -@table @code -@kindex info w32 -@item info w32 -This is a prefix of MS Windows specific commands which print -information about the target system and important OS structures. - -@item info w32 selector -This command displays information returned by -the Win32 API @code{GetThreadSelectorEntry} function. -It takes an optional argument that is evaluated to -a long value to give the information about this given selector. -Without argument, this command displays information -about the the six segment registers. - -@kindex info dll -@item info dll -This is a Cygwin specific alias of info shared. - -@kindex dll-symbols -@item dll-symbols -This command loads symbols from a dll similarly to -add-sym command but without the need to specify a base address. - -@kindex set new-console -@item set new-console @var{mode} -If @var{mode} is @code{on} the debuggee will -be started in a new console on next start. -If @var{mode} is @code{off}i, the debuggee will -be started in the same console as the debugger. - -@kindex show new-console -@item show new-console -Displays whether a new console is used -when the debuggee is started. - -@kindex set new-group -@item set new-group @var{mode} -This boolean value controls whether the debuggee should -start a new group or stay in the same group as the debugger. -This affects the way the Windows OS handles -Ctrl-C. - -@kindex show new-group -@item show new-group -Displays current value of new-group boolean. - -@kindex set debugevents -@item set debugevents -This boolean value adds debug output concerning events seen by the debugger. - -@kindex set debugexec -@item set debugexec -This boolean value adds debug output concerning execute events -seen by the debugger. - -@kindex set debugexceptions -@item set debugexceptions -This boolean value adds debug ouptut concerning exception events -seen by the debugger. - -@kindex set debugmemory -@item set debugmemory -This boolean value adds debug ouptut concerning memory events -seen by the debugger. - -@kindex set shell -@item set shell -This boolean values specifies whether the debuggee is called -via a shell or directly (default value is on). - -@kindex show shell -@item show shell -Displays if the debuggee will be started with a shell. - -@end table - -@menu -* Non-debug DLL symbols:: Support for DLLs without debugging symbols -@end menu - -@node Non-debug DLL symbols -@subsubsection Support for DLLs without debugging symbols -@cindex DLLs with no debugging symbols -@cindex Minimal symbols and DLLs - -Very often on windows, some of the DLLs that your program relies on do -not include symbolic debugging information (for example, -@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging -symbols in a DLL, it relies on the minimal amount of symbolic -information contained in the DLL's export table. This subsubsection -describes working with such symbols, known internally to @value{GDBN} as -``minimal symbols''. - -Note that before the debugged program has started execution, no DLLs -will have been loaded. The easiest way around this problem is simply to -start the program --- either by setting a breakpoint or letting the -program run once to completion. It is also possible to force -@value{GDBN} to load a particular DLL before starting the executable --- -see the shared library information in @pxref{Files} or the -@code{dll-symbols} command in @pxref{Cygwin Native}. Currently, -explicitly loading symbols from a DLL with no debugging information will -cause the symbol names to be duplicated in @value{GDBN}'s lookup table, -which may adversely affect symbol lookup performance. - -@subsubsection DLL name prefixes - -In keeping with the naming conventions used by the Microsoft debugging -tools, DLL export symbols are made available with a prefix based on the -DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is -also entered into the symbol table, so @code{CreateFileA} is often -sufficient. In some cases there will be name clashes within a program -(particularly if the executable itself includes full debugging symbols) -necessitating the use of the fully qualified name when referring to the -contents of the DLL. Use single-quotes around the name to avoid the -exclamation mark (``!'') being interpreted as a language operator. - -Note that the internal name of the DLL may be all upper-case, even -though the file name of the DLL is lower-case, or vice-versa. Since -symbols within @value{GDBN} are @emph{case-sensitive} this may cause -some confusion. If in doubt, try the @code{info functions} and -@code{info variables} commands or even @code{maint print msymbols} (see -@pxref{Symbols}). Here's an example: - -@smallexample -(gdb) info function CreateFileA -All functions matching regular expression "CreateFileA": - -Non-debugging symbols: -0x77e885f4 CreateFileA -0x77e885f4 KERNEL32!CreateFileA -@end smallexample - -@smallexample -(gdb) info function ! -All functions matching regular expression "!": - -Non-debugging symbols: -0x6100114c cygwin1!__assert -0x61004034 cygwin1!_dll_crt0@@0 -0x61004240 cygwin1!dll_crt0(per_process *) -[etc...] -@end smallexample - -@subsubsection Working with minimal symbols - -Symbols extracted from a DLL's export table do not contain very much -type information. All that @value{GDBN} can do is guess whether a symbol -refers to a function or variable depending on the linker section that -contains the symbol. Also note that the actual contents of the memory -contained in a DLL are not available unless the program is running. This -means that you cannot examine the contents of a variable or disassemble -a function within a DLL without a running program. - -Variables are generally treated as pointers and dereferenced -automatically. For this reason, it is often necessary to prefix a -variable name with the address-of operator (``&'') and provide explicit -type information in the command. Here's an example of the type of -problem: - -@smallexample -(gdb) print 'cygwin1!__argv' -$1 = 268572168 -@end smallexample - -@smallexample -(gdb) x 'cygwin1!__argv' -0x10021610: "\230y\"" -@end smallexample - -And two possible solutions: - -@smallexample -(gdb) print ((char **)'cygwin1!__argv')[0] -$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" -@end smallexample - -@smallexample -(gdb) x/2x &'cygwin1!__argv' -0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 -(gdb) x/x 0x10021608 -0x10021608: 0x0022fd98 -(gdb) x/s 0x0022fd98 -0x22fd98: "/cygdrive/c/mydirectory/myprogram" -@end smallexample - -Setting a break point within a DLL is possible even before the program -starts execution. However, under these circumstances, @value{GDBN} can't -examine the initial instructions of the function in order to skip the -function's frame set-up code. You can work around this by using ``*&'' -to set the breakpoint at a raw memory address: - -@smallexample -(gdb) break *&'python22!PyOS_Readline' -Breakpoint 1 at 0x1e04eff0 -@end smallexample - -The author of these extensions is not entirely convinced that setting a -break point within a shared DLL like @file{kernel32.dll} is completely -safe. - -@node Embedded OS -@section Embedded Operating Systems - -This section describes configurations involving the debugging of -embedded operating systems that are available for several different -architectures. - -@menu -* VxWorks:: Using @value{GDBN} with VxWorks -@end menu - -@value{GDBN} includes the ability to debug programs running on -various real-time operating systems. - -@node VxWorks -@subsection Using @value{GDBN} with VxWorks - -@cindex VxWorks - -@table @code - -@kindex target vxworks -@item target vxworks @var{machinename} -A VxWorks system, attached via TCP/IP. The argument @var{machinename} -is the target system's machine name or IP address. - -@end table - -On VxWorks, @code{load} links @var{filename} dynamically on the -current target system as well as adding its symbols in @value{GDBN}. - -@value{GDBN} enables developers to spawn and debug tasks running on networked -VxWorks targets from a Unix host. Already-running tasks spawned from -the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on -both the Unix host and on the VxWorks target. The program -@code{@value{GDBP}} is installed and executed on the Unix host. (It may be -installed with the name @code{vxgdb}, to distinguish it from a -@value{GDBN} for debugging programs on the host itself.) - -@table @code -@item VxWorks-timeout @var{args} -@kindex vxworks-timeout -All VxWorks-based targets now support the option @code{vxworks-timeout}. -This option is set by the user, and @var{args} represents the number of -seconds @value{GDBN} waits for responses to rpc's. You might use this if -your VxWorks target is a slow software simulator or is on the far side -of a thin network line. -@end table - -The following information on connecting to VxWorks was current when -this manual was produced; newer releases of VxWorks may use revised -procedures. - -@kindex INCLUDE_RDB -To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel -to include the remote debugging interface routines in the VxWorks -library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the -VxWorks configuration file @file{configAll.h} and rebuild your VxWorks -kernel. The resulting kernel contains @file{rdb.a}, and spawns the -source debugging task @code{tRdbTask} when VxWorks is booted. For more -information on configuring and remaking VxWorks, see the manufacturer's -manual. -@c VxWorks, see the @cite{VxWorks Programmer's Guide}. - -Once you have included @file{rdb.a} in your VxWorks system image and set -your Unix execution search path to find @value{GDBN}, you are ready to -run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or -@code{vxgdb}, depending on your installation). - -@value{GDBN} comes up showing the prompt: - -@smallexample -(vxgdb) -@end smallexample - -@menu -* VxWorks Connection:: Connecting to VxWorks -* VxWorks Download:: VxWorks download -* VxWorks Attach:: Running tasks -@end menu - -@node VxWorks Connection -@subsubsection Connecting to VxWorks - -The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the -network. To connect to a target whose host name is ``@code{tt}'', type: - -@smallexample -(vxgdb) target vxworks tt -@end smallexample - -@need 750 -@value{GDBN} displays messages like these: - -@smallexample -Attaching remote machine across net... -Connected to tt. -@end smallexample - -@need 1000 -@value{GDBN} then attempts to read the symbol tables of any object modules -loaded into the VxWorks target since it was last booted. @value{GDBN} locates -these files by searching the directories listed in the command search -path (@pxref{Environment, ,Your program's environment}); if it fails -to find an object file, it displays a message such as: - -@smallexample -prog.o: No such file or directory. -@end smallexample - -When this happens, add the appropriate directory to the search path with -the @value{GDBN} command @code{path}, and execute the @code{target} -command again. - -@node VxWorks Download -@subsubsection VxWorks download - -@cindex download to VxWorks -If you have connected to the VxWorks target and you want to debug an -object that has not yet been loaded, you can use the @value{GDBN} -@code{load} command to download a file from Unix to VxWorks -incrementally. The object file given as an argument to the @code{load} -command is actually opened twice: first by the VxWorks target in order -to download the code, then by @value{GDBN} in order to read the symbol -table. This can lead to problems if the current working directories on -the two systems differ. If both systems have NFS mounted the same -filesystems, you can avoid these problems by using absolute paths. -Otherwise, it is simplest to set the working directory on both systems -to the directory in which the object file resides, and then to reference -the file by its name, without any path. For instance, a program -@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks -and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this -program, type this on VxWorks: - -@smallexample --> cd "@var{vxpath}/vw/demo/rdb" -@end smallexample - -@noindent -Then, in @value{GDBN}, type: - -@smallexample -(vxgdb) cd @var{hostpath}/vw/demo/rdb -(vxgdb) load prog.o -@end smallexample - -@value{GDBN} displays a response similar to this: - -@smallexample -Reading symbol data from wherever/vw/demo/rdb/prog.o... done. -@end smallexample - -You can also use the @code{load} command to reload an object module -after editing and recompiling the corresponding source file. Note that -this makes @value{GDBN} delete all currently-defined breakpoints, -auto-displays, and convenience variables, and to clear the value -history. (This is necessary in order to preserve the integrity of -debugger's data structures that reference the target system's symbol -table.) - -@node VxWorks Attach -@subsubsection Running tasks - -@cindex running VxWorks tasks -You can also attach to an existing task using the @code{attach} command as -follows: - -@smallexample -(vxgdb) attach @var{task} -@end smallexample - -@noindent -where @var{task} is the VxWorks hexadecimal task ID. The task can be running -or suspended when you attach to it. Running tasks are suspended at -the time of attachment. - -@node Embedded Processors -@section Embedded Processors - -This section goes into details specific to particular embedded -configurations. - - -@menu -* ARM:: ARM -* H8/300:: Renesas H8/300 -* H8/500:: Renesas H8/500 -* M32R/D:: Renesas M32R/D -* M68K:: Motorola M68K -* MIPS Embedded:: MIPS Embedded -* OpenRISC 1000:: OpenRisc 1000 -* PA:: HP PA Embedded -* PowerPC: PowerPC -* SH:: Renesas SH -* Sparclet:: Tsqware Sparclet -* Sparclite:: Fujitsu Sparclite -* ST2000:: Tandem ST2000 -* Z8000:: Zilog Z8000 -@end menu - -@node ARM -@subsection ARM - -@table @code - -@kindex target rdi -@item target rdi @var{dev} -ARM Angel monitor, via RDI library interface to ADP protocol. You may -use this target to communicate with both boards running the Angel -monitor, or with the EmbeddedICE JTAG debug device. - -@kindex target rdp -@item target rdp @var{dev} -ARM Demon monitor. - -@end table - -@node H8/300 -@subsection Renesas H8/300 - -@table @code - -@kindex target hms@r{, with H8/300} -@item target hms @var{dev} -A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host. -Use special commands @code{device} and @code{speed} to control the serial -line and the communications speed used. - -@kindex target e7000@r{, with H8/300} -@item target e7000 @var{dev} -E7000 emulator for Renesas H8 and SH. - -@kindex target sh3@r{, with H8/300} -@kindex target sh3e@r{, with H8/300} -@item target sh3 @var{dev} -@itemx target sh3e @var{dev} -Renesas SH-3 and SH-3E target systems. - -@end table - -@cindex download to H8/300 or H8/500 -@cindex H8/300 or H8/500 download -@cindex download to Renesas SH -@cindex Renesas SH download -When you select remote debugging to a Renesas SH, H8/300, or H8/500 -board, the @code{load} command downloads your program to the Renesas -board and also opens it as the current executable target for -@value{GDBN} on your host (like the @code{file} command). - -@value{GDBN} needs to know these things to talk to your -Renesas SH, H8/300, or H8/500: - -@enumerate -@item -that you want to use @samp{target hms}, the remote debugging interface -for Renesas microprocessors, or @samp{target e7000}, the in-circuit -emulator for the Renesas SH and the Renesas 300H. (@samp{target hms} is -the default when @value{GDBN} is configured specifically for the Renesas SH, -H8/300, or H8/500.) - -@item -what serial device connects your host to your Renesas board (the first -serial device available on your host is the default). - -@item -what speed to use over the serial device. -@end enumerate - -@menu -* Renesas Boards:: Connecting to Renesas boards. -* Renesas ICE:: Using the E7000 In-Circuit Emulator. -* Renesas Special:: Special @value{GDBN} commands for Renesas micros. -@end menu - -@node Renesas Boards -@subsubsection Connecting to Renesas boards - -@c only for Unix hosts -@kindex device -@cindex serial device, Renesas micros -Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you -need to explicitly set the serial device. The default @var{port} is the -first available port on your host. This is only necessary on Unix -hosts, where it is typically something like @file{/dev/ttya}. - -@kindex speed -@cindex serial line speed, Renesas micros -@code{@value{GDBN}} has another special command to set the communications -speed: @samp{speed @var{bps}}. This command also is only used from Unix -hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with -the DOS @code{mode} command (for instance, -@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection). - -The @samp{device} and @samp{speed} commands are available only when you -use a Unix host to debug your Renesas microprocessor programs. If you -use a DOS host, -@value{GDBN} depends on an auxiliary terminate-and-stay-resident program -called @code{asynctsr} to communicate with the development board -through a PC serial port. You must also use the DOS @code{mode} command -to set up the serial port on the DOS side. - -The following sample session illustrates the steps needed to start a -program under @value{GDBN} control on an H8/300. The example uses a -sample H8/300 program called @file{t.x}. The procedure is the same for -the Renesas SH and the H8/500. - -First hook up your development board. In this example, we use a -board attached to serial port @code{COM2}; if you use a different serial -port, substitute its name in the argument of the @code{mode} command. -When you call @code{asynctsr}, the auxiliary comms program used by the -debugger, you give it just the numeric part of the serial port's name; -for example, @samp{asyncstr 2} below runs @code{asyncstr} on -@code{COM2}. - -@smallexample -C:\H8300\TEST> asynctsr 2 -C:\H8300\TEST> mode com2:9600,n,8,1,p - -Resident portion of MODE loaded - -COM2: 9600, n, 8, 1, p - -@end smallexample - -@quotation -@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with -@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to -disable it, or even boot without it, to use @code{asynctsr} to control -your development board. -@end quotation - -@kindex target hms@r{, and serial protocol} -Now that serial communications are set up, and the development board is -connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with -the name of your program as the argument. @code{@value{GDBN}} prompts -you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special -commands to begin your debugging session: @samp{target hms} to specify -cross-debugging to the Renesas board, and the @code{load} command to -download your program to the board. @code{load} displays the names of -the program's sections, and a @samp{*} for each 2K of data downloaded. -(If you want to refresh @value{GDBN} data on symbols or on the -executable file without downloading, use the @value{GDBN} commands -@code{file} or @code{symbol-file}. These commands, and @code{load} -itself, are described in @ref{Files,,Commands to specify files}.) - -@smallexample -(eg-C:\H8300\TEST) @value{GDBP} t.x -@value{GDBN} is free software and you are welcome to distribute copies - of it under certain conditions; type "show copying" to see - the conditions. -There is absolutely no warranty for @value{GDBN}; type "show warranty" -for details. -@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc... -(@value{GDBP}) target hms -Connected to remote H8/300 HMS system. -(@value{GDBP}) load t.x -.text : 0x8000 .. 0xabde *********** -.data : 0xabde .. 0xad30 * -.stack : 0xf000 .. 0xf014 * -@end smallexample - -At this point, you're ready to run or debug your program. From here on, -you can use all the usual @value{GDBN} commands. The @code{break} command -sets breakpoints; the @code{run} command starts your program; -@code{print} or @code{x} display data; the @code{continue} command -resumes execution after stopping at a breakpoint. You can use the -@code{help} command at any time to find out more about @value{GDBN} commands. - -Remember, however, that @emph{operating system} facilities aren't -available on your development board; for example, if your program hangs, -you can't send an interrupt---but you can press the @sc{reset} switch! - -Use the @sc{reset} button on the development board -@itemize @bullet -@item -to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has -no way to pass an interrupt signal to the development board); and - -@item -to return to the @value{GDBN} command prompt after your program finishes -normally. The communications protocol provides no other way for @value{GDBN} -to detect program completion. -@end itemize - -In either case, @value{GDBN} sees the effect of a @sc{reset} on the -development board as a ``normal exit'' of your program. - -@node Renesas ICE -@subsubsection Using the E7000 in-circuit emulator - -@kindex target e7000@r{, with Renesas ICE} -You can use the E7000 in-circuit emulator to develop code for either the -Renesas SH or the H8/300H. Use one of these forms of the @samp{target -e7000} command to connect @value{GDBN} to your E7000: - -@table @code -@item target e7000 @var{port} @var{speed} -Use this form if your E7000 is connected to a serial port. The -@var{port} argument identifies what serial port to use (for example, -@samp{com2}). The third argument is the line speed in bits per second -(for example, @samp{9600}). - -@item target e7000 @var{hostname} -If your E7000 is installed as a host on a TCP/IP network, you can just -specify its hostname; @value{GDBN} uses @code{telnet} to connect. -@end table - -@node Renesas Special -@subsubsection Special @value{GDBN} commands for Renesas micros - -Some @value{GDBN} commands are available only for the H8/300: - -@table @code - -@kindex set machine -@kindex show machine -@item set machine h8300 -@itemx set machine h8300h -Condition @value{GDBN} for one of the two variants of the H8/300 -architecture with @samp{set machine}. You can use @samp{show machine} -to check which variant is currently in effect. - -@end table - -@node H8/500 -@subsection H8/500 - -@table @code - -@kindex set memory @var{mod} -@cindex memory models, H8/500 -@item set memory @var{mod} -@itemx show memory -Specify which H8/500 memory model (@var{mod}) you are using with -@samp{set memory}; check which memory model is in effect with @samp{show -memory}. The accepted values for @var{mod} are @code{small}, -@code{big}, @code{medium}, and @code{compact}. - -@end table - -@node M32R/D -@subsection Renesas M32R/D - -@table @code - -@kindex target m32r -@item target m32r @var{dev} -Renesas M32R/D ROM monitor. - -@kindex target m32rsdi -@item target m32rsdi @var{dev} -Renesas M32R SDI server, connected via parallel port to the board. - -@end table - -@node M68K -@subsection M68k - -The Motorola m68k configuration includes ColdFire support, and -target command for the following ROM monitors. - -@table @code - -@kindex target abug -@item target abug @var{dev} -ABug ROM monitor for M68K. - -@kindex target cpu32bug -@item target cpu32bug @var{dev} -CPU32BUG monitor, running on a CPU32 (M68K) board. - -@kindex target dbug -@item target dbug @var{dev} -dBUG ROM monitor for Motorola ColdFire. - -@kindex target est -@item target est @var{dev} -EST-300 ICE monitor, running on a CPU32 (M68K) board. - -@kindex target rom68k -@item target rom68k @var{dev} -ROM 68K monitor, running on an M68K IDP board. - -@end table - -@table @code - -@kindex target rombug -@item target rombug @var{dev} -ROMBUG ROM monitor for OS/9000. - -@end table - -@node MIPS Embedded -@subsection MIPS Embedded - -@cindex MIPS boards -@value{GDBN} can use the MIPS remote debugging protocol to talk to a -MIPS board attached to a serial line. This is available when -you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. - -@need 1000 -Use these @value{GDBN} commands to specify the connection to your target board: - -@table @code -@item target mips @var{port} -@kindex target mips @var{port} -To run a program on the board, start up @code{@value{GDBP}} with the -name of your program as the argument. To connect to the board, use the -command @samp{target mips @var{port}}, where @var{port} is the name of -the serial port connected to the board. If the program has not already -been downloaded to the board, you may use the @code{load} command to -download it. You can then use all the usual @value{GDBN} commands. - -For example, this sequence connects to the target board through a serial -port, and loads and runs a program called @var{prog} through the -debugger: - -@smallexample -host$ @value{GDBP} @var{prog} -@value{GDBN} is free software and @dots{} -(@value{GDBP}) target mips /dev/ttyb -(@value{GDBP}) load @var{prog} -(@value{GDBP}) run -@end smallexample - -@item target mips @var{hostname}:@var{portnumber} -On some @value{GDBN} host configurations, you can specify a TCP -connection (for instance, to a serial line managed by a terminal -concentrator) instead of a serial port, using the syntax -@samp{@var{hostname}:@var{portnumber}}. - -@item target pmon @var{port} -@kindex target pmon @var{port} -PMON ROM monitor. - -@item target ddb @var{port} -@kindex target ddb @var{port} -NEC's DDB variant of PMON for Vr4300. - -@item target lsi @var{port} -@kindex target lsi @var{port} -LSI variant of PMON. - -@kindex target r3900 -@item target r3900 @var{dev} -Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. - -@kindex target array -@item target array @var{dev} -Array Tech LSI33K RAID controller board. - -@end table - - -@noindent -@value{GDBN} also supports these special commands for MIPS targets: - -@table @code -@item set processor @var{args} -@itemx show processor -@kindex set processor @var{args} -@kindex show processor -Use the @code{set processor} command to set the type of MIPS -processor when you want to access processor-type-specific registers. -For example, @code{set processor @var{r3041}} tells @value{GDBN} -to use the CPU registers appropriate for the 3041 chip. -Use the @code{show processor} command to see what MIPS processor @value{GDBN} -is using. Use the @code{info reg} command to see what registers -@value{GDBN} is using. - -@item set mipsfpu double -@itemx set mipsfpu single -@itemx set mipsfpu none -@itemx show mipsfpu -@kindex set mipsfpu -@kindex show mipsfpu -@cindex MIPS remote floating point -@cindex floating point, MIPS remote -If your target board does not support the MIPS floating point -coprocessor, you should use the command @samp{set mipsfpu none} (if you -need this, you may wish to put the command in your @value{GDBN} init -file). This tells @value{GDBN} how to find the return value of -functions which return floating point values. It also allows -@value{GDBN} to avoid saving the floating point registers when calling -functions on the board. If you are using a floating point coprocessor -with only single precision floating point support, as on the @sc{r4650} -processor, use the command @samp{set mipsfpu single}. The default -double precision floating point coprocessor may be selected using -@samp{set mipsfpu double}. - -In previous versions the only choices were double precision or no -floating point, so @samp{set mipsfpu on} will select double precision -and @samp{set mipsfpu off} will select no floating point. - -As usual, you can inquire about the @code{mipsfpu} variable with -@samp{show mipsfpu}. - -@item set remotedebug @var{n} -@itemx show remotedebug -@kindex set remotedebug@r{, MIPS protocol} -@kindex show remotedebug@r{, MIPS protocol} -@cindex @code{remotedebug}, MIPS protocol -@cindex MIPS @code{remotedebug} protocol -@c FIXME! For this to be useful, you must know something about the MIPS -@c FIXME...protocol. Where is it described? -You can see some debugging information about communications with the board -by setting the @code{remotedebug} variable. If you set it to @code{1} using -@samp{set remotedebug 1}, every packet is displayed. If you set it -to @code{2}, every character is displayed. You can check the current value -at any time with the command @samp{show remotedebug}. - -@item set timeout @var{seconds} -@itemx set retransmit-timeout @var{seconds} -@itemx show timeout -@itemx show retransmit-timeout -@cindex @code{timeout}, MIPS protocol -@cindex @code{retransmit-timeout}, MIPS protocol -@kindex set timeout -@kindex show timeout -@kindex set retransmit-timeout -@kindex show retransmit-timeout -You can control the timeout used while waiting for a packet, in the MIPS -remote protocol, with the @code{set timeout @var{seconds}} command. The -default is 5 seconds. Similarly, you can control the timeout used while -waiting for an acknowledgement of a packet with the @code{set -retransmit-timeout @var{seconds}} command. The default is 3 seconds. -You can inspect both values with @code{show timeout} and @code{show -retransmit-timeout}. (These commands are @emph{only} available when -@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.) - -The timeout set by @code{set timeout} does not apply when @value{GDBN} -is waiting for your program to stop. In that case, @value{GDBN} waits -forever because it has no way of knowing how long the program is going -to run before stopping. -@end table - -@node OpenRISC 1000 -@subsection OpenRISC 1000 -@cindex OpenRISC 1000 - -@cindex or1k boards -See OR1k Architecture document (@uref{www.opencores.org}) for more information -about platform and commands. - -@table @code - -@kindex target jtag -@item target jtag jtag://@var{host}:@var{port} - -Connects to remote JTAG server. -JTAG remote server can be either an or1ksim or JTAG server, -connected via parallel port to the board. - -Example: @code{target jtag jtag://localhost:9999} - -@kindex or1ksim -@item or1ksim @var{command} -If connected to @code{or1ksim} OpenRISC 1000 Architectural -Simulator, proprietary commands can be executed. - -@kindex info or1k spr -@item info or1k spr -Displays spr groups. - -@item info or1k spr @var{group} -@itemx info or1k spr @var{groupno} -Displays register names in selected group. - -@item info or1k spr @var{group} @var{register} -@itemx info or1k spr @var{register} -@itemx info or1k spr @var{groupno} @var{registerno} -@itemx info or1k spr @var{registerno} -Shows information about specified spr register. - -@kindex spr -@item spr @var{group} @var{register} @var{value} -@itemx spr @var{register @var{value}} -@itemx spr @var{groupno} @var{registerno @var{value}} -@itemx spr @var{registerno @var{value}} -Writes @var{value} to specified spr register. -@end table - -Some implementations of OpenRISC 1000 Architecture also have hardware trace. -It is very similar to @value{GDBN} trace, except it does not interfere with normal -program execution and is thus much faster. Hardware breakpoints/watchpoint -triggers can be set using: -@table @code -@item $LEA/$LDATA -Load effective address/data -@item $SEA/$SDATA -Store effective address/data -@item $AEA/$ADATA -Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) -@item $FETCH -Fetch data -@end table - -When triggered, it can capture low level data, like: @code{PC}, @code{LSEA}, -@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}. - -@code{htrace} commands: -@cindex OpenRISC 1000 htrace -@table @code -@kindex hwatch -@item hwatch @var{conditional} -Set hardware watchpoint on combination of Load/Store Effecive Address(es) -or Data. For example: - -@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} - -@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)} - -@kindex htrace info -@item htrace info -Display information about current HW trace configuration. - -@kindex htrace trigger -@item htrace trigger @var{conditional} -Set starting criteria for HW trace. - -@kindex htrace qualifier -@item htrace qualifier @var{conditional} -Set acquisition qualifier for HW trace. - -@kindex htrace stop -@item htrace stop @var{conditional} -Set HW trace stopping criteria. - -@kindex htrace record -@item htrace record [@var{data}]* -Selects the data to be recorded, when qualifier is met and HW trace was -triggered. - -@kindex htrace enable -@item htrace enable -@kindex htrace disable -@itemx htrace disable -Enables/disables the HW trace. - -@kindex htrace rewind -@item htrace rewind [@var{filename}] -Clears currently recorded trace data. - -If filename is specified, new trace file is made and any newly collected data -will be written there. - -@kindex htrace print -@item htrace print [@var{start} [@var{len}]] -Prints trace buffer, using current record configuration. - -@kindex htrace mode continuous -@item htrace mode continuous -Set continuous trace mode. - -@kindex htrace mode suspend -@item htrace mode suspend -Set suspend trace mode. - -@end table - -@node PowerPC -@subsection PowerPC - -@table @code - -@kindex target dink32 -@item target dink32 @var{dev} -DINK32 ROM monitor. - -@kindex target ppcbug -@item target ppcbug @var{dev} -@kindex target ppcbug1 -@item target ppcbug1 @var{dev} -PPCBUG ROM monitor for PowerPC. - -@kindex target sds -@item target sds @var{dev} -SDS monitor, running on a PowerPC board (such as Motorola's ADS). - -@end table - -@node PA -@subsection HP PA Embedded - -@table @code - -@kindex target op50n -@item target op50n @var{dev} -OP50N monitor, running on an OKI HPPA board. - -@kindex target w89k -@item target w89k @var{dev} -W89K monitor, running on a Winbond HPPA board. - -@end table - -@node SH -@subsection Renesas SH - -@table @code - -@kindex target hms@r{, with Renesas SH} -@item target hms @var{dev} -A Renesas SH board attached via serial line to your host. Use special -commands @code{device} and @code{speed} to control the serial line and -the communications speed used. - -@kindex target e7000@r{, with Renesas SH} -@item target e7000 @var{dev} -E7000 emulator for Renesas SH. - -@kindex target sh3@r{, with SH} -@kindex target sh3e@r{, with SH} -@item target sh3 @var{dev} -@item target sh3e @var{dev} -Renesas SH-3 and SH-3E target systems. - -@end table - -@node Sparclet -@subsection Tsqware Sparclet - -@cindex Sparclet - -@value{GDBN} enables developers to debug tasks running on -Sparclet targets from a Unix host. -@value{GDBN} uses code that runs on -both the Unix host and on the Sparclet target. The program -@code{@value{GDBP}} is installed and executed on the Unix host. - -@table @code -@item remotetimeout @var{args} -@kindex remotetimeout -@value{GDBN} supports the option @code{remotetimeout}. -This option is set by the user, and @var{args} represents the number of -seconds @value{GDBN} waits for responses. -@end table - -@cindex compiling, on Sparclet -When compiling for debugging, include the options @samp{-g} to get debug -information and @samp{-Ttext} to relocate the program to where you wish to -load it on the target. You may also want to add the options @samp{-n} or -@samp{-N} in order to reduce the size of the sections. Example: - -@smallexample -sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N -@end smallexample - -You can use @code{objdump} to verify that the addresses are what you intended: - -@smallexample -sparclet-aout-objdump --headers --syms prog -@end smallexample - -@cindex running, on Sparclet -Once you have set -your Unix execution search path to find @value{GDBN}, you are ready to -run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} -(or @code{sparclet-aout-gdb}, depending on your installation). - -@value{GDBN} comes up showing the prompt: - -@smallexample -(gdbslet) -@end smallexample - -@menu -* Sparclet File:: Setting the file to debug -* Sparclet Connection:: Connecting to Sparclet -* Sparclet Download:: Sparclet download -* Sparclet Execution:: Running and debugging -@end menu - -@node Sparclet File -@subsubsection Setting file to debug - -The @value{GDBN} command @code{file} lets you choose with program to debug. - -@smallexample -(gdbslet) file prog -@end smallexample - -@need 1000 -@value{GDBN} then attempts to read the symbol table of @file{prog}. -@value{GDBN} locates -the file by searching the directories listed in the command search -path. -If the file was compiled with debug information (option "-g"), source -files will be searched as well. -@value{GDBN} locates -the source files by searching the directories listed in the directory search -path (@pxref{Environment, ,Your program's environment}). -If it fails -to find a file, it displays a message such as: - -@smallexample -prog: No such file or directory. -@end smallexample - -When this happens, add the appropriate directories to the search paths with -the @value{GDBN} commands @code{path} and @code{dir}, and execute the -@code{target} command again. - -@node Sparclet Connection -@subsubsection Connecting to Sparclet - -The @value{GDBN} command @code{target} lets you connect to a Sparclet target. -To connect to a target on serial port ``@code{ttya}'', type: - -@smallexample -(gdbslet) target sparclet /dev/ttya -Remote target sparclet connected to /dev/ttya -main () at ../prog.c:3 -@end smallexample - -@need 750 -@value{GDBN} displays messages like these: - -@smallexample -Connected to ttya. -@end smallexample - -@node Sparclet Download -@subsubsection Sparclet download - -@cindex download to Sparclet -Once connected to the Sparclet target, -you can use the @value{GDBN} -@code{load} command to download the file from the host to the target. -The file name and load offset should be given as arguments to the @code{load} -command. -Since the file format is aout, the program must be loaded to the starting -address. You can use @code{objdump} to find out what this value is. The load -offset is an offset which is added to the VMA (virtual memory address) -of each of the file's sections. -For instance, if the program -@file{prog} was linked to text address 0x1201000, with data at 0x12010160 -and bss at 0x12010170, in @value{GDBN}, type: - -@smallexample -(gdbslet) load prog 0x12010000 -Loading section .text, size 0xdb0 vma 0x12010000 -@end smallexample - -If the code is loaded at a different address then what the program was linked -to, you may need to use the @code{section} and @code{add-symbol-file} commands -to tell @value{GDBN} where to map the symbol table. - -@node Sparclet Execution -@subsubsection Running and debugging - -@cindex running and debugging Sparclet programs -You can now begin debugging the task using @value{GDBN}'s execution control -commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} -manual for the list of commands. - -@smallexample -(gdbslet) b main -Breakpoint 1 at 0x12010000: file prog.c, line 3. -(gdbslet) run -Starting program: prog -Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 -3 char *symarg = 0; -(gdbslet) step -4 char *execarg = "hello!"; -(gdbslet) -@end smallexample - -@node Sparclite -@subsection Fujitsu Sparclite - -@table @code - -@kindex target sparclite -@item target sparclite @var{dev} -Fujitsu sparclite boards, used only for the purpose of loading. -You must use an additional command to debug the program. -For example: target remote @var{dev} using @value{GDBN} standard -remote protocol. - -@end table - -@node ST2000 -@subsection Tandem ST2000 - -@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's -STDBUG protocol. - -To connect your ST2000 to the host system, see the manufacturer's -manual. Once the ST2000 is physically attached, you can run: - -@smallexample -target st2000 @var{dev} @var{speed} -@end smallexample - -@noindent -to establish it as your debugging environment. @var{dev} is normally -the name of a serial device, such as @file{/dev/ttya}, connected to the -ST2000 via a serial line. You can instead specify @var{dev} as a TCP -connection (for example, to a serial line attached via a terminal -concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}. - -The @code{load} and @code{attach} commands are @emph{not} defined for -this target; you must load your program into the ST2000 as you normally -would for standalone operation. @value{GDBN} reads debugging information -(such as symbols) from a separate, debugging version of the program -available on your host computer. -@c FIXME!! This is terribly vague; what little content is here is -@c basically hearsay. - -@cindex ST2000 auxiliary commands -These auxiliary @value{GDBN} commands are available to help you with the ST2000 -environment: - -@table @code -@item st2000 @var{command} -@kindex st2000 @var{cmd} -@cindex STDBUG commands (ST2000) -@cindex commands to STDBUG (ST2000) -Send a @var{command} to the STDBUG monitor. See the manufacturer's -manual for available commands. - -@item connect -@cindex connect (to STDBUG) -Connect the controlling terminal to the STDBUG command monitor. When -you are done interacting with STDBUG, typing either of two character -sequences gets you back to the @value{GDBN} command prompt: -@kbd{@key{RET}~.} (Return, followed by tilde and period) or -@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D). -@end table - -@node Z8000 -@subsection Zilog Z8000 - -@cindex Z8000 -@cindex simulator, Z8000 -@cindex Zilog Z8000 simulator - -When configured for debugging Zilog Z8000 targets, @value{GDBN} includes -a Z8000 simulator. - -For the Z8000 family, @samp{target sim} simulates either the Z8002 (the -unsegmented variant of the Z8000 architecture) or the Z8001 (the -segmented variant). The simulator recognizes which architecture is -appropriate by inspecting the object code. - -@table @code -@item target sim @var{args} -@kindex sim -@kindex target sim@r{, with Z8000} -Debug programs on a simulated CPU. If the simulator supports setup -options, specify them via @var{args}. -@end table - -@noindent -After specifying this target, you can debug programs for the simulated -CPU in the same style as programs for your host computer; use the -@code{file} command to load a new program image, the @code{run} command -to run your program, and so on. - -As well as making available all the usual machine registers -(@pxref{Registers, ,Registers}), the Z8000 simulator provides three -additional items of information as specially named registers: - -@table @code - -@item cycles -Counts clock-ticks in the simulator. - -@item insts -Counts instructions run in the simulator. - -@item time -Execution time in 60ths of a second. - -@end table - -You can refer to these values in @value{GDBN} expressions with the usual -conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a -conditional breakpoint that suspends only after at least 5000 -simulated clock ticks. - -@node Architectures -@section Architectures - -This section describes characteristics of architectures that affect -all uses of @value{GDBN} with the architecture, both native and cross. - -@menu -* A29K:: -* Alpha:: -* MIPS:: -@end menu - -@node A29K -@subsection A29K - -@table @code - -@kindex set rstack_high_address -@cindex AMD 29K register stack -@cindex register stack, AMD29K -@item set rstack_high_address @var{address} -On AMD 29000 family processors, registers are saved in a separate -@dfn{register stack}. There is no way for @value{GDBN} to determine the -extent of this stack. Normally, @value{GDBN} just assumes that the -stack is ``large enough''. This may result in @value{GDBN} 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 @code{set rstack_high_address} command. The argument should be an -address, which you probably want to precede with @samp{0x} to specify in -hexadecimal. - -@kindex show rstack_high_address -@item show rstack_high_address -Display the current limit of the register stack, on AMD 29000 family -processors. - -@end table - -@node Alpha -@subsection Alpha - -See the following section. - -@node MIPS -@subsection MIPS - -@cindex stack on Alpha -@cindex stack on MIPS -@cindex Alpha stack -@cindex MIPS stack -Alpha- and MIPS-based computers use an unusual stack frame, which -sometimes requires @value{GDBN} to search backward in the object code to -find the beginning of a function. - -@cindex response time, MIPS debugging -To improve response time (especially for embedded applications, where -@value{GDBN} may be restricted to a slow serial line for this search) -you may want to limit the size of this search, using one of these -commands: - -@table @code -@cindex @code{heuristic-fence-post} (Alpha, MIPS) -@item set heuristic-fence-post @var{limit} -Restrict @value{GDBN} to examining at most @var{limit} bytes in its -search for the beginning of a function. A value of @var{0} (the -default) means there is no limit. However, except for @var{0}, the -larger the limit the more bytes @code{heuristic-fence-post} must search -and therefore the longer it takes to run. - -@item show heuristic-fence-post -Display the current limit. -@end table - -@noindent -These commands are available @emph{only} when @value{GDBN} is configured -for debugging programs on Alpha or MIPS processors. - - -@node Controlling GDB -@chapter Controlling @value{GDBN} - -You can alter the way @value{GDBN} interacts with you by using the -@code{set} command. For commands controlling how @value{GDBN} displays -data, see @ref{Print Settings, ,Print settings}. Other settings are -described here. - -@menu -* Prompt:: Prompt -* Editing:: Command editing -* History:: Command history -* Screen Size:: Screen size -* Numbers:: Numbers -* ABI:: Configuring the current ABI -* Messages/Warnings:: Optional warnings and messages -* Debugging Output:: Optional messages about internal happenings -@end menu - -@node Prompt -@section Prompt - -@cindex prompt - -@value{GDBN} indicates its readiness to read a command by printing a string -called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You -can change the prompt string with the @code{set prompt} command. For -instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change -the prompt in one of the @value{GDBN} sessions so that you can always tell -which one you are talking to. - -@emph{Note:} @code{set prompt} does not add a space for you after the -prompt you set. This allows you to set a prompt which ends in a space -or a prompt that does not. - -@table @code -@kindex set prompt -@item set prompt @var{newprompt} -Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. - -@kindex show prompt -@item show prompt -Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} -@end table - -@node Editing -@section Command editing -@cindex readline -@cindex command line editing - -@value{GDBN} reads its input commands via the @dfn{readline} interface. This -@sc{gnu} library provides consistent behavior for programs which provide a -command line interface to the user. Advantages are @sc{gnu} Emacs-style -or @dfn{vi}-style inline editing of commands, @code{csh}-like history -substitution, and a storage and recall of command history across -debugging sessions. - -You may control the behavior of command line editing in @value{GDBN} with the -command @code{set}. - -@table @code -@kindex set editing -@cindex editing -@item set editing -@itemx set editing on -Enable command line editing (enabled by default). - -@item set editing off -Disable command line editing. - -@kindex show editing -@item show editing -Show whether command line editing is enabled. -@end table - -@node History -@section Command history - -@value{GDBN} can keep track of the commands you type during your -debugging sessions, so that you can be certain of precisely what -happened. Use these commands to manage the @value{GDBN} command -history facility. - -@table @code -@cindex history substitution -@cindex history file -@kindex set history filename -@kindex GDBHISTFILE -@item set history filename @var{fname} -Set the name of the @value{GDBN} command history file to @var{fname}. -This is the file where @value{GDBN} reads an initial command history -list, and where it writes the command history from this session when it -exits. You can access this list through history expansion or through -the history command editing characters listed below. This file defaults -to the value of the environment variable @code{GDBHISTFILE}, or to -@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable -is not set. - -@cindex history save -@kindex set history save -@item set history save -@itemx set history save on -Record command history in a file, whose name may be specified with the -@code{set history filename} command. By default, this option is disabled. - -@item set history save off -Stop recording command history in a file. - -@cindex history size -@kindex set history size -@item set history size @var{size} -Set the number of commands which @value{GDBN} keeps in its history list. -This defaults to the value of the environment variable -@code{HISTSIZE}, or to 256 if this variable is not set. -@end table - -@cindex history expansion -History expansion assigns special meaning to the character @kbd{!}. -@ifset have-readline-appendices -@xref{Event Designators}. -@end ifset - -Since @kbd{!} is also the logical not operator in C, history expansion -is off by default. If you decide to enable history expansion with the -@code{set history expansion on} command, you may sometimes need to -follow @kbd{!} (when it is used as logical not, in an expression) with -a space or a tab to prevent it from being expanded. The readline -history facilities do not attempt substitution on the strings -@kbd{!=} and @kbd{!(}, even when history expansion is enabled. - -The commands to control history expansion are: - -@table @code -@kindex set history expansion -@item set history expansion on -@itemx set history expansion -Enable history expansion. History expansion is off by default. - -@item set history expansion off -Disable history expansion. - -The readline code comes with more complete documentation of -editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs -or @code{vi} may wish to read it. -@ifset have-readline-appendices -@xref{Command Line Editing}. -@end ifset - -@c @group -@kindex show history -@item show history -@itemx show history filename -@itemx show history save -@itemx show history size -@itemx show history expansion -These commands display the state of the @value{GDBN} history parameters. -@code{show history} by itself displays all four states. -@c @end group -@end table - -@table @code -@kindex shows -@item show commands -Display the last ten commands in the command history. - -@item show commands @var{n} -Print ten commands centered on command number @var{n}. - -@item show commands + -Print ten commands just after the commands last printed. -@end table - -@node Screen Size -@section Screen size -@cindex size of screen -@cindex pauses in output - -Certain commands to @value{GDBN} may produce large amounts of -information output to the screen. To help you read all of it, -@value{GDBN} pauses and asks you for input at the end of each page of -output. Type @key{RET} when you want to continue the output, or @kbd{q} -to discard the remaining output. Also, the screen width setting -determines when to wrap lines of output. Depending on what is being -printed, @value{GDBN} tries to break the line at a readable place, -rather than simply letting it overflow onto the following line. - -Normally @value{GDBN} knows the size of the screen from the terminal -driver software. For example, on Unix @value{GDBN} uses the termcap data base -together with the value of the @code{TERM} environment variable and the -@code{stty rows} and @code{stty cols} settings. If this is not correct, -you can override it with the @code{set height} and @code{set -width} commands: - -@table @code -@kindex set height -@kindex set width -@kindex show width -@kindex show height -@item set height @var{lpp} -@itemx show height -@itemx set width @var{cpl} -@itemx show width -These @code{set} commands specify a screen height of @var{lpp} lines and -a screen width of @var{cpl} characters. The associated @code{show} -commands display the current settings. - -If you specify a height of zero lines, @value{GDBN} does not pause during -output no matter how long the output is. This is useful if output is to a -file or to an editor buffer. - -Likewise, you can specify @samp{set width 0} to prevent @value{GDBN} -from wrapping its output. -@end table - -@node Numbers -@section Numbers -@cindex number representation -@cindex entering numbers - -You can always enter numbers in octal, decimal, or hexadecimal in -@value{GDBN} by the usual conventions: octal numbers begin with -@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers -begin with @samp{0x}. Numbers that begin with none of these are, by -default, entered in base 10; likewise, the default display for -numbers---when no particular format is specified---is base 10. You can -change the default base for both input and output with the @code{set -radix} command. - -@table @code -@kindex set input-radix -@item set input-radix @var{base} -Set the default base for numeric input. Supported choices -for @var{base} are decimal 8, 10, or 16. @var{base} must itself be -specified either unambiguously or using the current default radix; for -example, any of - -@smallexample -set radix 012 -set radix 10. -set radix 0xa -@end smallexample - -@noindent -sets the base to decimal. On the other hand, @samp{set radix 10} -leaves the radix unchanged no matter what it was. - -@kindex set output-radix -@item set output-radix @var{base} -Set the default base for numeric display. Supported choices -for @var{base} are decimal 8, 10, or 16. @var{base} must itself be -specified either unambiguously or using the current default radix. - -@kindex show input-radix -@item show input-radix -Display the current default base for numeric input. - -@kindex show output-radix -@item show output-radix -Display the current default base for numeric display. -@end table - -@node ABI -@section Configuring the current ABI - -@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your -application automatically. However, sometimes you need to override its -conclusions. Use these commands to manage @value{GDBN}'s view of the -current ABI. - -@cindex OS ABI -@kindex set osabi -@kindex show osabi - -One @value{GDBN} configuration can debug binaries for multiple operating -system targets, either via remote debugging or native emulation. -@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, -but you can override its conclusion using the @code{set osabi} command. -One example where this is useful is in debugging of binaries which use -an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does -not have the same identifying marks that the standard C library for your -platform provides. - -@table @code -@item show osabi -Show the OS ABI currently in use. - -@item set osabi -With no argument, show the list of registered available OS ABI's. - -@item set osabi @var{abi} -Set the current OS ABI to @var{abi}. -@end table - -@cindex float promotion -@kindex set coerce-float-to-double - -Generally, the way that an argument of type @code{float} is passed to a -function depends on whether the function is prototyped. For a prototyped -(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged, -according to the architecture's convention for @code{float}. For unprototyped -(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type -@code{double} and then passed. - -Unfortunately, some forms of debug information do not reliably indicate whether -a function is prototyped. If @value{GDBN} calls a function that is not marked -as prototyped, it consults @kbd{set coerce-float-to-double}. - -@table @code -@item set coerce-float-to-double -@itemx set coerce-float-to-double on -Arguments of type @code{float} will be promoted to @code{double} when passed -to an unprototyped function. This is the default setting. - -@item set coerce-float-to-double off -Arguments of type @code{float} will be passed directly to unprototyped -functions. -@end table - -@kindex set cp-abi -@kindex show cp-abi -@value{GDBN} needs to know the ABI used for your program's C@t{++} -objects. The correct C@t{++} ABI depends on which C@t{++} compiler was -used to build your application. @value{GDBN} only fully supports -programs with a single C@t{++} ABI; if your program contains code using -multiple C@t{++} ABI's or if @value{GDBN} can not identify your -program's ABI correctly, you can tell @value{GDBN} which ABI to use. -Currently supported ABI's include ``gnu-v2'', for @code{g++} versions -before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and -``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may -use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is -``auto''. - -@table @code -@item show cp-abi -Show the C@t{++} ABI currently in use. - -@item set cp-abi -With no argument, show the list of supported C@t{++} ABI's. - -@item set cp-abi @var{abi} -@itemx set cp-abi auto -Set the current C@t{++} ABI to @var{abi}, or return to automatic detection. -@end table - -@node Messages/Warnings -@section Optional warnings and messages - -By default, @value{GDBN} is silent about its inner workings. If you are -running on a slow machine, you may want to use the @code{set verbose} -command. This makes @value{GDBN} tell you when it does a lengthy -internal operation, so you will not think it has crashed. - -Currently, the messages controlled by @code{set verbose} are those -which announce that the symbol table for a source file is being read; -see @code{symbol-file} in @ref{Files, ,Commands to specify files}. - -@table @code -@kindex set verbose -@item set verbose on -Enables @value{GDBN} output of certain informational messages. - -@item set verbose off -Disables @value{GDBN} output of certain informational messages. - -@kindex show verbose -@item show verbose -Displays whether @code{set verbose} is on or off. -@end table - -By default, if @value{GDBN} encounters bugs in the symbol table of an -object file, it is silent; but if you are debugging a compiler, you may -find this information useful (@pxref{Symbol Errors, ,Errors reading -symbol files}). - -@table @code - -@kindex set complaints -@item set complaints @var{limit} -Permits @value{GDBN} to output @var{limit} complaints about each type of -unusual symbols before becoming silent about the problem. Set -@var{limit} to zero to suppress all complaints; set it to a large number -to prevent complaints from being suppressed. - -@kindex show complaints -@item show complaints -Displays how many symbol complaints @value{GDBN} is permitted to produce. - -@end table - -By default, @value{GDBN} is cautious, and asks what sometimes seems to be a -lot of stupid questions to confirm certain commands. For example, if -you try to run a program which is already running: - -@smallexample -(@value{GDBP}) run -The program being debugged has been started already. -Start it from the beginning? (y or n) -@end smallexample - -If you are willing to unflinchingly face the consequences of your own -commands, you can disable this ``feature'': - -@table @code - -@kindex set confirm -@cindex flinching -@cindex confirmation -@cindex stupid questions -@item set confirm off -Disables confirmation requests. - -@item set confirm on -Enables confirmation requests (the default). - -@kindex show confirm -@item show confirm -Displays state of confirmation requests. - -@end table - -@node Debugging Output -@section Optional messages about internal happenings -@table @code -@kindex set debug arch -@item set debug arch -Turns on or off display of gdbarch debugging info. The default is off -@kindex show debug arch -@item show debug arch -Displays the current state of displaying gdbarch debugging info. -@kindex set debug event -@item set debug event -Turns on or off display of @value{GDBN} event debugging info. The -default is off. -@kindex show debug event -@item show debug event -Displays the current state of displaying @value{GDBN} event debugging -info. -@kindex set debug expression -@item set debug expression -Turns on or off display of @value{GDBN} expression debugging info. The -default is off. -@kindex show debug expression -@item show debug expression -Displays the current state of displaying @value{GDBN} expression -debugging info. -@kindex set debug frame -@item set debug frame -Turns on or off display of @value{GDBN} frame debugging info. The -default is off. -@kindex show debug frame -@item show debug frame -Displays the current state of displaying @value{GDBN} frame debugging -info. -@kindex set debug overload -@item set debug overload -Turns on or off display of @value{GDBN} C@t{++} overload debugging -info. This includes info such as ranking of functions, etc. The default -is off. -@kindex show debug overload -@item show debug overload -Displays the current state of displaying @value{GDBN} C@t{++} overload -debugging info. -@kindex set debug remote -@cindex packets, reporting on stdout -@cindex serial connections, debugging -@item set debug remote -Turns on or off display of reports on all packets sent back and forth across -the serial line to the remote machine. The info is printed on the -@value{GDBN} standard output stream. The default is off. -@kindex show debug remote -@item show debug remote -Displays the state of display of remote packets. -@kindex set debug serial -@item set debug serial -Turns on or off display of @value{GDBN} serial debugging info. The -default is off. -@kindex show debug serial -@item show debug serial -Displays the current state of displaying @value{GDBN} serial debugging -info. -@kindex set debug target -@item set debug target -Turns on or off display of @value{GDBN} target debugging info. This info -includes what is going on at the target level of GDB, as it happens. The -default is off. -@kindex show debug target -@item show debug target -Displays the current state of displaying @value{GDBN} target debugging -info. -@kindex set debug varobj -@item set debug varobj -Turns on or off display of @value{GDBN} variable object debugging -info. The default is off. -@kindex show debug varobj -@item show debug varobj -Displays the current state of displaying @value{GDBN} variable object -debugging info. -@end table - -@node Sequences -@chapter Canned Sequences of Commands - -Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint -command lists}), @value{GDBN} provides two ways to store sequences of -commands for execution as a unit: user-defined commands and command -files. - -@menu -* Define:: User-defined commands -* Hooks:: User-defined command hooks -* Command Files:: Command files -* Output:: Commands for controlled output -@end menu - -@node Define -@section User-defined commands - -@cindex user-defined command -A @dfn{user-defined command} is a sequence of @value{GDBN} commands to -which you assign a new name as a command. This is done with the -@code{define} command. User commands may accept up to 10 arguments -separated by whitespace. Arguments are accessed within the user command -via @var{$arg0@dots{}$arg9}. A trivial example: - -@smallexample -define adder - print $arg0 + $arg1 + $arg2 -@end smallexample - -@noindent -To execute the command use: - -@smallexample -adder 1 2 3 -@end smallexample - -@noindent -This defines the command @code{adder}, which prints the sum of -its three arguments. Note the arguments are text substitutions, so they may -reference variables, use complex expressions, or even perform inferior -functions calls. - -@table @code - -@kindex define -@item define @var{commandname} -Define a command named @var{commandname}. If there is already a command -by that name, you are asked to confirm that you want to redefine it. - -The definition of the command is made up of other @value{GDBN} command lines, -which are given following the @code{define} command. The end of these -commands is marked by a line containing @code{end}. - -@kindex if -@kindex else -@item if -Takes a single argument, which is an expression to evaluate. -It is followed by a series of commands that are executed -only if the expression is true (nonzero). -There can then optionally be a line @code{else}, followed -by a series of commands that are only executed if the expression -was false. The end of the list is marked by a line containing @code{end}. - -@kindex while -@item while -The syntax is similar to @code{if}: the command takes a single argument, -which is an expression to evaluate, and must be followed by the commands to -execute, one per line, terminated by an @code{end}. -The commands are executed repeatedly as long as the expression -evaluates to true. - -@kindex document -@item document @var{commandname} -Document the user-defined command @var{commandname}, so that it can be -accessed by @code{help}. The command @var{commandname} must already be -defined. This command reads lines of documentation just as @code{define} -reads the lines of the command definition, ending with @code{end}. -After the @code{document} command is finished, @code{help} on command -@var{commandname} displays the documentation you have written. - -You may use the @code{document} command again to change the -documentation of a command. Redefining the command with @code{define} -does not change the documentation. - -@kindex help user-defined -@item help user-defined -List all user-defined commands, with the first line of the documentation -(if any) for each. - -@kindex show user -@item show user -@itemx show user @var{commandname} -Display the @value{GDBN} commands used to define @var{commandname} (but -not its documentation). If no @var{commandname} is given, display the -definitions for all user-defined commands. - -@kindex show max-user-call-depth -@kindex set max-user-call-depth -@item show max-user-call-depth -@itemx set max-user-call-depth -The value of @code{max-user-call-depth} controls how many recursion -levels are allowed in user-defined commands before GDB suspects an -infinite recursion and aborts the command. - -@end table - -When user-defined commands are executed, the -commands of the definition are not printed. An error in any command -stops execution of the user-defined command. - -If used interactively, commands that would ask for confirmation proceed -without asking when used inside a user-defined command. Many @value{GDBN} -commands that normally print messages to say what they are doing omit the -messages when used in a user-defined command. - -@node Hooks -@section User-defined command hooks -@cindex command hooks -@cindex hooks, for commands -@cindex hooks, pre-command - -@kindex hook -@kindex hook- -You may define @dfn{hooks}, which are a special kind of user-defined -command. Whenever you run the command @samp{foo}, if the user-defined -command @samp{hook-foo} exists, it is executed (with no arguments) -before that command. - -@cindex hooks, post-command -@kindex hookpost -@kindex hookpost- -A hook may also be defined which is run after the command you executed. -Whenever you run the command @samp{foo}, if the user-defined command -@samp{hookpost-foo} exists, it is executed (with no arguments) after -that command. Post-execution hooks may exist simultaneously with -pre-execution hooks, for the same command. - -It is valid for a hook to call the command which it hooks. If this -occurs, the hook is not re-executed, thereby avoiding infinte recursion. - -@c It would be nice if hookpost could be passed a parameter indicating -@c if the command it hooks executed properly or not. FIXME! - -@kindex stop@r{, a pseudo-command} -In addition, a pseudo-command, @samp{stop} exists. Defining -(@samp{hook-stop}) makes the associated commands execute every time -execution stops in your program: before breakpoint commands are run, -displays are printed, or the stack frame is printed. - -For example, to ignore @code{SIGALRM} signals while -single-stepping, but treat them normally during normal execution, -you could define: - -@smallexample -define hook-stop -handle SIGALRM nopass -end - -define hook-run -handle SIGALRM pass -end - -define hook-continue -handle SIGLARM pass -end -@end smallexample - -As a further example, to hook at the begining and end of the @code{echo} -command, and to add extra text to the beginning and end of the message, -you could define: - -@smallexample -define hook-echo -echo <<<--- -end - -define hookpost-echo -echo --->>>\n -end - -(@value{GDBP}) echo Hello World -<<<---Hello World--->>> -(@value{GDBP}) - -@end smallexample - -You can define a hook for any single-word command in @value{GDBN}, but -not for command aliases; you should define a hook for the basic command -name, e.g. @code{backtrace} rather than @code{bt}. -@c FIXME! So how does Joe User discover whether a command is an alias -@c or not? -If an error occurs during the execution of your hook, execution of -@value{GDBN} commands stops and @value{GDBN} issues a prompt -(before the command that you actually typed had a chance to run). - -If you try to define a hook which does not match any known command, you -get a warning from the @code{define} command. - -@node Command Files -@section Command files - -@cindex command files -A command file for @value{GDBN} is a file of lines that are @value{GDBN} -commands. Comments (lines starting with @kbd{#}) may also be included. -An empty line in a command file does nothing; it does not mean to repeat -the last command, as it would from the terminal. - -@cindex init file -@cindex @file{.gdbinit} -@cindex @file{gdb.ini} -When you start @value{GDBN}, it automatically executes commands from its -@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP -port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the -limitations of file names imposed by DOS filesystems.}. -During startup, @value{GDBN} does the following: - -@enumerate -@item -Reads the init file (if any) in your home directory@footnote{On -DOS/Windows systems, the home directory is the one pointed to by the -@code{HOME} environment variable.}. - -@item -Processes command line options and operands. - -@item -Reads the init file (if any) in the current working directory. - -@item -Reads command files specified by the @samp{-x} option. -@end enumerate - -The init file in your home directory can set options (such as @samp{set -complaints}) that affect subsequent processing of command line options -and operands. Init files are not executed if you use the @samp{-nx} -option (@pxref{Mode Options, ,Choosing modes}). - -@cindex init file name -On some configurations of @value{GDBN}, the init file is known by a -different name (these are typically environments where a specialized -form of @value{GDBN} may need to coexist with other forms, hence a -different name for the specialized version's init file). These are the -environments with special init file names: - -@cindex @file{.vxgdbinit} -@itemize @bullet -@item -VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit} - -@cindex @file{.os68gdbinit} -@item -OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit} - -@cindex @file{.esgdbinit} -@item -ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit} -@end itemize - -You can also request the execution of a command file with the -@code{source} command: - -@table @code -@kindex source -@item source @var{filename} -Execute the command file @var{filename}. -@end table - -The lines in a command file are executed sequentially. They are not -printed as they are executed. An error in any command terminates -execution of the command file and control is returned to the console. - -Commands that would ask for confirmation if used interactively proceed -without asking when used in a command file. Many @value{GDBN} commands that -normally print messages to say what they are doing omit the messages -when called from command files. - -@value{GDBN} also accepts command input from standard input. In this -mode, normal output goes to standard output and error output goes to -standard error. Errors in a command file supplied on standard input do -not terminate execution of the command file --- execution continues with -the next command. - -@smallexample -gdb < cmds > log 2>&1 -@end smallexample - -(The syntax above will vary depending on the shell used.) This example -will execute commands from the file @file{cmds}. All output and errors -would be directed to @file{log}. - -@node Output -@section Commands for controlled output - -During the execution of a command file or a user-defined command, normal -@value{GDBN} output is suppressed; the only output that appears is what is -explicitly printed by the commands in the definition. This section -describes three commands useful for generating exactly the output you -want. - -@table @code -@kindex echo -@item echo @var{text} -@c I do not consider backslash-space a standard C escape sequence -@c because it is not in ANSI. -Print @var{text}. Nonprinting characters can be included in -@var{text} using C escape sequences, such as @samp{\n} to print a -newline. @strong{No newline is printed unless you specify one.} -In addition to the standard C escape sequences, a backslash followed -by a space stands for a space. This is useful for displaying a -string with spaces at the beginning or the end, since leading and -trailing spaces are otherwise trimmed from all arguments. -To print @samp{@w{ }and foo =@w{ }}, use the command -@samp{echo \@w{ }and foo = \@w{ }}. - -A backslash at the end of @var{text} can be used, as in C, to continue -the command onto subsequent lines. For example, - -@smallexample -echo This is some text\n\ -which is continued\n\ -onto several lines.\n -@end smallexample - -produces the same output as - -@smallexample -echo This is some text\n -echo which is continued\n -echo onto several lines.\n -@end smallexample - -@kindex output -@item output @var{expression} -Print the value of @var{expression} and nothing but that value: no -newlines, no @samp{$@var{nn} = }. The value is not entered in the -value history either. @xref{Expressions, ,Expressions}, for more information -on expressions. - -@item output/@var{fmt} @var{expression} -Print the value of @var{expression} in format @var{fmt}. You can use -the same formats as for @code{print}. @xref{Output Formats,,Output -formats}, for more information. - -@kindex printf -@item printf @var{string}, @var{expressions}@dots{} -Print the values of the @var{expressions} under the control of -@var{string}. The @var{expressions} are separated by commas and may be -either numbers or pointers. Their values are printed as specified by -@var{string}, exactly as if your program were to execute the C -subroutine -@c FIXME: the above implies that at least all ANSI C formats are -@c supported, but it isn't true: %E and %G don't work (or so it seems). -@c Either this is a bug, or the manual should document what formats are -@c supported. - -@smallexample -printf (@var{string}, @var{expressions}@dots{}); -@end smallexample - -For example, you can print two values in hex like this: - -@smallexample -printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo -@end smallexample - -The only backslash-escape sequences that you can use in the format -string are the simple ones that consist of backslash followed by a -letter. -@end table - -@node Interpreters -@chapter Command Interpreters -@cindex command interpreters - -@value{GDBN} supports multiple command interpreters, and some command -infrastructure to allow users or user interface writers to switch -between interpreters or run commands in other interpreters. - -@value{GDBN} currently supports two command interpreters, the console -interpreter (sometimes called the command-line interpreter or @sc{cli}) -and the machine interface interpreter (or @sc{gdb/mi}). This manual -describes both of these interfaces in great detail. - -By default, @value{GDBN} will start with the console interpreter. -However, the user may choose to start @value{GDBN} with another -interpreter by specifying the @option{-i} or @option{--interpreter} -startup options. Defined interpreters include: - -@table @code -@item console -@cindex console interpreter -The traditional console or command-line interpreter. This is the most often -used interpreter with @value{GDBN}. With no interpreter specified at runtime, -@value{GDBN} will use this interpreter. - -@item mi -@cindex mi interpreter -The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily -by programs wishing to use @value{GDBN} as a backend for a debugger GUI -or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi} -Interface}. - -@item mi2 -@cindex mi2 interpreter -The current @sc{gdb/mi} interface. - -@item mi1 -@cindex mi1 interpreter -The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3. - -@end table - -@cindex invoke another interpreter -The interpreter being used by @value{GDBN} may not be dynamically -switched at runtime. Although possible, this could lead to a very -precarious situation. Consider an IDE using @sc{gdb/mi}. If a user -enters the command "interpreter-set console" in a console view, -@value{GDBN} would switch to using the console interpreter, rendering -the IDE inoperable! - -@kindex interpreter-exec -Although you may only choose a single interpreter at startup, you may execute -commands in any interpreter from the current interpreter using the appropriate -command. If you are running the console interpreter, simply use the -@code{interpreter-exec} command: - -@smallexample -interpreter-exec mi "-data-list-register-names" -@end smallexample - -@sc{gdb/mi} has a similar command, although it is only available in versions of -@value{GDBN} which support @sc{gdb/mi} version 2 (or greater). - -@node TUI -@chapter @value{GDBN} Text User Interface -@cindex TUI -@cindex Text User Interface - -@menu -* TUI Overview:: TUI overview -* TUI Keys:: TUI key bindings -* TUI Single Key Mode:: TUI single key mode -* TUI Commands:: TUI specific commands -* TUI Configuration:: TUI configuration variables -@end menu - -The @value{GDBN} Text User Interface, TUI in short, is a terminal -interface which uses the @code{curses} library to show the source -file, the assembly output, the program registers and @value{GDBN} -commands in separate text windows. - -The TUI is enabled by invoking @value{GDBN} using either -@pindex gdbtui -@samp{gdbtui} or @samp{gdb -tui}. - -@node TUI Overview -@section TUI overview - -The TUI has two display modes that can be switched while -@value{GDBN} runs: - -@itemize @bullet -@item -A curses (or TUI) mode in which it displays several text -windows on the terminal. - -@item -A standard mode which corresponds to the @value{GDBN} configured without -the TUI. -@end itemize - -In the TUI mode, @value{GDBN} can display several text window -on the terminal: - -@table @emph -@item command -This window is the @value{GDBN} command window with the @value{GDBN} -prompt and the @value{GDBN} outputs. The @value{GDBN} input is still -managed using readline but through the TUI. The @emph{command} -window is always visible. - -@item source -The source window shows the source file of the program. The current -line as well as active breakpoints are displayed in this window. - -@item assembly -The assembly window shows the disassembly output of the program. - -@item register -This window shows the processor registers. It detects when -a register is changed and when this is the case, registers that have -changed are highlighted. - -@end table - -The source and assembly windows show the current program position -by highlighting the current line and marking them with the @samp{>} marker. -Breakpoints are also indicated with two markers. A first one -indicates the breakpoint type: - -@table @code -@item B -Breakpoint which was hit at least once. - -@item b -Breakpoint which was never hit. - -@item H -Hardware breakpoint which was hit at least once. - -@item h -Hardware breakpoint which was never hit. - -@end table - -The second marker indicates whether the breakpoint is enabled or not: - -@table @code -@item + -Breakpoint is enabled. - -@item - -Breakpoint is disabled. - -@end table - -The source, assembly and register windows are attached to the thread -and the frame position. They are updated when the current thread -changes, when the frame changes or when the program counter changes. -These three windows are arranged by the TUI according to several -layouts. The layout defines which of these three windows are visible. -The following layouts are available: - -@itemize @bullet -@item -source - -@item -assembly - -@item -source and assembly - -@item -source and registers - -@item -assembly and registers - -@end itemize - -On top of the command window a status line gives various information -concerning the current process begin debugged. The status line is -updated when the information it shows changes. The following fields -are displayed: - -@table @emph -@item target -Indicates the current gdb target -(@pxref{Targets, ,Specifying a Debugging Target}). - -@item process -Gives information about the current process or thread number. -When no process is being debugged, this field is set to @code{No process}. - -@item function -Gives the current function name for the selected frame. -The name is demangled if demangling is turned on (@pxref{Print Settings}). -When there is no symbol corresponding to the current program counter -the string @code{??} is displayed. - -@item line -Indicates the current line number for the selected frame. -When the current line number is not known the string @code{??} is displayed. - -@item pc -Indicates the current program counter address. - -@end table - -@node TUI Keys -@section TUI Key Bindings -@cindex TUI key bindings - -The TUI installs several key bindings in the readline keymaps -(@pxref{Command Line Editing}). -They allow to leave or enter in the TUI mode or they operate -directly on the TUI layout and windows. The TUI also provides -a @emph{SingleKey} keymap which binds several keys directly to -@value{GDBN} commands. The following key bindings -are installed for both TUI mode and the @value{GDBN} standard mode. - -@table @kbd -@kindex C-x C-a -@item C-x C-a -@kindex C-x a -@itemx C-x a -@kindex C-x A -@itemx C-x A -Enter or leave the TUI mode. When the TUI mode is left, -the curses window management is left and @value{GDBN} operates using -its standard mode writing on the terminal directly. When the TUI -mode is entered, the control is given back to the curses windows. -The screen is then refreshed. - -@kindex C-x 1 -@item C-x 1 -Use a TUI layout with only one window. The layout will -either be @samp{source} or @samp{assembly}. When the TUI mode -is not active, it will switch to the TUI mode. - -Think of this key binding as the Emacs @kbd{C-x 1} binding. - -@kindex C-x 2 -@item C-x 2 -Use a TUI layout with at least two windows. When the current -layout shows already two windows, a next layout with two windows is used. -When a new layout is chosen, one window will always be common to the -previous layout and the new one. - -Think of it as the Emacs @kbd{C-x 2} binding. - -@kindex C-x o -@item C-x o -Change the active window. The TUI associates several key bindings -(like scrolling and arrow keys) to the active window. This command -gives the focus to the next TUI window. - -Think of it as the Emacs @kbd{C-x o} binding. - -@kindex C-x s -@item C-x s -Use the TUI @emph{SingleKey} keymap that binds single key to gdb commands -(@pxref{TUI Single Key Mode}). - -@end table - -The following key bindings are handled only by the TUI mode: - -@table @key -@kindex PgUp -@item PgUp -Scroll the active window one page up. - -@kindex PgDn -@item PgDn -Scroll the active window one page down. - -@kindex Up -@item Up -Scroll the active window one line up. - -@kindex Down -@item Down -Scroll the active window one line down. - -@kindex Left -@item Left -Scroll the active window one column left. - -@kindex Right -@item Right -Scroll the active window one column right. - -@kindex C-L -@item C-L -Refresh the screen. - -@end table - -In the TUI mode, the arrow keys are used by the active window -for scrolling. This means they are available for readline when the -active window is the command window. When the command window -does not have the focus, it is necessary to use other readline -key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}. - -@node TUI Single Key Mode -@section TUI Single Key Mode -@cindex TUI single key mode - -The TUI provides a @emph{SingleKey} mode in which it installs a particular -key binding in the readline keymaps to connect single keys to -some gdb commands. - -@table @kbd -@kindex c @r{(SingleKey TUI key)} -@item c -continue - -@kindex d @r{(SingleKey TUI key)} -@item d -down - -@kindex f @r{(SingleKey TUI key)} -@item f -finish - -@kindex n @r{(SingleKey TUI key)} -@item n -next - -@kindex q @r{(SingleKey TUI key)} -@item q -exit the @emph{SingleKey} mode. - -@kindex r @r{(SingleKey TUI key)} -@item r -run - -@kindex s @r{(SingleKey TUI key)} -@item s -step - -@kindex u @r{(SingleKey TUI key)} -@item u -up - -@kindex v @r{(SingleKey TUI key)} -@item v -info locals - -@kindex w @r{(SingleKey TUI key)} -@item w -where - -@end table - -Other keys temporarily switch to the @value{GDBN} command prompt. -The key that was pressed is inserted in the editing buffer so that -it is possible to type most @value{GDBN} commands without interaction -with the TUI @emph{SingleKey} mode. Once the command is entered the TUI -@emph{SingleKey} mode is restored. The only way to permanently leave -this mode is by hitting @key{q} or @samp{@key{C-x} @key{s}}. - - -@node TUI Commands -@section TUI specific commands -@cindex TUI commands - -The TUI has specific commands to control the text windows. -These commands are always available, that is they do not depend on -the current terminal mode in which @value{GDBN} runs. When @value{GDBN} -is in the standard mode, using these commands will automatically switch -in the TUI mode. - -@table @code -@item info win -@kindex info win -List and give the size of all displayed windows. - -@item layout next -@kindex layout next -Display the next layout. - -@item layout prev -@kindex layout prev -Display the previous layout. - -@item layout src -@kindex layout src -Display the source window only. - -@item layout asm -@kindex layout asm -Display the assembly window only. - -@item layout split -@kindex layout split -Display the source and assembly window. - -@item layout regs -@kindex layout regs -Display the register window together with the source or assembly window. - -@item focus next | prev | src | asm | regs | split -@kindex focus -Set the focus to the named window. -This command allows to change the active window so that scrolling keys -can be affected to another window. - -@item refresh -@kindex refresh -Refresh the screen. This is similar to using @key{C-L} key. - -@item tui reg float -@kindex tui reg -Show the floating point registers in the register window. - -@item tui reg general -Show the general registers in the register window. - -@item tui reg next -Show the next register group. The list of register groups as well as -their order is target specific. The predefined register groups are the -following: @code{general}, @code{float}, @code{system}, @code{vector}, -@code{all}, @code{save}, @code{restore}. - -@item tui reg system -Show the system registers in the register window. - -@item update -@kindex update -Update the source window and the current execution point. - -@item winheight @var{name} +@var{count} -@itemx winheight @var{name} -@var{count} -@kindex winheight -Change the height of the window @var{name} by @var{count} -lines. Positive counts increase the height, while negative counts -decrease it. - -@end table - -@node TUI Configuration -@section TUI configuration variables -@cindex TUI configuration variables - -The TUI has several configuration variables that control the -appearance of windows on the terminal. - -@table @code -@item set tui border-kind @var{kind} -@kindex set tui border-kind -Select the border appearance for the source, assembly and register windows. -The possible values are the following: -@table @code -@item space -Use a space character to draw the border. - -@item ascii -Use ascii characters + - and | to draw the border. - -@item acs -Use the Alternate Character Set to draw the border. The border is -drawn using character line graphics if the terminal supports them. - -@end table - -@item set tui active-border-mode @var{mode} -@kindex set tui active-border-mode -Select the attributes to display the border of the active window. -The possible values are @code{normal}, @code{standout}, @code{reverse}, -@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}. - -@item set tui border-mode @var{mode} -@kindex set tui border-mode -Select the attributes to display the border of other windows. -The @var{mode} can be one of the following: -@table @code -@item normal -Use normal attributes to display the border. - -@item standout -Use standout mode. - -@item reverse -Use reverse video mode. - -@item half -Use half bright mode. - -@item half-standout -Use half bright and standout mode. - -@item bold -Use extra bright or bold mode. - -@item bold-standout -Use extra bright or bold and standout mode. - -@end table - -@end table - -@node Emacs -@chapter Using @value{GDBN} under @sc{gnu} Emacs - -@cindex Emacs -@cindex @sc{gnu} Emacs -A special interface allows you to use @sc{gnu} Emacs to view (and -edit) the source files for the program you are debugging with -@value{GDBN}. - -To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the -executable file you want to debug as an argument. This command starts -@value{GDBN} as a subprocess of Emacs, with input and output through a newly -created Emacs buffer. -@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) - -Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two -things: - -@itemize @bullet -@item -All ``terminal'' input and output goes through the Emacs buffer. -@end itemize - -This applies both to @value{GDBN} commands and their output, and to the input -and output done by the program you are debugging. - -This is useful because it means that you can copy the text of previous -commands and input them again; you can even use parts of the output -in this way. - -All the facilities of Emacs' Shell mode are available for interacting -with your program. In particular, you can send signals the usual -way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a -stop. - -@itemize @bullet -@item -@value{GDBN} displays source code through Emacs. -@end itemize - -Each time @value{GDBN} displays a stack frame, Emacs automatically finds the -source file for that frame and puts an arrow (@samp{=>}) at the -left margin of the current line. Emacs uses a separate buffer for -source display, and splits the screen to show both your @value{GDBN} session -and the source. - -Explicit @value{GDBN} @code{list} or search commands still produce output as -usual, but you probably have no reason to use them from Emacs. - -If you specify an absolute file name when prompted for the @kbd{M-x -gdb} argument, then Emacs sets your current working directory to where -your program resides. If you only specify the file name, then Emacs -sets your current working directory to to the directory associated -with the previous buffer. In this case, @value{GDBN} may find your -program by searching your environment's @code{PATH} variable, but on -some operating systems it might not find the source. So, although the -@value{GDBN} input and output session proceeds normally, the auxiliary -buffer does not display the current source and line of execution. - -The initial working directory of @value{GDBN} is printed on the top -line of the @value{GDBN} I/O buffer and this serves as a default for -the commands that specify files for @value{GDBN} to operate -on. @xref{Files, ,Commands to specify files}. - -By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you -need to call @value{GDBN} by a different name (for example, if you -keep several configurations around, with different names) you can -customize the Emacs variable @code{gud-gdb-command-name} to run the -one you want. - -In the @value{GDBN} I/O buffer, you can use these special Emacs commands in -addition to the standard Shell mode commands: - -@table @kbd -@item C-h m -Describe the features of Emacs' @value{GDBN} Mode. - -@item C-c C-s -Execute to another source line, like the @value{GDBN} @code{step} command; also -update the display window to show the current file and location. - -@item C-c C-n -Execute to next source line in this function, skipping all function -calls, like the @value{GDBN} @code{next} command. Then update the display window -to show the current file and location. - -@item C-c C-i -Execute one instruction, like the @value{GDBN} @code{stepi} command; update -display window accordingly. - -@item C-c C-f -Execute until exit from the selected stack frame, like the @value{GDBN} -@code{finish} command. - -@item C-c C-r -Continue execution of your program, like the @value{GDBN} @code{continue} -command. - -@item C-c < -Go up the number of frames indicated by the numeric argument -(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), -like the @value{GDBN} @code{up} command. - -@item C-c > -Go down the number of frames indicated by the numeric argument, like the -@value{GDBN} @code{down} command. -@end table - -In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break}) -tells @value{GDBN} to set a breakpoint on the source line point is on. - -If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which -shows a backtrace when the @value{GDBN} I/O buffer is current. Move -point to any frame in the stack and type @key{RET} to make it become the -current frame and display the associated source in the source buffer. -Alternatively, click @kbd{Mouse-2} to make the selected frame become the -current one. - -If you accidentally delete the source-display buffer, an easy way to get -it back is to type the command @code{f} in the @value{GDBN} buffer, to -request a frame display; when you run under Emacs, this recreates -the source buffer if necessary to show you the context of the current -frame. - -The source files displayed in Emacs are in ordinary Emacs buffers -which are visiting the source files in the usual way. You can edit -the files with these buffers if you wish; but keep in mind that @value{GDBN} -communicates with Emacs in terms of line numbers. If you add or -delete lines from the text, the line numbers that @value{GDBN} knows cease -to correspond properly with the code. - -The description given here is for GNU Emacs version 21.3 and a more -detailed description of its interaction with @value{GDBN} is given in -the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}). - -@c The following dropped because Epoch is nonstandard. Reactivate -@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990 -@ignore -@kindex Emacs Epoch environment -@kindex Epoch -@kindex inspect - -Version 18 of @sc{gnu} Emacs has a built-in window system -called the @code{epoch} -environment. Users of this environment can use a new command, -@code{inspect} which performs identically to @code{print} except that -each value is printed in its own window. -@end ignore - - -@node GDB/MI -@chapter The @sc{gdb/mi} Interface - -@unnumberedsec Function and Purpose - -@cindex @sc{gdb/mi}, its purpose -@sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is -specifically intended to support the development of systems which use -the debugger as just one small component of a larger system. - -This chapter is a specification of the @sc{gdb/mi} interface. It is written -in the form of a reference manual. - -Note that @sc{gdb/mi} is still under construction, so some of the -features described below are incomplete and subject to change. - -@unnumberedsec Notation and Terminology - -@cindex notational conventions, for @sc{gdb/mi} -This chapter uses the following notation: - -@itemize @bullet -@item -@code{|} separates two alternatives. - -@item -@code{[ @var{something} ]} indicates that @var{something} is optional: -it may or may not be given. - -@item -@code{( @var{group} )*} means that @var{group} inside the parentheses -may repeat zero or more times. - -@item -@code{( @var{group} )+} means that @var{group} inside the parentheses -may repeat one or more times. - -@item -@code{"@var{string}"} means a literal @var{string}. -@end itemize - -@ignore -@heading Dependencies -@end ignore - -@heading Acknowledgments - -In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and -Elena Zannoni. - -@menu -* GDB/MI Command Syntax:: -* GDB/MI Compatibility with CLI:: -* GDB/MI Output Records:: -* GDB/MI Command Description Format:: -* GDB/MI Breakpoint Table Commands:: -* GDB/MI Data Manipulation:: -* GDB/MI Program Control:: -* GDB/MI Miscellaneous Commands:: -@ignore -* GDB/MI Kod Commands:: -* GDB/MI Memory Overlay Commands:: -* GDB/MI Signal Handling Commands:: -@end ignore -* GDB/MI Stack Manipulation:: -* GDB/MI Symbol Query:: -* GDB/MI Target Manipulation:: -* GDB/MI Thread Commands:: -* GDB/MI Tracepoint Commands:: -* GDB/MI Variable Objects:: -@end menu - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Command Syntax -@section @sc{gdb/mi} Command Syntax - -@menu -* GDB/MI Input Syntax:: -* GDB/MI Output Syntax:: -* GDB/MI Simple Examples:: -@end menu - -@node GDB/MI Input Syntax -@subsection @sc{gdb/mi} Input Syntax - -@cindex input syntax for @sc{gdb/mi} -@cindex @sc{gdb/mi}, input syntax -@table @code -@item @var{command} @expansion{} -@code{@var{cli-command} | @var{mi-command}} - -@item @var{cli-command} @expansion{} -@code{[ @var{token} ] @var{cli-command} @var{nl}}, where -@var{cli-command} is any existing @value{GDBN} CLI command. - -@item @var{mi-command} @expansion{} -@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* -@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} - -@item @var{token} @expansion{} -"any sequence of digits" - -@item @var{option} @expansion{} -@code{"-" @var{parameter} [ " " @var{parameter} ]} - -@item @var{parameter} @expansion{} -@code{@var{non-blank-sequence} | @var{c-string}} - -@item @var{operation} @expansion{} -@emph{any of the operations described in this chapter} - -@item @var{non-blank-sequence} @expansion{} -@emph{anything, provided it doesn't contain special characters such as -"-", @var{nl}, """ and of course " "} - -@item @var{c-string} @expansion{} -@code{""" @var{seven-bit-iso-c-string-content} """} - -@item @var{nl} @expansion{} -@code{CR | CR-LF} -@end table - -@noindent -Notes: - -@itemize @bullet -@item -The CLI commands are still handled by the @sc{mi} interpreter; their -output is described below. - -@item -The @code{@var{token}}, when present, is passed back when the command -finishes. - -@item -Some @sc{mi} commands accept optional arguments as part of the parameter -list. Each option is identified by a leading @samp{-} (dash) and may be -followed by an optional argument parameter. Options occur first in the -parameter list and can be delimited from normal parameters using -@samp{--} (this is useful when some parameters begin with a dash). -@end itemize - -Pragmatics: - -@itemize @bullet -@item -We want easy access to the existing CLI syntax (for debugging). - -@item -We want it to be easy to spot a @sc{mi} operation. -@end itemize - -@node GDB/MI Output Syntax -@subsection @sc{gdb/mi} Output Syntax - -@cindex output syntax of @sc{gdb/mi} -@cindex @sc{gdb/mi}, output syntax -The output from @sc{gdb/mi} consists of zero or more out-of-band records -followed, optionally, by a single result record. This result record -is for the most recent command. The sequence of output records is -terminated by @samp{(@value{GDBP})}. - -If an input command was prefixed with a @code{@var{token}} then the -corresponding output for that command will also be prefixed by that same -@var{token}. - -@table @code -@item @var{output} @expansion{} -@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} - -@item @var{result-record} @expansion{} -@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} - -@item @var{out-of-band-record} @expansion{} -@code{@var{async-record} | @var{stream-record}} - -@item @var{async-record} @expansion{} -@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} - -@item @var{exec-async-output} @expansion{} -@code{[ @var{token} ] "*" @var{async-output}} - -@item @var{status-async-output} @expansion{} -@code{[ @var{token} ] "+" @var{async-output}} - -@item @var{notify-async-output} @expansion{} -@code{[ @var{token} ] "=" @var{async-output}} - -@item @var{async-output} @expansion{} -@code{@var{async-class} ( "," @var{result} )* @var{nl}} - -@item @var{result-class} @expansion{} -@code{"done" | "running" | "connected" | "error" | "exit"} - -@item @var{async-class} @expansion{} -@code{"stopped" | @var{others}} (where @var{others} will be added -depending on the needs---this is still in development). - -@item @var{result} @expansion{} -@code{ @var{variable} "=" @var{value}} - -@item @var{variable} @expansion{} -@code{ @var{string} } - -@item @var{value} @expansion{} -@code{ @var{const} | @var{tuple} | @var{list} } - -@item @var{const} @expansion{} -@code{@var{c-string}} - -@item @var{tuple} @expansion{} -@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } - -@item @var{list} @expansion{} -@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" -@var{result} ( "," @var{result} )* "]" } - -@item @var{stream-record} @expansion{} -@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} - -@item @var{console-stream-output} @expansion{} -@code{"~" @var{c-string}} - -@item @var{target-stream-output} @expansion{} -@code{"@@" @var{c-string}} - -@item @var{log-stream-output} @expansion{} -@code{"&" @var{c-string}} - -@item @var{nl} @expansion{} -@code{CR | CR-LF} - -@item @var{token} @expansion{} -@emph{any sequence of digits}. -@end table - -@noindent -Notes: - -@itemize @bullet -@item -All output sequences end in a single line containing a period. - -@item -The @code{@var{token}} is from the corresponding request. If an execution -command is interrupted by the @samp{-exec-interrupt} command, the -@var{token} associated with the @samp{*stopped} message is the one of the -original execution command, not the one of the interrupt command. - -@item -@cindex status output in @sc{gdb/mi} -@var{status-async-output} contains on-going status information about the -progress of a slow operation. It can be discarded. All status output is -prefixed by @samp{+}. - -@item -@cindex async output in @sc{gdb/mi} -@var{exec-async-output} contains asynchronous state change on the target -(stopped, started, disappeared). All async output is prefixed by -@samp{*}. - -@item -@cindex notify output in @sc{gdb/mi} -@var{notify-async-output} contains supplementary information that the -client should handle (e.g., a new breakpoint information). All notify -output is prefixed by @samp{=}. - -@item -@cindex console output in @sc{gdb/mi} -@var{console-stream-output} is output that should be displayed as is in the -console. It is the textual response to a CLI command. All the console -output is prefixed by @samp{~}. - -@item -@cindex target output in @sc{gdb/mi} -@var{target-stream-output} is the output produced by the target program. -All the target output is prefixed by @samp{@@}. - -@item -@cindex log output in @sc{gdb/mi} -@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for -instance messages that should be displayed as part of an error log. All -the log output is prefixed by @samp{&}. - -@item -@cindex list output in @sc{gdb/mi} -New @sc{gdb/mi} commands should only output @var{lists} containing -@var{values}. - - -@end itemize - -@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more -details about the various output records. - -@node GDB/MI Simple Examples -@subsection Simple Examples of @sc{gdb/mi} Interaction -@cindex @sc{gdb/mi}, simple examples - -This subsection presents several simple examples of interaction using -the @sc{gdb/mi} interface. In these examples, @samp{->} means that the -following line is passed to @sc{gdb/mi} as input, while @samp{<-} means -the output received from @sc{gdb/mi}. - -@subsubheading Target Stop -@c Ummm... There is no "-stop" command. This assumes async, no? -Here's an example of stopping the inferior process: - -@smallexample --> -stop -<- (@value{GDBP}) -@end smallexample - -@noindent -and later: - -@smallexample -<- *stop,reason="stop",address="0x123",source="a.c:123" -<- (@value{GDBP}) -@end smallexample - -@subsubheading Simple CLI Command - -Here's an example of a simple CLI command being passed through -@sc{gdb/mi} and on to the CLI. - -@smallexample --> print 1+2 -<- &"print 1+2\n" -<- ~"$1 = 3\n" -<- ^done -<- (@value{GDBP}) -@end smallexample - -@subsubheading Command With Side Effects - -@smallexample --> -symbol-file xyz.exe -<- *breakpoint,nr="3",address="0x123",source="a.c:123" -<- (@value{GDBP}) -@end smallexample - -@subsubheading A Bad Command - -Here's what happens if you pass a non-existent command: - -@smallexample --> -rubbish -<- ^error,msg="Undefined MI command: rubbish" -<- (@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Compatibility with CLI -@section @sc{gdb/mi} Compatibility with CLI - -@cindex compatibility, @sc{gdb/mi} and CLI -@cindex @sc{gdb/mi}, compatibility with CLI -To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi} -accepts existing CLI commands. As specified by the syntax, such -commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will -respond. - -This mechanism is provided as an aid to developers of @sc{gdb/mi} -clients and not as a reliable interface into the CLI. Since the command -is being interpreteted in an environment that assumes @sc{gdb/mi} -behaviour, the exact output of such commands is likely to end up being -an un-supported hybrid of @sc{gdb/mi} and CLI output. - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Output Records -@section @sc{gdb/mi} Output Records - -@menu -* GDB/MI Result Records:: -* GDB/MI Stream Records:: -* GDB/MI Out-of-band Records:: -@end menu - -@node GDB/MI Result Records -@subsection @sc{gdb/mi} Result Records - -@cindex result records in @sc{gdb/mi} -@cindex @sc{gdb/mi}, result records -In addition to a number of out-of-band notifications, the response to a -@sc{gdb/mi} command includes one of the following result indications: - -@table @code -@findex ^done -@item "^done" [ "," @var{results} ] -The synchronous operation was successful, @code{@var{results}} are the return -values. - -@item "^running" -@findex ^running -@c Is this one correct? Should it be an out-of-band notification? -The asynchronous operation was successfully started. The target is -running. - -@item "^error" "," @var{c-string} -@findex ^error -The operation failed. The @code{@var{c-string}} contains the corresponding -error message. -@end table - -@node GDB/MI Stream Records -@subsection @sc{gdb/mi} Stream Records - -@cindex @sc{gdb/mi}, stream records -@cindex stream records in @sc{gdb/mi} -@value{GDBN} internally maintains a number of output streams: the console, the -target, and the log. The output intended for each of these streams is -funneled through the @sc{gdb/mi} interface using @dfn{stream records}. - -Each stream record begins with a unique @dfn{prefix character} which -identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output -Syntax}). In addition to the prefix, each stream record contains a -@code{@var{string-output}}. This is either raw text (with an implicit new -line) or a quoted C string (which does not contain an implicit newline). - -@table @code -@item "~" @var{string-output} -The console output stream contains text that should be displayed in the -CLI console window. It contains the textual responses to CLI commands. - -@item "@@" @var{string-output} -The target output stream contains any textual output from the running -target. - -@item "&" @var{string-output} -The log stream contains debugging messages being produced by @value{GDBN}'s -internals. -@end table - -@node GDB/MI Out-of-band Records -@subsection @sc{gdb/mi} Out-of-band Records - -@cindex out-of-band records in @sc{gdb/mi} -@cindex @sc{gdb/mi}, out-of-band records -@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of -additional changes that have occurred. Those changes can either be a -consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of -target activity (e.g., target stopped). - -The following is a preliminary list of possible out-of-band records. - -@table @code -@item "*" "stop" -@end table - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Command Description Format -@section @sc{gdb/mi} Command Description Format - -The remaining sections describe blocks of commands. Each block of -commands is laid out in a fashion similar to this section. - -Note the the line breaks shown in the examples are here only for -readability. They don't appear in the real output. -Also note that the commands with a non-available example (N.A.@:) are -not yet implemented. - -@subheading Motivation - -The motivation for this collection of commands. - -@subheading Introduction - -A brief introduction to this collection of commands as a whole. - -@subheading Commands - -For each command in the block, the following is described: - -@subsubheading Synopsis - -@smallexample - -command @var{args}@dots{} -@end smallexample - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} CLI command. - -@subsubheading Result - -@subsubheading Out-of-band - -@subsubheading Notes - -@subsubheading Example - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Breakpoint Table Commands -@section @sc{gdb/mi} Breakpoint table commands - -@cindex breakpoint commands for @sc{gdb/mi} -@cindex @sc{gdb/mi}, breakpoint commands -This section documents @sc{gdb/mi} commands for manipulating -breakpoints. - -@subheading The @code{-break-after} Command -@findex -break-after - -@subsubheading Synopsis - -@smallexample - -break-after @var{number} @var{count} -@end smallexample - -The breakpoint number @var{number} is not in effect until it has been -hit @var{count} times. To see how this is reflected in the output of -the @samp{-break-list} command, see the description of the -@samp{-break-list} command below. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{ignore}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-insert main -^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@} -(@value{GDBP}) --break-after 1 3 -~ -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x000100d0",func="main",file="hello.c",line="5",times="0", -ignore="3"@}]@} -(@value{GDBP}) -@end smallexample - -@ignore -@subheading The @code{-break-catch} Command -@findex -break-catch - -@subheading The @code{-break-commands} Command -@findex -break-commands -@end ignore - - -@subheading The @code{-break-condition} Command -@findex -break-condition - -@subsubheading Synopsis - -@smallexample - -break-condition @var{number} @var{expr} -@end smallexample - -Breakpoint @var{number} will stop the program only if the condition in -@var{expr} is true. The condition becomes part of the -@samp{-break-list} output (see the description of the @samp{-break-list} -command below). - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{condition}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-condition 1 1 -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x000100d0",func="main",file="hello.c",line="5",cond="1", -times="0",ignore="3"@}]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-delete} Command -@findex -break-delete - -@subsubheading Synopsis - -@smallexample - -break-delete ( @var{breakpoint} )+ -@end smallexample - -Delete the breakpoint(s) whose number(s) are specified in the argument -list. This is obviously reflected in the breakpoint list. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{delete}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-delete 1 -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="0",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-disable} Command -@findex -break-disable - -@subsubheading Synopsis - -@smallexample - -break-disable ( @var{breakpoint} )+ -@end smallexample - -Disable the named @var{breakpoint}(s). The field @samp{enabled} in the -break list is now set to @samp{n} for the named @var{breakpoint}(s). - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{disable}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-disable 2 -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", -addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-enable} Command -@findex -break-enable - -@subsubheading Synopsis - -@smallexample - -break-enable ( @var{breakpoint} )+ -@end smallexample - -Enable (previously disabled) @var{breakpoint}(s). - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{enable}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-enable 2 -^done -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", -addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-info} Command -@findex -break-info - -@subsubheading Synopsis - -@smallexample - -break-info @var{breakpoint} -@end smallexample - -@c REDUNDANT??? -Get information about a single breakpoint. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. - -@subsubheading Example -N.A. - -@subheading The @code{-break-insert} Command -@findex -break-insert - -@subsubheading Synopsis - -@smallexample - -break-insert [ -t ] [ -h ] [ -r ] - [ -c @var{condition} ] [ -i @var{ignore-count} ] - [ -p @var{thread} ] [ @var{line} | @var{addr} ] -@end smallexample - -@noindent -If specified, @var{line}, can be one of: - -@itemize @bullet -@item function -@c @item +offset -@c @item -offset -@c @item linenum -@item filename:linenum -@item filename:function -@item *address -@end itemize - -The possible optional parameters of this command are: - -@table @samp -@item -t -Insert a tempoary breakpoint. -@item -h -Insert a hardware breakpoint. -@item -c @var{condition} -Make the breakpoint conditional on @var{condition}. -@item -i @var{ignore-count} -Initialize the @var{ignore-count}. -@item -r -Insert a regular breakpoint in all the functions whose names match the -given regular expression. Other flags are not applicable to regular -expresson. -@end table - -@subsubheading Result - -The result is in the form: - -@smallexample - ^done,bkptno="@var{number}",func="@var{funcname}", - file="@var{filename}",line="@var{lineno}" -@end smallexample - -@noindent -where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname} -is the name of the function where the breakpoint was inserted, -@var{filename} is the name of the source file which contains this -function, and @var{lineno} is the source line number within that file. - -Note: this format is open to change. -@c An out-of-band breakpoint instead of part of the result? - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, -@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-insert main -^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} -(@value{GDBP}) --break-insert -t foo -^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@} -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="2",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@}, -bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", -addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@} -(@value{GDBP}) --break-insert -r foo.* -~int foo(int, int); -^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-list} Command -@findex -break-list - -@subsubheading Synopsis - -@smallexample - -break-list -@end smallexample - -Displays the list of inserted breakpoints, showing the following fields: - -@table @samp -@item Number -number of the breakpoint -@item Type -type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} -@item Disposition -should the breakpoint be deleted or disabled when it is hit: @samp{keep} -or @samp{nokeep} -@item Enabled -is the breakpoint enabled or no: @samp{y} or @samp{n} -@item Address -memory location at which the breakpoint is set -@item What -logical location of the breakpoint, expressed by function name, file -name, line number -@item Times -number of times the breakpoint has been hit -@end table - -If there are no breakpoints or watchpoints, the @code{BreakpointTable} -@code{body} field is an empty list. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info break}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="2",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}, -bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", -addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@} -(@value{GDBP}) -@end smallexample - -Here's an example of the result when there are no breakpoints: - -@smallexample -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="0",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[]@} -(@value{GDBP}) -@end smallexample - -@subheading The @code{-break-watch} Command -@findex -break-watch - -@subsubheading Synopsis - -@smallexample - -break-watch [ -a | -r ] -@end smallexample - -Create a watchpoint. With the @samp{-a} option it will create an -@dfn{access} watchpoint, i.e. a watchpoint that triggers either on a -read from or on a write to the memory location. With the @samp{-r} -option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will -trigger only when the memory location is accessed for reading. Without -either of the options, the watchpoint created is a regular watchpoint, -i.e. it will trigger when the memory location is accessed for writing. -@xref{Set Watchpoints, , Setting watchpoints}. - -Note that @samp{-break-list} will report a single list of watchpoints and -breakpoints inserted. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and -@samp{rwatch}. - -@subsubheading Example - -Setting a watchpoint on a variable in the @code{main} function: - -@smallexample -(@value{GDBP}) --break-watch x -^done,wpt=@{number="2",exp="x"@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, -value=@{old="-268439212",new="55"@}, -frame=@{func="main",args=[],file="recursive2.c",line="5"@} -(@value{GDBP}) -@end smallexample - -Setting a watchpoint on a variable local to a function. @value{GDBN} will stop -the program execution twice: first for the variable changing value, then -for the watchpoint going out of scope. - -@smallexample -(@value{GDBP}) --break-watch C -^done,wpt=@{number="5",exp="C"@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-trigger", -wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, -frame=@{func="callee4",args=[], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-scope",wpnum="5", -frame=@{func="callee3",args=[@{name="strarg", -value="0x11940 \"A string argument.\""@}], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} -(@value{GDBP}) -@end smallexample - -Listing breakpoints and watchpoints, at different points in the program -execution. Note that once the watchpoint goes out of scope, it is -deleted. - -@smallexample -(@value{GDBP}) --break-watch C -^done,wpt=@{number="2",exp="C"@} -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="2",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x00010734",func="callee4", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, -bkpt=@{number="2",type="watchpoint",disp="keep", -enabled="y",addr="",what="C",times="0"@}]@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, -value=@{old="-276895068",new="3"@}, -frame=@{func="callee4",args=[], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@} -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="2",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x00010734",func="callee4", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}, -bkpt=@{number="2",type="watchpoint",disp="keep", -enabled="y",addr="",what="C",times="-5"@}]@} -(@value{GDBP}) --exec-continue -^running -^done,reason="watchpoint-scope",wpnum="2", -frame=@{func="callee3",args=[@{name="strarg", -value="0x11940 \"A string argument.\""@}], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} -(@value{GDBP}) --break-list -^done,BreakpointTable=@{nr_rows="1",nr_cols="6", -hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, -@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, -@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, -@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, -@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, -@{width="40",alignment="2",col_name="what",colhdr="What"@}], -body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", -addr="0x00010734",func="callee4", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@} -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Data Manipulation -@section @sc{gdb/mi} Data Manipulation - -@cindex data manipulation, in @sc{gdb/mi} -@cindex @sc{gdb/mi}, data manipulation -This section describes the @sc{gdb/mi} commands that manipulate data: -examine memory and registers, evaluate expressions, etc. - -@c REMOVED FROM THE INTERFACE. -@c @subheading -data-assign -@c Change the value of a program variable. Plenty of side effects. -@c @subsubheading GDB command -@c set variable -@c @subsubheading Example -@c N.A. - -@subheading The @code{-data-disassemble} Command -@findex -data-disassemble - -@subsubheading Synopsis - -@smallexample - -data-disassemble - [ -s @var{start-addr} -e @var{end-addr} ] - | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] - -- @var{mode} -@end smallexample - -@noindent -Where: - -@table @samp -@item @var{start-addr} -is the beginning address (or @code{$pc}) -@item @var{end-addr} -is the end address -@item @var{filename} -is the name of the file to disassemble -@item @var{linenum} -is the line number to disassemble around -@item @var{lines} -is the the number of disassembly lines to be produced. If it is -1, -the whole function will be disassembled, in case no @var{end-addr} is -specified. If @var{end-addr} is specified as a non-zero value, and -@var{lines} is lower than the number of disassembly lines between -@var{start-addr} and @var{end-addr}, only @var{lines} lines are -displayed; if @var{lines} is higher than the number of lines between -@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} -are displayed. -@item @var{mode} -is either 0 (meaning only disassembly) or 1 (meaning mixed source and -disassembly). -@end table - -@subsubheading Result - -The output for each instruction is composed of four fields: - -@itemize @bullet -@item Address -@item Func-name -@item Offset -@item Instruction -@end itemize - -Note that whatever included in the instruction field, is not manipulated -directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format. - -@subsubheading @value{GDBN} Command - -There's no direct mapping from this command to the CLI. - -@subsubheading Example - -Disassemble from the current value of @code{$pc} to @code{$pc + 20}: - -@smallexample -(@value{GDBP}) --data-disassemble -s $pc -e "$pc + 20" -- 0 -^done, -asm_insns=[ -@{address="0x000107c0",func-name="main",offset="4", -inst="mov 2, %o0"@}, -@{address="0x000107c4",func-name="main",offset="8", -inst="sethi %hi(0x11800), %o2"@}, -@{address="0x000107c8",func-name="main",offset="12", -inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, -@{address="0x000107cc",func-name="main",offset="16", -inst="sethi %hi(0x11800), %o2"@}, -@{address="0x000107d0",func-name="main",offset="20", -inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] -(@value{GDBP}) -@end smallexample - -Disassemble the whole @code{main} function. Line 32 is part of -@code{main}. - -@smallexample --data-disassemble -f basics.c -l 32 -- 0 -^done,asm_insns=[ -@{address="0x000107bc",func-name="main",offset="0", -inst="save %sp, -112, %sp"@}, -@{address="0x000107c0",func-name="main",offset="4", -inst="mov 2, %o0"@}, -@{address="0x000107c4",func-name="main",offset="8", -inst="sethi %hi(0x11800), %o2"@}, -[@dots{}] -@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, -@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] -(@value{GDBP}) -@end smallexample - -Disassemble 3 instructions from the start of @code{main}: - -@smallexample -(@value{GDBP}) --data-disassemble -f basics.c -l 32 -n 3 -- 0 -^done,asm_insns=[ -@{address="0x000107bc",func-name="main",offset="0", -inst="save %sp, -112, %sp"@}, -@{address="0x000107c0",func-name="main",offset="4", -inst="mov 2, %o0"@}, -@{address="0x000107c4",func-name="main",offset="8", -inst="sethi %hi(0x11800), %o2"@}] -(@value{GDBP}) -@end smallexample - -Disassemble 3 instructions from the start of @code{main} in mixed mode: - -@smallexample -(@value{GDBP}) --data-disassemble -f basics.c -l 32 -n 3 -- 1 -^done,asm_insns=[ -src_and_asm_line=@{line="31", -file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ - testsuite/gdb.mi/basics.c",line_asm_insn=[ -@{address="0x000107bc",func-name="main",offset="0", -inst="save %sp, -112, %sp"@}]@}, -src_and_asm_line=@{line="32", -file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ - testsuite/gdb.mi/basics.c",line_asm_insn=[ -@{address="0x000107c0",func-name="main",offset="4", -inst="mov 2, %o0"@}, -@{address="0x000107c4",func-name="main",offset="8", -inst="sethi %hi(0x11800), %o2"@}]@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-data-evaluate-expression} Command -@findex -data-evaluate-expression - -@subsubheading Synopsis - -@smallexample - -data-evaluate-expression @var{expr} -@end smallexample - -Evaluate @var{expr} as an expression. The expression could contain an -inferior function call. The function call will execute synchronously. -If the expression contains spaces, it must be enclosed in double quotes. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and -@samp{call}. In @code{gdbtk} only, there's a corresponding -@samp{gdb_eval} command. - -@subsubheading Example - -In the following example, the numbers that precede the commands are the -@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} -Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its -output. - -@smallexample -211-data-evaluate-expression A -211^done,value="1" -(@value{GDBP}) -311-data-evaluate-expression &A -311^done,value="0xefffeb7c" -(@value{GDBP}) -411-data-evaluate-expression A+3 -411^done,value="4" -(@value{GDBP}) -511-data-evaluate-expression "A + 3" -511^done,value="4" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-data-list-changed-registers} Command -@findex -data-list-changed-registers - -@subsubheading Synopsis - -@smallexample - -data-list-changed-registers -@end smallexample - -Display a list of the registers that have changed. - -@subsubheading @value{GDBN} Command - -@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} -has the corresponding command @samp{gdb_changed_register_list}. - -@subsubheading Example - -On a PPC MBX board: - -@smallexample -(@value{GDBP}) --exec-continue -^running - -(@value{GDBP}) -*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main", -args=[],file="try.c",line="5"@} -(@value{GDBP}) --data-list-changed-registers -^done,changed-registers=["0","1","2","4","5","6","7","8","9", -"10","11","13","14","15","16","17","18","19","20","21","22","23", -"24","25","26","27","28","30","31","64","65","66","67","69"] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-data-list-register-names} Command -@findex -data-list-register-names - -@subsubheading Synopsis - -@smallexample - -data-list-register-names [ ( @var{regno} )+ ] -@end smallexample - -Show a list of register names for the current target. If no arguments -are given, it shows a list of the names of all the registers. If -integer numbers are given as arguments, it will print a list of the -names of the registers corresponding to the arguments. To ensure -consistency between a register name and its number, the output list may -include empty register names. - -@subsubheading @value{GDBN} Command - -@value{GDBN} does not have a command which corresponds to -@samp{-data-list-register-names}. In @code{gdbtk} there is a -corresponding command @samp{gdb_regnames}. - -@subsubheading Example - -For the PPC MBX board: -@smallexample -(@value{GDBP}) --data-list-register-names -^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", -"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", -"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", -"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", -"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", -"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", -"", "pc","ps","cr","lr","ctr","xer"] -(@value{GDBP}) --data-list-register-names 1 2 3 -^done,register-names=["r1","r2","r3"] -(@value{GDBP}) -@end smallexample - -@subheading The @code{-data-list-register-values} Command -@findex -data-list-register-values - -@subsubheading Synopsis - -@smallexample - -data-list-register-values @var{fmt} [ ( @var{regno} )*] -@end smallexample - -Display the registers' contents. @var{fmt} is the format according to -which the registers' contents are to be returned, followed by an optional -list of numbers specifying the registers to display. A missing list of -numbers indicates that the contents of all the registers must be returned. - -Allowed formats for @var{fmt} are: - -@table @code -@item x -Hexadecimal -@item o -Octal -@item t -Binary -@item d -Decimal -@item r -Raw -@item N -Natural -@end table - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info -all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. - -@subsubheading Example - -For a PPC MBX board (note: line breaks are for readability only, they -don't appear in the actual output): - -@smallexample -(@value{GDBP}) --data-list-register-values r 64 65 -^done,register-values=[@{number="64",value="0xfe00a300"@}, -@{number="65",value="0x00029002"@}] -(@value{GDBP}) --data-list-register-values x -^done,register-values=[@{number="0",value="0xfe0043c8"@}, -@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, -@{number="3",value="0x0"@},@{number="4",value="0xa"@}, -@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, -@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, -@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, -@{number="11",value="0x1"@},@{number="12",value="0x0"@}, -@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, -@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, -@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, -@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, -@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, -@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, -@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, -@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, -@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, -@{number="31",value="0x0"@},@{number="32",value="0x0"@}, -@{number="33",value="0x0"@},@{number="34",value="0x0"@}, -@{number="35",value="0x0"@},@{number="36",value="0x0"@}, -@{number="37",value="0x0"@},@{number="38",value="0x0"@}, -@{number="39",value="0x0"@},@{number="40",value="0x0"@}, -@{number="41",value="0x0"@},@{number="42",value="0x0"@}, -@{number="43",value="0x0"@},@{number="44",value="0x0"@}, -@{number="45",value="0x0"@},@{number="46",value="0x0"@}, -@{number="47",value="0x0"@},@{number="48",value="0x0"@}, -@{number="49",value="0x0"@},@{number="50",value="0x0"@}, -@{number="51",value="0x0"@},@{number="52",value="0x0"@}, -@{number="53",value="0x0"@},@{number="54",value="0x0"@}, -@{number="55",value="0x0"@},@{number="56",value="0x0"@}, -@{number="57",value="0x0"@},@{number="58",value="0x0"@}, -@{number="59",value="0x0"@},@{number="60",value="0x0"@}, -@{number="61",value="0x0"@},@{number="62",value="0x0"@}, -@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, -@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, -@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, -@{number="69",value="0x20002b03"@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-data-read-memory} Command -@findex -data-read-memory - -@subsubheading Synopsis - -@smallexample - -data-read-memory [ -o @var{byte-offset} ] - @var{address} @var{word-format} @var{word-size} - @var{nr-rows} @var{nr-cols} [ @var{aschar} ] -@end smallexample - -@noindent -where: - -@table @samp -@item @var{address} -An expression specifying the address of the first memory word to be -read. Complex expressions containing embedded white space should be -quoted using the C convention. - -@item @var{word-format} -The format to be used to print the memory words. The notation is the -same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, -,Output formats}). - -@item @var{word-size} -The size of each memory word in bytes. - -@item @var{nr-rows} -The number of rows in the output table. - -@item @var{nr-cols} -The number of columns in the output table. - -@item @var{aschar} -If present, indicates that each row should include an @sc{ascii} dump. The -value of @var{aschar} is used as a padding character when a byte is not a -member of the printable @sc{ascii} character set (printable @sc{ascii} -characters are those whose code is between 32 and 126, inclusively). - -@item @var{byte-offset} -An offset to add to the @var{address} before fetching memory. -@end table - -This command displays memory contents as a table of @var{nr-rows} by -@var{nr-cols} words, each word being @var{word-size} bytes. In total, -@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read -(returned as @samp{total-bytes}). Should less than the requested number -of bytes be returned by the target, the missing words are identified -using @samp{N/A}. The number of bytes read from the target is returned -in @samp{nr-bytes} and the starting address used to read memory in -@samp{addr}. - -The address of the next/previous row or page is available in -@samp{next-row} and @samp{prev-row}, @samp{next-page} and -@samp{prev-page}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has -@samp{gdb_get_mem} memory read command. - -@subsubheading Example - -Read six bytes of memory starting at @code{bytes+6} but then offset by -@code{-6} bytes. Format as three rows of two columns. One byte per -word. Display each word in hex. - -@smallexample -(@value{GDBP}) -9-data-read-memory -o -6 -- bytes+6 x 1 3 2 -9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", -next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", -prev-page="0x0000138a",memory=[ -@{addr="0x00001390",data=["0x00","0x01"]@}, -@{addr="0x00001392",data=["0x02","0x03"]@}, -@{addr="0x00001394",data=["0x04","0x05"]@}] -(@value{GDBP}) -@end smallexample - -Read two bytes of memory starting at address @code{shorts + 64} and -display as a single word formatted in decimal. - -@smallexample -(@value{GDBP}) -5-data-read-memory shorts+64 d 2 1 1 -5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", -next-row="0x00001512",prev-row="0x0000150e", -next-page="0x00001512",prev-page="0x0000150e",memory=[ -@{addr="0x00001510",data=["128"]@}] -(@value{GDBP}) -@end smallexample - -Read thirty two bytes of memory starting at @code{bytes+16} and format -as eight rows of four columns. Include a string encoding with @samp{x} -used as the non-printable character. - -@smallexample -(@value{GDBP}) -4-data-read-memory bytes+16 x 1 8 4 x -4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", -next-row="0x000013c0",prev-row="0x0000139c", -next-page="0x000013c0",prev-page="0x00001380",memory=[ -@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, -@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, -@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, -@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, -@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, -@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, -@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, -@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] -(@value{GDBP}) -@end smallexample - -@subheading The @code{-display-delete} Command -@findex -display-delete - -@subsubheading Synopsis - -@smallexample - -display-delete @var{number} -@end smallexample - -Delete the display @var{number}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{delete display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-display-disable} Command -@findex -display-disable - -@subsubheading Synopsis - -@smallexample - -display-disable @var{number} -@end smallexample - -Disable display @var{number}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{disable display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-display-enable} Command -@findex -display-enable - -@subsubheading Synopsis - -@smallexample - -display-enable @var{number} -@end smallexample - -Enable display @var{number}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{enable display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-display-insert} Command -@findex -display-insert - -@subsubheading Synopsis - -@smallexample - -display-insert @var{expression} -@end smallexample - -Display @var{expression} every time the program stops. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-display-list} Command -@findex -display-list - -@subsubheading Synopsis - -@smallexample - -display-list -@end smallexample - -List the displays. Do not show the current values. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info display}. - -@subsubheading Example -N.A. - - -@subheading The @code{-environment-cd} Command -@findex -environment-cd - -@subsubheading Synopsis - -@smallexample - -environment-cd @var{pathdir} -@end smallexample - -Set @value{GDBN}'s working directory. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{cd}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-environment-directory} Command -@findex -environment-directory - -@subsubheading Synopsis - -@smallexample - -environment-directory [ -r ] [ @var{pathdir} ]+ -@end smallexample - -Add directories @var{pathdir} to beginning of search path for source files. -If the @samp{-r} option is used, the search path is reset to the default -search path. If directories @var{pathdir} are supplied in addition to the -@samp{-r} option, the search path is first reset and then addition -occurs as normal. -Multiple directories may be specified, separated by blanks. Specifying -multiple directories in a single command -results in the directories added to the beginning of the -search path in the same order they were presented in the command. -If blanks are needed as -part of a directory name, double-quotes should be used around -the name. In the command output, the path will show up separated -by the system directory-separator character. The directory-seperator -character must not be used -in any directory name. -If no directories are specified, the current search path is displayed. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{dir}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb -^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" -(@value{GDBP}) --environment-directory "" -^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" -(@value{GDBP}) --environment-directory -r /home/jjohnstn/src/gdb /usr/src -^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" -(@value{GDBP}) --environment-directory -r -^done,source-path="$cdir:$cwd" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-environment-path} Command -@findex -environment-path - -@subsubheading Synopsis - -@smallexample - -environment-path [ -r ] [ @var{pathdir} ]+ -@end smallexample - -Add directories @var{pathdir} to beginning of search path for object files. -If the @samp{-r} option is used, the search path is reset to the original -search path that existed at gdb start-up. If directories @var{pathdir} are -supplied in addition to the -@samp{-r} option, the search path is first reset and then addition -occurs as normal. -Multiple directories may be specified, separated by blanks. Specifying -multiple directories in a single command -results in the directories added to the beginning of the -search path in the same order they were presented in the command. -If blanks are needed as -part of a directory name, double-quotes should be used around -the name. In the command output, the path will show up separated -by the system directory-separator character. The directory-seperator -character must not be used -in any directory name. -If no directories are specified, the current path is displayed. - - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{path}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --environment-path -^done,path="/usr/bin" -(@value{GDBP}) --environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin -^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" -(@value{GDBP}) --environment-path -r /usr/local/bin -^done,path="/usr/local/bin:/usr/bin" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-environment-pwd} Command -@findex -environment-pwd - -@subsubheading Synopsis - -@smallexample - -environment-pwd -@end smallexample - -Show the current working directory. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{pwd}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --environment-pwd -^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Program Control -@section @sc{gdb/mi} Program control - -@subsubheading Program termination - -As a result of execution, the inferior program can run to completion, if -it doesn't encounter any breakpoints. In this case the output will -include an exit code, if the program has exited exceptionally. - -@subsubheading Examples - -@noindent -Program exited normally: - -@smallexample -(@value{GDBP}) --exec-run -^running -(@value{GDBP}) -x = 55 -*stopped,reason="exited-normally" -(@value{GDBP}) -@end smallexample - -@noindent -Program exited exceptionally: - -@smallexample -(@value{GDBP}) --exec-run -^running -(@value{GDBP}) -x = 55 -*stopped,reason="exited",exit-code="01" -(@value{GDBP}) -@end smallexample - -Another way the program can terminate is if it receives a signal such as -@code{SIGINT}. In this case, @sc{gdb/mi} displays this: - -@smallexample -(@value{GDBP}) -*stopped,reason="exited-signalled",signal-name="SIGINT", -signal-meaning="Interrupt" -@end smallexample - - -@subheading The @code{-exec-abort} Command -@findex -exec-abort - -@subsubheading Synopsis - -@smallexample - -exec-abort -@end smallexample - -Kill the inferior running program. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{kill}. - -@subsubheading Example -N.A. - - -@subheading The @code{-exec-arguments} Command -@findex -exec-arguments - -@subsubheading Synopsis - -@smallexample - -exec-arguments @var{args} -@end smallexample - -Set the inferior program arguments, to be used in the next -@samp{-exec-run}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{set args}. - -@subsubheading Example - -@c FIXME! -Don't have one around. - - -@subheading The @code{-exec-continue} Command -@findex -exec-continue - -@subsubheading Synopsis - -@smallexample - -exec-continue -@end smallexample - -Asynchronous command. Resumes the execution of the inferior program -until a breakpoint is encountered, or until the inferior exits. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} corresponding is @samp{continue}. - -@subsubheading Example - -@smallexample --exec-continue -^running -(@value{GDBP}) -@@Hello world -*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[], -file="hello.c",line="13"@} -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-finish} Command -@findex -exec-finish - -@subsubheading Synopsis - -@smallexample - -exec-finish -@end smallexample - -Asynchronous command. Resumes the execution of the inferior program -until the current function is exited. Displays the results returned by -the function. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{finish}. - -@subsubheading Example - -Function returning @code{void}. - -@smallexample --exec-finish -^running -(@value{GDBP}) -@@hello from foo -*stopped,reason="function-finished",frame=@{func="main",args=[], -file="hello.c",line="7"@} -(@value{GDBP}) -@end smallexample - -Function returning other than @code{void}. The name of the internal -@value{GDBN} variable storing the result is printed, together with the -value itself. - -@smallexample --exec-finish -^running -(@value{GDBP}) -*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", -args=[@{name="a",value="1"],@{name="b",value="9"@}@}, -file="recursive2.c",line="14"@}, -gdb-result-var="$1",return-value="0" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-interrupt} Command -@findex -exec-interrupt - -@subsubheading Synopsis - -@smallexample - -exec-interrupt -@end smallexample - -Asynchronous command. Interrupts the background execution of the target. -Note how the token associated with the stop message is the one for the -execution command that has been interrupted. The token for the interrupt -itself only appears in the @samp{^done} output. If the user is trying to -interrupt a non-running program, an error message will be printed. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{interrupt}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) -111-exec-continue -111^running - -(@value{GDBP}) -222-exec-interrupt -222^done -(@value{GDBP}) -111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", -frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@} -(@value{GDBP}) - -(@value{GDBP}) --exec-interrupt -^error,msg="mi_cmd_exec_interrupt: Inferior not executing." -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-next} Command -@findex -exec-next - -@subsubheading Synopsis - -@smallexample - -exec-next -@end smallexample - -Asynchronous command. Resumes execution of the inferior program, stopping -when the beginning of the next source line is reached. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{next}. - -@subsubheading Example - -@smallexample --exec-next -^running -(@value{GDBP}) -*stopped,reason="end-stepping-range",line="8",file="hello.c" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-next-instruction} Command -@findex -exec-next-instruction - -@subsubheading Synopsis - -@smallexample - -exec-next-instruction -@end smallexample - -Asynchronous command. Executes one machine instruction. If the -instruction is a function call continues until the function returns. If -the program stops at an instruction in the middle of a source line, the -address will be printed as well. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{nexti}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --exec-next-instruction -^running - -(@value{GDBP}) -*stopped,reason="end-stepping-range", -addr="0x000100d4",line="5",file="hello.c" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-return} Command -@findex -exec-return - -@subsubheading Synopsis - -@smallexample - -exec-return -@end smallexample - -Makes current function return immediately. Doesn't execute the inferior. -Displays the new current frame. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{return}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) -200-break-insert callee4 -200^done,bkpt=@{number="1",addr="0x00010734", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} -(@value{GDBP}) -000-exec-run -000^running -(@value{GDBP}) -000*stopped,reason="breakpoint-hit",bkptno="1", -frame=@{func="callee4",args=[], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} -(@value{GDBP}) -205-break-delete -205^done -(@value{GDBP}) -111-exec-return -111^done,frame=@{level="0",func="callee3", -args=[@{name="strarg", -value="0x11940 \"A string argument.\""@}], -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@} -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-run} Command -@findex -exec-run - -@subsubheading Synopsis - -@smallexample - -exec-run -@end smallexample - -Asynchronous command. Starts execution of the inferior from the -beginning. The inferior executes until either a breakpoint is -encountered or the program exits. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{run}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --break-insert main -^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} -(@value{GDBP}) --exec-run -^running -(@value{GDBP}) -*stopped,reason="breakpoint-hit",bkptno="1", -frame=@{func="main",args=[],file="recursive2.c",line="4"@} -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-show-arguments} Command -@findex -exec-show-arguments - -@subsubheading Synopsis - -@smallexample - -exec-show-arguments -@end smallexample - -Print the arguments of the program. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{show args}. - -@subsubheading Example -N.A. - -@c @subheading -exec-signal - -@subheading The @code{-exec-step} Command -@findex -exec-step - -@subsubheading Synopsis - -@smallexample - -exec-step -@end smallexample - -Asynchronous command. Resumes execution of the inferior program, stopping -when the beginning of the next source line is reached, if the next -source line is not a function call. If it is, stop at the first -instruction of the called function. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{step}. - -@subsubheading Example - -Stepping into a function: - -@smallexample --exec-step -^running -(@value{GDBP}) -*stopped,reason="end-stepping-range", -frame=@{func="foo",args=[@{name="a",value="10"@}, -@{name="b",value="0"@}],file="recursive2.c",line="11"@} -(@value{GDBP}) -@end smallexample - -Regular stepping: - -@smallexample --exec-step -^running -(@value{GDBP}) -*stopped,reason="end-stepping-range",line="14",file="recursive2.c" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-step-instruction} Command -@findex -exec-step-instruction - -@subsubheading Synopsis - -@smallexample - -exec-step-instruction -@end smallexample - -Asynchronous command. Resumes the inferior which executes one machine -instruction. The output, once @value{GDBN} has stopped, will vary depending on -whether we have stopped in the middle of a source line or not. In the -former case, the address at which the program stopped will be printed as -well. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{stepi}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --exec-step-instruction -^running - -(@value{GDBP}) -*stopped,reason="end-stepping-range", -frame=@{func="foo",args=[],file="try.c",line="10"@} -(@value{GDBP}) --exec-step-instruction -^running - -(@value{GDBP}) -*stopped,reason="end-stepping-range", -frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@} -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-exec-until} Command -@findex -exec-until - -@subsubheading Synopsis - -@smallexample - -exec-until [ @var{location} ] -@end smallexample - -Asynchronous command. Executes the inferior until the @var{location} -specified in the argument is reached. If there is no argument, the inferior -executes until a source line greater than the current one is reached. -The reason for stopping in this case will be @samp{location-reached}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{until}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --exec-until recursive2.c:6 -^running -(@value{GDBP}) -x = 55 -*stopped,reason="location-reached",frame=@{func="main",args=[], -file="recursive2.c",line="6"@} -(@value{GDBP}) -@end smallexample - -@ignore -@subheading -file-clear -Is this going away???? -@end ignore - - -@subheading The @code{-file-exec-and-symbols} Command -@findex -file-exec-and-symbols - -@subsubheading Synopsis - -@smallexample - -file-exec-and-symbols @var{file} -@end smallexample - -Specify the executable file to be debugged. This file is the one from -which the symbol table is also read. If no file is specified, the -command clears the executable and symbol information. If breakpoints -are set when using this command with no arguments, @value{GDBN} will produce -error messages. Otherwise, no output is produced, except a completion -notification. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{file}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-file-exec-file} Command -@findex -file-exec-file - -@subsubheading Synopsis - -@smallexample - -file-exec-file @var{file} -@end smallexample - -Specify the executable file to be debugged. Unlike -@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read -from this file. If used without argument, @value{GDBN} clears the information -about the executable file. No output is produced, except a completion -notification. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{exec-file}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-file-list-exec-sections} Command -@findex -file-list-exec-sections - -@subsubheading Synopsis - -@smallexample - -file-list-exec-sections -@end smallexample - -List the sections of the current executable file. - -@subsubheading @value{GDBN} Command - -The @value{GDBN} command @samp{info file} shows, among the rest, the same -information as this command. @code{gdbtk} has a corresponding command -@samp{gdb_load_info}. - -@subsubheading Example -N.A. - - -@subheading The @code{-file-list-exec-source-file} Command -@findex -file-list-exec-source-file - -@subsubheading Synopsis - -@smallexample - -file-list-exec-source-file -@end smallexample - -List the line number, the current source file, and the absolute path -to the current source file for the current executable. - -@subsubheading @value{GDBN} Command - -There's no @value{GDBN} command which directly corresponds to this one. - -@subsubheading Example - -@smallexample -(@value{GDBP}) -123-file-list-exec-source-file -123^done,line="1",file="foo.c",fullname="/home/bar/foo.c" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-file-list-exec-source-files} Command -@findex -file-list-exec-source-files - -@subsubheading Synopsis - -@smallexample - -file-list-exec-source-files -@end smallexample - -List the source files for the current executable. - -@subsubheading @value{GDBN} Command - -There's no @value{GDBN} command which directly corresponds to this one. -@code{gdbtk} has an analogous command @samp{gdb_listfiles}. - -@subsubheading Example -N.A. - - -@subheading The @code{-file-list-shared-libraries} Command -@findex -file-list-shared-libraries - -@subsubheading Synopsis - -@smallexample - -file-list-shared-libraries -@end smallexample - -List the shared libraries in the program. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info shared}. - -@subsubheading Example -N.A. - - -@subheading The @code{-file-list-symbol-files} Command -@findex -file-list-symbol-files - -@subsubheading Synopsis - -@smallexample - -file-list-symbol-files -@end smallexample - -List symbol files. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info file} (part of it). - -@subsubheading Example -N.A. - - -@subheading The @code{-file-symbol-file} Command -@findex -file-symbol-file - -@subsubheading Synopsis - -@smallexample - -file-symbol-file @var{file} -@end smallexample - -Read symbol table info from the specified @var{file} argument. When -used without arguments, clears @value{GDBN}'s symbol table info. No output is -produced, except for a completion notification. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{symbol-file}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx -^done -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Miscellaneous Commands -@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi} - -@c @subheading -gdb-complete - -@subheading The @code{-gdb-exit} Command -@findex -gdb-exit - -@subsubheading Synopsis - -@smallexample - -gdb-exit -@end smallexample - -Exit @value{GDBN} immediately. - -@subsubheading @value{GDBN} Command - -Approximately corresponds to @samp{quit}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --gdb-exit -@end smallexample - -@subheading The @code{-gdb-set} Command -@findex -gdb-set - -@subsubheading Synopsis - -@smallexample - -gdb-set -@end smallexample - -Set an internal @value{GDBN} variable. -@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{set}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --gdb-set $foo=3 -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-gdb-show} Command -@findex -gdb-show - -@subsubheading Synopsis - -@smallexample - -gdb-show -@end smallexample - -Show the current value of a @value{GDBN} variable. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{show}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --gdb-show annotate -^done,value="0" -(@value{GDBP}) -@end smallexample - -@c @subheading -gdb-source - - -@subheading The @code{-gdb-version} Command -@findex -gdb-version - -@subsubheading Synopsis - -@smallexample - -gdb-version -@end smallexample - -Show version information for @value{GDBN}. Used mostly in testing. - -@subsubheading @value{GDBN} Command - -There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this -information when you start an interactive session. - -@subsubheading Example - -@c This example modifies the actual output from GDB to avoid overfull -@c box in TeX. -@smallexample -(@value{GDBP}) --gdb-version -~GNU gdb 5.2.1 -~Copyright 2000 Free Software Foundation, Inc. -~GDB is free software, covered by the GNU General Public License, and -~you are welcome to change it and/or distribute copies of it under -~ certain conditions. -~Type "show copying" to see the conditions. -~There is absolutely no warranty for GDB. Type "show warranty" for -~ details. -~This GDB was configured as - "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". -^done -(@value{GDBP}) -@end smallexample - -@subheading The @code{-interpreter-exec} Command -@findex -interpreter-exec - -@subheading Synopsis - -@smallexample --interpreter-exec @var{interpreter} @var{command} -@end smallexample - -Execute the specified @var{command} in the given @var{interpreter}. - -@subheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{interpreter-exec}. - -@subheading Example - -@smallexample -(@value{GDBP}) --interpreter-exec console "break main" -&"During symbol reading, couldn't parse type; debugger out of date?.\n" -&"During symbol reading, bad structure-type format.\n" -~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" -^done -(@value{GDBP}) -@end smallexample - -@ignore -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Kod Commands -@section @sc{gdb/mi} Kod Commands - -The Kod commands are not implemented. - -@c @subheading -kod-info - -@c @subheading -kod-list - -@c @subheading -kod-list-object-types - -@c @subheading -kod-show - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Memory Overlay Commands -@section @sc{gdb/mi} Memory Overlay Commands - -The memory overlay commands are not implemented. - -@c @subheading -overlay-auto - -@c @subheading -overlay-list-mapping-state - -@c @subheading -overlay-list-overlays - -@c @subheading -overlay-map - -@c @subheading -overlay-off - -@c @subheading -overlay-on - -@c @subheading -overlay-unmap - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Signal Handling Commands -@section @sc{gdb/mi} Signal Handling Commands - -Signal handling commands are not implemented. - -@c @subheading -signal-handle - -@c @subheading -signal-list-handle-actions - -@c @subheading -signal-list-signal-types -@end ignore - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Stack Manipulation -@section @sc{gdb/mi} Stack Manipulation Commands - - -@subheading The @code{-stack-info-frame} Command -@findex -stack-info-frame - -@subsubheading Synopsis - -@smallexample - -stack-info-frame -@end smallexample - -Get info on the current frame. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} -(without arguments). - -@subsubheading Example -N.A. - -@subheading The @code{-stack-info-depth} Command -@findex -stack-info-depth - -@subsubheading Synopsis - -@smallexample - -stack-info-depth [ @var{max-depth} ] -@end smallexample - -Return the depth of the stack. If the integer argument @var{max-depth} -is specified, do not count beyond @var{max-depth} frames. - -@subsubheading @value{GDBN} Command - -There's no equivalent @value{GDBN} command. - -@subsubheading Example - -For a stack with frame levels 0 through 11: - -@smallexample -(@value{GDBP}) --stack-info-depth -^done,depth="12" -(@value{GDBP}) --stack-info-depth 4 -^done,depth="4" -(@value{GDBP}) --stack-info-depth 12 -^done,depth="12" -(@value{GDBP}) --stack-info-depth 11 -^done,depth="11" -(@value{GDBP}) --stack-info-depth 13 -^done,depth="12" -(@value{GDBP}) -@end smallexample - -@subheading The @code{-stack-list-arguments} Command -@findex -stack-list-arguments - -@subsubheading Synopsis - -@smallexample - -stack-list-arguments @var{show-values} - [ @var{low-frame} @var{high-frame} ] -@end smallexample - -Display a list of the arguments for the frames between @var{low-frame} -and @var{high-frame} (inclusive). If @var{low-frame} and -@var{high-frame} are not provided, list the arguments for the whole call -stack. - -The @var{show-values} argument must have a value of 0 or 1. A value of -0 means that only the names of the arguments are listed, a value of 1 -means that both names and values of the arguments are printed. - -@subsubheading @value{GDBN} Command - -@value{GDBN} does not have an equivalent command. @code{gdbtk} has a -@samp{gdb_get_args} command which partially overlaps with the -functionality of @samp{-stack-list-arguments}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --stack-list-frames -^done, -stack=[ -frame=@{level="0",addr="0x00010734",func="callee4", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}, -frame=@{level="1",addr="0x0001076c",func="callee3", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}, -frame=@{level="2",addr="0x0001078c",func="callee2", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@}, -frame=@{level="3",addr="0x000107b4",func="callee1", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@}, -frame=@{level="4",addr="0x000107e0",func="main", -file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}] -(@value{GDBP}) --stack-list-arguments 0 -^done, -stack-args=[ -frame=@{level="0",args=[]@}, -frame=@{level="1",args=[name="strarg"]@}, -frame=@{level="2",args=[name="intarg",name="strarg"]@}, -frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, -frame=@{level="4",args=[]@}] -(@value{GDBP}) --stack-list-arguments 1 -^done, -stack-args=[ -frame=@{level="0",args=[]@}, -frame=@{level="1", - args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, -frame=@{level="2",args=[ -@{name="intarg",value="2"@}, -@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, -@{frame=@{level="3",args=[ -@{name="intarg",value="2"@}, -@{name="strarg",value="0x11940 \"A string argument.\""@}, -@{name="fltarg",value="3.5"@}]@}, -frame=@{level="4",args=[]@}] -(@value{GDBP}) --stack-list-arguments 0 2 2 -^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] -(@value{GDBP}) --stack-list-arguments 1 2 2 -^done,stack-args=[frame=@{level="2", -args=[@{name="intarg",value="2"@}, -@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] -(@value{GDBP}) -@end smallexample - -@c @subheading -stack-list-exception-handlers - - -@subheading The @code{-stack-list-frames} Command -@findex -stack-list-frames - -@subsubheading Synopsis - -@smallexample - -stack-list-frames [ @var{low-frame} @var{high-frame} ] -@end smallexample - -List the frames currently on the stack. For each frame it displays the -following info: - -@table @samp -@item @var{level} -The frame number, 0 being the topmost frame, i.e. the innermost function. -@item @var{addr} -The @code{$pc} value for that frame. -@item @var{func} -Function name. -@item @var{file} -File name of the source file where the function lives. -@item @var{line} -Line number corresponding to the @code{$pc}. -@end table - -If invoked without arguments, this command prints a backtrace for the -whole stack. If given two integer arguments, it shows the frames whose -levels are between the two arguments (inclusive). If the two arguments -are equal, it shows the single frame at the corresponding level. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. - -@subsubheading Example - -Full stack backtrace: - -@smallexample -(@value{GDBP}) --stack-list-frames -^done,stack= -[frame=@{level="0",addr="0x0001076c",func="foo", - file="recursive2.c",line="11"@}, -frame=@{level="1",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="2",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="4",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="5",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="6",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="7",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="8",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="9",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="10",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="11",addr="0x00010738",func="main", - file="recursive2.c",line="4"@}] -(@value{GDBP}) -@end smallexample - -Show frames between @var{low_frame} and @var{high_frame}: - -@smallexample -(@value{GDBP}) --stack-list-frames 3 5 -^done,stack= -[frame=@{level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="4",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}, -frame=@{level="5",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}] -(@value{GDBP}) -@end smallexample - -Show a single frame: - -@smallexample -(@value{GDBP}) --stack-list-frames 3 3 -^done,stack= -[frame=@{level="3",addr="0x000107a4",func="foo", - file="recursive2.c",line="14"@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-stack-list-locals} Command -@findex -stack-list-locals - -@subsubheading Synopsis - -@smallexample - -stack-list-locals @var{print-values} -@end smallexample - -Display the local variable names for the current frame. With an -argument of 0 or @code{--no-values}, prints only the names of the variables. -With argument of 1 or @code{--all-values}, prints also their values. With -argument of 2 or @code{--simple-values}, prints the name, type and value for -simple data types and the name and type for arrays, structures and -unions. In this last case, the idea is that the user can see the -value of simple data types immediately and he can create variable -objects for other data types if he wishes to explore their values in -more detail. - -@subsubheading @value{GDBN} Command - -@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --stack-list-locals 0 -^done,locals=[name="A",name="B",name="C"] -(@value{GDBP}) --stack-list-locals --all-values -^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, - @{name="C",value="@{1, 2, 3@}"@}] --stack-list-locals --simple-values -^done,locals=[@{name="A",type="int",value="1"@}, - @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-stack-select-frame} Command -@findex -stack-select-frame - -@subsubheading Synopsis - -@smallexample - -stack-select-frame @var{framenum} -@end smallexample - -Change the current frame. Select a different frame @var{framenum} on -the stack. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, -@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --stack-select-frame 2 -^done -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Symbol Query -@section @sc{gdb/mi} Symbol Query Commands - - -@subheading The @code{-symbol-info-address} Command -@findex -symbol-info-address - -@subsubheading Synopsis - -@smallexample - -symbol-info-address @var{symbol} -@end smallexample - -Describe where @var{symbol} is stored. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info address}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-info-file} Command -@findex -symbol-info-file - -@subsubheading Synopsis - -@smallexample - -symbol-info-file -@end smallexample - -Show the file for the symbol. - -@subsubheading @value{GDBN} Command - -There's no equivalent @value{GDBN} command. @code{gdbtk} has -@samp{gdb_find_file}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-info-function} Command -@findex -symbol-info-function - -@subsubheading Synopsis - -@smallexample - -symbol-info-function -@end smallexample - -Show which function the symbol lives in. - -@subsubheading @value{GDBN} Command - -@samp{gdb_get_function} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-info-line} Command -@findex -symbol-info-line - -@subsubheading Synopsis - -@smallexample - -symbol-info-line -@end smallexample - -Show the core addresses of the code for a source line. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info line}. -@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-info-symbol} Command -@findex -symbol-info-symbol - -@subsubheading Synopsis - -@smallexample - -symbol-info-symbol @var{addr} -@end smallexample - -Describe what symbol is at location @var{addr}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{info symbol}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-list-functions} Command -@findex -symbol-list-functions - -@subsubheading Synopsis - -@smallexample - -symbol-list-functions -@end smallexample - -List the functions in the executable. - -@subsubheading @value{GDBN} Command - -@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and -@samp{gdb_search} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-list-lines} Command -@findex -symbol-list-lines - -@subsubheading Synopsis - -@smallexample - -symbol-list-lines @var{filename} -@end smallexample - -Print the list of lines that contain code and their associated program -addresses for the given source filename. The entries are sorted in -ascending PC order. - -@subsubheading @value{GDBN} Command - -There is no corresponding @value{GDBN} command. - -@subsubheading Example -@smallexample -(@value{GDBP}) --symbol-list-lines basics.c -^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}] -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-symbol-list-types} Command -@findex -symbol-list-types - -@subsubheading Synopsis - -@smallexample - -symbol-list-types -@end smallexample - -List all the type names. - -@subsubheading @value{GDBN} Command - -The corresponding commands are @samp{info types} in @value{GDBN}, -@samp{gdb_search} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-list-variables} Command -@findex -symbol-list-variables - -@subsubheading Synopsis - -@smallexample - -symbol-list-variables -@end smallexample - -List all the global and static variable names. - -@subsubheading @value{GDBN} Command - -@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-locate} Command -@findex -symbol-locate - -@subsubheading Synopsis - -@smallexample - -symbol-locate -@end smallexample - -@subsubheading @value{GDBN} Command - -@samp{gdb_loc} in @code{gdbtk}. - -@subsubheading Example -N.A. - - -@subheading The @code{-symbol-type} Command -@findex -symbol-type - -@subsubheading Synopsis - -@smallexample - -symbol-type @var{variable} -@end smallexample - -Show type of @var{variable}. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has -@samp{gdb_obj_variable}. - -@subsubheading Example -N.A. - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Target Manipulation -@section @sc{gdb/mi} Target Manipulation Commands - - -@subheading The @code{-target-attach} Command -@findex -target-attach - -@subsubheading Synopsis - -@smallexample - -target-attach @var{pid} | @var{file} -@end smallexample - -Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{attach}. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-compare-sections} Command -@findex -target-compare-sections - -@subsubheading Synopsis - -@smallexample - -target-compare-sections [ @var{section} ] -@end smallexample - -Compare data of section @var{section} on target to the exec file. -Without the argument, all sections are compared. - -@subsubheading @value{GDBN} Command - -The @value{GDBN} equivalent is @samp{compare-sections}. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-detach} Command -@findex -target-detach - -@subsubheading Synopsis - -@smallexample - -target-detach -@end smallexample - -Disconnect from the remote target. There's no output. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{detach}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --target-detach -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-target-disconnect} Command -@findex -target-disconnect - -@subsubheading Synopsis - -@example - -target-disconnect -@end example - -Disconnect from the remote target. There's no output. - -@subsubheading @value{GDBN} command - -The corresponding @value{GDBN} command is @samp{disconnect}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --target-disconnect -^done -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-target-download} Command -@findex -target-download - -@subsubheading Synopsis - -@smallexample - -target-download -@end smallexample - -Loads the executable onto the remote target. -It prints out an update message every half second, which includes the fields: - -@table @samp -@item section -The name of the section. -@item section-sent -The size of what has been sent so far for that section. -@item section-size -The size of the section. -@item total-sent -The total size of what was sent so far (the current and the previous sections). -@item total-size -The size of the overall executable to download. -@end table - -@noindent -Each message is sent as status record (@pxref{GDB/MI Output Syntax, , -@sc{gdb/mi} Output Syntax}). - -In addition, it prints the name and size of the sections, as they are -downloaded. These messages include the following fields: - -@table @samp -@item section -The name of the section. -@item section-size -The size of the section. -@item total-size -The size of the overall executable to download. -@end table - -@noindent -At the end, a summary is printed. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{load}. - -@subsubheading Example - -Note: each status message appears on a single line. Here the messages -have been broken down so that they can fit onto a page. - -@smallexample -(@value{GDBP}) --target-download -+download,@{section=".text",section-size="6668",total-size="9880"@} -+download,@{section=".text",section-sent="512",section-size="6668", -total-sent="512",total-size="9880"@} -+download,@{section=".text",section-sent="1024",section-size="6668", -total-sent="1024",total-size="9880"@} -+download,@{section=".text",section-sent="1536",section-size="6668", -total-sent="1536",total-size="9880"@} -+download,@{section=".text",section-sent="2048",section-size="6668", -total-sent="2048",total-size="9880"@} -+download,@{section=".text",section-sent="2560",section-size="6668", -total-sent="2560",total-size="9880"@} -+download,@{section=".text",section-sent="3072",section-size="6668", -total-sent="3072",total-size="9880"@} -+download,@{section=".text",section-sent="3584",section-size="6668", -total-sent="3584",total-size="9880"@} -+download,@{section=".text",section-sent="4096",section-size="6668", -total-sent="4096",total-size="9880"@} -+download,@{section=".text",section-sent="4608",section-size="6668", -total-sent="4608",total-size="9880"@} -+download,@{section=".text",section-sent="5120",section-size="6668", -total-sent="5120",total-size="9880"@} -+download,@{section=".text",section-sent="5632",section-size="6668", -total-sent="5632",total-size="9880"@} -+download,@{section=".text",section-sent="6144",section-size="6668", -total-sent="6144",total-size="9880"@} -+download,@{section=".text",section-sent="6656",section-size="6668", -total-sent="6656",total-size="9880"@} -+download,@{section=".init",section-size="28",total-size="9880"@} -+download,@{section=".fini",section-size="28",total-size="9880"@} -+download,@{section=".data",section-size="3156",total-size="9880"@} -+download,@{section=".data",section-sent="512",section-size="3156", -total-sent="7236",total-size="9880"@} -+download,@{section=".data",section-sent="1024",section-size="3156", -total-sent="7748",total-size="9880"@} -+download,@{section=".data",section-sent="1536",section-size="3156", -total-sent="8260",total-size="9880"@} -+download,@{section=".data",section-sent="2048",section-size="3156", -total-sent="8772",total-size="9880"@} -+download,@{section=".data",section-sent="2560",section-size="3156", -total-sent="9284",total-size="9880"@} -+download,@{section=".data",section-sent="3072",section-size="3156", -total-sent="9796",total-size="9880"@} -^done,address="0x10004",load-size="9880",transfer-rate="6586", -write-rate="429" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-target-exec-status} Command -@findex -target-exec-status - -@subsubheading Synopsis - -@smallexample - -target-exec-status -@end smallexample - -Provide information on the state of the target (whether it is running or -not, for instance). - -@subsubheading @value{GDBN} Command - -There's no equivalent @value{GDBN} command. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-list-available-targets} Command -@findex -target-list-available-targets - -@subsubheading Synopsis - -@smallexample - -target-list-available-targets -@end smallexample - -List the possible targets to connect to. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{help target}. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-list-current-targets} Command -@findex -target-list-current-targets - -@subsubheading Synopsis - -@smallexample - -target-list-current-targets -@end smallexample - -Describe the current target. - -@subsubheading @value{GDBN} Command - -The corresponding information is printed by @samp{info file} (among -other things). - -@subsubheading Example -N.A. - - -@subheading The @code{-target-list-parameters} Command -@findex -target-list-parameters - -@subsubheading Synopsis - -@smallexample - -target-list-parameters -@end smallexample - -@c ???? - -@subsubheading @value{GDBN} Command - -No equivalent. - -@subsubheading Example -N.A. - - -@subheading The @code{-target-select} Command -@findex -target-select - -@subsubheading Synopsis - -@smallexample - -target-select @var{type} @var{parameters @dots{}} -@end smallexample - -Connect @value{GDBN} to the remote target. This command takes two args: - -@table @samp -@item @var{type} -The type of target, for instance @samp{async}, @samp{remote}, etc. -@item @var{parameters} -Device names, host names and the like. @xref{Target Commands, , -Commands for managing targets}, for more details. -@end table - -The output is a connection notification, followed by the address at -which the target program is, in the following form: - -@smallexample -^connected,addr="@var{address}",func="@var{function name}", - args=[@var{arg list}] -@end smallexample - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{target}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --target-select async /dev/ttya -^connected,addr="0xfe00a300",func="??",args=[] -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Thread Commands -@section @sc{gdb/mi} Thread Commands - - -@subheading The @code{-thread-info} Command -@findex -thread-info - -@subsubheading Synopsis - -@smallexample - -thread-info -@end smallexample - -@subsubheading @value{GDBN} command - -No equivalent. - -@subsubheading Example -N.A. - - -@subheading The @code{-thread-list-all-threads} Command -@findex -thread-list-all-threads - -@subsubheading Synopsis - -@smallexample - -thread-list-all-threads -@end smallexample - -@subsubheading @value{GDBN} Command - -The equivalent @value{GDBN} command is @samp{info threads}. - -@subsubheading Example -N.A. - - -@subheading The @code{-thread-list-ids} Command -@findex -thread-list-ids - -@subsubheading Synopsis - -@smallexample - -thread-list-ids -@end smallexample - -Produces a list of the currently known @value{GDBN} thread ids. At the -end of the list it also prints the total number of such threads. - -@subsubheading @value{GDBN} Command - -Part of @samp{info threads} supplies the same information. - -@subsubheading Example - -No threads present, besides the main process: - -@smallexample -(@value{GDBP}) --thread-list-ids -^done,thread-ids=@{@},number-of-threads="0" -(@value{GDBP}) -@end smallexample - - -Several threads: - -@smallexample -(@value{GDBP}) --thread-list-ids -^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, -number-of-threads="3" -(@value{GDBP}) -@end smallexample - - -@subheading The @code{-thread-select} Command -@findex -thread-select - -@subsubheading Synopsis - -@smallexample - -thread-select @var{threadnum} -@end smallexample - -Make @var{threadnum} the current thread. It prints the number of the new -current thread, and the topmost frame for that thread. - -@subsubheading @value{GDBN} Command - -The corresponding @value{GDBN} command is @samp{thread}. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --exec-next -^running -(@value{GDBP}) -*stopped,reason="end-stepping-range",thread-id="2",line="187", -file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" -(@value{GDBP}) --thread-list-ids -^done, -thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, -number-of-threads="3" -(@value{GDBP}) --thread-select 3 -^done,new-thread-id="3", -frame=@{level="0",func="vprintf", -args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, -@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@} -(@value{GDBP}) -@end smallexample - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Tracepoint Commands -@section @sc{gdb/mi} Tracepoint Commands - -The tracepoint commands are not yet implemented. - -@c @subheading -trace-actions - -@c @subheading -trace-delete - -@c @subheading -trace-disable - -@c @subheading -trace-dump - -@c @subheading -trace-enable - -@c @subheading -trace-exists - -@c @subheading -trace-find - -@c @subheading -trace-frame-number - -@c @subheading -trace-info - -@c @subheading -trace-insert - -@c @subheading -trace-list - -@c @subheading -trace-pass-count - -@c @subheading -trace-save - -@c @subheading -trace-start - -@c @subheading -trace-stop - - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@node GDB/MI Variable Objects -@section @sc{gdb/mi} Variable Objects - - -@subheading Motivation for Variable Objects in @sc{gdb/mi} - -For the implementation of a variable debugger window (locals, watched -expressions, etc.), we are proposing the adaptation of the existing code -used by @code{Insight}. - -The two main reasons for that are: - -@enumerate 1 -@item -It has been proven in practice (it is already on its second generation). - -@item -It will shorten development time (needless to say how important it is -now). -@end enumerate - -The original interface was designed to be used by Tcl code, so it was -slightly changed so it could be used through @sc{gdb/mi}. This section -describes the @sc{gdb/mi} operations that will be available and gives some -hints about their use. - -@emph{Note}: In addition to the set of operations described here, we -expect the @sc{gui} implementation of a variable window to require, at -least, the following operations: - -@itemize @bullet -@item @code{-gdb-show} @code{output-radix} -@item @code{-stack-list-arguments} -@item @code{-stack-list-locals} -@item @code{-stack-select-frame} -@end itemize - -@subheading Introduction to Variable Objects in @sc{gdb/mi} - -@cindex variable objects in @sc{gdb/mi} -The basic idea behind variable objects is the creation of a named object -to represent a variable, an expression, a memory location or even a CPU -register. For each object created, a set of operations is available for -examining or changing its properties. - -Furthermore, complex data types, such as C structures, are represented -in a tree format. For instance, the @code{struct} type variable is the -root and the children will represent the struct members. If a child -is itself of a complex type, it will also have children of its own. -Appropriate language differences are handled for C, C@t{++} and Java. - -When returning the actual values of the objects, this facility allows -for the individual selection of the display format used in the result -creation. It can be chosen among: binary, decimal, hexadecimal, octal -and natural. Natural refers to a default format automatically -chosen based on the variable type (like decimal for an @code{int}, hex -for pointers, etc.). - -The following is the complete set of @sc{gdb/mi} operations defined to -access this functionality: - -@multitable @columnfractions .4 .6 -@item @strong{Operation} -@tab @strong{Description} - -@item @code{-var-create} -@tab create a variable object -@item @code{-var-delete} -@tab delete the variable object and its children -@item @code{-var-set-format} -@tab set the display format of this variable -@item @code{-var-show-format} -@tab show the display format of this variable -@item @code{-var-info-num-children} -@tab tells how many children this object has -@item @code{-var-list-children} -@tab return a list of the object's children -@item @code{-var-info-type} -@tab show the type of this variable object -@item @code{-var-info-expression} -@tab print what this variable object represents -@item @code{-var-show-attributes} -@tab is this variable editable? does it exist here? -@item @code{-var-evaluate-expression} -@tab get the value of this variable -@item @code{-var-assign} -@tab set the value of this variable -@item @code{-var-update} -@tab update the variable and its children -@end multitable - -In the next subsection we describe each operation in detail and suggest -how it can be used. - -@subheading Description And Use of Operations on Variable Objects - -@subheading The @code{-var-create} Command -@findex -var-create - -@subsubheading Synopsis - -@smallexample - -var-create @{@var{name} | "-"@} - @{@var{frame-addr} | "*"@} @var{expression} -@end smallexample - -This operation creates a variable object, which allows the monitoring of -a variable, the result of an expression, a memory cell or a CPU -register. - -The @var{name} parameter is the string by which the object can be -referenced. It must be unique. If @samp{-} is specified, the varobj -system will generate a string ``varNNNNNN'' automatically. It will be -unique provided that one does not specify @var{name} on that format. -The command fails if a duplicate name is found. - -The frame under which the expression should be evaluated can be -specified by @var{frame-addr}. A @samp{*} indicates that the current -frame should be used. - -@var{expression} is any expression valid on the current language set (must not -begin with a @samp{*}), or one of the following: - -@itemize @bullet -@item -@samp{*@var{addr}}, where @var{addr} is the address of a memory cell - -@item -@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) - -@item -@samp{$@var{regname}} --- a CPU register name -@end itemize - -@subsubheading Result - -This operation returns the name, number of children and the type of the -object created. Type is returned as a string as the ones generated by -the @value{GDBN} CLI: - -@smallexample - name="@var{name}",numchild="N",type="@var{type}" -@end smallexample - - -@subheading The @code{-var-delete} Command -@findex -var-delete - -@subsubheading Synopsis - -@smallexample - -var-delete @var{name} -@end smallexample - -Deletes a previously created variable object and all of its children. - -Returns an error if the object @var{name} is not found. - - -@subheading The @code{-var-set-format} Command -@findex -var-set-format - -@subsubheading Synopsis - -@smallexample - -var-set-format @var{name} @var{format-spec} -@end smallexample - -Sets the output format for the value of the object @var{name} to be -@var{format-spec}. - -The syntax for the @var{format-spec} is as follows: - -@smallexample - @var{format-spec} @expansion{} - @{binary | decimal | hexadecimal | octal | natural@} -@end smallexample - - -@subheading The @code{-var-show-format} Command -@findex -var-show-format - -@subsubheading Synopsis - -@smallexample - -var-show-format @var{name} -@end smallexample - -Returns the format used to display the value of the object @var{name}. - -@smallexample - @var{format} @expansion{} - @var{format-spec} -@end smallexample - - -@subheading The @code{-var-info-num-children} Command -@findex -var-info-num-children - -@subsubheading Synopsis - -@smallexample - -var-info-num-children @var{name} -@end smallexample - -Returns the number of children of a variable object @var{name}: - -@smallexample - numchild=@var{n} -@end smallexample - - -@subheading The @code{-var-list-children} Command -@findex -var-list-children - -@subsubheading Synopsis - -@smallexample - -var-list-children [@var{print-values}] @var{name} -@end smallexample - -Returns a list of the children of the specified variable object. With -just the variable object name as an argument or with an optional -preceding argument of 0 or @code{--no-values}, prints only the names of the -variables. With an optional preceding argument of 1 or @code{--all-values}, -also prints their values. - -@subsubheading Example - -@smallexample -(@value{GDBP}) - -var-list-children n - numchild=@var{n},children=[@{name=@var{name}, - numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] -(@value{GDBP}) - -var-list-children --all-values n - numchild=@var{n},children=[@{name=@var{name}, - numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] -@end smallexample - - -@subheading The @code{-var-info-type} Command -@findex -var-info-type - -@subsubheading Synopsis - -@smallexample - -var-info-type @var{name} -@end smallexample - -Returns the type of the specified variable @var{name}. The type is -returned as a string in the same format as it is output by the -@value{GDBN} CLI: - -@smallexample - type=@var{typename} -@end smallexample - - -@subheading The @code{-var-info-expression} Command -@findex -var-info-expression - -@subsubheading Synopsis - -@smallexample - -var-info-expression @var{name} -@end smallexample - -Returns what is represented by the variable object @var{name}: - -@smallexample - lang=@var{lang-spec},exp=@var{expression} -@end smallexample - -@noindent -where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}. - -@subheading The @code{-var-show-attributes} Command -@findex -var-show-attributes - -@subsubheading Synopsis - -@smallexample - -var-show-attributes @var{name} -@end smallexample - -List attributes of the specified variable object @var{name}: - -@smallexample - status=@var{attr} [ ( ,@var{attr} )* ] -@end smallexample - -@noindent -where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. - -@subheading The @code{-var-evaluate-expression} Command -@findex -var-evaluate-expression - -@subsubheading Synopsis - -@smallexample - -var-evaluate-expression @var{name} -@end smallexample - -Evaluates the expression that is represented by the specified variable -object and returns its value as a string in the current format specified -for the object: - -@smallexample - value=@var{value} -@end smallexample - -Note that one must invoke @code{-var-list-children} for a variable -before the value of a child variable can be evaluated. - -@subheading The @code{-var-assign} Command -@findex -var-assign - -@subsubheading Synopsis - -@smallexample - -var-assign @var{name} @var{expression} -@end smallexample - -Assigns the value of @var{expression} to the variable object specified -by @var{name}. The object must be @samp{editable}. If the variable's -value is altered by the assign, the variable will show up in any -subsequent @code{-var-update} list. - -@subsubheading Example - -@smallexample -(@value{GDBP}) --var-assign var1 3 -^done,value="3" -(@value{GDBP}) --var-update * -^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] -(@value{GDBP}) -@end smallexample - -@subheading The @code{-var-update} Command -@findex -var-update - -@subsubheading Synopsis - -@smallexample - -var-update @{@var{name} | "*"@} -@end smallexample - -Update the value of the variable object @var{name} by evaluating its -expression after fetching all the new values from memory or registers. -A @samp{*} causes all existing variable objects to be updated. - - -@node Annotations -@chapter @value{GDBN} Annotations - -This chapter describes annotations in @value{GDBN}. Annotations were -designed to interface @value{GDBN} to graphical user interfaces or other -similar programs which want to interact with @value{GDBN} at a -relatively high level. - -The annotation mechanism has largely been superseeded by @sc{gdb/mi} -(@pxref{GDB/MI}). - -@ignore -This is Edition @value{EDITION}, @value{DATE}. -@end ignore - -@menu -* Annotations Overview:: What annotations are; the general syntax. -* Server Prefix:: Issuing a command without affecting user state. -* Prompting:: Annotations marking @value{GDBN}'s need for input. -* Errors:: Annotations for error messages. -* Invalidation:: Some annotations describe things now invalid. -* Annotations for Running:: - Whether the program is running, how it stopped, etc. -* Source Annotations:: Annotations describing source code. -@end menu - -@node Annotations Overview -@section What is an Annotation? -@cindex annotations - -Annotations start with a newline character, two @samp{control-z} -characters, and the name of the annotation. If there is no additional -information associated with this annotation, the name of the annotation -is followed immediately by a newline. If there is additional -information, the name of the annotation is followed by a space, the -additional information, and a newline. The additional information -cannot contain newline characters. - -Any output not beginning with a newline and two @samp{control-z} -characters denotes literal output from @value{GDBN}. Currently there is -no need for @value{GDBN} to output a newline followed by two -@samp{control-z} characters, but if there was such a need, the -annotations could be extended with an @samp{escape} annotation which -means those three characters as output. - -The annotation @var{level}, which is specified using the -@option{--annotate} command line option (@pxref{Mode Options}), controls -how much information @value{GDBN} prints together with its prompt, -values of expressions, source lines, and other types of output. Level 0 -is for no anntations, level 1 is for use when @value{GDBN} is run as a -subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable -for programs that control @value{GDBN}, and level 2 annotations have -been made obsolete (@pxref{Limitations, , Limitations of the Annotation -Interface, annotate, GDB's Obsolete Annotations}). This chapter -describes level 3 annotations. - -A simple example of starting up @value{GDBN} with annotations is: - -@smallexample -$ @kbd{gdb --annotate=3} -GNU gdb 6.0 -Copyright 2003 Free Software Foundation, Inc. -GDB is free software, covered by the GNU General Public License, -and you are welcome to change it and/or distribute copies of it -under certain conditions. -Type "show copying" to see the conditions. -There is absolutely no warranty for GDB. Type "show warranty" -for details. -This GDB was configured as "i386-pc-linux-gnu" - -^Z^Zpre-prompt -(gdb) -^Z^Zprompt -@kbd{quit} - -^Z^Zpost-prompt -$ -@end smallexample - -Here @samp{quit} is input to @value{GDBN}; the rest is output from -@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} -denotes a @samp{control-z} character) are annotations; the rest is -output from @value{GDBN}. - -@node Server Prefix -@section The Server Prefix -@cindex server prefix for annotations - -To issue a command to @value{GDBN} without affecting certain aspects of -the state which is seen by users, prefix it with @samp{server }. This -means that this command will not affect the command history, nor will it -affect @value{GDBN}'s notion of which command to repeat if @key{RET} is -pressed on a line by itself. - -The server prefix does not affect the recording of values into the value -history; to print a value without recording it into the value history, -use the @code{output} command instead of the @code{print} command. - -@node Prompting -@section Annotation for @value{GDBN} Input - -@cindex annotations for prompts -When @value{GDBN} prompts for input, it annotates this fact so it is possible -to know when to send output, when the output from a given command is -over, etc. - -Different kinds of input each have a different @dfn{input type}. Each -input type has three annotations: a @code{pre-} annotation, which -denotes the beginning of any prompt which is being output, a plain -annotation, which denotes the end of the prompt, and then a @code{post-} -annotation which denotes the end of any echo which may (or may not) be -associated with the input. For example, the @code{prompt} input type -features the following annotations: - -@smallexample -^Z^Zpre-prompt -^Z^Zprompt -^Z^Zpost-prompt -@end smallexample - -The input types are - -@table @code -@findex pre-prompt -@findex prompt -@findex post-prompt -@item prompt -When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). - -@findex pre-commands -@findex commands -@findex post-commands -@item commands -When @value{GDBN} prompts for a set of commands, like in the @code{commands} -command. The annotations are repeated for each command which is input. - -@findex pre-overload-choice -@findex overload-choice -@findex post-overload-choice -@item overload-choice -When @value{GDBN} wants the user to select between various overloaded functions. - -@findex pre-query -@findex query -@findex post-query -@item query -When @value{GDBN} wants the user to confirm a potentially dangerous operation. - -@findex pre-prompt-for-continue -@findex prompt-for-continue -@findex post-prompt-for-continue -@item prompt-for-continue -When @value{GDBN} is asking the user to press return to continue. Note: Don't -expect this to work well; instead use @code{set height 0} to disable -prompting. This is because the counting of lines is buggy in the -presence of annotations. -@end table - -@node Errors -@section Errors -@cindex annotations for errors, warnings and interrupts - -@findex quit -@smallexample -^Z^Zquit -@end smallexample - -This annotation occurs right before @value{GDBN} responds to an interrupt. - -@findex error -@smallexample -^Z^Zerror -@end smallexample - -This annotation occurs right before @value{GDBN} responds to an error. - -Quit and error annotations indicate that any annotations which @value{GDBN} was -in the middle of may end abruptly. For example, if a -@code{value-history-begin} annotation is followed by a @code{error}, one -cannot expect to receive the matching @code{value-history-end}. One -cannot expect not to receive it either, however; an error annotation -does not necessarily mean that @value{GDBN} is immediately returning all the way -to the top level. - -@findex error-begin -A quit or error annotation may be preceded by - -@smallexample -^Z^Zerror-begin -@end smallexample - -Any output between that and the quit or error annotation is the error -message. - -Warning messages are not yet annotated. -@c If we want to change that, need to fix warning(), type_error(), -@c range_error(), and possibly other places. - -@node Invalidation -@section Invalidation Notices - -@cindex annotations for invalidation messages -The following annotations say that certain pieces of state may have -changed. - -@table @code -@findex frames-invalid -@item ^Z^Zframes-invalid - -The frames (for example, output from the @code{backtrace} command) may -have changed. - -@findex breakpoints-invalid -@item ^Z^Zbreakpoints-invalid - -The breakpoints may have changed. For example, the user just added or -deleted a breakpoint. -@end table - -@node Annotations for Running -@section Running the Program -@cindex annotations for running programs - -@findex starting -@findex stopping -When the program starts executing due to a @value{GDBN} command such as -@code{step} or @code{continue}, - -@smallexample -^Z^Zstarting -@end smallexample - -is output. When the program stops, - -@smallexample -^Z^Zstopped -@end smallexample - -is output. Before the @code{stopped} annotation, a variety of -annotations describe how the program stopped. - -@table @code -@findex exited -@item ^Z^Zexited @var{exit-status} -The program exited, and @var{exit-status} is the exit status (zero for -successful exit, otherwise nonzero). - -@findex signalled -@findex signal-name -@findex signal-name-end -@findex signal-string -@findex signal-string-end -@item ^Z^Zsignalled -The program exited with a signal. After the @code{^Z^Zsignalled}, the -annotation continues: - -@smallexample -@var{intro-text} -^Z^Zsignal-name -@var{name} -^Z^Zsignal-name-end -@var{middle-text} -^Z^Zsignal-string -@var{string} -^Z^Zsignal-string-end -@var{end-text} -@end smallexample - -@noindent -where @var{name} is the name of the signal, such as @code{SIGILL} or -@code{SIGSEGV}, and @var{string} is the explanation of the signal, such -as @code{Illegal Instruction} or @code{Segmentation fault}. -@var{intro-text}, @var{middle-text}, and @var{end-text} are for the -user's benefit and have no particular format. - -@findex signal -@item ^Z^Zsignal -The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is -just saying that the program received the signal, not that it was -terminated with it. - -@findex breakpoint -@item ^Z^Zbreakpoint @var{number} -The program hit breakpoint number @var{number}. - -@findex watchpoint -@item ^Z^Zwatchpoint @var{number} -The program hit watchpoint number @var{number}. -@end table - -@node Source Annotations -@section Displaying Source -@cindex annotations for source display - -@findex source -The following annotation is used instead of displaying source code: - -@smallexample -^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} -@end smallexample - -where @var{filename} is an absolute file name indicating which source -file, @var{line} is the line number within that file (where 1 is the -first line in the file), @var{character} is the character position -within the file (where 0 is the first character in the file) (for most -debug formats this will necessarily point to the beginning of a line), -@var{middle} is @samp{middle} if @var{addr} is in the middle of the -line, or @samp{beg} if @var{addr} is at the beginning of the line, and -@var{addr} is the address in the target program associated with the -source which is being displayed. @var{addr} is in the form @samp{0x} -followed by one or more lowercase hex digits (note that this does not -depend on the language). - -@node GDB Bugs -@chapter Reporting Bugs in @value{GDBN} -@cindex bugs in @value{GDBN} -@cindex reporting bugs in @value{GDBN} - -Your bug reports play an essential role in making @value{GDBN} reliable. - -Reporting a bug may help you by bringing a solution to your problem, or it -may not. But in any case the principal function of a bug report is to help -the entire community by making the next version of @value{GDBN} work better. Bug -reports are your contribution to the maintenance of @value{GDBN}. - -In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -@menu -* Bug Criteria:: Have you found a bug? -* Bug Reporting:: How to report bugs -@end menu - -@node Bug Criteria -@section Have you found a bug? -@cindex bug criteria - -If you are not sure whether you have found a bug, here are some guidelines: - -@itemize @bullet -@cindex fatal signal -@cindex debugger crash -@cindex crash of debugger -@item -If the debugger gets a fatal signal, for any input whatever, that is a -@value{GDBN} bug. Reliable debuggers never crash. - -@cindex error on valid input -@item -If @value{GDBN} produces an error message for valid input, that is a -bug. (Note that if you're cross debugging, the problem may also be -somewhere in the connection to the target.) - -@cindex invalid input -@item -If @value{GDBN} does not produce an error message for invalid input, -that is a bug. However, you should note that your idea of -``invalid input'' might be our idea of ``an extension'' or ``support -for traditional practice''. - -@item -If you are an experienced user of debugging tools, your suggestions -for improvement of @value{GDBN} are welcome in any case. -@end itemize - -@node Bug Reporting -@section How to report bugs -@cindex bug reports -@cindex @value{GDBN} bugs, reporting - -A number of companies and individuals offer support for @sc{gnu} products. -If you obtained @value{GDBN} from a support organization, we recommend you -contact that organization first. - -You can find contact information for many support companies and -individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs -distribution. -@c should add a web page ref... - -In any event, we also recommend that you submit bug reports for -@value{GDBN}. The prefered method is to submit them directly using -@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web -page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can -be used. - -@strong{Do not send bug reports to @samp{info-gdb}, or to -@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do -not want to receive bug reports. Those that do have arranged to receive -@samp{bug-gdb}. - -The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which -serves as a repeater. The mailing list and the newsgroup carry exactly -the same messages. Often people think of posting bug reports to the -newsgroup instead of mailing them. This appears to work, but it has one -problem which can be crucial: a newsgroup posting often lacks a mail -path back to the sender. Thus, if we need to ask for more information, -we may be unable to reach you. For this reason, it is better to send -bug reports to the mailing list. - -The fundamental principle of reporting bugs usefully is this: -@strong{report all the facts}. If you are not sure whether to state a -fact or leave it out, state it! - -Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of the variable you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is a -stray memory reference which happens to fetch from the location where that -name is stored in memory; perhaps, if the name were different, the contents -of that location would fool the debugger into doing the right thing despite -the bug. Play it safe and give a specific, complete example. That is the -easiest thing for you to do, and the most helpful. - -Keep in mind that the purpose of a bug report is to enable us to fix the -bug. It may be that the bug has been reported previously, but neither -you nor we can know that unless your bug report is complete and -self-contained. - -Sometimes people give a few sketchy facts and ask, ``Does this ring a -bell?'' Those bug reports are useless, and we urge everyone to -@emph{refuse to respond to them} except to chide the sender to report -bugs properly. - -To enable us to fix the bug, you should include all these things: - -@itemize @bullet -@item -The version of @value{GDBN}. @value{GDBN} announces it if you start -with no arguments; you can also print it at any time using @code{show -version}. - -Without this, we will not know whether there is any point in looking for -the bug in the current version of @value{GDBN}. - -@item -The type of machine you are using, and the operating system name and -version number. - -@item -What compiler (and its version) was used to compile @value{GDBN}---e.g. -``@value{GCC}--2.8.1''. - -@item -What compiler (and its version) was used to compile the program you are -debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP -C Compiler''. For GCC, you can say @code{gcc --version} to get this -information; for other compilers, see the documentation for those -compilers. - -@item -The command arguments you gave the compiler to compile your example and -observe the bug. For example, did you use @samp{-O}? To guarantee -you will not omit something important, list them all. A copy of the -Makefile (or the output from make) is sufficient. - -If we were to try to guess the arguments, we would probably guess wrong -and then we might not encounter the bug. - -@item -A complete input script, and all necessary source files, that will -reproduce the bug. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``It gets a fatal signal.'' - -Of course, if the bug is that @value{GDBN} gets a fatal signal, then we -will certainly notice it. But if the bug is incorrect output, we might -not notice unless it is glaringly wrong. You might as well not give us -a chance to make a mistake. - -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of @value{GDBN} is out of synch, or you have encountered a bug in -the C library on your system. (This has happened!) Your copy might -crash and ours would not. If you told us to expect a crash, then when -ours fails to crash, we would know that the bug was not happening for -us. If you had not told us to expect a crash, then we would not be able -to draw any conclusion from our observations. - -@item -If you wish to suggest changes to the @value{GDBN} source, send us context -diffs. If you even discuss something in the @value{GDBN} source, refer to -it by context, not by line number. - -The line numbers in our development sources will not match those in your -sources. Your line numbers would convey no useful information to us. - -@end itemize - -Here are some things that are not necessary: - -@itemize @bullet -@item -A description of the envelope of the bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. - -This is often time consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger -with breakpoints, not by pure deduction from a series of examples. -We recommend that you save your time for something else. - -Of course, if you can find a simpler example to report @emph{instead} -of the original one, that is a convenience for us. Errors in the -output will be easier to spot, running under the debugger will take -less time, and so on. - -However, simplification is not vital; if you do not want to do this, -report the bug anyway and send us the entire test case you used. - -@item -A patch for the bug. - -A patch for the bug does help us if it is a good one. But do not omit -the necessary information, such as the test case, on the assumption that -a patch is all we need. We might see problems with your patch and decide -to fix the problem another way, or we might not understand it at all. - -Sometimes with a program as complicated as @value{GDBN} it is very hard to -construct an example that will make the program follow a certain path -through the code. If you do not send us the example, we will not be able -to construct one, so we will not be able to verify that the bug is fixed. - -And if we cannot understand what bug you are trying to fix, or why your -patch should be an improvement, we will not install it. A test case will -help us to understand. - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even we cannot guess right about such -things without first using the debugger to find the facts. -@end itemize - -@c The readline documentation is distributed with the readline code -@c and consists of the two following files: -@c rluser.texinfo -@c inc-hist.texinfo -@c Use -I with makeinfo to point to the appropriate directory, -@c environment var TEXINPUTS with TeX. -@include rluser.texinfo -@include inc-hist.texinfo - - -@node Formatting Documentation -@appendix Formatting Documentation - -@cindex @value{GDBN} reference card -@cindex reference card -The @value{GDBN} 4 release includes an already-formatted reference card, ready -for printing with PostScript or Ghostscript, in the @file{gdb} -subdirectory of the main source directory@footnote{In -@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} -release.}. If you can use PostScript or Ghostscript with your printer, -you can print the reference card immediately with @file{refcard.ps}. - -The release also includes the source for the reference card. You -can format it, using @TeX{}, by typing: - -@smallexample -make refcard.dvi -@end smallexample - -The @value{GDBN} reference card is designed to print in @dfn{landscape} -mode on US ``letter'' size paper; -that is, on a sheet 11 inches wide by 8.5 inches -high. You will need to specify this form of printing as an option to -your @sc{dvi} output program. - -@cindex documentation - -All the documentation for @value{GDBN} comes as part of the machine-readable -distribution. The documentation is written in Texinfo format, which is -a documentation system that uses a single source file to produce both -on-line information and a printed manual. You can use one of the Info -formatting commands to create the on-line version of the documentation -and @TeX{} (or @code{texi2roff}) to typeset the printed version. - -@value{GDBN} includes an already formatted copy of the on-line Info -version of this manual in the @file{gdb} subdirectory. The main Info -file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to -subordinate files matching @samp{gdb.info*} in the same directory. If -necessary, you can print out these files, or read them with any editor; -but they are easier to read using the @code{info} subsystem in @sc{gnu} -Emacs or the standalone @code{info} program, available as part of the -@sc{gnu} Texinfo distribution. - -If you want to format these Info files yourself, you need one of the -Info formatting programs, such as @code{texinfo-format-buffer} or -@code{makeinfo}. - -If you have @code{makeinfo} installed, and are in the top level -@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of -version @value{GDBVN}), you can make the Info file by typing: - -@smallexample -cd gdb -make gdb.info -@end smallexample - -If you want to typeset and print copies of this manual, you need @TeX{}, -a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the -Texinfo definitions file. - -@TeX{} is a typesetting program; it does not print files directly, but -produces output files called @sc{dvi} files. To print a typeset -document, you need a program to print @sc{dvi} files. If your system -has @TeX{} installed, chances are it has such a program. The precise -command to use depends on your system; @kbd{lpr -d} is common; another -(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may -require a file name without any extension or a @samp{.dvi} extension. - -@TeX{} also requires a macro definitions file called -@file{texinfo.tex}. This file tells @TeX{} how to typeset a document -written in Texinfo format. On its own, @TeX{} cannot either read or -typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB -and is located in the @file{gdb-@var{version-number}/texinfo} -directory. - -If you have @TeX{} and a @sc{dvi} printer program installed, you can -typeset and print this manual. First switch to the the @file{gdb} -subdirectory of the main source directory (for example, to -@file{gdb-@value{GDBVN}/gdb}) and type: - -@smallexample -make gdb.dvi -@end smallexample - -Then give @file{gdb.dvi} to your @sc{dvi} printing program. - -@node Installing GDB -@appendix Installing @value{GDBN} -@cindex configuring @value{GDBN} -@cindex installation -@cindex configuring @value{GDBN}, and source tree subdirectories - -@value{GDBN} comes with a @code{configure} script that automates the process -of preparing @value{GDBN} for installation; you can then use @code{make} to -build the @code{gdb} program. -@iftex -@c irrelevant in info file; it's as current as the code it lives with. -@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, -look at the @file{README} file in the sources; we may have improved the -installation procedures since publishing this manual.} -@end iftex - -The @value{GDBN} distribution includes all the source code you need for -@value{GDBN} in a single directory, whose name is usually composed by -appending the version number to @samp{gdb}. - -For example, the @value{GDBN} version @value{GDBVN} distribution is in the -@file{gdb-@value{GDBVN}} directory. That directory contains: - -@table @code -@item gdb-@value{GDBVN}/configure @r{(and supporting files)} -script for configuring @value{GDBN} and all its supporting libraries - -@item gdb-@value{GDBVN}/gdb -the source specific to @value{GDBN} itself - -@item gdb-@value{GDBVN}/bfd -source for the Binary File Descriptor library - -@item gdb-@value{GDBVN}/include -@sc{gnu} include files - -@item gdb-@value{GDBVN}/libiberty -source for the @samp{-liberty} free software library - -@item gdb-@value{GDBVN}/opcodes -source for the library of opcode tables and disassemblers - -@item gdb-@value{GDBVN}/readline -source for the @sc{gnu} command-line interface - -@item gdb-@value{GDBVN}/glob -source for the @sc{gnu} filename pattern-matching subroutine - -@item gdb-@value{GDBVN}/mmalloc -source for the @sc{gnu} memory-mapped malloc package -@end table - -The simplest way to configure and build @value{GDBN} is to run @code{configure} -from the @file{gdb-@var{version-number}} source directory, which in -this example is the @file{gdb-@value{GDBVN}} directory. - -First switch to the @file{gdb-@var{version-number}} source directory -if you are not already in it; then run @code{configure}. Pass the -identifier for the platform on which @value{GDBN} will run as an -argument. - -For example: - -@smallexample -cd gdb-@value{GDBVN} -./configure @var{host} -make -@end smallexample - -@noindent -where @var{host} is an identifier such as @samp{sun4} or -@samp{decstation}, that identifies the platform where @value{GDBN} will run. -(You can often leave off @var{host}; @code{configure} tries to guess the -correct value by examining your system.) - -Running @samp{configure @var{host}} and then running @code{make} builds the -@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty} -libraries, then @code{gdb} itself. The configured source files, and the -binaries, are left in the corresponding source directories. - -@need 750 -@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your -system does not recognize this automatically when you run a different -shell, you may need to run @code{sh} on it explicitly: - -@smallexample -sh configure @var{host} -@end smallexample - -If you run @code{configure} from a directory that contains source -directories for multiple libraries or programs, such as the -@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure} -creates configuration files for every directory level underneath (unless -you tell it not to, with the @samp{--norecursion} option). - -You should run the @code{configure} script from the top directory in the -source tree, the @file{gdb-@var{version-number}} directory. If you run -@code{configure} from one of the subdirectories, you will configure only -that subdirectory. That is usually not what you want. In particular, -if you run the first @code{configure} from the @file{gdb} subdirectory -of the @file{gdb-@var{version-number}} directory, you will omit the -configuration of @file{bfd}, @file{readline}, and other sibling -directories of the @file{gdb} subdirectory. This leads to build errors -about missing include files such as @file{bfd/bfd.h}. - -You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. -However, you should make sure that the shell on your path (named by -the @samp{SHELL} environment variable) is publicly readable. Remember -that @value{GDBN} uses the shell to start your program---some systems refuse to -let @value{GDBN} debug child processes whose programs are not readable. - -@menu -* Separate Objdir:: Compiling @value{GDBN} in another directory -* Config Names:: Specifying names for hosts and targets -* Configure Options:: Summary of options for configure -@end menu - -@node Separate Objdir -@section Compiling @value{GDBN} in another directory - -If you want to run @value{GDBN} versions for several host or target machines, -you need a different @code{gdb} compiled for each combination of -host and target. @code{configure} is designed to make this easy by -allowing you to generate each configuration in a separate subdirectory, -rather than in the source directory. If your @code{make} program -handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running -@code{make} in each of these directories builds the @code{gdb} -program specified there. - -To build @code{gdb} in a separate directory, run @code{configure} -with the @samp{--srcdir} option to specify where to find the source. -(You also need to specify a path to find @code{configure} -itself from your working directory. If the path to @code{configure} -would be the same as the argument to @samp{--srcdir}, you can leave out -the @samp{--srcdir} option; it is assumed.) - -For example, with version @value{GDBVN}, you can build @value{GDBN} in a -separate directory for a Sun 4 like this: - -@smallexample -@group -cd gdb-@value{GDBVN} -mkdir ../gdb-sun4 -cd ../gdb-sun4 -../gdb-@value{GDBVN}/configure sun4 -make -@end group -@end smallexample - -When @code{configure} builds a configuration using a remote source -directory, it creates a tree for the binaries with the same structure -(and using the same names) as the tree under the source directory. In -the example, you'd find the Sun 4 library @file{libiberty.a} in the -directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in -@file{gdb-sun4/gdb}. - -Make sure that your path to the @file{configure} script has just one -instance of @file{gdb} in it. If your path to @file{configure} looks -like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only -one subdirectory of @value{GDBN}, not the whole package. This leads to -build errors about missing include files such as @file{bfd/bfd.h}. - -One popular reason to build several @value{GDBN} configurations in separate -directories is to configure @value{GDBN} for cross-compiling (where -@value{GDBN} runs on one machine---the @dfn{host}---while debugging -programs that run on another machine---the @dfn{target}). -You specify a cross-debugging target by -giving the @samp{--target=@var{target}} option to @code{configure}. - -When you run @code{make} to build a program or library, you must run -it in a configured directory---whatever directory you were in when you -called @code{configure} (or one of its subdirectories). - -The @code{Makefile} that @code{configure} generates in each source -directory also runs recursively. If you type @code{make} in a source -directory such as @file{gdb-@value{GDBVN}} (or in a separate configured -directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you -will build all the required libraries, and then build GDB. - -When you have multiple hosts or targets configured in separate -directories, you can run @code{make} on them in parallel (for example, -if they are NFS-mounted on each of the hosts); they will not interfere -with each other. - -@node Config Names -@section Specifying names for hosts and targets - -The specifications used for hosts and targets in the @code{configure} -script are based on a three-part naming scheme, but some short predefined -aliases are also supported. The full naming scheme encodes three pieces -of information in the following pattern: - -@smallexample -@var{architecture}-@var{vendor}-@var{os} -@end smallexample - -For example, you can use the alias @code{sun4} as a @var{host} argument, -or as the value for @var{target} in a @code{--target=@var{target}} -option. The equivalent full name is @samp{sparc-sun-sunos4}. - -The @code{configure} script accompanying @value{GDBN} does not provide -any query facility to list all supported host and target names or -aliases. @code{configure} calls the Bourne shell script -@code{config.sub} to map abbreviations to full names; you can read the -script, if you wish, or you can use it to test your guesses on -abbreviations---for example: - -@smallexample -% sh config.sub i386-linux -i386-pc-linux-gnu -% sh config.sub alpha-linux -alpha-unknown-linux-gnu -% sh config.sub hp9k700 -hppa1.1-hp-hpux -% sh config.sub sun4 -sparc-sun-sunos4.1.1 -% sh config.sub sun3 -m68k-sun-sunos4.1.1 -% sh config.sub i986v -Invalid configuration `i986v': machine `i986v' not recognized -@end smallexample - -@noindent -@code{config.sub} is also distributed in the @value{GDBN} source -directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). - -@node Configure Options -@section @code{configure} options - -Here is a summary of the @code{configure} options and arguments that -are most often useful for building @value{GDBN}. @code{configure} also has -several other options not listed here. @inforef{What Configure -Does,,configure.info}, for a full explanation of @code{configure}. - -@smallexample -configure @r{[}--help@r{]} - @r{[}--prefix=@var{dir}@r{]} - @r{[}--exec-prefix=@var{dir}@r{]} - @r{[}--srcdir=@var{dirname}@r{]} - @r{[}--norecursion@r{]} @r{[}--rm@r{]} - @r{[}--target=@var{target}@r{]} - @var{host} -@end smallexample - -@noindent -You may introduce options with a single @samp{-} rather than -@samp{--} if you prefer; but you may abbreviate option names if you use -@samp{--}. - -@table @code -@item --help -Display a quick summary of how to invoke @code{configure}. - -@item --prefix=@var{dir} -Configure the source to install programs and files under directory -@file{@var{dir}}. - -@item --exec-prefix=@var{dir} -Configure the source to install programs under directory -@file{@var{dir}}. - -@c avoid splitting the warning from the explanation: -@need 2000 -@item --srcdir=@var{dirname} -@strong{Warning: using this option requires @sc{gnu} @code{make}, or another -@code{make} that implements the @code{VPATH} feature.}@* -Use this option to make configurations in directories separate from the -@value{GDBN} source directories. Among other things, you can use this to -build (or maintain) several configurations simultaneously, in separate -directories. @code{configure} writes configuration specific files in -the current directory, but arranges for them to use the source in the -directory @var{dirname}. @code{configure} creates directories under -the working directory in parallel to the source directories below -@var{dirname}. - -@item --norecursion -Configure only the directory level where @code{configure} is executed; do not -propagate configuration to subdirectories. - -@item --target=@var{target} -Configure @value{GDBN} for cross-debugging programs running on the specified -@var{target}. Without this option, @value{GDBN} is configured to debug -programs that run on the same machine (@var{host}) as @value{GDBN} itself. - -There is no convenient way to generate a list of all available targets. - -@item @var{host} @dots{} -Configure @value{GDBN} to run on the specified @var{host}. - -There is no convenient way to generate a list of all available hosts. -@end table - -There are many other options available as well, but they are generally -needed for special purposes only. - -@node Maintenance Commands -@appendix Maintenance Commands -@cindex maintenance commands -@cindex internal commands - -In addition to commands intended for @value{GDBN} users, @value{GDBN} -includes a number of commands intended for @value{GDBN} developers. -These commands are provided here for reference. - -@table @code -@kindex maint info breakpoints -@item @anchor{maint info breakpoints}maint info breakpoints -Using the same format as @samp{info breakpoints}, display both the -breakpoints you've set explicitly, and those @value{GDBN} is using for -internal purposes. Internal breakpoints are shown with negative -breakpoint numbers. The type column identifies what kind of breakpoint -is shown: - -@table @code -@item breakpoint -Normal, explicitly set breakpoint. - -@item watchpoint -Normal, explicitly set watchpoint. - -@item longjmp -Internal breakpoint, used to handle correctly stepping through -@code{longjmp} calls. - -@item longjmp resume -Internal breakpoint at the target of a @code{longjmp}. - -@item until -Temporary internal breakpoint used by the @value{GDBN} @code{until} command. - -@item finish -Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. - -@item shlib events -Shared library events. - -@end table - -@kindex maint internal-error -@kindex maint internal-warning -@item maint internal-error -@itemx maint internal-warning -Cause @value{GDBN} to call the internal function @code{internal_error} -or @code{internal_warning} and hence behave as though an internal error -or internal warning has been detected. In addition to reporting the -internal problem, these functions give the user the opportunity to -either quit @value{GDBN} or create a core file of the current -@value{GDBN} session. - -@smallexample -(gdb) @kbd{maint internal-error testing, 1, 2} -@dots{}/maint.c:121: internal-error: testing, 1, 2 -A problem internal to GDB has been detected. Further -debugging may prove unreliable. -Quit this debugging session? (y or n) @kbd{n} -Create a core file? (y or n) @kbd{n} -(gdb) -@end smallexample - -Takes an optional parameter that is used as the text of the error or -warning message. - -@kindex maint print dummy-frames -@item maint print dummy-frames - -Prints the contents of @value{GDBN}'s internal dummy-frame stack. - -@smallexample -(gdb) @kbd{b add} -@dots{} -(gdb) @kbd{print add(2,3)} -Breakpoint 2, add (a=2, b=3) at @dots{} -58 return (a + b); -The program being debugged stopped while in a function called from GDB. -@dots{} -(gdb) @kbd{maint print dummy-frames} -0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 - top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@} - call_lo=0x01014000 call_hi=0x01014001 -(gdb) -@end smallexample - -Takes an optional file parameter. - -@kindex maint print registers -@kindex maint print raw-registers -@kindex maint print cooked-registers -@kindex maint print register-groups -@item maint print registers -@itemx maint print raw-registers -@itemx maint print cooked-registers -@itemx maint print register-groups -Print @value{GDBN}'s internal register data structures. - -The command @code{maint print raw-registers} includes the contents of -the raw register cache; the command @code{maint print cooked-registers} -includes the (cooked) value of all registers; and the command -@code{maint print register-groups} includes the groups that each -register is a member of. @xref{Registers,, Registers, gdbint, -@value{GDBN} Internals}. - -Takes an optional file parameter. - -@kindex maint print reggroups -@item maint print reggroups -Print @value{GDBN}'s internal register group data structures. - -Takes an optional file parameter. - -@smallexample -(gdb) @kbd{maint print reggroups} - Group Type - general user - float user - all user - vector user - system user - save internal - restore internal -@end smallexample - -@kindex maint set profile -@kindex maint show profile -@cindex profiling GDB -@item maint set profile -@itemx maint show profile -Control profiling of @value{GDBN}. - -Profiling will be disabled until you use the @samp{maint set profile} -command to enable it. When you enable profiling, the system will begin -collecting timing and execution count data; when you disable profiling or -exit @value{GDBN}, the results will be written to a log file. Remember that -if you use profiling, @value{GDBN} will overwrite the profiling log file -(often called @file{gmon.out}). If you have a record of important profiling -data in a @file{gmon.out} file, be sure to move it to a safe location. - -Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be -compiled with the @samp{-pg} compiler option. - -@end table - - -@node Remote Protocol -@appendix @value{GDBN} Remote Serial Protocol - -@menu -* Overview:: -* Packets:: -* Stop Reply Packets:: -* General Query Packets:: -* Register Packet Format:: -* Examples:: -* File-I/O remote protocol extension:: -@end menu - -@node Overview -@section Overview - -There may be occasions when you need to know something about the -protocol---for example, if there is only one serial port to your target -machine, you might want your program to do something special if it -recognizes a packet meant for @value{GDBN}. - -In the examples below, @samp{->} and @samp{<-} are used to indicate -transmitted and received data respectfully. - -@cindex protocol, @value{GDBN} remote serial -@cindex serial protocol, @value{GDBN} remote -@cindex remote serial protocol -All @value{GDBN} commands and responses (other than acknowledgments) are -sent as a @var{packet}. A @var{packet} is introduced with the character -@samp{$}, the actual @var{packet-data}, and the terminating character -@samp{#} followed by a two-digit @var{checksum}: - -@smallexample -@code{$}@var{packet-data}@code{#}@var{checksum} -@end smallexample -@noindent - -@cindex checksum, for @value{GDBN} remote -@noindent -The two-digit @var{checksum} is computed as the modulo 256 sum of all -characters between the leading @samp{$} and the trailing @samp{#} (an -eight bit unsigned checksum). - -Implementors should note that prior to @value{GDBN} 5.0 the protocol -specification also included an optional two-digit @var{sequence-id}: - -@smallexample -@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} -@end smallexample - -@cindex sequence-id, for @value{GDBN} remote -@noindent -That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} -has never output @var{sequence-id}s. Stubs that handle packets added -since @value{GDBN} 5.0 must not accept @var{sequence-id}. - -@cindex acknowledgment, for @value{GDBN} remote -When either the host or the target machine receives a packet, the first -response expected is an acknowledgment: either @samp{+} (to indicate -the package was received correctly) or @samp{-} (to request -retransmission): - -@smallexample --> @code{$}@var{packet-data}@code{#}@var{checksum} -<- @code{+} -@end smallexample -@noindent - -The host (@value{GDBN}) sends @var{command}s, and the target (the -debugging stub incorporated in your program) sends a @var{response}. In -the case of step and continue @var{command}s, the response is only sent -when the operation has completed (the target has again stopped). - -@var{packet-data} consists of a sequence of characters with the -exception of @samp{#} and @samp{$} (see @samp{X} packet for additional -exceptions). - -Fields within the packet should be separated using @samp{,} @samp{;} or -@cindex remote protocol, field separator -@samp{:}. Except where otherwise noted all numbers are represented in -@sc{hex} with leading zeros suppressed. - -Implementors should note that prior to @value{GDBN} 5.0, the character -@samp{:} could not appear as the third character in a packet (as it -would potentially conflict with the @var{sequence-id}). - -Response @var{data} can be run-length encoded to save space. A @samp{*} -means that the next character is an @sc{ascii} encoding giving a repeat count -which stands for that many repetitions of the character preceding the -@samp{*}. The encoding is @code{n+29}, yielding a printable character -where @code{n >=3} (which is where rle starts to win). The printable -characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric -value greater than 126 should not be used. - -So: -@smallexample -"@code{0* }" -@end smallexample -@noindent -means the same as "0000". - -The error response returned for some packets includes a two character -error number. That number is not well defined. - -For any @var{command} not supported by the stub, an empty response -(@samp{$#00}) should be returned. That way it is possible to extend the -protocol. A newer @value{GDBN} can tell if a packet is supported based -on that response. - -A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, -@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are -optional. - -@node Packets -@section Packets - -The following table provides a complete list of all currently defined -@var{command}s and their corresponding response @var{data}. - -@table @r - -@item @code{!} --- extended mode -@cindex @code{!} packet - -Enable extended mode. In extended mode, the remote server is made -persistent. The @samp{R} packet is used to restart the program being -debugged. - -Reply: -@table @samp -@item OK -The remote target both supports and has enabled extended mode. -@end table - -@item @code{?} --- last signal -@cindex @code{?} packet - -Indicate the reason the target halted. The reply is the same as for -step and continue. - -Reply: -@xref{Stop Reply Packets}, for the reply specifications. - -@item @code{a} --- reserved - -Reserved for future use. - -@item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)} -@cindex @code{A} packet - -Initialized @samp{argv[]} array passed into program. @var{arglen} -specifies the number of bytes in the hex encoded byte stream @var{arg}. -See @code{gdbserver} for more details. - -Reply: -@table @samp -@item OK -@item E@var{NN} -@end table - -@item @code{b}@var{baud} --- set baud @strong{(deprecated)} -@cindex @code{b} packet - -Change the serial line speed to @var{baud}. - -JTC: @emph{When does the transport layer state change? When it's -received, or after the ACK is transmitted. In either case, there are -problems if the command or the acknowledgment packet is dropped.} - -Stan: @emph{If people really wanted to add something like this, and get -it working for the first time, they ought to modify ser-unix.c to send -some kind of out-of-band message to a specially-setup stub and have the -switch happen "in between" packets, so that from remote protocol's point -of view, nothing actually happened.} - -@item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)} -@cindex @code{B} packet - -Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a -breakpoint at @var{addr}. - -This packet has been replaced by the @samp{Z} and @samp{z} packets -(@pxref{insert breakpoint or watchpoint packet}). - -@item @code{c}@var{addr} --- continue -@cindex @code{c} packet - -@var{addr} is address to resume. If @var{addr} is omitted, resume at -current address. - -Reply: -@xref{Stop Reply Packets}, for the reply specifications. - -@item @code{C}@var{sig}@code{;}@var{addr} --- continue with signal -@cindex @code{C} packet - -Continue with signal @var{sig} (hex signal number). If -@code{;}@var{addr} is omitted, resume at same address. - -Reply: -@xref{Stop Reply Packets}, for the reply specifications. - -@item @code{d} --- toggle debug @strong{(deprecated)} -@cindex @code{d} packet - -Toggle debug flag. - -@item @code{D} --- detach -@cindex @code{D} packet - -Detach @value{GDBN} from the remote system. Sent to the remote target -before @value{GDBN} disconnects via the @code{detach} command. - -Reply: -@table @samp -@item @emph{no response} -@value{GDBN} does not check for any response after sending this packet. -@end table - -@item @code{e} --- reserved - -Reserved for future use. - -@item @code{E} --- reserved - -Reserved for future use. - -@item @code{f} --- reserved - -Reserved for future use. - -@item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet. -@cindex @code{F} packet - -This packet is send by @value{GDBN} as reply to a @code{F} request packet -sent by the target. This is part of the File-I/O protocol extension. -@xref{File-I/O remote protocol extension}, for the specification. - -@item @code{g} --- read registers -@anchor{read registers packet} -@cindex @code{g} packet - -Read general registers. - -Reply: -@table @samp -@item @var{XX@dots{}} -Each byte of register data is described by two hex digits. The bytes -with the register are transmitted in target byte order. The size of -each register and their position within the @samp{g} @var{packet} are -determined by the @value{GDBN} internal macros -@var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The -specification of several standard @code{g} packets is specified below. -@item E@var{NN} -for an error. -@end table - -@item @code{G}@var{XX@dots{}} --- write regs -@cindex @code{G} packet - -@xref{read registers packet}, for a description of the @var{XX@dots{}} -data. - -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error -@end table - -@item @code{h} --- reserved - -Reserved for future use. - -@item @code{H}@var{c}@var{t@dots{}} --- set thread -@cindex @code{H} packet - -Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, -@samp{G}, et.al.). @var{c} depends on the operation to be performed: it -should be @samp{c} for step and continue operations, @samp{g} for other -operations. The thread designator @var{t@dots{}} may be -1, meaning all -the threads, a thread number, or zero which means pick any thread. - -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error -@end table - -@c FIXME: JTC: -@c 'H': How restrictive (or permissive) is the thread model. If a -@c thread is selected and stopped, are other threads allowed -@c to continue to execute? As I mentioned above, I think the -@c semantics of each command when a thread is selected must be -@c described. For example: -@c -@c 'g': If the stub supports threads and a specific thread is -@c selected, returns the register block from that thread; -@c otherwise returns current registers. -@c -@c 'G' If the stub supports threads and a specific thread is -@c selected, sets the registers of the register block of -@c that thread; otherwise sets current registers. - -@item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)} -@anchor{cycle step packet} -@cindex @code{i} packet - -Step the remote target by a single clock cycle. If @code{,}@var{nnn} is -present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle -step starting at that address. - -@item @code{I} --- signal then cycle step @strong{(reserved)} -@cindex @code{I} packet - -@xref{step with signal packet}. @xref{cycle step packet}. - -@item @code{j} --- reserved - -Reserved for future use. - -@item @code{J} --- reserved - -Reserved for future use. - -@item @code{k} --- kill request -@cindex @code{k} packet - -FIXME: @emph{There is no description of how to operate when a specific -thread context has been selected (i.e.@: does 'k' kill only that -thread?)}. - -@item @code{K} --- reserved - -Reserved for future use. - -@item @code{l} --- reserved - -Reserved for future use. - -@item @code{L} --- reserved - -Reserved for future use. - -@item @code{m}@var{addr}@code{,}@var{length} --- read memory -@cindex @code{m} packet - -Read @var{length} bytes of memory starting at address @var{addr}. -Neither @value{GDBN} nor the stub assume that sized memory transfers are -assumed using word aligned accesses. FIXME: @emph{A word aligned memory -transfer mechanism is needed.} - -Reply: -@table @samp -@item @var{XX@dots{}} -@var{XX@dots{}} is mem contents. Can be fewer bytes than requested if able -to read only part of the data. Neither @value{GDBN} nor the stub assume -that sized memory transfers are assumed using word aligned -accesses. FIXME: @emph{A word aligned memory transfer mechanism is -needed.} -@item E@var{NN} -@var{NN} is errno -@end table - -@item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem -@cindex @code{M} packet - -Write @var{length} bytes of memory starting at address @var{addr}. -@var{XX@dots{}} is the data. - -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error (this includes the case where only part of the data was -written). -@end table - -@item @code{n} --- reserved - -Reserved for future use. - -@item @code{N} --- reserved - -Reserved for future use. - -@item @code{o} --- reserved - -Reserved for future use. - -@item @code{O} --- reserved - -Reserved for future use. - -@item @code{p}@var{n@dots{}} --- read reg @strong{(reserved)} -@cindex @code{p} packet - -@xref{write register packet}. - -Reply: -@table @samp -@item @var{r@dots{}.} -The hex encoded value of the register in target byte order. -@end table - -@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register -@anchor{write register packet} -@cindex @code{P} packet - -Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex -digits for each byte in the register (target byte order). - -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error -@end table - -@item @code{q}@var{query} --- general query -@anchor{general query packet} -@cindex @code{q} packet - -Request info about @var{query}. In general @value{GDBN} queries have a -leading upper case letter. Custom vendor queries should use a company -prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may optionally -be followed by a @samp{,} or @samp{;} separated list. Stubs must ensure -that they match the full @var{query} name. - -Reply: -@table @samp -@item @var{XX@dots{}} -Hex encoded data from query. The reply can not be empty. -@item E@var{NN} -error reply -@item -Indicating an unrecognized @var{query}. -@end table - -@item @code{Q}@var{var}@code{=}@var{val} --- general set -@cindex @code{Q} packet - -Set value of @var{var} to @var{val}. - -@xref{general query packet}, for a discussion of naming conventions. - -@item @code{r} --- reset @strong{(deprecated)} -@cindex @code{r} packet - -Reset the entire system. - -@item @code{R}@var{XX} --- remote restart -@cindex @code{R} packet - -Restart the program being debugged. @var{XX}, while needed, is ignored. -This packet is only available in extended mode. - -Reply: -@table @samp -@item @emph{no reply} -The @samp{R} packet has no reply. -@end table - -@item @code{s}@var{addr} --- step -@cindex @code{s} packet - -@var{addr} is address to resume. If @var{addr} is omitted, resume at -same address. - -Reply: -@xref{Stop Reply Packets}, for the reply specifications. - -@item @code{S}@var{sig}@code{;}@var{addr} --- step with signal -@anchor{step with signal packet} -@cindex @code{S} packet - -Like @samp{C} but step not continue. - -Reply: -@xref{Stop Reply Packets}, for the reply specifications. - -@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search -@cindex @code{t} packet - -Search backwards starting at address @var{addr} for a match with pattern -@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes. -@var{addr} must be at least 3 digits. - -@item @code{T}@var{XX} --- thread alive -@cindex @code{T} packet - -Find out if the thread XX is alive. - -Reply: -@table @samp -@item OK -thread is still alive -@item E@var{NN} -thread is dead -@end table - -@item @code{u} --- reserved - -Reserved for future use. - -@item @code{U} --- reserved - -Reserved for future use. - -@item @code{v} --- verbose packet prefix - -Packets starting with @code{v} are identified by a multi-letter name, -up to the first @code{;} or @code{?} (or the end of the packet). - -@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume -@cindex @code{vCont} packet - -Resume the inferior. Different actions may be specified for each thread. -If an action is specified with no @var{tid}, then it is applied to any -threads that don't have a specific action specified; if no default action is -specified then other threads should remain stopped. Specifying multiple -default actions is an error; specifying no actions is also an error. -Thread IDs are specified in hexadecimal. Currently supported actions are: - -@table @code -@item c -Continue. -@item C@var{sig} -Continue with signal @var{sig}. @var{sig} should be two hex digits. -@item s -Step. -@item S@var{sig} -Step with signal @var{sig}. @var{sig} should be two hex digits. -@end table - -The optional @var{addr} argument normally associated with these packets is -not supported in @code{vCont}. - -Reply: -@xref{Stop Reply Packets}, for the reply specifications. - -@item @code{vCont?} --- extended resume query -@cindex @code{vCont?} packet - -Query support for the @code{vCont} packet. - -Reply: -@table @samp -@item @code{vCont}[;@var{action}]... -The @code{vCont} packet is supported. Each @var{action} is a supported -command in the @code{vCont} packet. -@item -The @code{vCont} packet is not supported. -@end table - -@item @code{V} --- reserved - -Reserved for future use. - -@item @code{w} --- reserved - -Reserved for future use. - -@item @code{W} --- reserved - -Reserved for future use. - -@item @code{x} --- reserved - -Reserved for future use. - -@item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary) -@cindex @code{X} packet - -@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}} -is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are -escaped using @code{0x7d}. - -Reply: -@table @samp -@item OK -for success -@item E@var{NN} -for an error -@end table - -@item @code{y} --- reserved - -Reserved for future use. - -@item @code{Y} reserved - -Reserved for future use. - -@item @code{z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- remove breakpoint or watchpoint @strong{(draft)} -@itemx @code{Z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- insert breakpoint or watchpoint @strong{(draft)} -@anchor{insert breakpoint or watchpoint packet} -@cindex @code{z} packet -@cindex @code{Z} packets - -Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or -watchpoint starting at address @var{address} and covering the next -@var{length} bytes. - -Each breakpoint and watchpoint packet @var{type} is documented -separately. - -@emph{Implementation notes: A remote target shall return an empty string -for an unrecognized breakpoint or watchpoint packet @var{type}. A -remote target shall support either both or neither of a given -@code{Z}@var{type}@dots{} and @code{z}@var{type}@dots{} packet pair. To -avoid potential problems with duplicate packets, the operations should -be implemented in an idempotent way.} - -@item @code{z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- remove memory breakpoint @strong{(draft)} -@item @code{Z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- insert memory breakpoint @strong{(draft)} -@cindex @code{z0} packet -@cindex @code{Z0} packet - -Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address -@code{addr} of size @code{length}. - -A memory breakpoint is implemented by replacing the instruction at -@var{addr} with a software breakpoint or trap instruction. The -@code{length} is used by targets that indicates the size of the -breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and -@sc{mips} can insert either a 2 or 4 byte breakpoint). - -@emph{Implementation note: It is possible for a target to copy or move -code that contains memory breakpoints (e.g., when implementing -overlays). The behavior of this packet, in the presence of such a -target, is not defined.} - -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error -@end table - -@item @code{z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- remove hardware breakpoint @strong{(draft)} -@item @code{Z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- insert hardware breakpoint @strong{(draft)} -@cindex @code{z1} packet -@cindex @code{Z1} packet - -Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at -address @code{addr} of size @code{length}. - -A hardware breakpoint is implemented using a mechanism that is not -dependant on being able to modify the target's memory. - -@emph{Implementation note: A hardware breakpoint is not affected by code -movement.} - -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error -@end table - -@item @code{z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- remove write watchpoint @strong{(draft)} -@item @code{Z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- insert write watchpoint @strong{(draft)} -@cindex @code{z2} packet -@cindex @code{Z2} packet - -Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint. - -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error -@end table - -@item @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- remove read watchpoint @strong{(draft)} -@item @code{Z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- insert read watchpoint @strong{(draft)} -@cindex @code{z3} packet -@cindex @code{Z3} packet - -Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint. - -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error -@end table - -@item @code{z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- remove access watchpoint @strong{(draft)} -@item @code{Z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- insert access watchpoint @strong{(draft)} -@cindex @code{z4} packet -@cindex @code{Z4} packet - -Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint. - -Reply: -@table @samp -@item OK -success -@item -not supported -@item E@var{NN} -for an error -@end table - -@end table - -@node Stop Reply Packets -@section Stop Reply Packets -@cindex stop reply packets - -The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can -receive any of the below as a reply. In the case of the @samp{C}, -@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned -when the target halts. In the below the exact meaning of @samp{signal -number} is poorly defined. In general one of the UNIX signal numbering -conventions is used. - -@table @samp - -@item S@var{AA} -@var{AA} is the signal number - -@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} -@cindex @code{T} packet reply - -@var{AA} = two hex digit signal number; @var{n...} = register number -(hex), @var{r...} = target byte ordered register contents, size defined -by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, -@var{r...} = thread process ID, this is a hex integer; @var{n...} = -(@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data -address, this is a hex integer; @var{n...} = other string not starting -with valid hex digit. @value{GDBN} should ignore this @var{n...}, -@var{r...} pair and go on to the next. This way we can extend the -protocol. - -@item W@var{AA} - -The process exited, and @var{AA} is the exit status. This is only -applicable to certain targets. - -@item X@var{AA} - -The process terminated with signal @var{AA}. - -@item O@var{XX@dots{}} - -@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at -any time while the program is running and the debugger should continue -to wait for @samp{W}, @samp{T}, etc. - -@item F@var{call-id}@code{,}@var{parameter@dots{}} - -@var{call-id} is the identifier which says which host system call should -be called. This is just the name of the function. Translation into the -correct system call is only applicable as it's defined in @value{GDBN}. -@xref{File-I/O remote protocol extension}, for a list of implemented -system calls. - -@var{parameter@dots{}} is a list of parameters as defined for this very -system call. - -The target replies with this packet when it expects @value{GDBN} to call -a host system call on behalf of the target. @value{GDBN} replies with -an appropriate @code{F} packet and keeps up waiting for the next reply -packet from the target. The latest @samp{C}, @samp{c}, @samp{S} or -@samp{s} action is expected to be continued. -@xref{File-I/O remote protocol extension}, for more details. - -@end table - -@node General Query Packets -@section General Query Packets - -The following set and query packets have already been defined. - -@table @r - -@item @code{q}@code{C} --- current thread - -Return the current thread id. - -Reply: -@table @samp -@item @code{QC}@var{pid} -Where @var{pid} is a HEX encoded 16 bit process id. -@item * -Any other reply implies the old pid. -@end table - -@item @code{q}@code{fThreadInfo} -- all thread ids - -@code{q}@code{sThreadInfo} - -Obtain a list of active thread ids from the target (OS). Since there -may be too many active threads to fit into one reply packet, this query -works iteratively: it may require more than one query/reply sequence to -obtain the entire list of threads. The first query of the sequence will -be the @code{qf}@code{ThreadInfo} query; subsequent queries in the -sequence will be the @code{qs}@code{ThreadInfo} query. - -NOTE: replaces the @code{qL} query (see below). - -Reply: -@table @samp -@item @code{m}@var{id} -A single thread id -@item @code{m}@var{id},@var{id}@dots{} -a comma-separated list of thread ids -@item @code{l} -(lower case 'el') denotes end of list. -@end table - -In response to each query, the target will reply with a list of one or -more thread ids, in big-endian hex, separated by commas. @value{GDBN} -will respond to each reply with a request for more thread ids (using the -@code{qs} form of the query), until the target responds with @code{l} -(lower-case el, for @code{'last'}). - -@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info - -Where @var{id} is a thread-id in big-endian hex. Obtain a printable -string description of a thread's attributes from the target OS. This -string may contain anything that the target OS thinks is interesting for -@value{GDBN} to tell the user about the thread. The string is displayed -in @value{GDBN}'s @samp{info threads} display. Some examples of -possible thread extra info strings are ``Runnable'', or ``Blocked on -Mutex''. - -Reply: -@table @samp -@item @var{XX@dots{}} -Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising -the printable string containing the extra information about the thread's -attributes. -@end table - -@item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)} - -Obtain thread information from RTOS. Where: @var{startflag} (one hex -digit) is one to indicate the first query and zero to indicate a -subsequent query; @var{threadcount} (two hex digits) is the maximum -number of threads the response packet can contain; and @var{nextthread} -(eight hex digits), for subsequent queries (@var{startflag} is zero), is -returned in the response as @var{argthread}. - -NOTE: this query is replaced by the @code{q}@code{fThreadInfo} query -(see above). - -Reply: -@table @samp -@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}} -Where: @var{count} (two hex digits) is the number of threads being -returned; @var{done} (one hex digit) is zero to indicate more threads -and one indicates no further threads; @var{argthreadid} (eight hex -digits) is @var{nextthread} from the request packet; @var{thread@dots{}} -is a sequence of thread IDs from the target. @var{threadid} (eight hex -digits). See @code{remote.c:parse_threadlist_response()}. -@end table - -@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block - -Reply: -@table @samp -@item @code{E}@var{NN} -An error (such as memory fault) -@item @code{C}@var{CRC32} -A 32 bit cyclic redundancy check of the specified memory region. -@end table - -@item @code{q}@code{Offsets} --- query sect offs - -Get section offsets that the target used when re-locating the downloaded -image. @emph{Note: while a @code{Bss} offset is included in the -response, @value{GDBN} ignores this and instead applies the @code{Data} -offset to the @code{Bss} section.} - -Reply: -@table @samp -@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} -@end table - -@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request - -Returns information on @var{threadid}. Where: @var{mode} is a hex -encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. - -Reply: -@table @samp -@item * -@end table - -See @code{remote.c:remote_unpack_thread_info_response()}. - -@item @code{q}@code{Rcmd,}@var{command} --- remote command - -@var{command} (hex encoded) is passed to the local interpreter for -execution. Invalid commands should be reported using the output string. -Before the final result packet, the target may also respond with a -number of intermediate @code{O}@var{output} console output packets. -@emph{Implementors should note that providing access to a stubs's -interpreter may have security implications}. - -Reply: -@table @samp -@item OK -A command response with no output. -@item @var{OUTPUT} -A command response with the hex encoded output string @var{OUTPUT}. -@item @code{E}@var{NN} -Indicate a badly formed request. -@item @samp{} -When @samp{q}@samp{Rcmd} is not recognized. -@end table - -@item @code{qSymbol::} --- symbol lookup - -Notify the target that @value{GDBN} is prepared to serve symbol lookup -requests. Accept requests from the target for the values of symbols. - -Reply: -@table @samp -@item @code{OK} -The target does not need to look up any (more) symbols. -@item @code{qSymbol:}@var{sym_name} -The target requests the value of symbol @var{sym_name} (hex encoded). -@value{GDBN} may provide the value by using the -@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below. -@end table - -@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value - -Set the value of @var{sym_name} to @var{sym_value}. - -@var{sym_name} (hex encoded) is the name of a symbol whose value the -target has previously requested. - -@var{sym_value} (hex) is the value for symbol @var{sym_name}. If -@value{GDBN} cannot supply a value for @var{sym_name}, then this field -will be empty. - -Reply: -@table @samp -@item @code{OK} -The target does not need to look up any (more) symbols. -@item @code{qSymbol:}@var{sym_name} -The target requests the value of a new symbol @var{sym_name} (hex -encoded). @value{GDBN} will continue to supply the values of symbols -(if available), until the target ceases to request them. -@end table - -@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data - -Read uninterpreted bytes from the target's special data area -identified by the keyword @code{object}. -Request @var{length} bytes starting at @var{offset} bytes into the data. -The content and encoding of @var{annex} is specific to the object; -it can supply additional details about what data to access. - -Here are the specific requests of this form defined so far. -All @samp{@code{qPart}:@var{object}:@code{read}:@dots{}} -requests use the same reply formats, listed below. - -@table @asis -@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length} -Access the target's @dfn{auxiliary vector}. @xref{Auxiliary Vector}. -Note @var{annex} must be empty. -@end table - -Reply: -@table @asis -@item @code{OK} -The @var{offset} in the request is at the end of the data. -There is no more data to be read. - -@item @var{XX@dots{}} -Hex encoded data bytes read. -This may be fewer bytes than the @var{length} in the request. - -@item @code{E00} -The request was malformed, or @var{annex} was invalid. - -@item @code{E}@var{nn} -The offset was invalid, or there was an error encountered reading the data. -@var{nn} is a hex-encoded @code{errno} value. - -@item @code{""} (empty) -An empty reply indicates the @var{object} or @var{annex} string was not -recognized by the stub. -@end table - -@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}} - -Write uninterpreted bytes into the target's special data area -identified by the keyword @code{object}, -starting at @var{offset} bytes into the data. -@var{data@dots{}} is the hex-encoded data to be written. -The content and encoding of @var{annex} is specific to the object; -it can supply additional details about what data to access. - -No requests of this form are presently in use. This specification -serves as a placeholder to document the common format that new -specific request specifications ought to use. - -Reply: -@table @asis -@item @var{nn} -@var{nn} (hex encoded) is the number of bytes written. -This may be fewer bytes than supplied in the request. - -@item @code{E00} -The request was malformed, or @var{annex} was invalid. - -@item @code{E}@var{nn} -The offset was invalid, or there was an error encountered writing the data. -@var{nn} is a hex-encoded @code{errno} value. - -@item @code{""} (empty) -An empty reply indicates the @var{object} or @var{annex} string was not -recognized by the stub, or that the object does not support writing. -@end table - -@item @code{qPart}:@var{object}:@var{operation}:@dots{} -Requests of this form may be added in the future. When a stub does -not recognize the @var{object} keyword, or its support for -@var{object} does not recognize the @var{operation} keyword, -the stub must respond with an empty packet. -@end table - -@node Register Packet Format -@section Register Packet Format - -The following @samp{g}/@samp{G} packets have previously been defined. -In the below, some thirty-two bit registers are transferred as -sixty-four bits. Those registers should be zero/sign extended (which?) -to fill the space allocated. Register bytes are transfered in target -byte order. The two nibbles within a register byte are transfered -most-significant - least-significant. - -@table @r - -@item MIPS32 - -All registers are transfered as thirty-two bit quantities in the order: -32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point -registers; fsr; fir; fp. - -@item MIPS64 - -All registers are transfered as sixty-four bit quantities (including -thirty-two bit registers such as @code{sr}). The ordering is the same -as @code{MIPS32}. - -@end table - -@node Examples -@section Examples - -Example sequence of a target being re-started. Notice how the restart -does not get any direct output: - -@smallexample --> @code{R00} -<- @code{+} -@emph{target restarts} --> @code{?} -<- @code{+} -<- @code{T001:1234123412341234} --> @code{+} -@end smallexample - -Example sequence of a target being stepped by a single instruction: - -@smallexample --> @code{G1445@dots{}} -<- @code{+} --> @code{s} -<- @code{+} -@emph{time passes} -<- @code{T001:1234123412341234} --> @code{+} --> @code{g} -<- @code{+} -<- @code{1455@dots{}} --> @code{+} -@end smallexample - -@node File-I/O remote protocol extension -@section File-I/O remote protocol extension -@cindex File-I/O remote protocol extension - -@menu -* File-I/O Overview:: -* Protocol basics:: -* The F request packet:: -* The F reply packet:: -* Memory transfer:: -* The Ctrl-C message:: -* Console I/O:: -* The isatty call:: -* The system call:: -* List of supported calls:: -* Protocol specific representation of datatypes:: -* Constants:: -* File-I/O Examples:: -@end menu - -@node File-I/O Overview -@subsection File-I/O Overview -@cindex file-i/o overview - -The File I/O remote protocol extension (short: File-I/O) allows the -target to use the hosts file system and console I/O when calling various -system calls. System calls on the target system are translated into a -remote protocol packet to the host system which then performs the needed -actions and returns with an adequate response packet to the target system. -This simulates file system operations even on targets that lack file systems. - -The protocol is defined host- and target-system independent. It uses -it's own independent representation of datatypes and values. Both, -@value{GDBN} and the target's @value{GDBN} stub are responsible for -translating the system dependent values into the unified protocol values -when data is transmitted. - -The communication is synchronous. A system call is possible only -when GDB is waiting for the @samp{C}, @samp{c}, @samp{S} or @samp{s} -packets. While @value{GDBN} handles the request for a system call, -the target is stopped to allow deterministic access to the target's -memory. Therefore File-I/O is not interuptible by target signals. It -is possible to interrupt File-I/O by a user interrupt (Ctrl-C), though. - -The target's request to perform a host system call does not finish -the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means, -after finishing the system call, the target returns to continuing the -previous activity (continue, step). No additional continue or step -request from @value{GDBN} is required. - -@smallexample -(gdb) continue - <- target requests 'system call X' - target is stopped, @value{GDBN} executes system call - -> GDB returns result - ... target continues, GDB returns to wait for the target - <- target hits breakpoint and sends a Txx packet -@end smallexample - -The protocol is only used for files on the host file system and -for I/O on the console. Character or block special devices, pipes, -named pipes or sockets or any other communication method on the host -system are not supported by this protocol. - -@node Protocol basics -@subsection Protocol basics -@cindex protocol basics, file-i/o - -The File-I/O protocol uses the @code{F} packet, as request as well -as as reply packet. Since a File-I/O system call can only occur when -@value{GDBN} is waiting for the continuing or stepping target, the -File-I/O request is a reply that @value{GDBN} has to expect as a result -of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. -This @code{F} packet contains all information needed to allow @value{GDBN} -to call the appropriate host system call: - -@itemize @bullet -@item -A unique identifier for the requested system call. - -@item -All parameters to the system call. Pointers are given as addresses -in the target memory address space. Pointers to strings are given as -pointer/length pair. Numerical values are given as they are. -Numerical control values are given in a protocol specific representation. - -@end itemize - -At that point @value{GDBN} has to perform the following actions. - -@itemize @bullet -@item -If parameter pointer values are given, which point to data needed as input -to a system call, @value{GDBN} requests this data from the target with a -standard @code{m} packet request. This additional communication has to be -expected by the target implementation and is handled as any other @code{m} -packet. - -@item -@value{GDBN} translates all value from protocol representation to host -representation as needed. Datatypes are coerced into the host types. - -@item -@value{GDBN} calls the system call - -@item -It then coerces datatypes back to protocol representation. - -@item -If pointer parameters in the request packet point to buffer space in which -a system call is expected to copy data to, the data is transmitted to the -target using a @code{M} or @code{X} packet. This packet has to be expected -by the target implementation and is handled as any other @code{M} or @code{X} -packet. - -@end itemize - -Eventually @value{GDBN} replies with another @code{F} packet which contains all -necessary information for the target to continue. This at least contains - -@itemize @bullet -@item -Return value. - -@item -@code{errno}, if has been changed by the system call. - -@item -``Ctrl-C'' flag. - -@end itemize - -After having done the needed type and value coercion, the target continues -the latest continue or step action. - -@node The F request packet -@subsection The @code{F} request packet -@cindex file-i/o request packet -@cindex @code{F} request packet - -The @code{F} request packet has the following format: - -@table @samp - -@smallexample -@code{F}@var{call-id}@code{,}@var{parameter@dots{}} -@end smallexample - -@var{call-id} is the identifier to indicate the host system call to be called. -This is just the name of the function. - -@var{parameter@dots{}} are the parameters to the system call. - -@end table - -Parameters are hexadecimal integer values, either the real values in case -of scalar datatypes, as pointers to target buffer space in case of compound -datatypes and unspecified memory areas or as pointer/length pairs in case -of string parameters. These are appended to the call-id, each separated -from its predecessor by a comma. All values are transmitted in ASCII -string representation, pointer/length pairs separated by a slash. - -@node The F reply packet -@subsection The @code{F} reply packet -@cindex file-i/o reply packet -@cindex @code{F} reply packet - -The @code{F} reply packet has the following format: - -@table @samp - -@smallexample -@code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment} -@end smallexample - -@var{retcode} is the return code of the system call as hexadecimal value. - -@var{errno} is the errno set by the call, in protocol specific representation. -This parameter can be omitted if the call was successful. - -@var{Ctrl-C flag} is only send if the user requested a break. In this -case, @var{errno} must be send as well, even if the call was successful. -The @var{Ctrl-C flag} itself consists of the character 'C': - -@smallexample -F0,0,C -@end smallexample - -@noindent -or, if the call was interupted before the host call has been performed: - -@smallexample -F-1,4,C -@end smallexample - -@noindent -assuming 4 is the protocol specific representation of @code{EINTR}. - -@end table - -@node Memory transfer -@subsection Memory transfer -@cindex memory transfer, in file-i/o protocol - -Structured data which is transferred using a memory read or write as e.g.@: -a @code{struct stat} is expected to be in a protocol specific format with -all scalar multibyte datatypes being big endian. This should be done by -the target before the @code{F} packet is sent resp.@: by @value{GDBN} before -it transfers memory to the target. Transferred pointers to structured -data should point to the already coerced data at any time. - -@node The Ctrl-C message -@subsection The Ctrl-C message -@cindex ctrl-c message, in file-i/o protocol - -A special case is, if the @var{Ctrl-C flag} is set in the @value{GDBN} -reply packet. In this case the target should behave, as if it had -gotten a break message. The meaning for the target is ``system call -interupted by @code{SIGINT}''. Consequentially, the target should actually stop -(as with a break message) and return to @value{GDBN} with a @code{T02} -packet. In this case, it's important for the target to know, in which -state the system call was interrupted. Since this action is by design -not an atomic operation, we have to differ between two cases: - -@itemize @bullet -@item -The system call hasn't been performed on the host yet. - -@item -The system call on the host has been finished. - -@end itemize - -These two states can be distinguished by the target by the value of the -returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system -call hasn't been performed. This is equivalent to the @code{EINTR} handling -on POSIX systems. In any other case, the target may presume that the -system call has been finished --- successful or not --- and should behave -as if the break message arrived right after the system call. - -@value{GDBN} must behave reliable. If the system call has not been called -yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as -@code{errno} in the packet. If the system call on the host has been finished -before the user requests a break, the full action must be finshed by -@value{GDBN}. This requires sending @code{M} or @code{X} packets as they fit. -The @code{F} packet may only be send when either nothing has happened -or the full action has been completed. - -@node Console I/O -@subsection Console I/O -@cindex console i/o as part of file-i/o - -By default and if not explicitely closed by the target system, the file -descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output -on the @value{GDBN} console is handled as any other file output operation -(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled -by @value{GDBN} so that after the target read request from file descriptor -0 all following typing is buffered until either one of the following -conditions is met: - -@itemize @bullet -@item -The user presses @kbd{Ctrl-C}. The behaviour is as explained above, the -@code{read} -system call is treated as finished. - -@item -The user presses @kbd{Enter}. This is treated as end of input with a trailing -line feed. - -@item -The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing -character, especially no Ctrl-D is appended to the input. - -@end itemize - -If the user has typed more characters as fit in the buffer given to -the read call, the trailing characters are buffered in @value{GDBN} until -either another @code{read(0, @dots{})} is requested by the target or debugging -is stopped on users request. - -@node The isatty call -@subsection The isatty(3) call -@cindex isatty call, file-i/o protocol - -A special case in this protocol is the library call @code{isatty} which -is implemented as it's own call inside of this protocol. It returns -1 to the target if the file descriptor given as parameter is attached -to the @value{GDBN} console, 0 otherwise. Implementing through system calls -would require implementing @code{ioctl} and would be more complex than -needed. - -@node The system call -@subsection The system(3) call -@cindex system call, file-i/o protocol - -The other special case in this protocol is the @code{system} call which -is implemented as it's own call, too. @value{GDBN} is taking over the full -task of calling the necessary host calls to perform the @code{system} -call. The return value of @code{system} is simplified before it's returned -to the target. Basically, the only signal transmitted back is @code{EINTR} -in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists -entirely of the exit status of the called command. - -Due to security concerns, the @code{system} call is refused to be called -by @value{GDBN} by default. The user has to allow this call explicitly by -entering - -@table @samp -@kindex set remote system-call-allowed 1 -@item @code{set remote system-call-allowed 1} -@end table - -Disabling the @code{system} call is done by - -@table @samp -@kindex set remote system-call-allowed 0 -@item @code{set remote system-call-allowed 0} -@end table - -The current setting is shown by typing - -@table @samp -@kindex show remote system-call-allowed -@item @code{show remote system-call-allowed} -@end table - -@node List of supported calls -@subsection List of supported calls -@cindex list of supported file-i/o calls - -@menu -* open:: -* close:: -* read:: -* write:: -* lseek:: -* rename:: -* unlink:: -* stat/fstat:: -* gettimeofday:: -* isatty:: -* system:: -@end menu - -@node open -@unnumberedsubsubsec open -@cindex open, file-i/o system call - -@smallexample -@exdent Synopsis: -int open(const char *pathname, int flags); -int open(const char *pathname, int flags, mode_t mode); - -@exdent Request: -Fopen,pathptr/len,flags,mode -@end smallexample - -@noindent -@code{flags} is the bitwise or of the following values: - -@table @code -@item O_CREAT -If the file does not exist it will be created. The host -rules apply as far as file ownership and time stamps -are concerned. - -@item O_EXCL -When used with O_CREAT, if the file already exists it is -an error and open() fails. - -@item O_TRUNC -If the file already exists and the open mode allows -writing (O_RDWR or O_WRONLY is given) it will be -truncated to length 0. - -@item O_APPEND -The file is opened in append mode. - -@item O_RDONLY -The file is opened for reading only. - -@item O_WRONLY -The file is opened for writing only. - -@item O_RDWR -The file is opened for reading and writing. - -@noindent -Each other bit is silently ignored. - -@end table - -@noindent -@code{mode} is the bitwise or of the following values: - -@table @code -@item S_IRUSR -User has read permission. - -@item S_IWUSR -User has write permission. - -@item S_IRGRP -Group has read permission. - -@item S_IWGRP -Group has write permission. - -@item S_IROTH -Others have read permission. - -@item S_IWOTH -Others have write permission. - -@noindent -Each other bit is silently ignored. - -@end table - -@smallexample -@exdent Return value: -open returns the new file descriptor or -1 if an error -occured. - -@exdent Errors: -@end smallexample - -@table @code -@item EEXIST -pathname already exists and O_CREAT and O_EXCL were used. - -@item EISDIR -pathname refers to a directory. - -@item EACCES -The requested access is not allowed. - -@item ENAMETOOLONG -pathname was too long. - -@item ENOENT -A directory component in pathname does not exist. - -@item ENODEV -pathname refers to a device, pipe, named pipe or socket. - -@item EROFS -pathname refers to a file on a read-only filesystem and -write access was requested. - -@item EFAULT -pathname is an invalid pointer value. - -@item ENOSPC -No space on device to create the file. - -@item EMFILE -The process already has the maximum number of files open. - -@item ENFILE -The limit on the total number of files open on the system -has been reached. - -@item EINTR -The call was interrupted by the user. -@end table - -@node close -@unnumberedsubsubsec close -@cindex close, file-i/o system call - -@smallexample -@exdent Synopsis: -int close(int fd); - -@exdent Request: -Fclose,fd - -@exdent Return value: -close returns zero on success, or -1 if an error occurred. - -@exdent Errors: -@end smallexample - -@table @code -@item EBADF -fd isn't a valid open file descriptor. - -@item EINTR -The call was interrupted by the user. -@end table - -@node read -@unnumberedsubsubsec read -@cindex read, file-i/o system call - -@smallexample -@exdent Synopsis: -int read(int fd, void *buf, unsigned int count); - -@exdent Request: -Fread,fd,bufptr,count - -@exdent Return value: -On success, the number of bytes read is returned. -Zero indicates end of file. If count is zero, read -returns zero as well. On error, -1 is returned. - -@exdent Errors: -@end smallexample - -@table @code -@item EBADF -fd is not a valid file descriptor or is not open for -reading. - -@item EFAULT -buf is an invalid pointer value. - -@item EINTR -The call was interrupted by the user. -@end table - -@node write -@unnumberedsubsubsec write -@cindex write, file-i/o system call - -@smallexample -@exdent Synopsis: -int write(int fd, const void *buf, unsigned int count); - -@exdent Request: -Fwrite,fd,bufptr,count - -@exdent Return value: -On success, the number of bytes written are returned. -Zero indicates nothing was written. On error, -1 -is returned. - -@exdent Errors: -@end smallexample - -@table @code -@item EBADF -fd is not a valid file descriptor or is not open for -writing. - -@item EFAULT -buf is an invalid pointer value. - -@item EFBIG -An attempt was made to write a file that exceeds the -host specific maximum file size allowed. - -@item ENOSPC -No space on device to write the data. - -@item EINTR -The call was interrupted by the user. -@end table - -@node lseek -@unnumberedsubsubsec lseek -@cindex lseek, file-i/o system call - -@smallexample -@exdent Synopsis: -long lseek (int fd, long offset, int flag); - -@exdent Request: -Flseek,fd,offset,flag -@end smallexample - -@code{flag} is one of: - -@table @code -@item SEEK_SET -The offset is set to offset bytes. - -@item SEEK_CUR -The offset is set to its current location plus offset -bytes. - -@item SEEK_END -The offset is set to the size of the file plus offset -bytes. -@end table - -@smallexample -@exdent Return value: -On success, the resulting unsigned offset in bytes from -the beginning of the file is returned. Otherwise, a -value of -1 is returned. - -@exdent Errors: -@end smallexample - -@table @code -@item EBADF -fd is not a valid open file descriptor. - -@item ESPIPE -fd is associated with the @value{GDBN} console. - -@item EINVAL -flag is not a proper value. - -@item EINTR -The call was interrupted by the user. -@end table - -@node rename -@unnumberedsubsubsec rename -@cindex rename, file-i/o system call - -@smallexample -@exdent Synopsis: -int rename(const char *oldpath, const char *newpath); - -@exdent Request: -Frename,oldpathptr/len,newpathptr/len - -@exdent Return value: -On success, zero is returned. On error, -1 is returned. - -@exdent Errors: -@end smallexample - -@table @code -@item EISDIR -newpath is an existing directory, but oldpath is not a -directory. - -@item EEXIST -newpath is a non-empty directory. - -@item EBUSY -oldpath or newpath is a directory that is in use by some -process. - -@item EINVAL -An attempt was made to make a directory a subdirectory -of itself. - -@item ENOTDIR -A component used as a directory in oldpath or new -path is not a directory. Or oldpath is a directory -and newpath exists but is not a directory. - -@item EFAULT -oldpathptr or newpathptr are invalid pointer values. - -@item EACCES -No access to the file or the path of the file. - -@item ENAMETOOLONG - -oldpath or newpath was too long. - -@item ENOENT -A directory component in oldpath or newpath does not exist. - -@item EROFS -The file is on a read-only filesystem. - -@item ENOSPC -The device containing the file has no room for the new -directory entry. - -@item EINTR -The call was interrupted by the user. -@end table - -@node unlink -@unnumberedsubsubsec unlink -@cindex unlink, file-i/o system call - -@smallexample -@exdent Synopsis: -int unlink(const char *pathname); - -@exdent Request: -Funlink,pathnameptr/len - -@exdent Return value: -On success, zero is returned. On error, -1 is returned. - -@exdent Errors: -@end smallexample - -@table @code -@item EACCES -No access to the file or the path of the file. - -@item EPERM -The system does not allow unlinking of directories. - -@item EBUSY -The file pathname cannot be unlinked because it's -being used by another process. - -@item EFAULT -pathnameptr is an invalid pointer value. - -@item ENAMETOOLONG -pathname was too long. - -@item ENOENT -A directory component in pathname does not exist. - -@item ENOTDIR -A component of the path is not a directory. - -@item EROFS -The file is on a read-only filesystem. - -@item EINTR -The call was interrupted by the user. -@end table - -@node stat/fstat -@unnumberedsubsubsec stat/fstat -@cindex fstat, file-i/o system call -@cindex stat, file-i/o system call - -@smallexample -@exdent Synopsis: -int stat(const char *pathname, struct stat *buf); -int fstat(int fd, struct stat *buf); - -@exdent Request: -Fstat,pathnameptr/len,bufptr -Ffstat,fd,bufptr - -@exdent Return value: -On success, zero is returned. On error, -1 is returned. - -@exdent Errors: -@end smallexample - -@table @code -@item EBADF -fd is not a valid open file. - -@item ENOENT -A directory component in pathname does not exist or the -path is an empty string. - -@item ENOTDIR -A component of the path is not a directory. - -@item EFAULT -pathnameptr is an invalid pointer value. - -@item EACCES -No access to the file or the path of the file. - -@item ENAMETOOLONG -pathname was too long. - -@item EINTR -The call was interrupted by the user. -@end table - -@node gettimeofday -@unnumberedsubsubsec gettimeofday -@cindex gettimeofday, file-i/o system call - -@smallexample -@exdent Synopsis: -int gettimeofday(struct timeval *tv, void *tz); - -@exdent Request: -Fgettimeofday,tvptr,tzptr - -@exdent Return value: -On success, 0 is returned, -1 otherwise. - -@exdent Errors: -@end smallexample - -@table @code -@item EINVAL -tz is a non-NULL pointer. - -@item EFAULT -tvptr and/or tzptr is an invalid pointer value. -@end table - -@node isatty -@unnumberedsubsubsec isatty -@cindex isatty, file-i/o system call - -@smallexample -@exdent Synopsis: -int isatty(int fd); - -@exdent Request: -Fisatty,fd - -@exdent Return value: -Returns 1 if fd refers to the @value{GDBN} console, 0 otherwise. - -@exdent Errors: -@end smallexample - -@table @code -@item EINTR -The call was interrupted by the user. -@end table - -@node system -@unnumberedsubsubsec system -@cindex system, file-i/o system call - -@smallexample -@exdent Synopsis: -int system(const char *command); - -@exdent Request: -Fsystem,commandptr/len - -@exdent Return value: -The value returned is -1 on error and the return status -of the command otherwise. Only the exit status of the -command is returned, which is extracted from the hosts -system return value by calling WEXITSTATUS(retval). -In case /bin/sh could not be executed, 127 is returned. - -@exdent Errors: -@end smallexample - -@table @code -@item EINTR -The call was interrupted by the user. -@end table - -@node Protocol specific representation of datatypes -@subsection Protocol specific representation of datatypes -@cindex protocol specific representation of datatypes, in file-i/o protocol - -@menu -* Integral datatypes:: -* Pointer values:: -* struct stat:: -* struct timeval:: -@end menu - -@node Integral datatypes -@unnumberedsubsubsec Integral datatypes -@cindex integral datatypes, in file-i/o protocol - -The integral datatypes used in the system calls are - -@smallexample -int@r{,} unsigned int@r{,} long@r{,} unsigned long@r{,} mode_t @r{and} time_t -@end smallexample - -@code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are -implemented as 32 bit values in this protocol. - -@code{Long} and @code{unsigned long} are implemented as 64 bit types. - -@xref{Limits}, for corresponding MIN and MAX values (similar to those -in @file{limits.h}) to allow range checking on host and target. - -@code{time_t} datatypes are defined as seconds since the Epoch. - -All integral datatypes transferred as part of a memory read or write of a -structured datatype e.g.@: a @code{struct stat} have to be given in big endian -byte order. - -@node Pointer values -@unnumberedsubsubsec Pointer values -@cindex pointer values, in file-i/o protocol - -Pointers to target data are transmitted as they are. An exception -is made for pointers to buffers for which the length isn't -transmitted as part of the function call, namely strings. Strings -are transmitted as a pointer/length pair, both as hex values, e.g.@: - -@smallexample -@code{1aaf/12} -@end smallexample - -@noindent -which is a pointer to data of length 18 bytes at position 0x1aaf. -The length is defined as the full string length in bytes, including -the trailing null byte. Example: - -@smallexample -``hello, world'' at address 0x123456 -@end smallexample - -@noindent -is transmitted as - -@smallexample -@code{123456/d} -@end smallexample - -@node struct stat -@unnumberedsubsubsec struct stat -@cindex struct stat, in file-i/o protocol - -The buffer of type struct stat used by the target and @value{GDBN} is defined -as follows: - -@smallexample -struct stat @{ - unsigned int st_dev; /* device */ - unsigned int st_ino; /* inode */ - mode_t st_mode; /* protection */ - unsigned int st_nlink; /* number of hard links */ - unsigned int st_uid; /* user ID of owner */ - unsigned int st_gid; /* group ID of owner */ - unsigned int st_rdev; /* device type (if inode device) */ - unsigned long st_size; /* total size, in bytes */ - unsigned long st_blksize; /* blocksize for filesystem I/O */ - unsigned long st_blocks; /* number of blocks allocated */ - time_t st_atime; /* time of last access */ - time_t st_mtime; /* time of last modification */ - time_t st_ctime; /* time of last change */ -@}; -@end smallexample - -The integral datatypes are conforming to the definitions given in the -approriate section (see @ref{Integral datatypes}, for details) so this -structure is of size 64 bytes. - -The values of several fields have a restricted meaning and/or -range of values. - -@smallexample -st_dev: 0 file - 1 console - -st_ino: No valid meaning for the target. Transmitted unchanged. - -st_mode: Valid mode bits are described in Appendix C. Any other - bits have currently no meaning for the target. - -st_uid: No valid meaning for the target. Transmitted unchanged. - -st_gid: No valid meaning for the target. Transmitted unchanged. - -st_rdev: No valid meaning for the target. Transmitted unchanged. - -st_atime, st_mtime, st_ctime: - These values have a host and file system dependent - accuracy. Especially on Windows hosts the file systems - don't support exact timing values. -@end smallexample - -The target gets a struct stat of the above representation and is -responsible to coerce it to the target representation before -continuing. - -Note that due to size differences between the host and target -representation of stat members, these members could eventually -get truncated on the target. - -@node struct timeval -@unnumberedsubsubsec struct timeval -@cindex struct timeval, in file-i/o protocol - -The buffer of type struct timeval used by the target and @value{GDBN} -is defined as follows: - -@smallexample -struct timeval @{ - time_t tv_sec; /* second */ - long tv_usec; /* microsecond */ -@}; -@end smallexample - -The integral datatypes are conforming to the definitions given in the -approriate section (see @ref{Integral datatypes}, for details) so this -structure is of size 8 bytes. - -@node Constants -@subsection Constants -@cindex constants, in file-i/o protocol - -The following values are used for the constants inside of the -protocol. @value{GDBN} and target are resposible to translate these -values before and after the call as needed. - -@menu -* Open flags:: -* mode_t values:: -* Errno values:: -* Lseek flags:: -* Limits:: -@end menu - -@node Open flags -@unnumberedsubsubsec Open flags -@cindex open flags, in file-i/o protocol - -All values are given in hexadecimal representation. - -@smallexample - O_RDONLY 0x0 - O_WRONLY 0x1 - O_RDWR 0x2 - O_APPEND 0x8 - O_CREAT 0x200 - O_TRUNC 0x400 - O_EXCL 0x800 -@end smallexample - -@node mode_t values -@unnumberedsubsubsec mode_t values -@cindex mode_t values, in file-i/o protocol - -All values are given in octal representation. - -@smallexample - S_IFREG 0100000 - S_IFDIR 040000 - S_IRUSR 0400 - S_IWUSR 0200 - S_IXUSR 0100 - S_IRGRP 040 - S_IWGRP 020 - S_IXGRP 010 - S_IROTH 04 - S_IWOTH 02 - S_IXOTH 01 -@end smallexample - -@node Errno values -@unnumberedsubsubsec Errno values -@cindex errno values, in file-i/o protocol - -All values are given in decimal representation. - -@smallexample - EPERM 1 - ENOENT 2 - EINTR 4 - EBADF 9 - EACCES 13 - EFAULT 14 - EBUSY 16 - EEXIST 17 - ENODEV 19 - ENOTDIR 20 - EISDIR 21 - EINVAL 22 - ENFILE 23 - EMFILE 24 - EFBIG 27 - ENOSPC 28 - ESPIPE 29 - EROFS 30 - ENAMETOOLONG 91 - EUNKNOWN 9999 -@end smallexample - - EUNKNOWN is used as a fallback error value if a host system returns - any error value not in the list of supported error numbers. - -@node Lseek flags -@unnumberedsubsubsec Lseek flags -@cindex lseek flags, in file-i/o protocol - -@smallexample - SEEK_SET 0 - SEEK_CUR 1 - SEEK_END 2 -@end smallexample - -@node Limits -@unnumberedsubsubsec Limits -@cindex limits, in file-i/o protocol - -All values are given in decimal representation. - -@smallexample - INT_MIN -2147483648 - INT_MAX 2147483647 - UINT_MAX 4294967295 - LONG_MIN -9223372036854775808 - LONG_MAX 9223372036854775807 - ULONG_MAX 18446744073709551615 -@end smallexample - -@node File-I/O Examples -@subsection File-I/O Examples -@cindex file-i/o examples - -Example sequence of a write call, file descriptor 3, buffer is at target -address 0x1234, 6 bytes should be written: - -@smallexample -<- @code{Fwrite,3,1234,6} -@emph{request memory read from target} --> @code{m1234,6} -<- XXXXXX -@emph{return "6 bytes written"} --> @code{F6} -@end smallexample - -Example sequence of a read call, file descriptor 3, buffer is at target -address 0x1234, 6 bytes should be read: - -@smallexample -<- @code{Fread,3,1234,6} -@emph{request memory write to target} --> @code{X1234,6:XXXXXX} -@emph{return "6 bytes read"} --> @code{F6} -@end smallexample - -Example sequence of a read call, call fails on the host due to invalid -file descriptor (EBADF): - -@smallexample -<- @code{Fread,3,1234,6} --> @code{F-1,9} -@end smallexample - -Example sequence of a read call, user presses Ctrl-C before syscall on -host is called: - -@smallexample -<- @code{Fread,3,1234,6} --> @code{F-1,4,C} -<- @code{T02} -@end smallexample - -Example sequence of a read call, user presses Ctrl-C after syscall on -host is called: - -@smallexample -<- @code{Fread,3,1234,6} --> @code{X1234,6:XXXXXX} -<- @code{T02} -@end smallexample - -@include agentexpr.texi - -@include gpl.texi - -@raisesections -@include fdl.texi -@lowersections - -@node Index -@unnumbered Index - -@printindex cp - -@tex -% I think something like @colophon should be in texinfo. In the -% meantime: -\long\def\colophon{\hbox to0pt{}\vfill -\centerline{The body of this manual is set in} -\centerline{\fontname\tenrm,} -\centerline{with headings in {\bf\fontname\tenbf}} -\centerline{and examples in {\tt\fontname\tentt}.} -\centerline{{\it\fontname\tenit\/},} -\centerline{{\bf\fontname\tenbf}, and} -\centerline{{\sl\fontname\tensl\/}} -\centerline{are used for emphasis.}\vfill} -\page\colophon -% Blame: doc@cygnus.com, 1991. -@end tex - -@bye diff --git a/contrib/gdb/gdb/doc/gdbint.texinfo b/contrib/gdb/gdb/doc/gdbint.texinfo deleted file mode 100644 index 2fe4b29fa1ab..000000000000 --- a/contrib/gdb/gdb/doc/gdbint.texinfo +++ /dev/null @@ -1,6757 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@setfilename gdbint.info -@include gdb-cfg.texi -@dircategory Software development -@direntry -* Gdb-Internals: (gdbint). The GNU debugger's internals. -@end direntry - -@ifinfo -This file documents the internals of the GNU debugger @value{GDBN}. -Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003,2004 - Free Software Foundation, Inc. -Contributed by Cygnus Solutions. Written by John Gilmore. -Second Edition by Stan Shebs. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end ifinfo - -@setchapternewpage off -@settitle @value{GDBN} Internals - -@syncodeindex fn cp -@syncodeindex vr cp - -@titlepage -@title @value{GDBN} Internals -@subtitle{A guide to the internals of the GNU debugger} -@author John Gilmore -@author Cygnus Solutions -@author Second Edition: -@author Stan Shebs -@author Cygnus Solutions -@page -@tex -\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision$} % For use in headers, footers too -{\parskip=0pt -\hfill Cygnus Solutions\par -\hfill \manvers\par -\hfill \TeX{}info \texinfoversion\par -} -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, - 2002, 2003, 2004 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end titlepage - -@contents - -@node Top -@c Perhaps this should be the title of the document (but only for info, -@c not for TeX). Existing GNU manuals seem inconsistent on this point. -@top Scope of this Document - -This document documents the internals of the GNU debugger, @value{GDBN}. It -includes description of @value{GDBN}'s key algorithms and operations, as well -as the mechanisms that adapt @value{GDBN} to specific hosts and targets. - -@menu -* Requirements:: -* Overall Structure:: -* Algorithms:: -* User Interface:: -* libgdb:: -* Symbol Handling:: -* Language Support:: -* Host Definition:: -* Target Architecture Definition:: -* Target Vector Definition:: -* Native Debugging:: -* Support Libraries:: -* Coding:: -* Porting GDB:: -* Releasing GDB:: -* Testsuite:: -* Hints:: - -* GDB Observers:: @value{GDBN} Currently available observers -* GNU Free Documentation License:: The license for this documentation -* Index:: -@end menu - -@node Requirements - -@chapter Requirements -@cindex requirements for @value{GDBN} - -Before diving into the internals, you should understand the formal -requirements and other expectations for @value{GDBN}. Although some -of these may seem obvious, there have been proposals for @value{GDBN} -that have run counter to these requirements. - -First of all, @value{GDBN} is a debugger. It's not designed to be a -front panel for embedded systems. It's not a text editor. It's not a -shell. It's not a programming environment. - -@value{GDBN} is an interactive tool. Although a batch mode is -available, @value{GDBN}'s primary role is to interact with a human -programmer. - -@value{GDBN} should be responsive to the user. A programmer hot on -the trail of a nasty bug, and operating under a looming deadline, is -going to be very impatient of everything, including the response time -to debugger commands. - -@value{GDBN} should be relatively permissive, such as for expressions. -While the compiler should be picky (or have the option to be made -picky), since source code lives for a long time usually, the -programmer doing debugging shouldn't be spending time figuring out to -mollify the debugger. - -@value{GDBN} will be called upon to deal with really large programs. -Executable sizes of 50 to 100 megabytes occur regularly, and we've -heard reports of programs approaching 1 gigabyte in size. - -@value{GDBN} should be able to run everywhere. No other debugger is -available for even half as many configurations as @value{GDBN} -supports. - - -@node Overall Structure - -@chapter Overall Structure - -@value{GDBN} consists of three major subsystems: user interface, -symbol handling (the @dfn{symbol side}), and target system handling (the -@dfn{target side}). - -The user interface consists of several actual interfaces, plus -supporting code. - -The symbol side consists of object file readers, debugging info -interpreters, symbol table management, source language expression -parsing, type and value printing. - -The target side consists of execution control, stack frame analysis, and -physical target manipulation. - -The target side/symbol side division is not formal, and there are a -number of exceptions. For instance, core file support involves symbolic -elements (the basic core file reader is in BFD) and target elements (it -supplies the contents of memory and the values of registers). Instead, -this division is useful for understanding how the minor subsystems -should fit together. - -@section The Symbol Side - -The symbolic side of @value{GDBN} can be thought of as ``everything -you can do in @value{GDBN} without having a live program running''. -For instance, you can look at the types of variables, and evaluate -many kinds of expressions. - -@section The Target Side - -The target side of @value{GDBN} is the ``bits and bytes manipulator''. -Although it may make reference to symbolic info here and there, most -of the target side will run with only a stripped executable -available---or even no executable at all, in remote debugging cases. - -Operations such as disassembly, stack frame crawls, and register -display, are able to work with no symbolic info at all. In some cases, -such as disassembly, @value{GDBN} will use symbolic info to present addresses -relative to symbols rather than as raw numbers, but it will work either -way. - -@section Configurations - -@cindex host -@cindex target -@dfn{Host} refers to attributes of the system where @value{GDBN} runs. -@dfn{Target} refers to the system where the program being debugged -executes. In most cases they are the same machine, in which case a -third type of @dfn{Native} attributes come into play. - -Defines and include files needed to build on the host are host support. -Examples are tty support, system defined types, host byte order, host -float format. - -Defines and information needed to handle the target format are target -dependent. Examples are the stack frame format, instruction set, -breakpoint instruction, registers, and how to set up and tear down the stack -to call a function. - -Information that is only needed when the host and target are the same, -is native dependent. One example is Unix child process support; if the -host and target are not the same, doing a fork to start the target -process is a bad idea. The various macros needed for finding the -registers in the @code{upage}, running @code{ptrace}, and such are all -in the native-dependent files. - -Another example of native-dependent code is support for features that -are really part of the target environment, but which require -@code{#include} files that are only available on the host system. Core -file handling and @code{setjmp} handling are two common cases. - -When you want to make @value{GDBN} work ``native'' on a particular machine, you -have to include all three kinds of information. - - -@node Algorithms - -@chapter Algorithms -@cindex algorithms - -@value{GDBN} uses a number of debugging-specific algorithms. They are -often not very complicated, but get lost in the thicket of special -cases and real-world issues. This chapter describes the basic -algorithms and mentions some of the specific target definitions that -they use. - -@section Frames - -@cindex frame -@cindex call stack frame -A frame is a construct that @value{GDBN} uses to keep track of calling -and called functions. - -@findex create_new_frame -@vindex FRAME_FP -@code{FRAME_FP} in the machine description has no meaning to the -machine-independent part of @value{GDBN}, except that it is used when -setting up a new frame from scratch, as follows: - -@smallexample -create_new_frame (read_register (DEPRECATED_FP_REGNUM), read_pc ())); -@end smallexample - -@cindex frame pointer register -Other than that, all the meaning imparted to @code{DEPRECATED_FP_REGNUM} -is imparted by the machine-dependent code. So, -@code{DEPRECATED_FP_REGNUM} can have any value that is convenient for -the code that creates new frames. (@code{create_new_frame} calls -@code{DEPRECATED_INIT_EXTRA_FRAME_INFO} if it is defined; that is where -you should use the @code{DEPRECATED_FP_REGNUM} value, if your frames are -nonstandard.) - -@cindex frame chain -Given a @value{GDBN} frame, define @code{DEPRECATED_FRAME_CHAIN} to -determine the address of the calling function's frame. This will be -used to create a new @value{GDBN} frame struct, and then -@code{DEPRECATED_INIT_EXTRA_FRAME_INFO} and -@code{DEPRECATED_INIT_FRAME_PC} will be called for the new frame. - -@section Breakpoint Handling - -@cindex breakpoints -In general, a breakpoint is a user-designated location in the program -where the user wants to regain control if program execution ever reaches -that location. - -There are two main ways to implement breakpoints; either as ``hardware'' -breakpoints or as ``software'' breakpoints. - -@cindex hardware breakpoints -@cindex program counter -Hardware breakpoints are sometimes available as a builtin debugging -features with some chips. Typically these work by having dedicated -register into which the breakpoint address may be stored. If the PC -(shorthand for @dfn{program counter}) -ever matches a value in a breakpoint registers, the CPU raises an -exception and reports it to @value{GDBN}. - -Another possibility is when an emulator is in use; many emulators -include circuitry that watches the address lines coming out from the -processor, and force it to stop if the address matches a breakpoint's -address. - -A third possibility is that the target already has the ability to do -breakpoints somehow; for instance, a ROM monitor may do its own -software breakpoints. So although these are not literally ``hardware -breakpoints'', from @value{GDBN}'s point of view they work the same; -@value{GDBN} need not do anything more than set the breakpoint and wait -for something to happen. - -Since they depend on hardware resources, hardware breakpoints may be -limited in number; when the user asks for more, @value{GDBN} will -start trying to set software breakpoints. (On some architectures, -notably the 32-bit x86 platforms, @value{GDBN} cannot always know -whether there's enough hardware resources to insert all the hardware -breakpoints and watchpoints. On those platforms, @value{GDBN} prints -an error message only when the program being debugged is continued.) - -@cindex software breakpoints -Software breakpoints require @value{GDBN} to do somewhat more work. -The basic theory is that @value{GDBN} will replace a program -instruction with a trap, illegal divide, or some other instruction -that will cause an exception, and then when it's encountered, -@value{GDBN} will take the exception and stop the program. When the -user says to continue, @value{GDBN} will restore the original -instruction, single-step, re-insert the trap, and continue on. - -Since it literally overwrites the program being tested, the program area -must be writable, so this technique won't work on programs in ROM. It -can also distort the behavior of programs that examine themselves, -although such a situation would be highly unusual. - -Also, the software breakpoint instruction should be the smallest size of -instruction, so it doesn't overwrite an instruction that might be a jump -target, and cause disaster when the program jumps into the middle of the -breakpoint instruction. (Strictly speaking, the breakpoint must be no -larger than the smallest interval between instructions that may be jump -targets; perhaps there is an architecture where only even-numbered -instructions may jumped to.) Note that it's possible for an instruction -set not to have any instructions usable for a software breakpoint, -although in practice only the ARC has failed to define such an -instruction. - -@findex BREAKPOINT -The basic definition of the software breakpoint is the macro -@code{BREAKPOINT}. - -Basic breakpoint object handling is in @file{breakpoint.c}. However, -much of the interesting breakpoint action is in @file{infrun.c}. - -@section Single Stepping - -@section Signal Handling - -@section Thread Handling - -@section Inferior Function Calls - -@section Longjmp Support - -@cindex @code{longjmp} debugging -@value{GDBN} has support for figuring out that the target is doing a -@code{longjmp} and for stopping at the target of the jump, if we are -stepping. This is done with a few specialized internal breakpoints, -which are visible in the output of the @samp{maint info breakpoint} -command. - -@findex GET_LONGJMP_TARGET -To make this work, you need to define a macro called -@code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf} -structure and extract the longjmp target address. Since @code{jmp_buf} -is target specific, you will need to define it in the appropriate -@file{tm-@var{target}.h} file. Look in @file{tm-sun4os4.h} and -@file{sparc-tdep.c} for examples of how to do this. - -@section Watchpoints -@cindex watchpoints - -Watchpoints are a special kind of breakpoints (@pxref{Algorithms, -breakpoints}) which break when data is accessed rather than when some -instruction is executed. When you have data which changes without -your knowing what code does that, watchpoints are the silver bullet to -hunt down and kill such bugs. - -@cindex hardware watchpoints -@cindex software watchpoints -Watchpoints can be either hardware-assisted or not; the latter type is -known as ``software watchpoints.'' @value{GDBN} always uses -hardware-assisted watchpoints if they are available, and falls back on -software watchpoints otherwise. Typical situations where @value{GDBN} -will use software watchpoints are: - -@itemize @bullet -@item -The watched memory region is too large for the underlying hardware -watchpoint support. For example, each x86 debug register can watch up -to 4 bytes of memory, so trying to watch data structures whose size is -more than 16 bytes will cause @value{GDBN} to use software -watchpoints. - -@item -The value of the expression to be watched depends on data held in -registers (as opposed to memory). - -@item -Too many different watchpoints requested. (On some architectures, -this situation is impossible to detect until the debugged program is -resumed.) Note that x86 debug registers are used both for hardware -breakpoints and for watchpoints, so setting too many hardware -breakpoints might cause watchpoint insertion to fail. - -@item -No hardware-assisted watchpoints provided by the target -implementation. -@end itemize - -Software watchpoints are very slow, since @value{GDBN} needs to -single-step the program being debugged and test the value of the -watched expression(s) after each instruction. The rest of this -section is mostly irrelevant for software watchpoints. - -@value{GDBN} uses several macros and primitives to support hardware -watchpoints: - -@table @code -@findex TARGET_HAS_HARDWARE_WATCHPOINTS -@item TARGET_HAS_HARDWARE_WATCHPOINTS -If defined, the target supports hardware watchpoints. - -@findex TARGET_CAN_USE_HARDWARE_WATCHPOINT -@item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other}) -Return the number of hardware watchpoints of type @var{type} that are -possible to be set. The value is positive if @var{count} watchpoints -of this type can be set, zero if setting watchpoints of this type is -not supported, and negative if @var{count} is more than the maximum -number of watchpoints of type @var{type} that can be set. @var{other} -is non-zero if other types of watchpoints are currently enabled (there -are architectures which cannot set watchpoints of different types at -the same time). - -@findex TARGET_REGION_OK_FOR_HW_WATCHPOINT -@item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len}) -Return non-zero if hardware watchpoints can be used to watch a region -whose address is @var{addr} and whose length in bytes is @var{len}. - -@findex TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT -@item TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (@var{size}) -Return non-zero if hardware watchpoints can be used to watch a region -whose size is @var{size}. @value{GDBN} only uses this macro as a -fall-back, in case @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is not -defined. - -@findex TARGET_DISABLE_HW_WATCHPOINTS -@item TARGET_DISABLE_HW_WATCHPOINTS (@var{pid}) -Disables watchpoints in the process identified by @var{pid}. This is -used, e.g., on HP-UX which provides operations to disable and enable -the page-level memory protection that implements hardware watchpoints -on that platform. - -@findex TARGET_ENABLE_HW_WATCHPOINTS -@item TARGET_ENABLE_HW_WATCHPOINTS (@var{pid}) -Enables watchpoints in the process identified by @var{pid}. This is -used, e.g., on HP-UX which provides operations to disable and enable -the page-level memory protection that implements hardware watchpoints -on that platform. - -@findex target_insert_watchpoint -@findex target_remove_watchpoint -@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type}) -@itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type}) -Insert or remove a hardware watchpoint starting at @var{addr}, for -@var{len} bytes. @var{type} is the watchpoint type, one of the -possible values of the enumerated data type @code{target_hw_bp_type}, -defined by @file{breakpoint.h} as follows: - -@smallexample - enum target_hw_bp_type - @{ - hw_write = 0, /* Common (write) HW watchpoint */ - hw_read = 1, /* Read HW watchpoint */ - hw_access = 2, /* Access (read or write) HW watchpoint */ - hw_execute = 3 /* Execute HW breakpoint */ - @}; -@end smallexample - -@noindent -These two macros should return 0 for success, non-zero for failure. - -@cindex insert or remove hardware breakpoint -@findex target_remove_hw_breakpoint -@findex target_insert_hw_breakpoint -@item target_remove_hw_breakpoint (@var{addr}, @var{shadow}) -@itemx target_insert_hw_breakpoint (@var{addr}, @var{shadow}) -Insert or remove a hardware-assisted breakpoint at address @var{addr}. -Returns zero for success, non-zero for failure. @var{shadow} is the -real contents of the byte where the breakpoint has been inserted; it -is generally not valid when hardware breakpoints are used, but since -no other code touches these values, the implementations of the above -two macros can use them for their internal purposes. - -@findex target_stopped_data_address -@item target_stopped_data_address () -If the inferior has some watchpoint that triggered, return the address -associated with that watchpoint. Otherwise, return zero. - -@findex HAVE_STEPPABLE_WATCHPOINT -@item HAVE_STEPPABLE_WATCHPOINT -If defined to a non-zero value, it is not necessary to disable a -watchpoint to step over it. - -@findex HAVE_NONSTEPPABLE_WATCHPOINT -@item HAVE_NONSTEPPABLE_WATCHPOINT -If defined to a non-zero value, @value{GDBN} should disable a -watchpoint to step the inferior over it. - -@findex HAVE_CONTINUABLE_WATCHPOINT -@item HAVE_CONTINUABLE_WATCHPOINT -If defined to a non-zero value, it is possible to continue the -inferior after a watchpoint has been hit. - -@findex CANNOT_STEP_HW_WATCHPOINTS -@item CANNOT_STEP_HW_WATCHPOINTS -If this is defined to a non-zero value, @value{GDBN} will remove all -watchpoints before stepping the inferior. - -@findex STOPPED_BY_WATCHPOINT -@item STOPPED_BY_WATCHPOINT (@var{wait_status}) -Return non-zero if stopped by a watchpoint. @var{wait_status} is of -the type @code{struct target_waitstatus}, defined by @file{target.h}. -@end table - -@subsection x86 Watchpoints -@cindex x86 debug registers -@cindex watchpoints, on x86 - -The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug -registers designed to facilitate debugging. @value{GDBN} provides a -generic library of functions that x86-based ports can use to implement -support for watchpoints and hardware-assisted breakpoints. This -subsection documents the x86 watchpoint facilities in @value{GDBN}. - -To use the generic x86 watchpoint support, a port should do the -following: - -@itemize @bullet -@findex I386_USE_GENERIC_WATCHPOINTS -@item -Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the -target-dependent headers. - -@item -Include the @file{config/i386/nm-i386.h} header file @emph{after} -defining @code{I386_USE_GENERIC_WATCHPOINTS}. - -@item -Add @file{i386-nat.o} to the value of the Make variable -@code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}) or -@code{TDEPFILES} (@pxref{Target Architecture Definition, TDEPFILES}). - -@item -Provide implementations for the @code{I386_DR_LOW_*} macros described -below. Typically, each macro should call a target-specific function -which does the real work. -@end itemize - -The x86 watchpoint support works by maintaining mirror images of the -debug registers. Values are copied between the mirror images and the -real debug registers via a set of macros which each target needs to -provide: - -@table @code -@findex I386_DR_LOW_SET_CONTROL -@item I386_DR_LOW_SET_CONTROL (@var{val}) -Set the Debug Control (DR7) register to the value @var{val}. - -@findex I386_DR_LOW_SET_ADDR -@item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr}) -Put the address @var{addr} into the debug register number @var{idx}. - -@findex I386_DR_LOW_RESET_ADDR -@item I386_DR_LOW_RESET_ADDR (@var{idx}) -Reset (i.e.@: zero out) the address stored in the debug register -number @var{idx}. - -@findex I386_DR_LOW_GET_STATUS -@item I386_DR_LOW_GET_STATUS -Return the value of the Debug Status (DR6) register. This value is -used immediately after it is returned by -@code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status -register values. -@end table - -For each one of the 4 debug registers (whose indices are from 0 to 3) -that store addresses, a reference count is maintained by @value{GDBN}, -to allow sharing of debug registers by several watchpoints. This -allows users to define several watchpoints that watch the same -expression, but with different conditions and/or commands, without -wasting debug registers which are in short supply. @value{GDBN} -maintains the reference counts internally, targets don't have to do -anything to use this feature. - -The x86 debug registers can each watch a region that is 1, 2, or 4 -bytes long. The ia32 architecture requires that each watched region -be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte -region on 4-byte boundary. However, the x86 watchpoint support in -@value{GDBN} can watch unaligned regions and regions larger than 4 -bytes (up to 16 bytes) by allocating several debug registers to watch -a single region. This allocation of several registers per a watched -region is also done automatically without target code intervention. - -The generic x86 watchpoint support provides the following API for the -@value{GDBN}'s application code: - -@table @code -@findex i386_region_ok_for_watchpoint -@item i386_region_ok_for_watchpoint (@var{addr}, @var{len}) -The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call -this function. It counts the number of debug registers required to -watch a given region, and returns a non-zero value if that number is -less than 4, the number of debug registers available to x86 -processors. - -@findex i386_stopped_data_address -@item i386_stopped_data_address (void) -The macros @code{STOPPED_BY_WATCHPOINT} and -@code{target_stopped_data_address} are set to call this function. The -argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This -function examines the breakpoint condition bits in the DR6 Debug -Status register, as returned by the @code{I386_DR_LOW_GET_STATUS} -macro, and returns the address associated with the first bit that is -set in DR6. - -@findex i386_insert_watchpoint -@findex i386_remove_watchpoint -@item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type}) -@itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type}) -Insert or remove a watchpoint. The macros -@code{target_insert_watchpoint} and @code{target_remove_watchpoint} -are set to call these functions. @code{i386_insert_watchpoint} first -looks for a debug register which is already set to watch the same -region for the same access types; if found, it just increments the -reference count of that debug register, thus implementing debug -register sharing between watchpoints. If no such register is found, -the function looks for a vacant debug register, sets its mirrored -value to @var{addr}, sets the mirrored value of DR7 Debug Control -register as appropriate for the @var{len} and @var{type} parameters, -and then passes the new values of the debug register and DR7 to the -inferior by calling @code{I386_DR_LOW_SET_ADDR} and -@code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is -required to cover the given region, the above process is repeated for -each debug register. - -@code{i386_remove_watchpoint} does the opposite: it resets the address -in the mirrored value of the debug register and its read/write and -length bits in the mirrored value of DR7, then passes these new -values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and -@code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several -watchpoints, each time a @code{i386_remove_watchpoint} is called, it -decrements the reference count, and only calls -@code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when -the count goes to zero. - -@findex i386_insert_hw_breakpoint -@findex i386_remove_hw_breakpoint -@item i386_insert_hw_breakpoint (@var{addr}, @var{shadow} -@itemx i386_remove_hw_breakpoint (@var{addr}, @var{shadow}) -These functions insert and remove hardware-assisted breakpoints. The -macros @code{target_insert_hw_breakpoint} and -@code{target_remove_hw_breakpoint} are set to call these functions. -These functions work like @code{i386_insert_watchpoint} and -@code{i386_remove_watchpoint}, respectively, except that they set up -the debug registers to watch instruction execution, and each -hardware-assisted breakpoint always requires exactly one debug -register. - -@findex i386_stopped_by_hwbp -@item i386_stopped_by_hwbp (void) -This function returns non-zero if the inferior has some watchpoint or -hardware breakpoint that triggered. It works like -@code{i386_stopped_data_address}, except that it doesn't return the -address whose watchpoint triggered. - -@findex i386_cleanup_dregs -@item i386_cleanup_dregs (void) -This function clears all the reference counts, addresses, and control -bits in the mirror images of the debug registers. It doesn't affect -the actual debug registers in the inferior process. -@end table - -@noindent -@strong{Notes:} -@enumerate 1 -@item -x86 processors support setting watchpoints on I/O reads or writes. -However, since no target supports this (as of March 2001), and since -@code{enum target_hw_bp_type} doesn't even have an enumeration for I/O -watchpoints, this feature is not yet available to @value{GDBN} running -on x86. - -@item -x86 processors can enable watchpoints locally, for the current task -only, or globally, for all the tasks. For each debug register, -there's a bit in the DR7 Debug Control register that determines -whether the associated address is watched locally or globally. The -current implementation of x86 watchpoint support in @value{GDBN} -always sets watchpoints to be locally enabled, since global -watchpoints might interfere with the underlying OS and are probably -unavailable in many platforms. -@end enumerate - -@section Observing changes in @value{GDBN} internals -@cindex observer pattern interface -@cindex notifications about changes in internals - -In order to function properly, several modules need to be notified when -some changes occur in the @value{GDBN} internals. Traditionally, these -modules have relied on several paradigms, the most common ones being -hooks and gdb-events. Unfortunately, none of these paradigms was -versatile enough to become the standard notification mechanism in -@value{GDBN}. The fact that they only supported one ``client'' was also -a strong limitation. - -A new paradigm, based on the Observer pattern of the @cite{Design -Patterns} book, has therefore been implemented. The goal was to provide -a new interface overcoming the issues with the notification mechanisms -previously available. This new interface needed to be strongly typed, -easy to extend, and versatile enough to be used as the standard -interface when adding new notifications. - -See @ref{GDB Observers} for a brief description of the observers -currently implemented in GDB. The rationale for the current -implementation is also briefly discussed. - -@node User Interface - -@chapter User Interface - -@value{GDBN} has several user interfaces. Although the command-line interface -is the most common and most familiar, there are others. - -@section Command Interpreter - -@cindex command interpreter -@cindex CLI -The command interpreter in @value{GDBN} is fairly simple. It is designed to -allow for the set of commands to be augmented dynamically, and also -has a recursive subcommand capability, where the first argument to -a command may itself direct a lookup on a different command list. - -For instance, the @samp{set} command just starts a lookup on the -@code{setlist} command list, while @samp{set thread} recurses -to the @code{set_thread_cmd_list}. - -@findex add_cmd -@findex add_com -To add commands in general, use @code{add_cmd}. @code{add_com} adds to -the main command list, and should be used for those commands. The usual -place to add commands is in the @code{_initialize_@var{xyz}} routines at -the ends of most source files. - -@findex add_setshow_cmd -@findex add_setshow_cmd_full -To add paired @samp{set} and @samp{show} commands, use -@code{add_setshow_cmd} or @code{add_setshow_cmd_full}. The former is -a slightly simpler interface which is useful when you don't need to -further modify the new command structures, while the latter returns -the new command structures for manipulation. - -@cindex deprecating commands -@findex deprecate_cmd -Before removing commands from the command set it is a good idea to -deprecate them for some time. Use @code{deprecate_cmd} on commands or -aliases to set the deprecated flag. @code{deprecate_cmd} takes a -@code{struct cmd_list_element} as it's first argument. You can use the -return value from @code{add_com} or @code{add_cmd} to deprecate the -command immediately after it is created. - -The first time a command is used the user will be warned and offered a -replacement (if one exists). Note that the replacement string passed to -@code{deprecate_cmd} should be the full name of the command, i.e. the -entire string the user should type at the command line. - -@section UI-Independent Output---the @code{ui_out} Functions -@c This section is based on the documentation written by Fernando -@c Nasser <fnasser@redhat.com>. - -@cindex @code{ui_out} functions -The @code{ui_out} functions present an abstraction level for the -@value{GDBN} output code. They hide the specifics of different user -interfaces supported by @value{GDBN}, and thus free the programmer -from the need to write several versions of the same code, one each for -every UI, to produce output. - -@subsection Overview and Terminology - -In general, execution of each @value{GDBN} command produces some sort -of output, and can even generate an input request. - -Output can be generated for the following purposes: - -@itemize @bullet -@item -to display a @emph{result} of an operation; - -@item -to convey @emph{info} or produce side-effects of a requested -operation; - -@item -to provide a @emph{notification} of an asynchronous event (including -progress indication of a prolonged asynchronous operation); - -@item -to display @emph{error messages} (including warnings); - -@item -to show @emph{debug data}; - -@item -to @emph{query} or prompt a user for input (a special case). -@end itemize - -@noindent -This section mainly concentrates on how to build result output, -although some of it also applies to other kinds of output. - -Generation of output that displays the results of an operation -involves one or more of the following: - -@itemize @bullet -@item -output of the actual data - -@item -formatting the output as appropriate for console output, to make it -easily readable by humans - -@item -machine oriented formatting--a more terse formatting to allow for easy -parsing by programs which read @value{GDBN}'s output - -@item -annotation, whose purpose is to help legacy GUIs to identify interesting -parts in the output -@end itemize - -The @code{ui_out} routines take care of the first three aspects. -Annotations are provided by separate annotation routines. Note that use -of annotations for an interface between a GUI and @value{GDBN} is -deprecated. - -Output can be in the form of a single item, which we call a @dfn{field}; -a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of -non-identical fields; or a @dfn{table}, which is a tuple consisting of a -header and a body. In a BNF-like form: - -@table @code -@item <table> @expansion{} -@code{<header> <body>} -@item <header> @expansion{} -@code{@{ <column> @}} -@item <column> @expansion{} -@code{<width> <alignment> <title>} -@item <body> @expansion{} -@code{@{<row>@}} -@end table - - -@subsection General Conventions - -Most @code{ui_out} routines are of type @code{void}, the exceptions are -@code{ui_out_stream_new} (which returns a pointer to the newly created -object) and the @code{make_cleanup} routines. - -The first parameter is always the @code{ui_out} vector object, a pointer -to a @code{struct ui_out}. - -The @var{format} parameter is like in @code{printf} family of functions. -When it is present, there must also be a variable list of arguments -sufficient used to satisfy the @code{%} specifiers in the supplied -format. - -When a character string argument is not used in a @code{ui_out} function -call, a @code{NULL} pointer has to be supplied instead. - - -@subsection Table, Tuple and List Functions - -@cindex list output functions -@cindex table output functions -@cindex tuple output functions -This section introduces @code{ui_out} routines for building lists, -tuples and tables. The routines to output the actual data items -(fields) are presented in the next section. - -To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field -containing information about an object; a @dfn{list} is a sequence of -fields where each field describes an identical object. - -Use the @dfn{table} functions when your output consists of a list of -rows (tuples) and the console output should include a heading. Use this -even when you are listing just one object but you still want the header. - -@cindex nesting level in @code{ui_out} functions -Tables can not be nested. Tuples and lists can be nested up to a -maximum of five levels. - -The overall structure of the table output code is something like this: - -@smallexample - ui_out_table_begin - ui_out_table_header - @dots{} - ui_out_table_body - ui_out_tuple_begin - ui_out_field_* - @dots{} - ui_out_tuple_end - @dots{} - ui_out_table_end -@end smallexample - -Here is the description of table-, tuple- and list-related @code{ui_out} -functions: - -@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid}) -The function @code{ui_out_table_begin} marks the beginning of the output -of a table. It should always be called before any other @code{ui_out} -function for a given table. @var{nbrofcols} is the number of columns in -the table. @var{nr_rows} is the number of rows in the table. -@var{tblid} is an optional string identifying the table. The string -pointed to by @var{tblid} is copied by the implementation of -@code{ui_out_table_begin}, so the application can free the string if it -was @code{malloc}ed. - -The companion function @code{ui_out_table_end}, described below, marks -the end of the table's output. -@end deftypefun - -@deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr}) -@code{ui_out_table_header} provides the header information for a single -table column. You call this function several times, one each for every -column of the table, after @code{ui_out_table_begin}, but before -@code{ui_out_table_body}. - -The value of @var{width} gives the column width in characters. The -value of @var{alignment} is one of @code{left}, @code{center}, and -@code{right}, and it specifies how to align the header: left-justify, -center, or right-justify it. @var{colhdr} points to a string that -specifies the column header; the implementation copies that string, so -column header strings in @code{malloc}ed storage can be freed after the -call. -@end deftypefun - -@deftypefun void ui_out_table_body (struct ui_out *@var{uiout}) -This function delimits the table header from the table body. -@end deftypefun - -@deftypefun void ui_out_table_end (struct ui_out *@var{uiout}) -This function signals the end of a table's output. It should be called -after the table body has been produced by the list and field output -functions. - -There should be exactly one call to @code{ui_out_table_end} for each -call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions -will signal an internal error. -@end deftypefun - -The output of the tuples that represent the table rows must follow the -call to @code{ui_out_table_body} and precede the call to -@code{ui_out_table_end}. You build a tuple by calling -@code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable -calls to functions which actually output fields between them. - -@deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id}) -This function marks the beginning of a tuple output. @var{id} points -to an optional string that identifies the tuple; it is copied by the -implementation, and so strings in @code{malloc}ed storage can be freed -after the call. -@end deftypefun - -@deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout}) -This function signals an end of a tuple output. There should be exactly -one call to @code{ui_out_tuple_end} for each call to -@code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will -be signaled. -@end deftypefun - -@deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) -This function first opens the tuple and then establishes a cleanup -(@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient -and correct implementation of the non-portable@footnote{The function -cast is not portable ISO C.} code sequence: -@smallexample -struct cleanup *old_cleanup; -ui_out_tuple_begin (uiout, "..."); -old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end, - uiout); -@end smallexample -@end deftypefun - -@deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id}) -This function marks the beginning of a list output. @var{id} points to -an optional string that identifies the list; it is copied by the -implementation, and so strings in @code{malloc}ed storage can be freed -after the call. -@end deftypefun - -@deftypefun void ui_out_list_end (struct ui_out *@var{uiout}) -This function signals an end of a list output. There should be exactly -one call to @code{ui_out_list_end} for each call to -@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will -be signaled. -@end deftypefun - -@deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) -Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function -opens a list and then establishes cleanup (@pxref{Coding, Cleanups}) -that will close the list.list. -@end deftypefun - -@subsection Item Output Functions - -@cindex item output functions -@cindex field output functions -@cindex data output -The functions described below produce output for the actual data -items, or fields, which contain information about the object. - -Choose the appropriate function accordingly to your particular needs. - -@deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{format}, ...) -This is the most general output function. It produces the -representation of the data in the variable-length argument list -according to formatting specifications in @var{format}, a -@code{printf}-like format string. The optional argument @var{fldname} -supplies the name of the field. The data items themselves are -supplied as additional arguments after @var{format}. - -This generic function should be used only when it is not possible to -use one of the specialized versions (see below). -@end deftypefun - -@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value}) -This function outputs a value of an @code{int} variable. It uses the -@code{"%d"} output conversion specification. @var{fldname} specifies -the name of the field. -@end deftypefun - -@deftypefun void ui_out_field_fmt_int (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{fldname}, int @var{value}) -This function outputs a value of an @code{int} variable. It differs from -@code{ui_out_field_int} in that the caller specifies the desired @var{width} and @var{alignment} of the output. -@var{fldname} specifies -the name of the field. -@end deftypefun - -@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address}) -This function outputs an address. -@end deftypefun - -@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string}) -This function outputs a string using the @code{"%s"} conversion -specification. -@end deftypefun - -Sometimes, there's a need to compose your output piece by piece using -functions that operate on a stream, such as @code{value_print} or -@code{fprintf_symbol_filtered}. These functions accept an argument of -the type @code{struct ui_file *}, a pointer to a @code{ui_file} object -used to store the data stream used for the output. When you use one -of these functions, you need a way to pass their results stored in a -@code{ui_file} object to the @code{ui_out} functions. To this end, -you first create a @code{ui_stream} object by calling -@code{ui_out_stream_new}, pass the @code{stream} member of that -@code{ui_stream} object to @code{value_print} and similar functions, -and finally call @code{ui_out_field_stream} to output the field you -constructed. When the @code{ui_stream} object is no longer needed, -you should destroy it and free its memory by calling -@code{ui_out_stream_delete}. - -@deftypefun struct ui_stream *ui_out_stream_new (struct ui_out *@var{uiout}) -This function creates a new @code{ui_stream} object which uses the -same output methods as the @code{ui_out} object whose pointer is -passed in @var{uiout}. It returns a pointer to the newly created -@code{ui_stream} object. -@end deftypefun - -@deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf}) -This functions destroys a @code{ui_stream} object specified by -@var{streambuf}. -@end deftypefun - -@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf}) -This function consumes all the data accumulated in -@code{streambuf->stream} and outputs it like -@code{ui_out_field_string} does. After a call to -@code{ui_out_field_stream}, the accumulated data no longer exists, but -the stream is still valid and may be used for producing more fields. -@end deftypefun - -@strong{Important:} If there is any chance that your code could bail -out before completing output generation and reaching the point where -@code{ui_out_stream_delete} is called, it is necessary to set up a -cleanup, to avoid leaking memory and other resources. Here's a -skeleton code to do that: - -@smallexample - struct ui_stream *mybuf = ui_out_stream_new (uiout); - struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf); - ... - do_cleanups (old); -@end smallexample - -If the function already has the old cleanup chain set (for other kinds -of cleanups), you just have to add your cleanup to it: - -@smallexample - mybuf = ui_out_stream_new (uiout); - make_cleanup (ui_out_stream_delete, mybuf); -@end smallexample - -Note that with cleanups in place, you should not call -@code{ui_out_stream_delete} directly, or you would attempt to free the -same buffer twice. - -@subsection Utility Output Functions - -@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname}) -This function skips a field in a table. Use it if you have to leave -an empty field without disrupting the table alignment. The argument -@var{fldname} specifies a name for the (missing) filed. -@end deftypefun - -@deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string}) -This function outputs the text in @var{string} in a way that makes it -easy to be read by humans. For example, the console implementation of -this method filters the text through a built-in pager, to prevent it -from scrolling off the visible portion of the screen. - -Use this function for printing relatively long chunks of text around -the actual field data: the text it produces is not aligned according -to the table's format. Use @code{ui_out_field_string} to output a -string field, and use @code{ui_out_message}, described below, to -output short messages. -@end deftypefun - -@deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces}) -This function outputs @var{nspaces} spaces. It is handy to align the -text produced by @code{ui_out_text} with the rest of the table or -list. -@end deftypefun - -@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...) -This function produces a formatted message, provided that the current -verbosity level is at least as large as given by @var{verbosity}. The -current verbosity level is specified by the user with the @samp{set -verbositylevel} command.@footnote{As of this writing (April 2001), -setting verbosity level is not yet implemented, and is always returned -as zero. So calling @code{ui_out_message} with a @var{verbosity} -argument more than zero will cause the message to never be printed.} -@end deftypefun - -@deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent}) -This function gives the console output filter (a paging filter) a hint -of where to break lines which are too long. Ignored for all other -output consumers. @var{indent}, if non-@code{NULL}, is the string to -be printed to indent the wrapped text on the next line; it must remain -accessible until the next call to @code{ui_out_wrap_hint}, or until an -explicit newline is produced by one of the other functions. If -@var{indent} is @code{NULL}, the wrapped text will not be indented. -@end deftypefun - -@deftypefun void ui_out_flush (struct ui_out *@var{uiout}) -This function flushes whatever output has been accumulated so far, if -the UI buffers output. -@end deftypefun - - -@subsection Examples of Use of @code{ui_out} functions - -@cindex using @code{ui_out} functions -@cindex @code{ui_out} functions, usage examples -This section gives some practical examples of using the @code{ui_out} -functions to generalize the old console-oriented code in -@value{GDBN}. The examples all come from functions defined on the -@file{breakpoints.c} file. - -This example, from the @code{breakpoint_1} function, shows how to -produce a table. - -The original code was: - -@smallexample - if (!found_a_breakpoint++) - @{ - annotate_breakpoints_headers (); - - annotate_field (0); - printf_filtered ("Num "); - annotate_field (1); - printf_filtered ("Type "); - annotate_field (2); - printf_filtered ("Disp "); - annotate_field (3); - printf_filtered ("Enb "); - if (addressprint) - @{ - annotate_field (4); - printf_filtered ("Address "); - @} - annotate_field (5); - printf_filtered ("What\n"); - - annotate_breakpoints_table (); - @} -@end smallexample - -Here's the new version: - -@smallexample - nr_printable_breakpoints = @dots{}; - - if (addressprint) - ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable"); - else - ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable"); - - if (nr_printable_breakpoints > 0) - annotate_breakpoints_headers (); - if (nr_printable_breakpoints > 0) - annotate_field (0); - ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */ - if (nr_printable_breakpoints > 0) - annotate_field (1); - ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */ - if (nr_printable_breakpoints > 0) - annotate_field (2); - ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */ - if (nr_printable_breakpoints > 0) - annotate_field (3); - ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */ - if (addressprint) - @{ - if (nr_printable_breakpoints > 0) - annotate_field (4); - if (TARGET_ADDR_BIT <= 32) - ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */ - else - ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */ - @} - if (nr_printable_breakpoints > 0) - annotate_field (5); - ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */ - ui_out_table_body (uiout); - if (nr_printable_breakpoints > 0) - annotate_breakpoints_table (); -@end smallexample - -This example, from the @code{print_one_breakpoint} function, shows how -to produce the actual data for the table whose structure was defined -in the above example. The original code was: - -@smallexample - annotate_record (); - annotate_field (0); - printf_filtered ("%-3d ", b->number); - annotate_field (1); - if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0])) - || ((int) b->type != bptypes[(int) b->type].type)) - internal_error ("bptypes table does not describe type #%d.", - (int)b->type); - printf_filtered ("%-14s ", bptypes[(int)b->type].description); - annotate_field (2); - printf_filtered ("%-4s ", bpdisps[(int)b->disposition]); - annotate_field (3); - printf_filtered ("%-3c ", bpenables[(int)b->enable]); - @dots{} -@end smallexample - -This is the new version: - -@smallexample - annotate_record (); - ui_out_tuple_begin (uiout, "bkpt"); - annotate_field (0); - ui_out_field_int (uiout, "number", b->number); - annotate_field (1); - if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0]))) - || ((int) b->type != bptypes[(int) b->type].type)) - internal_error ("bptypes table does not describe type #%d.", - (int) b->type); - ui_out_field_string (uiout, "type", bptypes[(int)b->type].description); - annotate_field (2); - ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]); - annotate_field (3); - ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]); - @dots{} -@end smallexample - -This example, also from @code{print_one_breakpoint}, shows how to -produce a complicated output field using the @code{print_expression} -functions which requires a stream to be passed. It also shows how to -automate stream destruction with cleanups. The original code was: - -@smallexample - annotate_field (5); - print_expression (b->exp, gdb_stdout); -@end smallexample - -The new version is: - -@smallexample - struct ui_stream *stb = ui_out_stream_new (uiout); - struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb); - ... - annotate_field (5); - print_expression (b->exp, stb->stream); - ui_out_field_stream (uiout, "what", local_stream); -@end smallexample - -This example, also from @code{print_one_breakpoint}, shows how to use -@code{ui_out_text} and @code{ui_out_field_string}. The original code -was: - -@smallexample - annotate_field (5); - if (b->dll_pathname == NULL) - printf_filtered ("<any library> "); - else - printf_filtered ("library \"%s\" ", b->dll_pathname); -@end smallexample - -It became: - -@smallexample - annotate_field (5); - if (b->dll_pathname == NULL) - @{ - ui_out_field_string (uiout, "what", "<any library>"); - ui_out_spaces (uiout, 1); - @} - else - @{ - ui_out_text (uiout, "library \""); - ui_out_field_string (uiout, "what", b->dll_pathname); - ui_out_text (uiout, "\" "); - @} -@end smallexample - -The following example from @code{print_one_breakpoint} shows how to -use @code{ui_out_field_int} and @code{ui_out_spaces}. The original -code was: - -@smallexample - annotate_field (5); - if (b->forked_inferior_pid != 0) - printf_filtered ("process %d ", b->forked_inferior_pid); -@end smallexample - -It became: - -@smallexample - annotate_field (5); - if (b->forked_inferior_pid != 0) - @{ - ui_out_text (uiout, "process "); - ui_out_field_int (uiout, "what", b->forked_inferior_pid); - ui_out_spaces (uiout, 1); - @} -@end smallexample - -Here's an example of using @code{ui_out_field_string}. The original -code was: - -@smallexample - annotate_field (5); - if (b->exec_pathname != NULL) - printf_filtered ("program \"%s\" ", b->exec_pathname); -@end smallexample - -It became: - -@smallexample - annotate_field (5); - if (b->exec_pathname != NULL) - @{ - ui_out_text (uiout, "program \""); - ui_out_field_string (uiout, "what", b->exec_pathname); - ui_out_text (uiout, "\" "); - @} -@end smallexample - -Finally, here's an example of printing an address. The original code: - -@smallexample - annotate_field (4); - printf_filtered ("%s ", - local_hex_string_custom ((unsigned long) b->address, "08l")); -@end smallexample - -It became: - -@smallexample - annotate_field (4); - ui_out_field_core_addr (uiout, "Address", b->address); -@end smallexample - - -@section Console Printing - -@section TUI - -@node libgdb - -@chapter libgdb - -@section libgdb 1.0 -@cindex @code{libgdb} -@code{libgdb} 1.0 was an abortive project of years ago. The theory was -to provide an API to @value{GDBN}'s functionality. - -@section libgdb 2.0 -@cindex @code{libgdb} -@code{libgdb} 2.0 is an ongoing effort to update @value{GDBN} so that is -better able to support graphical and other environments. - -Since @code{libgdb} development is on-going, its architecture is still -evolving. The following components have so far been identified: - -@itemize @bullet -@item -Observer - @file{gdb-events.h}. -@item -Builder - @file{ui-out.h} -@item -Event Loop - @file{event-loop.h} -@item -Library - @file{gdb.h} -@end itemize - -The model that ties these components together is described below. - -@section The @code{libgdb} Model - -A client of @code{libgdb} interacts with the library in two ways. - -@itemize @bullet -@item -As an observer (using @file{gdb-events}) receiving notifications from -@code{libgdb} of any internal state changes (break point changes, run -state, etc). -@item -As a client querying @code{libgdb} (using the @file{ui-out} builder) to -obtain various status values from @value{GDBN}. -@end itemize - -Since @code{libgdb} could have multiple clients (e.g. a GUI supporting -the existing @value{GDBN} CLI), those clients must co-operate when -controlling @code{libgdb}. In particular, a client must ensure that -@code{libgdb} is idle (i.e. no other client is using @code{libgdb}) -before responding to a @file{gdb-event} by making a query. - -@section CLI support - -At present @value{GDBN}'s CLI is very much entangled in with the core of -@code{libgdb}. Consequently, a client wishing to include the CLI in -their interface needs to carefully co-ordinate its own and the CLI's -requirements. - -It is suggested that the client set @code{libgdb} up to be bi-modal -(alternate between CLI and client query modes). The notes below sketch -out the theory: - -@itemize @bullet -@item -The client registers itself as an observer of @code{libgdb}. -@item -The client create and install @code{cli-out} builder using its own -versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and -@code{gdb_stdout} streams. -@item -The client creates a separate custom @code{ui-out} builder that is only -used while making direct queries to @code{libgdb}. -@end itemize - -When the client receives input intended for the CLI, it simply passes it -along. Since the @code{cli-out} builder is installed by default, all -the CLI output in response to that command is routed (pronounced rooted) -through to the client controlled @code{gdb_stdout} et.@: al.@: streams. -At the same time, the client is kept abreast of internal changes by -virtue of being a @code{libgdb} observer. - -The only restriction on the client is that it must wait until -@code{libgdb} becomes idle before initiating any queries (using the -client's custom builder). - -@section @code{libgdb} components - -@subheading Observer - @file{gdb-events.h} -@file{gdb-events} provides the client with a very raw mechanism that can -be used to implement an observer. At present it only allows for one -observer and that observer must, internally, handle the need to delay -the processing of any event notifications until after @code{libgdb} has -finished the current command. - -@subheading Builder - @file{ui-out.h} -@file{ui-out} provides the infrastructure necessary for a client to -create a builder. That builder is then passed down to @code{libgdb} -when doing any queries. - -@subheading Event Loop - @file{event-loop.h} -@c There could be an entire section on the event-loop -@file{event-loop}, currently non-re-entrant, provides a simple event -loop. A client would need to either plug its self into this loop or, -implement a new event-loop that GDB would use. - -The event-loop will eventually be made re-entrant. This is so that -@value{GDBN} can better handle the problem of some commands blocking -instead of returning. - -@subheading Library - @file{gdb.h} -@file{libgdb} is the most obvious component of this system. It provides -the query interface. Each function is parameterized by a @code{ui-out} -builder. The result of the query is constructed using that builder -before the query function returns. - -@node Symbol Handling - -@chapter Symbol Handling - -Symbols are a key part of @value{GDBN}'s operation. Symbols include variables, -functions, and types. - -@section Symbol Reading - -@cindex symbol reading -@cindex reading of symbols -@cindex symbol files -@value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol -file is the file containing the program which @value{GDBN} is -debugging. @value{GDBN} can be directed to use a different file for -symbols (with the @samp{symbol-file} command), and it can also read -more symbols via the @samp{add-file} and @samp{load} commands, or while -reading symbols from shared libraries. - -@findex find_sym_fns -Symbol files are initially opened by code in @file{symfile.c} using -the BFD library (@pxref{Support Libraries}). BFD identifies the type -of the file by examining its header. @code{find_sym_fns} then uses -this identification to locate a set of symbol-reading functions. - -@findex add_symtab_fns -@cindex @code{sym_fns} structure -@cindex adding a symbol-reading module -Symbol-reading modules identify themselves to @value{GDBN} by calling -@code{add_symtab_fns} during their module initialization. The argument -to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the -name (or name prefix) of the symbol format, the length of the prefix, -and pointers to four functions. These functions are called at various -times to process symbol files whose identification matches the specified -prefix. - -The functions supplied by each module are: - -@table @code -@item @var{xyz}_symfile_init(struct sym_fns *sf) - -@cindex secondary symbol file -Called from @code{symbol_file_add} when we are about to read a new -symbol file. This function should clean up any internal state (possibly -resulting from half-read previous files, for example) and prepare to -read a new symbol file. Note that the symbol file which we are reading -might be a new ``main'' symbol file, or might be a secondary symbol file -whose symbols are being added to the existing symbol table. - -The argument to @code{@var{xyz}_symfile_init} is a newly allocated -@code{struct sym_fns} whose @code{bfd} field contains the BFD for the -new symbol file being read. Its @code{private} field has been zeroed, -and can be modified as desired. Typically, a struct of private -information will be @code{malloc}'d, and a pointer to it will be placed -in the @code{private} field. - -There is no result from @code{@var{xyz}_symfile_init}, but it can call -@code{error} if it detects an unavoidable problem. - -@item @var{xyz}_new_init() - -Called from @code{symbol_file_add} when discarding existing symbols. -This function needs only handle the symbol-reading module's internal -state; the symbol table data structures visible to the rest of -@value{GDBN} will be discarded by @code{symbol_file_add}. It has no -arguments and no result. It may be called after -@code{@var{xyz}_symfile_init}, if a new symbol table is being read, or -may be called alone if all symbols are simply being discarded. - -@item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) - -Called from @code{symbol_file_add} to actually read the symbols from a -symbol-file into a set of psymtabs or symtabs. - -@code{sf} points to the @code{struct sym_fns} originally passed to -@code{@var{xyz}_sym_init} for possible initialization. @code{addr} is -the offset between the file's specified start address and its true -address in memory. @code{mainline} is 1 if this is the main symbol -table being read, and 0 if a secondary symbol file (e.g. shared library -or dynamically loaded file) is being read.@refill -@end table - -In addition, if a symbol-reading module creates psymtabs when -@var{xyz}_symfile_read is called, these psymtabs will contain a pointer -to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called -from any point in the @value{GDBN} symbol-handling code. - -@table @code -@item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst) - -Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if -the psymtab has not already been read in and had its @code{pst->symtab} -pointer set. The argument is the psymtab to be fleshed-out into a -symtab. Upon return, @code{pst->readin} should have been set to 1, and -@code{pst->symtab} should contain a pointer to the new corresponding symtab, or -zero if there were no symbols in that part of the symbol file. -@end table - -@section Partial Symbol Tables - -@value{GDBN} has three types of symbol tables: - -@itemize @bullet -@cindex full symbol table -@cindex symtabs -@item -Full symbol tables (@dfn{symtabs}). These contain the main -information about symbols and addresses. - -@cindex psymtabs -@item -Partial symbol tables (@dfn{psymtabs}). These contain enough -information to know when to read the corresponding part of the full -symbol table. - -@cindex minimal symbol table -@cindex minsymtabs -@item -Minimal symbol tables (@dfn{msymtabs}). These contain information -gleaned from non-debugging symbols. -@end itemize - -@cindex partial symbol table -This section describes partial symbol tables. - -A psymtab is constructed by doing a very quick pass over an executable -file's debugging information. Small amounts of information are -extracted---enough to identify which parts of the symbol table will -need to be re-read and fully digested later, when the user needs the -information. The speed of this pass causes @value{GDBN} to start up very -quickly. Later, as the detailed rereading occurs, it occurs in small -pieces, at various times, and the delay therefrom is mostly invisible to -the user. -@c (@xref{Symbol Reading}.) - -The symbols that show up in a file's psymtab should be, roughly, those -visible to the debugger's user when the program is not running code from -that file. These include external symbols and types, static symbols and -types, and @code{enum} values declared at file scope. - -The psymtab also contains the range of instruction addresses that the -full symbol table would represent. - -@cindex finding a symbol -@cindex symbol lookup -The idea is that there are only two ways for the user (or much of the -code in the debugger) to reference a symbol: - -@itemize @bullet -@findex find_pc_function -@findex find_pc_line -@item -By its address (e.g. execution stops at some address which is inside a -function in this file). The address will be noticed to be in the -range of this psymtab, and the full symtab will be read in. -@code{find_pc_function}, @code{find_pc_line}, and other -@code{find_pc_@dots{}} functions handle this. - -@cindex lookup_symbol -@item -By its name -(e.g. the user asks to print a variable, or set a breakpoint on a -function). Global names and file-scope names will be found in the -psymtab, which will cause the symtab to be pulled in. Local names will -have to be qualified by a global name, or a file-scope name, in which -case we will have already read in the symtab as we evaluated the -qualifier. Or, a local symbol can be referenced when we are ``in'' a -local scope, in which case the first case applies. @code{lookup_symbol} -does most of the work here. -@end itemize - -The only reason that psymtabs exist is to cause a symtab to be read in -at the right moment. Any symbol that can be elided from a psymtab, -while still causing that to happen, should not appear in it. Since -psymtabs don't have the idea of scope, you can't put local symbols in -them anyway. Psymtabs don't have the idea of the type of a symbol, -either, so types need not appear, unless they will be referenced by -name. - -It is a bug for @value{GDBN} to behave one way when only a psymtab has -been read, and another way if the corresponding symtab has been read -in. Such bugs are typically caused by a psymtab that does not contain -all the visible symbols, or which has the wrong instruction address -ranges. - -The psymtab for a particular section of a symbol file (objfile) could be -thrown away after the symtab has been read in. The symtab should always -be searched before the psymtab, so the psymtab will never be used (in a -bug-free environment). Currently, psymtabs are allocated on an obstack, -and all the psymbols themselves are allocated in a pair of large arrays -on an obstack, so there is little to be gained by trying to free them -unless you want to do a lot more work. - -@section Types - -@unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}). - -@cindex fundamental types -These are the fundamental types that @value{GDBN} uses internally. Fundamental -types from the various debugging formats (stabs, ELF, etc) are mapped -into one of these. They are basically a union of all fundamental types -that @value{GDBN} knows about for all the languages that @value{GDBN} -knows about. - -@unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}). - -@cindex type codes -Each time @value{GDBN} builds an internal type, it marks it with one -of these types. The type may be a fundamental type, such as -@code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR} -which is a pointer to another type. Typically, several @code{FT_*} -types map to one @code{TYPE_CODE_*} type, and are distinguished by -other members of the type struct, such as whether the type is signed -or unsigned, and how many bits it uses. - -@unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}). - -These are instances of type structs that roughly correspond to -fundamental types and are created as global types for @value{GDBN} to -use for various ugly historical reasons. We eventually want to -eliminate these. Note for example that @code{builtin_type_int} -initialized in @file{gdbtypes.c} is basically the same as a -@code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for -an @code{FT_INTEGER} fundamental type. The difference is that the -@code{builtin_type} is not associated with any particular objfile, and -only one instance exists, while @file{c-lang.c} builds as many -@code{TYPE_CODE_INT} types as needed, with each one associated with -some particular objfile. - -@section Object File Formats -@cindex object file formats - -@subsection a.out - -@cindex @code{a.out} format -The @code{a.out} format is the original file format for Unix. It -consists of three sections: @code{text}, @code{data}, and @code{bss}, -which are for program code, initialized data, and uninitialized data, -respectively. - -The @code{a.out} format is so simple that it doesn't have any reserved -place for debugging information. (Hey, the original Unix hackers used -@samp{adb}, which is a machine-language debugger!) The only debugging -format for @code{a.out} is stabs, which is encoded as a set of normal -symbols with distinctive attributes. - -The basic @code{a.out} reader is in @file{dbxread.c}. - -@subsection COFF - -@cindex COFF format -The COFF format was introduced with System V Release 3 (SVR3) Unix. -COFF files may have multiple sections, each prefixed by a header. The -number of sections is limited. - -The COFF specification includes support for debugging. Although this -was a step forward, the debugging information was woefully limited. For -instance, it was not possible to represent code that came from an -included file. - -The COFF reader is in @file{coffread.c}. - -@subsection ECOFF - -@cindex ECOFF format -ECOFF is an extended COFF originally introduced for Mips and Alpha -workstations. - -The basic ECOFF reader is in @file{mipsread.c}. - -@subsection XCOFF - -@cindex XCOFF format -The IBM RS/6000 running AIX uses an object file format called XCOFF. -The COFF sections, symbols, and line numbers are used, but debugging -symbols are @code{dbx}-style stabs whose strings are located in the -@code{.debug} section (rather than the string table). For more -information, see @ref{Top,,,stabs,The Stabs Debugging Format}. - -The shared library scheme has a clean interface for figuring out what -shared libraries are in use, but the catch is that everything which -refers to addresses (symbol tables and breakpoints at least) needs to be -relocated for both shared libraries and the main executable. At least -using the standard mechanism this can only be done once the program has -been run (or the core file has been read). - -@subsection PE - -@cindex PE-COFF format -Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their -executables. PE is basically COFF with additional headers. - -While BFD includes special PE support, @value{GDBN} needs only the basic -COFF reader. - -@subsection ELF - -@cindex ELF format -The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar -to COFF in being organized into a number of sections, but it removes -many of COFF's limitations. - -The basic ELF reader is in @file{elfread.c}. - -@subsection SOM - -@cindex SOM format -SOM is HP's object file and debug format (not to be confused with IBM's -SOM, which is a cross-language ABI). - -The SOM reader is in @file{hpread.c}. - -@subsection Other File Formats - -@cindex Netware Loadable Module format -Other file formats that have been supported by @value{GDBN} include Netware -Loadable Modules (@file{nlmread.c}). - -@section Debugging File Formats - -This section describes characteristics of debugging information that -are independent of the object file format. - -@subsection stabs - -@cindex stabs debugging info -@code{stabs} started out as special symbols within the @code{a.out} -format. Since then, it has been encapsulated into other file -formats, such as COFF and ELF. - -While @file{dbxread.c} does some of the basic stab processing, -including for encapsulated versions, @file{stabsread.c} does -the real work. - -@subsection COFF - -@cindex COFF debugging info -The basic COFF definition includes debugging information. The level -of support is minimal and non-extensible, and is not often used. - -@subsection Mips debug (Third Eye) - -@cindex ECOFF debugging info -ECOFF includes a definition of a special debug format. - -The file @file{mdebugread.c} implements reading for this format. - -@subsection DWARF 1 - -@cindex DWARF 1 debugging info -DWARF 1 is a debugging format that was originally designed to be -used with ELF in SVR4 systems. - -@c GCC_PRODUCER -@c GPLUS_PRODUCER -@c LCC_PRODUCER -@c If defined, these are the producer strings in a DWARF 1 file. All of -@c these have reasonable defaults already. - -The DWARF 1 reader is in @file{dwarfread.c}. - -@subsection DWARF 2 - -@cindex DWARF 2 debugging info -DWARF 2 is an improved but incompatible version of DWARF 1. - -The DWARF 2 reader is in @file{dwarf2read.c}. - -@subsection SOM - -@cindex SOM debugging info -Like COFF, the SOM definition includes debugging information. - -@section Adding a New Symbol Reader to @value{GDBN} - -@cindex adding debugging info reader -If you are using an existing object file format (@code{a.out}, COFF, ELF, etc), -there is probably little to be done. - -If you need to add a new object file format, you must first add it to -BFD. This is beyond the scope of this document. - -You must then arrange for the BFD code to provide access to the -debugging symbols. Generally @value{GDBN} will have to call swapping routines -from BFD and a few other BFD internal routines to locate the debugging -information. As much as possible, @value{GDBN} should not depend on the BFD -internal data structures. - -For some targets (e.g., COFF), there is a special transfer vector used -to call swapping routines, since the external data structures on various -platforms have different sizes and layouts. Specialized routines that -will only ever be implemented by one object file format may be called -directly. This interface should be described in a file -@file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}. - - -@node Language Support - -@chapter Language Support - -@cindex language support -@value{GDBN}'s language support is mainly driven by the symbol reader, -although it is possible for the user to set the source language -manually. - -@value{GDBN} chooses the source language by looking at the extension -of the file recorded in the debug info; @file{.c} means C, @file{.f} -means Fortran, etc. It may also use a special-purpose language -identifier if the debug format supports it, like with DWARF. - -@section Adding a Source Language to @value{GDBN} - -@cindex adding source language -To add other languages to @value{GDBN}'s expression parser, follow the -following steps: - -@table @emph -@item Create the expression parser. - -@cindex expression parser -This should reside in a file @file{@var{lang}-exp.y}. Routines for -building parsed expressions into a @code{union exp_element} list are in -@file{parse.c}. - -@cindex language parser -Since we can't depend upon everyone having Bison, and YACC produces -parsers that define a bunch of global names, the following lines -@strong{must} be included at the top of the YACC parser, to prevent the -various parsers from defining the same global names: - -@smallexample -#define yyparse @var{lang}_parse -#define yylex @var{lang}_lex -#define yyerror @var{lang}_error -#define yylval @var{lang}_lval -#define yychar @var{lang}_char -#define yydebug @var{lang}_debug -#define yypact @var{lang}_pact -#define yyr1 @var{lang}_r1 -#define yyr2 @var{lang}_r2 -#define yydef @var{lang}_def -#define yychk @var{lang}_chk -#define yypgo @var{lang}_pgo -#define yyact @var{lang}_act -#define yyexca @var{lang}_exca -#define yyerrflag @var{lang}_errflag -#define yynerrs @var{lang}_nerrs -@end smallexample - -At the bottom of your parser, define a @code{struct language_defn} and -initialize it with the right values for your language. Define an -@code{initialize_@var{lang}} routine and have it call -@samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN} -that your language exists. You'll need some other supporting variables -and functions, which will be used via pointers from your -@code{@var{lang}_language_defn}. See the declaration of @code{struct -language_defn} in @file{language.h}, and the other @file{*-exp.y} files, -for more information. - -@item Add any evaluation routines, if necessary - -@cindex expression evaluation routines -@findex evaluate_subexp -@findex prefixify_subexp -@findex length_of_subexp -If you need new opcodes (that represent the operations of the language), -add them to the enumerated type in @file{expression.h}. Add support -code for these operations in the @code{evaluate_subexp} function -defined in the file @file{eval.c}. Add cases -for new opcodes in two functions from @file{parse.c}: -@code{prefixify_subexp} and @code{length_of_subexp}. These compute -the number of @code{exp_element}s that a given operation takes up. - -@item Update some existing code - -Add an enumerated identifier for your language to the enumerated type -@code{enum language} in @file{defs.h}. - -Update the routines in @file{language.c} so your language is included. -These routines include type predicates and such, which (in some cases) -are language dependent. If your language does not appear in the switch -statement, an error is reported. - -@vindex current_language -Also included in @file{language.c} is the code that updates the variable -@code{current_language}, and the routines that translate the -@code{language_@var{lang}} enumerated identifier into a printable -string. - -@findex _initialize_language -Update the function @code{_initialize_language} to include your -language. This function picks the default language upon startup, so is -dependent upon which languages that @value{GDBN} is built for. - -@findex allocate_symtab -Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading -code so that the language of each symtab (source file) is set properly. -This is used to determine the language to use at each stack frame level. -Currently, the language is set based upon the extension of the source -file. If the language can be better inferred from the symbol -information, please set the language of the symtab in the symbol-reading -code. - -@findex print_subexp -@findex op_print_tab -Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new -expression opcodes you have added to @file{expression.h}. Also, add the -printed representations of your operators to @code{op_print_tab}. - -@item Add a place of call - -@findex parse_exp_1 -Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in -@code{parse_exp_1} (defined in @file{parse.c}). - -@item Use macros to trim code - -@cindex trimming language-dependent code -The user has the option of building @value{GDBN} for some or all of the -languages. If the user decides to build @value{GDBN} for the language -@var{lang}, then every file dependent on @file{language.h} will have the -macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to -leave out large routines that the user won't need if he or she is not -using your language. - -Note that you do not need to do this in your YACC parser, since if @value{GDBN} -is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the -compiled form of your parser) is not linked into @value{GDBN} at all. - -See the file @file{configure.in} for how @value{GDBN} is configured -for different languages. - -@item Edit @file{Makefile.in} - -Add dependencies in @file{Makefile.in}. Make sure you update the macro -variables such as @code{HFILES} and @code{OBJS}, otherwise your code may -not get linked in, or, worse yet, it may not get @code{tar}red into the -distribution! -@end table - - -@node Host Definition - -@chapter Host Definition - -With the advent of Autoconf, it's rarely necessary to have host -definition machinery anymore. The following information is provided, -mainly, as an historical reference. - -@section Adding a New Host - -@cindex adding a new host -@cindex host, adding -@value{GDBN}'s host configuration support normally happens via Autoconf. -New host-specific definitions should not be needed. Older hosts -@value{GDBN} still use the host-specific definitions and files listed -below, but these mostly exist for historical reasons, and will -eventually disappear. - -@table @file -@item gdb/config/@var{arch}/@var{xyz}.mh -This file once contained both host and native configuration information -(@pxref{Native Debugging}) for the machine @var{xyz}. The host -configuration information is now handed by Autoconf. - -Host configuration information included a definition of -@code{XM_FILE=xm-@var{xyz}.h} and possibly definitions for @code{CC}, -@code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES}, -@code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}. - -New host only configurations do not need this file. - -@item gdb/config/@var{arch}/xm-@var{xyz}.h -This file once contained definitions and includes required when hosting -gdb on machine @var{xyz}. Those definitions and includes are now -handled by Autoconf. - -New host and native configurations do not need this file. - -@emph{Maintainer's note: Some hosts continue to use the @file{xm-xyz.h} -file to define the macros @var{HOST_FLOAT_FORMAT}, -@var{HOST_DOUBLE_FORMAT} and @var{HOST_LONG_DOUBLE_FORMAT}. That code -also needs to be replaced with either an Autoconf or run-time test.} - -@end table - -@subheading Generic Host Support Files - -@cindex generic host support -There are some ``generic'' versions of routines that can be used by -various systems. These can be customized in various ways by macros -defined in your @file{xm-@var{xyz}.h} file. If these routines work for -the @var{xyz} host, you can just include the generic file's name (with -@samp{.o}, not @samp{.c}) in @code{XDEPFILES}. - -Otherwise, if your machine needs custom support routines, you will need -to write routines that perform the same functions as the generic file. -Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o} -into @code{XDEPFILES}. - -@table @file -@cindex remote debugging support -@cindex serial line support -@item ser-unix.c -This contains serial line support for Unix systems. This is always -included, via the makefile variable @code{SER_HARDWIRE}; override this -variable in the @file{.mh} file to avoid it. - -@item ser-go32.c -This contains serial line support for 32-bit programs running under DOS, -using the DJGPP (a.k.a.@: GO32) execution environment. - -@cindex TCP remote support -@item ser-tcp.c -This contains generic TCP support using sockets. -@end table - -@section Host Conditionals - -When @value{GDBN} is configured and compiled, various macros are -defined or left undefined, to control compilation based on the -attributes of the host system. These macros and their meanings (or if -the meaning is not documented here, then one of the source files where -they are used is indicated) are: - -@ftable @code -@item @value{GDBN}INIT_FILENAME -The default name of @value{GDBN}'s initialization file (normally -@file{.gdbinit}). - -@item NO_STD_REGS -This macro is deprecated. - -@item NO_SYS_FILE -Define this if your system does not have a @code{<sys/file.h>}. - -@item SIGWINCH_HANDLER -If your host defines @code{SIGWINCH}, you can define this to be the name -of a function to be called if @code{SIGWINCH} is received. - -@item SIGWINCH_HANDLER_BODY -Define this to expand into code that will define the function named by -the expansion of @code{SIGWINCH_HANDLER}. - -@item ALIGN_STACK_ON_STARTUP -@cindex stack alignment -Define this if your system is of a sort that will crash in -@code{tgetent} if the stack happens not to be longword-aligned when -@code{main} is called. This is a rare situation, but is known to occur -on several different types of systems. - -@item CRLF_SOURCE_FILES -@cindex DOS text files -Define this if host files use @code{\r\n} rather than @code{\n} as a -line terminator. This will cause source file listings to omit @code{\r} -characters when printing and it will allow @code{\r\n} line endings of files -which are ``sourced'' by gdb. It must be possible to open files in binary -mode using @code{O_BINARY} or, for fopen, @code{"rb"}. - -@item DEFAULT_PROMPT -@cindex prompt -The default value of the prompt string (normally @code{"(gdb) "}). - -@item DEV_TTY -@cindex terminal device -The name of the generic TTY device, defaults to @code{"/dev/tty"}. - -@item FCLOSE_PROVIDED -Define this if the system declares @code{fclose} in the headers included -in @code{defs.h}. This isn't needed unless your compiler is unusually -anal. - -@item FOPEN_RB -Define this if binary files are opened the same way as text files. - -@item GETENV_PROVIDED -Define this if the system declares @code{getenv} in its headers included -in @code{defs.h}. This isn't needed unless your compiler is unusually -anal. - -@item HAVE_MMAP -@findex mmap -In some cases, use the system call @code{mmap} for reading symbol -tables. For some machines this allows for sharing and quick updates. - -@item HAVE_TERMIO -Define this if the host system has @code{termio.h}. - -@item INT_MAX -@itemx INT_MIN -@itemx LONG_MAX -@itemx UINT_MAX -@itemx ULONG_MAX -Values for host-side constants. - -@item ISATTY -Substitute for isatty, if not available. - -@item LONGEST -This is the longest integer type available on the host. If not defined, -it will default to @code{long long} or @code{long}, depending on -@code{CC_HAS_LONG_LONG}. - -@item CC_HAS_LONG_LONG -@cindex @code{long long} data type -Define this if the host C compiler supports @code{long long}. This is set -by the @code{configure} script. - -@item PRINTF_HAS_LONG_LONG -Define this if the host can handle printing of long long integers via -the printf format conversion specifier @code{ll}. This is set by the -@code{configure} script. - -@item HAVE_LONG_DOUBLE -Define this if the host C compiler supports @code{long double}. This is -set by the @code{configure} script. - -@item PRINTF_HAS_LONG_DOUBLE -Define this if the host can handle printing of long double float-point -numbers via the printf format conversion specifier @code{Lg}. This is -set by the @code{configure} script. - -@item SCANF_HAS_LONG_DOUBLE -Define this if the host can handle the parsing of long double -float-point numbers via the scanf format conversion specifier -@code{Lg}. This is set by the @code{configure} script. - -@item LSEEK_NOT_LINEAR -Define this if @code{lseek (n)} does not necessarily move to byte number -@code{n} in the file. This is only used when reading source files. It -is normally faster to define @code{CRLF_SOURCE_FILES} when possible. - -@item L_SET -This macro is used as the argument to @code{lseek} (or, most commonly, -@code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead, -which is the POSIX equivalent. - -@item NORETURN -If defined, this should be one or more tokens, such as @code{volatile}, -that can be used in both the declaration and definition of functions to -indicate that they never return. The default is already set correctly -if compiling with GCC. This will almost never need to be defined. - -@item ATTR_NORETURN -If defined, this should be one or more tokens, such as -@code{__attribute__ ((noreturn))}, that can be used in the declarations -of functions to indicate that they never return. The default is already -set correctly if compiling with GCC. This will almost never need to be -defined. - -@item NO_SIGINTERRUPT -@findex siginterrupt -Define this to indicate that @code{siginterrupt} is not available. - -@item SEEK_CUR -@itemx SEEK_SET -Define these to appropriate value for the system @code{lseek}, if not already -defined. - -@item STOP_SIGNAL -This is the signal for stopping @value{GDBN}. Defaults to -@code{SIGTSTP}. (Only redefined for the Convex.) - -@item USE_O_NOCTTY -Define this if the interior's tty should be opened with the @code{O_NOCTTY} -flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is -always linked in.) - -@item USG -Means that System V (prior to SVR4) include files are in use. (FIXME: -This symbol is abused in @file{infrun.c}, @file{regex.c}, and -@file{utils.c} for other things, at the moment.) - -@item lint -Define this to help placate @code{lint} in some situations. - -@item volatile -Define this to override the defaults of @code{__volatile__} or -@code{/**/}. -@end ftable - - -@node Target Architecture Definition - -@chapter Target Architecture Definition - -@cindex target architecture definition -@value{GDBN}'s target architecture defines what sort of -machine-language programs @value{GDBN} can work with, and how it works -with them. - -The target architecture object is implemented as the C structure -@code{struct gdbarch *}. The structure, and its methods, are generated -using the Bourne shell script @file{gdbarch.sh}. - -@section Operating System ABI Variant Handling -@cindex OS ABI variants - -@value{GDBN} provides a mechanism for handling variations in OS -ABIs. An OS ABI variant may have influence over any number of -variables in the target architecture definition. There are two major -components in the OS ABI mechanism: sniffers and handlers. - -A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair -(the architecture may be wildcarded) in an attempt to determine the -OS ABI of that file. Sniffers with a wildcarded architecture are considered -to be @dfn{generic}, while sniffers for a specific architecture are -considered to be @dfn{specific}. A match from a specific sniffer -overrides a match from a generic sniffer. Multiple sniffers for an -architecture/flavour may exist, in order to differentiate between two -different operating systems which use the same basic file format. The -OS ABI framework provides a generic sniffer for ELF-format files which -examines the @code{EI_OSABI} field of the ELF header, as well as note -sections known to be used by several operating systems. - -@cindex fine-tuning @code{gdbarch} structure -A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the -selected OS ABI. There may be only one handler for a given OS ABI -for each BFD architecture. - -The following OS ABI variants are defined in @file{osabi.h}: - -@table @code - -@findex GDB_OSABI_UNKNOWN -@item GDB_OSABI_UNKNOWN -The ABI of the inferior is unknown. The default @code{gdbarch} -settings for the architecture will be used. - -@findex GDB_OSABI_SVR4 -@item GDB_OSABI_SVR4 -UNIX System V Release 4 - -@findex GDB_OSABI_HURD -@item GDB_OSABI_HURD -GNU using the Hurd kernel - -@findex GDB_OSABI_SOLARIS -@item GDB_OSABI_SOLARIS -Sun Solaris - -@findex GDB_OSABI_OSF1 -@item GDB_OSABI_OSF1 -OSF/1, including Digital UNIX and Compaq Tru64 UNIX - -@findex GDB_OSABI_LINUX -@item GDB_OSABI_LINUX -GNU using the Linux kernel - -@findex GDB_OSABI_FREEBSD_AOUT -@item GDB_OSABI_FREEBSD_AOUT -FreeBSD using the a.out executable format - -@findex GDB_OSABI_FREEBSD_ELF -@item GDB_OSABI_FREEBSD_ELF -FreeBSD using the ELF executable format - -@findex GDB_OSABI_NETBSD_AOUT -@item GDB_OSABI_NETBSD_AOUT -NetBSD using the a.out executable format - -@findex GDB_OSABI_NETBSD_ELF -@item GDB_OSABI_NETBSD_ELF -NetBSD using the ELF executable format - -@findex GDB_OSABI_WINCE -@item GDB_OSABI_WINCE -Windows CE - -@findex GDB_OSABI_GO32 -@item GDB_OSABI_GO32 -DJGPP - -@findex GDB_OSABI_NETWARE -@item GDB_OSABI_NETWARE -Novell NetWare - -@findex GDB_OSABI_ARM_EABI_V1 -@item GDB_OSABI_ARM_EABI_V1 -ARM Embedded ABI version 1 - -@findex GDB_OSABI_ARM_EABI_V2 -@item GDB_OSABI_ARM_EABI_V2 -ARM Embedded ABI version 2 - -@findex GDB_OSABI_ARM_APCS -@item GDB_OSABI_ARM_APCS -Generic ARM Procedure Call Standard - -@end table - -Here are the functions that make up the OS ABI framework: - -@deftypefun const char *gdbarch_osabi_name (enum gdb_osabi @var{osabi}) -Return the name of the OS ABI corresponding to @var{osabi}. -@end deftypefun - -@deftypefun void gdbarch_register_osabi (enum bfd_architecture @var{arch}, unsigned long @var{machine}, enum gdb_osabi @var{osabi}, void (*@var{init_osabi})(struct gdbarch_info @var{info}, struct gdbarch *@var{gdbarch})) -Register the OS ABI handler specified by @var{init_osabi} for the -architecture, machine type and OS ABI specified by @var{arch}, -@var{machine} and @var{osabi}. In most cases, a value of zero for the -machine type, which implies the architecture's default machine type, -will suffice. -@end deftypefun - -@deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd})) -Register the OS ABI file sniffer specified by @var{sniffer} for the -BFD architecture/flavour pair specified by @var{arch} and @var{flavour}. -If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to -be generic, and is allowed to examine @var{flavour}-flavoured files for -any architecture. -@end deftypefun - -@deftypefun enum gdb_osabi gdbarch_lookup_osabi (bfd *@var{abfd}) -Examine the file described by @var{abfd} to determine its OS ABI. -The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot -be determined. -@end deftypefun - -@deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi}) -Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the -@code{gdbarch} structure specified by @var{gdbarch}. If a handler -corresponding to @var{osabi} has not been registered for @var{gdbarch}'s -architecture, a warning will be issued and the debugging session will continue -with the defaults already established for @var{gdbarch}. -@end deftypefun - -@section Registers and Memory - -@value{GDBN}'s model of the target machine is rather simple. -@value{GDBN} assumes the machine includes a bank of registers and a -block of memory. Each register may have a different size. - -@value{GDBN} does not have a magical way to match up with the -compiler's idea of which registers are which; however, it is critical -that they do match up accurately. The only way to make this work is -to get accurate information about the order that the compiler uses, -and to reflect that in the @code{REGISTER_NAME} and related macros. - -@value{GDBN} can handle big-endian, little-endian, and bi-endian architectures. - -@section Pointers Are Not Always Addresses -@cindex pointer representation -@cindex address representation -@cindex word-addressed machines -@cindex separate data and code address spaces -@cindex spaces, separate data and code address -@cindex address spaces, separate data and code -@cindex code pointers, word-addressed -@cindex converting between pointers and addresses -@cindex D10V addresses - -On almost all 32-bit architectures, the representation of a pointer is -indistinguishable from the representation of some fixed-length number -whose value is the byte address of the object pointed to. On such -machines, the words ``pointer'' and ``address'' can be used interchangeably. -However, architectures with smaller word sizes are often cramped for -address space, so they may choose a pointer representation that breaks this -identity, and allows a larger code address space. - -For example, the Renesas D10V is a 16-bit VLIW processor whose -instructions are 32 bits long@footnote{Some D10V instructions are -actually pairs of 16-bit sub-instructions. However, since you can't -jump into the middle of such a pair, code addresses can only refer to -full 32 bit instructions, which is what matters in this explanation.}. -If the D10V used ordinary byte addresses to refer to code locations, -then the processor would only be able to address 64kb of instructions. -However, since instructions must be aligned on four-byte boundaries, the -low two bits of any valid instruction's byte address are always -zero---byte addresses waste two bits. So instead of byte addresses, -the D10V uses word addresses---byte addresses shifted right two bits---to -refer to code. Thus, the D10V can use 16-bit words to address 256kb of -code space. - -However, this means that code pointers and data pointers have different -forms on the D10V. The 16-bit word @code{0xC020} refers to byte address -@code{0xC020} when used as a data address, but refers to byte address -@code{0x30080} when used as a code address. - -(The D10V also uses separate code and data address spaces, which also -affects the correspondence between pointers and addresses, but we're -going to ignore that here; this example is already too long.) - -To cope with architectures like this---the D10V is not the only -one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are -byte numbers, and @dfn{pointers}, which are the target's representation -of an address of a particular type of data. In the example above, -@code{0xC020} is the pointer, which refers to one of the addresses -@code{0xC020} or @code{0x30080}, depending on the type imposed upon it. -@value{GDBN} provides functions for turning a pointer into an address -and vice versa, in the appropriate way for the current architecture. - -Unfortunately, since addresses and pointers are identical on almost all -processors, this distinction tends to bit-rot pretty quickly. Thus, -each time you port @value{GDBN} to an architecture which does -distinguish between pointers and addresses, you'll probably need to -clean up some architecture-independent code. - -Here are functions which convert between pointers and addresses: - -@deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type}) -Treat the bytes at @var{buf} as a pointer or reference of type -@var{type}, and return the address it represents, in a manner -appropriate for the current architecture. This yields an address -@value{GDBN} can use to read target memory, disassemble, etc. Note that -@var{buf} refers to a buffer in @value{GDBN}'s memory, not the -inferior's. - -For example, if the current architecture is the Intel x86, this function -extracts a little-endian integer of the appropriate length from -@var{buf} and returns it. However, if the current architecture is the -D10V, this function will return a 16-bit integer extracted from -@var{buf}, multiplied by four if @var{type} is a pointer to a function. - -If @var{type} is not a pointer or reference type, then this function -will signal an internal error. -@end deftypefun - -@deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr}) -Store the address @var{addr} in @var{buf}, in the proper format for a -pointer of type @var{type} in the current architecture. Note that -@var{buf} refers to a buffer in @value{GDBN}'s memory, not the -inferior's. - -For example, if the current architecture is the Intel x86, this function -stores @var{addr} unmodified as a little-endian integer of the -appropriate length in @var{buf}. However, if the current architecture -is the D10V, this function divides @var{addr} by four if @var{type} is -a pointer to a function, and then stores it in @var{buf}. - -If @var{type} is not a pointer or reference type, then this function -will signal an internal error. -@end deftypefun - -@deftypefun CORE_ADDR value_as_address (struct value *@var{val}) -Assuming that @var{val} is a pointer, return the address it represents, -as appropriate for the current architecture. - -This function actually works on integral values, as well as pointers. -For pointers, it performs architecture-specific conversions as -described above for @code{extract_typed_address}. -@end deftypefun - -@deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr}) -Create and return a value representing a pointer of type @var{type} to -the address @var{addr}, as appropriate for the current architecture. -This function performs architecture-specific conversions as described -above for @code{store_typed_address}. -@end deftypefun - -Here are some macros which architectures can define to indicate the -relationship between pointers and addresses. These have default -definitions, appropriate for architectures on which all pointers are -simple unsigned byte addresses. - -@deftypefn {Target Macro} CORE_ADDR POINTER_TO_ADDRESS (struct type *@var{type}, char *@var{buf}) -Assume that @var{buf} holds a pointer of type @var{type}, in the -appropriate format for the current architecture. Return the byte -address the pointer refers to. - -This function may safely assume that @var{type} is either a pointer or a -C@t{++} reference type. -@end deftypefn - -@deftypefn {Target Macro} void ADDRESS_TO_POINTER (struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr}) -Store in @var{buf} a pointer of type @var{type} representing the address -@var{addr}, in the appropriate format for the current architecture. - -This function may safely assume that @var{type} is either a pointer or a -C@t{++} reference type. -@end deftypefn - -@section Address Classes -@cindex address classes -@cindex DW_AT_byte_size -@cindex DW_AT_address_class - -Sometimes information about different kinds of addresses is available -via the debug information. For example, some programming environments -define addresses of several different sizes. If the debug information -distinguishes these kinds of address classes through either the size -info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit -address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the -following macros should be defined in order to disambiguate these -types within @value{GDBN} as well as provide the added information to -a @value{GDBN} user when printing type expressions. - -@deftypefn {Target Macro} int ADDRESS_CLASS_TYPE_FLAGS (int @var{byte_size}, int @var{dwarf2_addr_class}) -Returns the type flags needed to construct a pointer type whose size -is @var{byte_size} and whose address class is @var{dwarf2_addr_class}. -This function is normally called from within a symbol reader. See -@file{dwarf2read.c}. -@end deftypefn - -@deftypefn {Target Macro} char *ADDRESS_CLASS_TYPE_FLAGS_TO_NAME (int @var{type_flags}) -Given the type flags representing an address class qualifier, return -its name. -@end deftypefn -@deftypefn {Target Macro} int ADDRESS_CLASS_NAME_to_TYPE_FLAGS (int @var{name}, int *var{type_flags_ptr}) -Given an address qualifier name, set the @code{int} refererenced by @var{type_flags_ptr} to the type flags -for that address class qualifier. -@end deftypefn - -Since the need for address classes is rather rare, none of -the address class macros defined by default. Predicate -macros are provided to detect when they are defined. - -Consider a hypothetical architecture in which addresses are normally -32-bits wide, but 16-bit addresses are also supported. Furthermore, -suppose that the @w{DWARF 2} information for this architecture simply -uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one -of these "short" pointers. The following functions could be defined -to implement the address class macros: - -@smallexample -somearch_address_class_type_flags (int byte_size, - int dwarf2_addr_class) -@{ - if (byte_size == 2) - return TYPE_FLAG_ADDRESS_CLASS_1; - else - return 0; -@} - -static char * -somearch_address_class_type_flags_to_name (int type_flags) -@{ - if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1) - return "short"; - else - return NULL; -@} - -int -somearch_address_class_name_to_type_flags (char *name, - int *type_flags_ptr) -@{ - if (strcmp (name, "short") == 0) - @{ - *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1; - return 1; - @} - else - return 0; -@} -@end smallexample - -The qualifier @code{@@short} is used in @value{GDBN}'s type expressions -to indicate the presence of one of these "short" pointers. E.g, if -the debug information indicates that @code{short_ptr_var} is one of these -short pointers, @value{GDBN} might show the following behavior: - -@smallexample -(gdb) ptype short_ptr_var -type = int * @@short -@end smallexample - - -@section Raw and Virtual Register Representations -@cindex raw register representation -@cindex virtual register representation -@cindex representations, raw and virtual registers - -@emph{Maintainer note: This section is pretty much obsolete. The -functionality described here has largely been replaced by -pseudo-registers and the mechanisms described in @ref{Target -Architecture Definition, , Using Different Register and Memory Data -Representations}. See also @uref{http://www.gnu.org/software/gdb/bugs/, -Bug Tracking Database} and -@uref{http://sources.redhat.com/gdb/current/ari/, ARI Index} for more -up-to-date information.} - -Some architectures use one representation for a value when it lives in a -register, but use a different representation when it lives in memory. -In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in -the target registers, and the @dfn{virtual} representation is the one -used in memory, and within @value{GDBN} @code{struct value} objects. - -@emph{Maintainer note: Notice that the same mechanism is being used to -both convert a register to a @code{struct value} and alternative -register forms.} - -For almost all data types on almost all architectures, the virtual and -raw representations are identical, and no special handling is needed. -However, they do occasionally differ. For example: - -@itemize @bullet -@item -The x86 architecture supports an 80-bit @code{long double} type. However, when -we store those values in memory, they occupy twelve bytes: the -floating-point number occupies the first ten, and the final two bytes -are unused. This keeps the values aligned on four-byte boundaries, -allowing more efficient access. Thus, the x86 80-bit floating-point -type is the raw representation, and the twelve-byte loosely-packed -arrangement is the virtual representation. - -@item -Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit -registers, with garbage in their upper bits. @value{GDBN} ignores the top 32 -bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the -raw representation, and the trimmed 32-bit representation is the -virtual representation. -@end itemize - -In general, the raw representation is determined by the architecture, or -@value{GDBN}'s interface to the architecture, while the virtual representation -can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file, -@code{registers}, holds the register contents in raw format, and the -@value{GDBN} remote protocol transmits register values in raw format. - -Your architecture may define the following macros to request -conversions between the raw and virtual format: - -@deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg}) -Return non-zero if register number @var{reg}'s value needs different raw -and virtual formats. - -You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register -unless this macro returns a non-zero value for that register. -@end deftypefn - -@deftypefn {Target Macro} int DEPRECATED_REGISTER_RAW_SIZE (int @var{reg}) -The size of register number @var{reg}'s raw value. This is the number -of bytes the register will occupy in @code{registers}, or in a @value{GDBN} -remote protocol packet. -@end deftypefn - -@deftypefn {Target Macro} int DEPRECATED_REGISTER_VIRTUAL_SIZE (int @var{reg}) -The size of register number @var{reg}'s value, in its virtual format. -This is the size a @code{struct value}'s buffer will have, holding that -register's value. -@end deftypefn - -@deftypefn {Target Macro} struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int @var{reg}) -This is the type of the virtual representation of register number -@var{reg}. Note that there is no need for a macro giving a type for the -register's raw form; once the register's value has been obtained, @value{GDBN} -always uses the virtual form. -@end deftypefn - -@deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to}) -Convert the value of register number @var{reg} to @var{type}, which -should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer -at @var{from} holds the register's value in raw format; the macro should -convert the value to virtual format, and place it at @var{to}. - -Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and -@code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type} -arguments in different orders. - -You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers -for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero -value. -@end deftypefn - -@deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to}) -Convert the value of register number @var{reg} to @var{type}, which -should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer -at @var{from} holds the register's value in raw format; the macro should -convert the value to virtual format, and place it at @var{to}. - -Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take -their @var{reg} and @var{type} arguments in different orders. -@end deftypefn - - -@section Using Different Register and Memory Data Representations -@cindex register representation -@cindex memory representation -@cindex representations, register and memory -@cindex register data formats, converting -@cindex @code{struct value}, converting register contents to - -@emph{Maintainer's note: The way GDB manipulates registers is undergoing -significant change. Many of the macros and functions refered to in this -section are likely to be subject to further revision. See -@uref{http://sources.redhat.com/gdb/current/ari/, A.R. Index} and -@uref{http://www.gnu.org/software/gdb/bugs, Bug Tracking Database} for -further information. cagney/2002-05-06.} - -Some architectures can represent a data object in a register using a -form that is different to the objects more normal memory representation. -For example: - -@itemize @bullet - -@item -The Alpha architecture can represent 32 bit integer values in -floating-point registers. - -@item -The x86 architecture supports 80-bit floating-point registers. The -@code{long double} data type occupies 96 bits in memory but only 80 bits -when stored in a register. - -@end itemize - -In general, the register representation of a data type is determined by -the architecture, or @value{GDBN}'s interface to the architecture, while -the memory representation is determined by the Application Binary -Interface. - -For almost all data types on almost all architectures, the two -representations are identical, and no special handling is needed. -However, they do occasionally differ. Your architecture may define the -following macros to request conversions between the register and memory -representations of a data type: - -@deftypefn {Target Macro} int CONVERT_REGISTER_P (int @var{reg}) -Return non-zero if the representation of a data value stored in this -register may be different to the representation of that same data value -when stored in memory. - -When non-zero, the macros @code{REGISTER_TO_VALUE} and -@code{VALUE_TO_REGISTER} are used to perform any necessary conversion. -@end deftypefn - -@deftypefn {Target Macro} void REGISTER_TO_VALUE (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to}) -Convert the value of register number @var{reg} to a data object of type -@var{type}. The buffer at @var{from} holds the register's value in raw -format; the converted value should be placed in the buffer at @var{to}. - -Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take -their @var{reg} and @var{type} arguments in different orders. - -You should only use @code{REGISTER_TO_VALUE} with registers for which -the @code{CONVERT_REGISTER_P} macro returns a non-zero value. -@end deftypefn - -@deftypefn {Target Macro} void VALUE_TO_REGISTER (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to}) -Convert a data value of type @var{type} to register number @var{reg}' -raw format. - -Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take -their @var{reg} and @var{type} arguments in different orders. - -You should only use @code{VALUE_TO_REGISTER} with registers for which -the @code{CONVERT_REGISTER_P} macro returns a non-zero value. -@end deftypefn - -@deftypefn {Target Macro} void REGISTER_CONVERT_TO_TYPE (int @var{regnum}, struct type *@var{type}, char *@var{buf}) -See @file{mips-tdep.c}. It does not do what you want. -@end deftypefn - - -@section Frame Interpretation - -@section Inferior Call Setup - -@section Compiler Characteristics - -@section Target Conditionals - -This section describes the macros that you can use to define the target -machine. - -@table @code - -@item ADDR_BITS_REMOVE (addr) -@findex ADDR_BITS_REMOVE -If a raw machine instruction address includes any bits that are not -really part of the address, then define this macro to expand into an -expression that zeroes those bits in @var{addr}. This is only used for -addresses of instructions, and even then not in all contexts. - -For example, the two low-order bits of the PC on the Hewlett-Packard PA -2.0 architecture contain the privilege level of the corresponding -instruction. Since instructions must always be aligned on four-byte -boundaries, the processor masks out these bits to generate the actual -address of the instruction. ADDR_BITS_REMOVE should filter out these -bits with an expression such as @code{((addr) & ~3)}. - -@item ADDRESS_CLASS_NAME_TO_TYPE_FLAGS (@var{name}, @var{type_flags_ptr}) -@findex ADDRESS_CLASS_NAME_TO_TYPE_FLAGS -If @var{name} is a valid address class qualifier name, set the @code{int} -referenced by @var{type_flags_ptr} to the mask representing the qualifier -and return 1. If @var{name} is not a valid address class qualifier name, -return 0. - -The value for @var{type_flags_ptr} should be one of -@code{TYPE_FLAG_ADDRESS_CLASS_1}, @code{TYPE_FLAG_ADDRESS_CLASS_2}, or -possibly some combination of these values or'd together. -@xref{Target Architecture Definition, , Address Classes}. - -@item ADDRESS_CLASS_NAME_TO_TYPE_FLAGS_P () -@findex ADDRESS_CLASS_NAME_TO_TYPE_FLAGS_P -Predicate which indicates whether @code{ADDRESS_CLASS_NAME_TO_TYPE_FLAGS} -has been defined. - -@item ADDRESS_CLASS_TYPE_FLAGS (@var{byte_size}, @var{dwarf2_addr_class}) -@findex ADDRESS_CLASS_TYPE_FLAGS (@var{byte_size}, @var{dwarf2_addr_class}) -Given a pointers byte size (as described by the debug information) and -the possible @code{DW_AT_address_class} value, return the type flags -used by @value{GDBN} to represent this address class. The value -returned should be one of @code{TYPE_FLAG_ADDRESS_CLASS_1}, -@code{TYPE_FLAG_ADDRESS_CLASS_2}, or possibly some combination of these -values or'd together. -@xref{Target Architecture Definition, , Address Classes}. - -@item ADDRESS_CLASS_TYPE_FLAGS_P () -@findex ADDRESS_CLASS_TYPE_FLAGS_P -Predicate which indicates whether @code{ADDRESS_CLASS_TYPE_FLAGS} has -been defined. - -@item ADDRESS_CLASS_TYPE_FLAGS_TO_NAME (@var{type_flags}) -@findex ADDRESS_CLASS_TYPE_FLAGS_TO_NAME -Return the name of the address class qualifier associated with the type -flags given by @var{type_flags}. - -@item ADDRESS_CLASS_TYPE_FLAGS_TO_NAME_P () -@findex ADDRESS_CLASS_TYPE_FLAGS_TO_NAME_P -Predicate which indicates whether @code{ADDRESS_CLASS_TYPE_FLAGS_TO_NAME} has -been defined. -@xref{Target Architecture Definition, , Address Classes}. - -@item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr}) -@findex ADDRESS_TO_POINTER -Store in @var{buf} a pointer of type @var{type} representing the address -@var{addr}, in the appropriate format for the current architecture. -This macro may safely assume that @var{type} is either a pointer or a -C@t{++} reference type. -@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. - -@item BELIEVE_PCC_PROMOTION -@findex BELIEVE_PCC_PROMOTION -Define if the compiler promotes a @code{short} or @code{char} -parameter to an @code{int}, but still reports the parameter as its -original type, rather than the promoted type. - -@item BELIEVE_PCC_PROMOTION_TYPE -@findex BELIEVE_PCC_PROMOTION_TYPE -Define this if @value{GDBN} should believe the type of a @code{short} -argument when compiled by @code{pcc}, but look within a full int space to get -its value. Only defined for Sun-3 at present. - -@item BITS_BIG_ENDIAN -@findex BITS_BIG_ENDIAN -Define this if the numbering of bits in the targets does @strong{not} match the -endianness of the target byte order. A value of 1 means that the bits -are numbered in a big-endian bit order, 0 means little-endian. - -@item BREAKPOINT -@findex BREAKPOINT -This is the character array initializer for the bit pattern to put into -memory where a breakpoint is set. Although it's common to use a trap -instruction for a breakpoint, it's not required; for instance, the bit -pattern could be an invalid instruction. The breakpoint must be no -longer than the shortest instruction of the architecture. - -@code{BREAKPOINT} has been deprecated in favor of -@code{BREAKPOINT_FROM_PC}. - -@item BIG_BREAKPOINT -@itemx LITTLE_BREAKPOINT -@findex LITTLE_BREAKPOINT -@findex BIG_BREAKPOINT -Similar to BREAKPOINT, but used for bi-endian targets. - -@code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in -favor of @code{BREAKPOINT_FROM_PC}. - -@item DEPRECATED_REMOTE_BREAKPOINT -@itemx DEPRECATED_LITTLE_REMOTE_BREAKPOINT -@itemx DEPRECATED_BIG_REMOTE_BREAKPOINT -@findex DEPRECATED_BIG_REMOTE_BREAKPOINT -@findex DEPRECATED_LITTLE_REMOTE_BREAKPOINT -@findex DEPRECATED_REMOTE_BREAKPOINT -Specify the breakpoint instruction sequence for a remote target. -@code{DEPRECATED_REMOTE_BREAKPOINT}, -@code{DEPRECATED_BIG_REMOTE_BREAKPOINT} and -@code{DEPRECATED_LITTLE_REMOTE_BREAKPOINT} have been deprecated in -favor of @code{BREAKPOINT_FROM_PC} (@pxref{BREAKPOINT_FROM_PC}). - -@item BREAKPOINT_FROM_PC (@var{pcptr}, @var{lenptr}) -@findex BREAKPOINT_FROM_PC -@anchor{BREAKPOINT_FROM_PC} Use the program counter to determine the -contents and size of a breakpoint instruction. It returns a pointer to -a string of bytes that encode a breakpoint instruction, stores the -length of the string to @code{*@var{lenptr}}, and adjusts the program -counter (if necessary) to point to the actual memory location where the -breakpoint should be inserted. - -Although it is common to use a trap instruction for a breakpoint, it's -not required; for instance, the bit pattern could be an invalid -instruction. The breakpoint must be no longer than the shortest -instruction of the architecture. - -Replaces all the other @var{BREAKPOINT} macros. - -@item MEMORY_INSERT_BREAKPOINT (@var{addr}, @var{contents_cache}) -@itemx MEMORY_REMOVE_BREAKPOINT (@var{addr}, @var{contents_cache}) -@findex MEMORY_REMOVE_BREAKPOINT -@findex MEMORY_INSERT_BREAKPOINT -Insert or remove memory based breakpoints. Reasonable defaults -(@code{default_memory_insert_breakpoint} and -@code{default_memory_remove_breakpoint} respectively) have been -provided so that it is not necessary to define these for most -architectures. Architectures which may want to define -@code{MEMORY_INSERT_BREAKPOINT} and @code{MEMORY_REMOVE_BREAKPOINT} will -likely have instructions that are oddly sized or are not stored in a -conventional manner. - -It may also be desirable (from an efficiency standpoint) to define -custom breakpoint insertion and removal routines if -@code{BREAKPOINT_FROM_PC} needs to read the target's memory for some -reason. - -@item ADJUST_BREAKPOINT_ADDRESS (@var{address}) -@findex ADJUST_BREAKPOINT_ADDRESS -@cindex breakpoint address adjusted -Given an address at which a breakpoint is desired, return a breakpoint -address adjusted to account for architectural constraints on -breakpoint placement. This method is not needed by most targets. - -The FR-V target (see @file{frv-tdep.c}) requires this method. -The FR-V is a VLIW architecture in which a number of RISC-like -instructions are grouped (packed) together into an aggregate -instruction or instruction bundle. When the processor executes -one of these bundles, the component instructions are executed -in parallel. - -In the course of optimization, the compiler may group instructions -from distinct source statements into the same bundle. The line number -information associated with one of the latter statements will likely -refer to some instruction other than the first one in the bundle. So, -if the user attempts to place a breakpoint on one of these latter -statements, @value{GDBN} must be careful to @emph{not} place the break -instruction on any instruction other than the first one in the bundle. -(Remember though that the instructions within a bundle execute -in parallel, so the @emph{first} instruction is the instruction -at the lowest address and has nothing to do with execution order.) - -The FR-V's @code{ADJUST_BREAKPOINT_ADDRESS} method will adjust a -breakpoint's address by scanning backwards for the beginning of -the bundle, returning the address of the bundle. - -Since the adjustment of a breakpoint may significantly alter a user's -expectation, @value{GDBN} prints a warning when an adjusted breakpoint -is initially set and each time that that breakpoint is hit. - -@item DEPRECATED_CALL_DUMMY_WORDS -@findex DEPRECATED_CALL_DUMMY_WORDS -Pointer to an array of @code{LONGEST} words of data containing -host-byte-ordered @code{DEPRECATED_REGISTER_SIZE} sized values that -partially specify the sequence of instructions needed for an inferior -function call. - -Should be deprecated in favor of a macro that uses target-byte-ordered -data. - -This method has been replaced by @code{push_dummy_code} -(@pxref{push_dummy_code}). - -@item DEPRECATED_SIZEOF_CALL_DUMMY_WORDS -@findex DEPRECATED_SIZEOF_CALL_DUMMY_WORDS -The size of @code{DEPRECATED_CALL_DUMMY_WORDS}. This must return a -positive value. See also @code{DEPRECATED_CALL_DUMMY_LENGTH}. - -This method has been replaced by @code{push_dummy_code} -(@pxref{push_dummy_code}). - -@item CALL_DUMMY -@findex CALL_DUMMY -A static initializer for @code{DEPRECATED_CALL_DUMMY_WORDS}. -Deprecated. - -This method has been replaced by @code{push_dummy_code} -(@pxref{push_dummy_code}). - -@item CALL_DUMMY_LOCATION -@findex CALL_DUMMY_LOCATION -See the file @file{inferior.h}. - -This method has been replaced by @code{push_dummy_code} -(@pxref{push_dummy_code}). - -@item CANNOT_FETCH_REGISTER (@var{regno}) -@findex CANNOT_FETCH_REGISTER -A C expression that should be nonzero if @var{regno} cannot be fetched -from an inferior process. This is only relevant if -@code{FETCH_INFERIOR_REGISTERS} is not defined. - -@item CANNOT_STORE_REGISTER (@var{regno}) -@findex CANNOT_STORE_REGISTER -A C expression that should be nonzero if @var{regno} should not be -written to the target. This is often the case for program counters, -status words, and other special registers. If this is not defined, -@value{GDBN} will assume that all registers may be written. - -@item DO_DEFERRED_STORES -@itemx CLEAR_DEFERRED_STORES -@findex CLEAR_DEFERRED_STORES -@findex DO_DEFERRED_STORES -Define this to execute any deferred stores of registers into the inferior, -and to cancel any deferred stores. - -Currently only implemented correctly for native Sparc configurations? - -@item int CONVERT_REGISTER_P(@var{regnum}) -@findex CONVERT_REGISTER_P -Return non-zero if register @var{regnum} can represent data values in a -non-standard form. -@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. - -@item DECR_PC_AFTER_BREAK -@findex DECR_PC_AFTER_BREAK -Define this to be the amount by which to decrement the PC after the -program encounters a breakpoint. This is often the number of bytes in -@code{BREAKPOINT}, though not always. For most targets this value will be 0. - -@item DISABLE_UNSETTABLE_BREAK (@var{addr}) -@findex DISABLE_UNSETTABLE_BREAK -If defined, this should evaluate to 1 if @var{addr} is in a shared -library in which breakpoints cannot be set and so should be disabled. - -@item PRINT_FLOAT_INFO() -@findex PRINT_FLOAT_INFO -If defined, then the @samp{info float} command will print information about -the processor's floating point unit. - -@item print_registers_info (@var{gdbarch}, @var{frame}, @var{regnum}, @var{all}) -@findex print_registers_info -If defined, pretty print the value of the register @var{regnum} for the -specified @var{frame}. If the value of @var{regnum} is -1, pretty print -either all registers (@var{all} is non zero) or a select subset of -registers (@var{all} is zero). - -The default method prints one register per line, and if @var{all} is -zero omits floating-point registers. - -@item PRINT_VECTOR_INFO() -@findex PRINT_VECTOR_INFO -If defined, then the @samp{info vector} command will call this function -to print information about the processor's vector unit. - -By default, the @samp{info vector} command will print all vector -registers (the register's type having the vector attribute). - -@item DWARF_REG_TO_REGNUM -@findex DWARF_REG_TO_REGNUM -Convert DWARF register number into @value{GDBN} regnum. If not defined, -no conversion will be performed. - -@item DWARF2_REG_TO_REGNUM -@findex DWARF2_REG_TO_REGNUM -Convert DWARF2 register number into @value{GDBN} regnum. If not -defined, no conversion will be performed. - -@item ECOFF_REG_TO_REGNUM -@findex ECOFF_REG_TO_REGNUM -Convert ECOFF register number into @value{GDBN} regnum. If not defined, -no conversion will be performed. - -@item END_OF_TEXT_DEFAULT -@findex END_OF_TEXT_DEFAULT -This is an expression that should designate the end of the text section. -@c (? FIXME ?) - -@item EXTRACT_RETURN_VALUE(@var{type}, @var{regbuf}, @var{valbuf}) -@findex EXTRACT_RETURN_VALUE -Define this to extract a function's return value of type @var{type} from -the raw register state @var{regbuf} and copy that, in virtual format, -into @var{valbuf}. - -This method has been deprecated in favour of @code{gdbarch_return_value} -(@pxref{gdbarch_return_value}). - -@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf}) -@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS -@anchor{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS} -When defined, extract from the array @var{regbuf} (containing the raw -register state) the @code{CORE_ADDR} at which a function should return -its structure value. - -@xref{gdbarch_return_value}. - -@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P() -@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P -Predicate for @code{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}. - -@item DEPRECATED_FP_REGNUM -@findex DEPRECATED_FP_REGNUM -If the virtual frame pointer is kept in a register, then define this -macro to be the number (greater than or equal to zero) of that register. - -This should only need to be defined if @code{DEPRECATED_TARGET_READ_FP} -is not defined. - -@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi}) -@findex DEPRECATED_FRAMELESS_FUNCTION_INVOCATION -Define this to an expression that returns 1 if the function invocation -represented by @var{fi} does not have a stack frame associated with it. -Otherwise return 0. - -@item frame_align (@var{address}) -@anchor{frame_align} -@findex frame_align -Define this to adjust @var{address} so that it meets the alignment -requirements for the start of a new stack frame. A stack frame's -alignment requirements are typically stronger than a target processors -stack alignment requirements (@pxref{DEPRECATED_STACK_ALIGN}). - -This function is used to ensure that, when creating a dummy frame, both -the initial stack pointer and (if needed) the address of the return -value are correctly aligned. - -Unlike @code{DEPRECATED_STACK_ALIGN}, this function always adjusts the -address in the direction of stack growth. - -By default, no frame based stack alignment is performed. - -@item int frame_red_zone_size - -The number of bytes, beyond the innermost-stack-address, reserved by the -@sc{abi}. A function is permitted to use this scratch area (instead of -allocating extra stack space). - -When performing an inferior function call, to ensure that it does not -modify this area, @value{GDBN} adjusts the innermost-stack-address by -@var{frame_red_zone_size} bytes before pushing parameters onto the -stack. - -By default, zero bytes are allocated. The value must be aligned -(@pxref{frame_align}). - -The @sc{amd64} (nee x86-64) @sc{abi} documentation refers to the -@emph{red zone} when describing this scratch area. -@cindex red zone - -@item DEPRECATED_FRAME_CHAIN(@var{frame}) -@findex DEPRECATED_FRAME_CHAIN -Given @var{frame}, return a pointer to the calling frame. - -@item DEPRECATED_FRAME_CHAIN_VALID(@var{chain}, @var{thisframe}) -@findex DEPRECATED_FRAME_CHAIN_VALID -Define this to be an expression that returns zero if the given frame is an -outermost frame, with no caller, and nonzero otherwise. Most normal -situations can be handled without defining this macro, including @code{NULL} -chain pointers, dummy frames, and frames whose PC values are inside the -startup file (e.g.@: @file{crt0.o}), inside @code{main}, or inside -@code{_start}. - -@item DEPRECATED_FRAME_INIT_SAVED_REGS(@var{frame}) -@findex DEPRECATED_FRAME_INIT_SAVED_REGS -See @file{frame.h}. Determines the address of all registers in the -current stack frame storing each in @code{frame->saved_regs}. Space for -@code{frame->saved_regs} shall be allocated by -@code{DEPRECATED_FRAME_INIT_SAVED_REGS} using -@code{frame_saved_regs_zalloc}. - -@code{FRAME_FIND_SAVED_REGS} is deprecated. - -@item FRAME_NUM_ARGS (@var{fi}) -@findex FRAME_NUM_ARGS -For the frame described by @var{fi} return the number of arguments that -are being passed. If the number of arguments is not known, return -@code{-1}. - -@item DEPRECATED_FRAME_SAVED_PC(@var{frame}) -@findex DEPRECATED_FRAME_SAVED_PC -@anchor{DEPRECATED_FRAME_SAVED_PC} Given @var{frame}, return the pc -saved there. This is the return address. - -This method is deprecated. @xref{unwind_pc}. - -@item CORE_ADDR unwind_pc (struct frame_info *@var{this_frame}) -@findex unwind_pc -@anchor{unwind_pc} Return the instruction address, in @var{this_frame}'s -caller, at which execution will resume after @var{this_frame} returns. -This is commonly refered to as the return address. - -The implementation, which must be frame agnostic (work with any frame), -is typically no more than: - -@smallexample -ULONGEST pc; -frame_unwind_unsigned_register (this_frame, D10V_PC_REGNUM, &pc); -return d10v_make_iaddr (pc); -@end smallexample - -@noindent -@xref{DEPRECATED_FRAME_SAVED_PC}, which this method replaces. - -@item CORE_ADDR unwind_sp (struct frame_info *@var{this_frame}) -@findex unwind_sp -@anchor{unwind_sp} Return the frame's inner most stack address. This is -commonly refered to as the frame's @dfn{stack pointer}. - -The implementation, which must be frame agnostic (work with any frame), -is typically no more than: - -@smallexample -ULONGEST sp; -frame_unwind_unsigned_register (this_frame, D10V_SP_REGNUM, &sp); -return d10v_make_daddr (sp); -@end smallexample - -@noindent -@xref{TARGET_READ_SP}, which this method replaces. - -@item FUNCTION_EPILOGUE_SIZE -@findex FUNCTION_EPILOGUE_SIZE -For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the -function end symbol is 0. For such targets, you must define -@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a -function's epilogue. - -@item FUNCTION_START_OFFSET -@findex FUNCTION_START_OFFSET -An integer, giving the offset in bytes from a function's address (as -used in the values of symbols, function pointers, etc.), and the -function's first genuine instruction. - -This is zero on almost all machines: the function's address is usually -the address of its first instruction. However, on the VAX, for example, -each function starts with two bytes containing a bitmask indicating -which registers to save upon entry to the function. The VAX @code{call} -instructions check this value, and save the appropriate registers -automatically. Thus, since the offset from the function's address to -its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would -be 2 on the VAX. - -@item GCC_COMPILED_FLAG_SYMBOL -@itemx GCC2_COMPILED_FLAG_SYMBOL -@findex GCC2_COMPILED_FLAG_SYMBOL -@findex GCC_COMPILED_FLAG_SYMBOL -If defined, these are the names of the symbols that @value{GDBN} will -look for to detect that GCC compiled the file. The default symbols -are @code{gcc_compiled.} and @code{gcc2_compiled.}, -respectively. (Currently only defined for the Delta 68.) - -@item @value{GDBN}_MULTI_ARCH -@findex @value{GDBN}_MULTI_ARCH -If defined and non-zero, enables support for multiple architectures -within @value{GDBN}. - -This support can be enabled at two levels. At level one, only -definitions for previously undefined macros are provided; at level two, -a multi-arch definition of all architecture dependent macros will be -defined. - -@item @value{GDBN}_TARGET_IS_HPPA -@findex @value{GDBN}_TARGET_IS_HPPA -This determines whether horrible kludge code in @file{dbxread.c} and -@file{partial-stab.h} is used to mangle multiple-symbol-table files from -HPPA's. This should all be ripped out, and a scheme like @file{elfread.c} -used instead. - -@item GET_LONGJMP_TARGET -@findex GET_LONGJMP_TARGET -For most machines, this is a target-dependent parameter. On the -DECstation and the Iris, this is a native-dependent parameter, since -the header file @file{setjmp.h} is needed to define it. - -This macro determines the target PC address that @code{longjmp} will jump to, -assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a -@code{CORE_ADDR *} as argument, and stores the target PC value through this -pointer. It examines the current state of the machine as needed. - -@item DEPRECATED_GET_SAVED_REGISTER -@findex DEPRECATED_GET_SAVED_REGISTER -Define this if you need to supply your own definition for the function -@code{DEPRECATED_GET_SAVED_REGISTER}. - -@item DEPRECATED_IBM6000_TARGET -@findex DEPRECATED_IBM6000_TARGET -Shows that we are configured for an IBM RS/6000 system. This -conditional should be eliminated (FIXME) and replaced by -feature-specific macros. It was introduced in a haste and we are -repenting at leisure. - -@item I386_USE_GENERIC_WATCHPOINTS -An x86-based target can define this to use the generic x86 watchpoint -support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}. - -@item SYMBOLS_CAN_START_WITH_DOLLAR -@findex SYMBOLS_CAN_START_WITH_DOLLAR -Some systems have routines whose names start with @samp{$}. Giving this -macro a non-zero value tells @value{GDBN}'s expression parser to check for such -routines when parsing tokens that begin with @samp{$}. - -On HP-UX, certain system routines (millicode) have names beginning with -@samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode -routine that handles inter-space procedure calls on PA-RISC. - -@item DEPRECATED_INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame}) -@findex DEPRECATED_INIT_EXTRA_FRAME_INFO -If additional information about the frame is required this should be -stored in @code{frame->extra_info}. Space for @code{frame->extra_info} -is allocated using @code{frame_extra_info_zalloc}. - -@item DEPRECATED_INIT_FRAME_PC (@var{fromleaf}, @var{prev}) -@findex DEPRECATED_INIT_FRAME_PC -This is a C statement that sets the pc of the frame pointed to by -@var{prev}. [By default...] - -@item INNER_THAN (@var{lhs}, @var{rhs}) -@findex INNER_THAN -Returns non-zero if stack address @var{lhs} is inner than (nearer to the -stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if -the target's stack grows downward in memory, or @code{lhs > rsh} if the -stack grows upward. - -@item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{pc}) -@findex gdbarch_in_function_epilogue_p -Returns non-zero if the given @var{pc} is in the epilogue of a function. -The epilogue of a function is defined as the part of a function where -the stack frame of the function already has been destroyed up to the -final `return from function call' instruction. - -@item SIGTRAMP_START (@var{pc}) -@findex SIGTRAMP_START -@itemx SIGTRAMP_END (@var{pc}) -@findex SIGTRAMP_END -Define these to be the start and end address of the @code{sigtramp} for the -given @var{pc}. On machines where the address is just a compile time -constant, the macro expansion will typically just ignore the supplied -@var{pc}. - -@item IN_SOLIB_CALL_TRAMPOLINE (@var{pc}, @var{name}) -@findex IN_SOLIB_CALL_TRAMPOLINE -Define this to evaluate to nonzero if the program is stopped in the -trampoline that connects to a shared library. - -@item IN_SOLIB_RETURN_TRAMPOLINE (@var{pc}, @var{name}) -@findex IN_SOLIB_RETURN_TRAMPOLINE -Define this to evaluate to nonzero if the program is stopped in the -trampoline that returns from a shared library. - -@item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc}) -@findex IN_SOLIB_DYNSYM_RESOLVE_CODE -Define this to evaluate to nonzero if the program is stopped in the -dynamic linker. - -@item SKIP_SOLIB_RESOLVER (@var{pc}) -@findex SKIP_SOLIB_RESOLVER -Define this to evaluate to the (nonzero) address at which execution -should continue to get past the dynamic linker's symbol resolution -function. A zero value indicates that it is not important or necessary -to set a breakpoint to get through the dynamic linker and that single -stepping will suffice. - -@item INTEGER_TO_ADDRESS (@var{type}, @var{buf}) -@findex INTEGER_TO_ADDRESS -@cindex converting integers to addresses -Define this when the architecture needs to handle non-pointer to address -conversions specially. Converts that value to an address according to -the current architectures conventions. - -@emph{Pragmatics: When the user copies a well defined expression from -their source code and passes it, as a parameter, to @value{GDBN}'s -@code{print} command, they should get the same value as would have been -computed by the target program. Any deviation from this rule can cause -major confusion and annoyance, and needs to be justified carefully. In -other words, @value{GDBN} doesn't really have the freedom to do these -conversions in clever and useful ways. It has, however, been pointed -out that users aren't complaining about how @value{GDBN} casts integers -to pointers; they are complaining that they can't take an address from a -disassembly listing and give it to @code{x/i}. Adding an architecture -method like @code{INTEGER_TO_ADDRESS} certainly makes it possible for -@value{GDBN} to ``get it right'' in all circumstances.} - -@xref{Target Architecture Definition, , Pointers Are Not Always -Addresses}. - -@item NO_HIF_SUPPORT -@findex NO_HIF_SUPPORT -(Specific to the a29k.) - -@item POINTER_TO_ADDRESS (@var{type}, @var{buf}) -@findex POINTER_TO_ADDRESS -Assume that @var{buf} holds a pointer of type @var{type}, in the -appropriate format for the current architecture. Return the byte -address the pointer refers to. -@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. - -@item REGISTER_CONVERTIBLE (@var{reg}) -@findex REGISTER_CONVERTIBLE -Return non-zero if @var{reg} uses different raw and virtual formats. -@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. - -@item REGISTER_TO_VALUE(@var{regnum}, @var{type}, @var{from}, @var{to}) -@findex REGISTER_TO_VALUE -Convert the raw contents of register @var{regnum} into a value of type -@var{type}. -@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. - -@item DEPRECATED_REGISTER_RAW_SIZE (@var{reg}) -@findex DEPRECATED_REGISTER_RAW_SIZE -Return the raw size of @var{reg}; defaults to the size of the register's -virtual type. -@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. - -@item register_reggroup_p (@var{gdbarch}, @var{regnum}, @var{reggroup}) -@findex register_reggroup_p -@cindex register groups -Return non-zero if register @var{regnum} is a member of the register -group @var{reggroup}. - -By default, registers are grouped as follows: - -@table @code -@item float_reggroup -Any register with a valid name and a floating-point type. -@item vector_reggroup -Any register with a valid name and a vector type. -@item general_reggroup -Any register with a valid name and a type other than vector or -floating-point. @samp{float_reggroup}. -@item save_reggroup -@itemx restore_reggroup -@itemx all_reggroup -Any register with a valid name. -@end table - -@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg}) -@findex DEPRECATED_REGISTER_VIRTUAL_SIZE -Return the virtual size of @var{reg}; defaults to the size of the -register's virtual type. -Return the virtual size of @var{reg}. -@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. - -@item DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg}) -@findex REGISTER_VIRTUAL_TYPE -Return the virtual type of @var{reg}. -@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. - -@item struct type *register_type (@var{gdbarch}, @var{reg}) -@findex register_type -If defined, return the type of register @var{reg}. This function -superseeds @code{DEPRECATED_REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture -Definition, , Raw and Virtual Register Representations}. - -@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to}) -@findex REGISTER_CONVERT_TO_VIRTUAL -Convert the value of register @var{reg} from its raw form to its virtual -form. -@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. - -@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to}) -@findex REGISTER_CONVERT_TO_RAW -Convert the value of register @var{reg} from its virtual form to its raw -form. -@xref{Target Architecture Definition, , Raw and Virtual Register Representations}. - -@item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size}) -@findex regset_from_core_section -Return the appropriate register set for a core file section with name -@var{sect_name} and size @var{sect_size}. - - -@item RETURN_VALUE_ON_STACK(@var{type}) -@findex RETURN_VALUE_ON_STACK -@cindex returning structures by value -@cindex structures, returning by value - -Return non-zero if values of type TYPE are returned on the stack, using -the ``struct convention'' (i.e., the caller provides a pointer to a -buffer in which the callee should store the return value). This -controls how the @samp{finish} command finds a function's return value, -and whether an inferior function call reserves space on the stack for -the return value. - -The full logic @value{GDBN} uses here is kind of odd. - -@itemize @bullet -@item -If the type being returned by value is not a structure, union, or array, -and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN} -concludes the value is not returned using the struct convention. - -@item -Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below). -If that returns non-zero, @value{GDBN} assumes the struct convention is -in use. -@end itemize - -In other words, to indicate that a given type is returned by value using -the struct convention, that type must be either a struct, union, array, -or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something -that @code{USE_STRUCT_CONVENTION} likes. - -Note that, in C and C@t{++}, arrays are never returned by value. In those -languages, these predicates will always see a pointer type, never an -array type. All the references above to arrays being returned by value -apply only to other languages. - -@item SOFTWARE_SINGLE_STEP_P() -@findex SOFTWARE_SINGLE_STEP_P -Define this as 1 if the target does not have a hardware single-step -mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined. - -@item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breapoints_p}) -@findex SOFTWARE_SINGLE_STEP -A function that inserts or removes (depending on -@var{insert_breapoints_p}) breakpoints at each possible destinations of -the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c} -for examples. - -@item SOFUN_ADDRESS_MAYBE_MISSING -@findex SOFUN_ADDRESS_MAYBE_MISSING -Somebody clever observed that, the more actual addresses you have in the -debug information, the more time the linker has to spend relocating -them. So whenever there's some other way the debugger could find the -address it needs, you should omit it from the debug info, to make -linking faster. - -@code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of -hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN} -entries in stabs-format debugging information. @code{N_SO} stabs mark -the beginning and ending addresses of compilation units in the text -segment. @code{N_FUN} stabs mark the starts and ends of functions. - -@code{SOFUN_ADDRESS_MAYBE_MISSING} means two things: - -@itemize @bullet -@item -@code{N_FUN} stabs have an address of zero. Instead, you should find the -addresses where the function starts by taking the function name from -the stab, and then looking that up in the minsyms (the -linker/assembler symbol table). In other words, the stab has the -name, and the linker/assembler symbol table is the only place that carries -the address. - -@item -@code{N_SO} stabs have an address of zero, too. You just look at the -@code{N_FUN} stabs that appear before and after the @code{N_SO} stab, -and guess the starting and ending addresses of the compilation unit from -them. -@end itemize - -@item PCC_SOL_BROKEN -@findex PCC_SOL_BROKEN -(Used only in the Convex target.) - -@item PC_IN_SIGTRAMP (@var{pc}, @var{name}) -@findex PC_IN_SIGTRAMP -@cindex sigtramp -The @dfn{sigtramp} is a routine that the kernel calls (which then calls -the signal handler). On most machines it is a library routine that is -linked into the executable. - -This function, given a program counter value in @var{pc} and the -(possibly NULL) name of the function in which that @var{pc} resides, -returns nonzero if the @var{pc} and/or @var{name} show that we are in -sigtramp. - -@item PC_LOAD_SEGMENT -@findex PC_LOAD_SEGMENT -If defined, print information about the load segment for the program -counter. (Defined only for the RS/6000.) - -@item PC_REGNUM -@findex PC_REGNUM -If the program counter is kept in a register, then define this macro to -be the number (greater than or equal to zero) of that register. - -This should only need to be defined if @code{TARGET_READ_PC} and -@code{TARGET_WRITE_PC} are not defined. - -@item PARM_BOUNDARY -@findex PARM_BOUNDARY -If non-zero, round arguments to a boundary of this many bits before -pushing them on the stack. - -@item stabs_argument_has_addr (@var{gdbarch}, @var{type}) -@findex stabs_argument_has_addr -@findex DEPRECATED_REG_STRUCT_HAS_ADDR -@anchor{stabs_argument_has_addr} Define this to return nonzero if a -function argument of type @var{type} is passed by reference instead of -value. - -This method replaces @code{DEPRECATED_REG_STRUCT_HAS_ADDR} -(@pxref{DEPRECATED_REG_STRUCT_HAS_ADDR}). - -@item PROCESS_LINENUMBER_HOOK -@findex PROCESS_LINENUMBER_HOOK -A hook defined for XCOFF reading. - -@item PROLOGUE_FIRSTLINE_OVERLAP -@findex PROLOGUE_FIRSTLINE_OVERLAP -(Only used in unsupported Convex configuration.) - -@item PS_REGNUM -@findex PS_REGNUM -If defined, this is the number of the processor status register. (This -definition is only used in generic code when parsing "$ps".) - -@item DEPRECATED_POP_FRAME -@findex DEPRECATED_POP_FRAME -@findex frame_pop -If defined, used by @code{frame_pop} to remove a stack frame. This -method has been superseeded by generic code. - -@item push_dummy_call (@var{gdbarch}, @var{func_addr}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr}) -@findex push_dummy_call -@findex DEPRECATED_PUSH_ARGUMENTS. -@anchor{push_dummy_call} Define this to push the dummy frame's call to -the inferior function onto the stack. In addition to pushing -@var{nargs}, the code should push @var{struct_addr} (when -@var{struct_return}), and the return address (@var{bp_addr}). - -Returns the updated top-of-stack pointer. - -This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}. - -@item CORE_ADDR push_dummy_code (@var{gdbarch}, @var{sp}, @var{funaddr}, @var{using_gcc}, @var{args}, @var{nargs}, @var{value_type}, @var{real_pc}, @var{bp_addr}) -@findex push_dummy_code -@findex DEPRECATED_FIX_CALL_DUMMY -@anchor{push_dummy_code} Given a stack based call dummy, push the -instruction sequence (including space for a breakpoint) to which the -called function should return. - -Set @var{bp_addr} to the address at which the breakpoint instruction -should be inserted, @var{real_pc} to the resume address when starting -the call sequence, and return the updated inner-most stack address. - -By default, the stack is grown sufficient to hold a frame-aligned -(@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address -reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}. - -This method replaces @code{DEPRECATED_CALL_DUMMY_WORDS}, -@code{DEPRECATED_SIZEOF_CALL_DUMMY_WORDS}, @code{CALL_DUMMY}, -@code{CALL_DUMMY_LOCATION}, @code{DEPRECATED_REGISTER_SIZE}, -@code{GDB_TARGET_IS_HPPA}, -@code{DEPRECATED_CALL_DUMMY_BREAKPOINT_OFFSET}, and -@code{DEPRECATED_FIX_CALL_DUMMY}. - -@item DEPRECATED_PUSH_DUMMY_FRAME -@findex DEPRECATED_PUSH_DUMMY_FRAME -Used in @samp{call_function_by_hand} to create an artificial stack frame. - -@item DEPRECATED_REGISTER_BYTES -@findex DEPRECATED_REGISTER_BYTES -The total amount of space needed to store @value{GDBN}'s copy of the -machine's register state. - -This is no longer needed. @value{GDBN} instead computes the size of the -register buffer at run-time. - -@item REGISTER_NAME(@var{i}) -@findex REGISTER_NAME -Return the name of register @var{i} as a string. May return @code{NULL} -or @code{NUL} to indicate that register @var{i} is not valid. - -@item DEPRECATED_REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type}) -@findex DEPRECATED_REG_STRUCT_HAS_ADDR -@anchor{DEPRECATED_REG_STRUCT_HAS_ADDR}Define this to return 1 if the -given type will be passed by pointer rather than directly. - -This method has been replaced by @code{stabs_argument_has_addr} -(@pxref{stabs_argument_has_addr}). - -@item SAVE_DUMMY_FRAME_TOS (@var{sp}) -@findex SAVE_DUMMY_FRAME_TOS -@anchor{SAVE_DUMMY_FRAME_TOS} Used in @samp{call_function_by_hand} to -notify the target dependent code of the top-of-stack value that will be -passed to the the inferior code. This is the value of the @code{SP} -after both the dummy frame and space for parameters/results have been -allocated on the stack. @xref{unwind_dummy_id}. - -@item SDB_REG_TO_REGNUM -@findex SDB_REG_TO_REGNUM -Define this to convert sdb register numbers into @value{GDBN} regnums. If not -defined, no conversion will be done. - -@item enum return_value_convention gdbarch_return_value (struct gdbarch *@var{gdbarch}, struct type *@var{valtype}, struct regcache *@var{regcache}, void *@var{readbuf}, const void *@var{writebuf}) -@findex gdbarch_return_value -@anchor{gdbarch_return_value} Given a function with a return-value of -type @var{rettype}, return which return-value convention that function -would use. - -@value{GDBN} currently recognizes two function return-value conventions: -@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found -in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return -value is found in memory and the address of that memory location is -passed in as the function's first parameter. - -If the register convention is being used, and @var{writebuf} is -non-@code{NULL}, also copy the return-value in @var{writebuf} into -@var{regcache}. - -If the register convention is being used, and @var{readbuf} is -non-@code{NULL}, also copy the return value from @var{regcache} into -@var{readbuf} (@var{regcache} contains a copy of the registers from the -just returned function). - -@xref{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}, for a description of how -return-values that use the struct convention are handled. - -@emph{Maintainer note: This method replaces separate predicate, extract, -store methods. By having only one method, the logic needed to determine -the return-value convention need only be implemented in one place. If -@value{GDBN} were written in an @sc{oo} language, this method would -instead return an object that knew how to perform the register -return-value extract and store.} - -@emph{Maintainer note: This method does not take a @var{gcc_p} -parameter, and such a parameter should not be added. If an architecture -that requires per-compiler or per-function information be identified, -then the replacement of @var{rettype} with @code{struct value} -@var{function} should be persued.} - -@emph{Maintainer note: The @var{regcache} parameter limits this methods -to the inner most frame. While replacing @var{regcache} with a -@code{struct frame_info} @var{frame} parameter would remove that -limitation there has yet to be a demonstrated need for such a change.} - -@item SKIP_PERMANENT_BREAKPOINT -@findex SKIP_PERMANENT_BREAKPOINT -Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally -steps over a breakpoint by removing it, stepping one instruction, and -re-inserting the breakpoint. However, permanent breakpoints are -hardwired into the inferior, and can't be removed, so this strategy -doesn't work. Calling @code{SKIP_PERMANENT_BREAKPOINT} adjusts the processor's -state so that execution will resume just after the breakpoint. This -macro does the right thing even when the breakpoint is in the delay slot -of a branch or jump. - -@item SKIP_PROLOGUE (@var{pc}) -@findex SKIP_PROLOGUE -A C expression that returns the address of the ``real'' code beyond the -function entry prologue found at @var{pc}. - -@item SKIP_TRAMPOLINE_CODE (@var{pc}) -@findex SKIP_TRAMPOLINE_CODE -If the target machine has trampoline code that sits between callers and -the functions being called, then define this macro to return a new PC -that is at the start of the real function. - -@item SP_REGNUM -@findex SP_REGNUM -If the stack-pointer is kept in a register, then define this macro to be -the number (greater than or equal to zero) of that register, or -1 if -there is no such register. - -@item STAB_REG_TO_REGNUM -@findex STAB_REG_TO_REGNUM -Define this to convert stab register numbers (as gotten from `r' -declarations) into @value{GDBN} regnums. If not defined, no conversion will be -done. - -@item DEPRECATED_STACK_ALIGN (@var{addr}) -@anchor{DEPRECATED_STACK_ALIGN} -@findex DEPRECATED_STACK_ALIGN -Define this to increase @var{addr} so that it meets the alignment -requirements for the processor's stack. - -Unlike @ref{frame_align}, this function always adjusts @var{addr} -upwards. - -By default, no stack alignment is performed. - -@item STEP_SKIPS_DELAY (@var{addr}) -@findex STEP_SKIPS_DELAY -Define this to return true if the address is of an instruction with a -delay slot. If a breakpoint has been placed in the instruction's delay -slot, @value{GDBN} will single-step over that instruction before resuming -normally. Currently only defined for the Mips. - -@item STORE_RETURN_VALUE (@var{type}, @var{regcache}, @var{valbuf}) -@findex STORE_RETURN_VALUE -A C expression that writes the function return value, found in -@var{valbuf}, into the @var{regcache}. @var{type} is the type of the -value that is to be returned. - -This method has been deprecated in favour of @code{gdbarch_return_value} -(@pxref{gdbarch_return_value}). - -@item SUN_FIXED_LBRAC_BUG -@findex SUN_FIXED_LBRAC_BUG -(Used only for Sun-3 and Sun-4 targets.) - -@item SYMBOL_RELOADING_DEFAULT -@findex SYMBOL_RELOADING_DEFAULT -The default value of the ``symbol-reloading'' variable. (Never defined in -current sources.) - -@item TARGET_CHAR_BIT -@findex TARGET_CHAR_BIT -Number of bits in a char; defaults to 8. - -@item TARGET_CHAR_SIGNED -@findex TARGET_CHAR_SIGNED -Non-zero if @code{char} is normally signed on this architecture; zero if -it should be unsigned. - -The ISO C standard requires the compiler to treat @code{char} as -equivalent to either @code{signed char} or @code{unsigned char}; any -character in the standard execution set is supposed to be positive. -Most compilers treat @code{char} as signed, but @code{char} is unsigned -on the IBM S/390, RS6000, and PowerPC targets. - -@item TARGET_COMPLEX_BIT -@findex TARGET_COMPLEX_BIT -Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}. - -At present this macro is not used. - -@item TARGET_DOUBLE_BIT -@findex TARGET_DOUBLE_BIT -Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}. - -@item TARGET_DOUBLE_COMPLEX_BIT -@findex TARGET_DOUBLE_COMPLEX_BIT -Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}. - -At present this macro is not used. - -@item TARGET_FLOAT_BIT -@findex TARGET_FLOAT_BIT -Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}. - -@item TARGET_INT_BIT -@findex TARGET_INT_BIT -Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}. - -@item TARGET_LONG_BIT -@findex TARGET_LONG_BIT -Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}. - -@item TARGET_LONG_DOUBLE_BIT -@findex TARGET_LONG_DOUBLE_BIT -Number of bits in a long double float; -defaults to @code{2 * TARGET_DOUBLE_BIT}. - -@item TARGET_LONG_LONG_BIT -@findex TARGET_LONG_LONG_BIT -Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}. - -@item TARGET_PTR_BIT -@findex TARGET_PTR_BIT -Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}. - -@item TARGET_SHORT_BIT -@findex TARGET_SHORT_BIT -Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. - -@item TARGET_READ_PC -@findex TARGET_READ_PC -@itemx TARGET_WRITE_PC (@var{val}, @var{pid}) -@findex TARGET_WRITE_PC -@anchor{TARGET_WRITE_PC} -@itemx TARGET_READ_SP -@findex TARGET_READ_SP -@itemx TARGET_READ_FP -@findex TARGET_READ_FP -@findex read_pc -@findex write_pc -@findex read_sp -@findex read_fp -@anchor{TARGET_READ_SP} These change the behavior of @code{read_pc}, -@code{write_pc}, @code{read_sp} and @code{deprecated_read_fp}. For most -targets, these may be left undefined. @value{GDBN} will call the read -and write register functions with the relevant @code{_REGNUM} argument. - -These macros are useful when a target keeps one of these registers in a -hard to get at place; for example, part in a segment register and part -in an ordinary register. - -@xref{unwind_sp}, which replaces @code{TARGET_READ_SP}. - -@item TARGET_VIRTUAL_FRAME_POINTER(@var{pc}, @var{regp}, @var{offsetp}) -@findex TARGET_VIRTUAL_FRAME_POINTER -Returns a @code{(register, offset)} pair representing the virtual frame -pointer in use at the code address @var{pc}. If virtual frame pointers -are not used, a default definition simply returns -@code{DEPRECATED_FP_REGNUM}, with an offset of zero. - -@item TARGET_HAS_HARDWARE_WATCHPOINTS -If non-zero, the target has support for hardware-assisted -watchpoints. @xref{Algorithms, watchpoints}, for more details and -other related macros. - -@item TARGET_PRINT_INSN (@var{addr}, @var{info}) -@findex TARGET_PRINT_INSN -This is the function used by @value{GDBN} to print an assembly -instruction. It prints the instruction at address @var{addr} in -debugged memory and returns the length of the instruction, in bytes. If -a target doesn't define its own printing routine, it defaults to an -accessor function for the global pointer -@code{deprecated_tm_print_insn}. This usually points to a function in -the @code{opcodes} library (@pxref{Support Libraries, ,Opcodes}). -@var{info} is a structure (of type @code{disassemble_info}) defined in -@file{include/dis-asm.h} used to pass information to the instruction -decoding routine. - -@item struct frame_id unwind_dummy_id (struct frame_info *@var{frame}) -@findex unwind_dummy_id -@anchor{unwind_dummy_id} Given @var{frame} return a @code{struct -frame_id} that uniquely identifies an inferior function call's dummy -frame. The value returned must match the dummy frame stack value -previously saved using @code{SAVE_DUMMY_FRAME_TOS}. -@xref{SAVE_DUMMY_FRAME_TOS}. - -@item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type}) -@findex USE_STRUCT_CONVENTION -If defined, this must be an expression that is nonzero if a value of the -given @var{type} being returned from a function must have space -allocated for it on the stack. @var{gcc_p} is true if the function -being considered is known to have been compiled by GCC; this is helpful -for systems where GCC is known to use different calling convention than -other compilers. - -This method has been deprecated in favour of @code{gdbarch_return_value} -(@pxref{gdbarch_return_value}). - -@item VALUE_TO_REGISTER(@var{type}, @var{regnum}, @var{from}, @var{to}) -@findex VALUE_TO_REGISTER -Convert a value of type @var{type} into the raw contents of register -@var{regnum}'s. -@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. - -@item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p}) -@findex VARIABLES_INSIDE_BLOCK -For dbx-style debugging information, if the compiler puts variable -declarations inside LBRAC/RBRAC blocks, this should be defined to be -nonzero. @var{desc} is the value of @code{n_desc} from the -@code{N_RBRAC} symbol, and @var{gcc_p} is true if @value{GDBN} has noticed the -presence of either the @code{GCC_COMPILED_SYMBOL} or the -@code{GCC2_COMPILED_SYMBOL}. By default, this is 0. - -@item OS9K_VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p}) -@findex OS9K_VARIABLES_INSIDE_BLOCK -Similarly, for OS/9000. Defaults to 1. -@end table - -Motorola M68K target conditionals. - -@ftable @code -@item BPT_VECTOR -Define this to be the 4-bit location of the breakpoint trap vector. If -not defined, it will default to @code{0xf}. - -@item REMOTE_BPT_VECTOR -Defaults to @code{1}. - -@item NAME_OF_MALLOC -@findex NAME_OF_MALLOC -A string containing the name of the function to call in order to -allocate some memory in the inferior. The default value is "malloc". - -@end ftable - -@section Adding a New Target - -@cindex adding a target -The following files add a target to @value{GDBN}: - -@table @file -@vindex TDEPFILES -@item gdb/config/@var{arch}/@var{ttt}.mt -Contains a Makefile fragment specific to this target. Specifies what -object files are needed for target @var{ttt}, by defining -@samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies -the header file which describes @var{ttt}, by defining @samp{TM_FILE= -tm-@var{ttt}.h}. - -You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS}, -but these are now deprecated, replaced by autoconf, and may go away in -future versions of @value{GDBN}. - -@item gdb/@var{ttt}-tdep.c -Contains any miscellaneous code required for this target machine. On -some machines it doesn't exist at all. Sometimes the macros in -@file{tm-@var{ttt}.h} become very complicated, so they are implemented -as functions here instead, and the macro is simply defined to call the -function. This is vastly preferable, since it is easier to understand -and debug. - -@item gdb/@var{arch}-tdep.c -@itemx gdb/@var{arch}-tdep.h -This often exists to describe the basic layout of the target machine's -processor chip (registers, stack, etc.). If used, it is included by -@file{@var{ttt}-tdep.h}. It can be shared among many targets that use -the same processor. - -@item gdb/config/@var{arch}/tm-@var{ttt}.h -(@file{tm.h} is a link to this file, created by @code{configure}). Contains -macro definitions about the target machine's registers, stack frame -format and instructions. - -New targets do not need this file and should not create it. - -@item gdb/config/@var{arch}/tm-@var{arch}.h -This often exists to describe the basic layout of the target machine's -processor chip (registers, stack, etc.). If used, it is included by -@file{tm-@var{ttt}.h}. It can be shared among many targets that use the -same processor. - -New targets do not need this file and should not create it. - -@end table - -If you are adding a new operating system for an existing CPU chip, add a -@file{config/tm-@var{os}.h} file that describes the operating system -facilities that are unusual (extra symbol table info; the breakpoint -instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h} -that just @code{#include}s @file{tm-@var{arch}.h} and -@file{config/tm-@var{os}.h}. - - -@section Converting an existing Target Architecture to Multi-arch -@cindex converting targets to multi-arch - -This section describes the current accepted best practice for converting -an existing target architecture to the multi-arch framework. - -The process consists of generating, testing, posting and committing a -sequence of patches. Each patch must contain a single change, for -instance: - -@itemize @bullet - -@item -Directly convert a group of functions into macros (the conversion does -not change the behavior of any of the functions). - -@item -Replace a non-multi-arch with a multi-arch mechanism (e.g., -@code{FRAME_INFO}). - -@item -Enable multi-arch level one. - -@item -Delete one or more files. - -@end itemize - -@noindent -There isn't a size limit on a patch, however, a developer is strongly -encouraged to keep the patch size down. - -Since each patch is well defined, and since each change has been tested -and shows no regressions, the patches are considered @emph{fairly} -obvious. Such patches, when submitted by developers listed in the -@file{MAINTAINERS} file, do not need approval. Occasional steps in the -process may be more complicated and less clear. The developer is -expected to use their judgment and is encouraged to seek advice as -needed. - -@subsection Preparation - -The first step is to establish control. Build (with @option{-Werror} -enabled) and test the target so that there is a baseline against which -the debugger can be compared. - -At no stage can the test results regress or @value{GDBN} stop compiling -with @option{-Werror}. - -@subsection Add the multi-arch initialization code - -The objective of this step is to establish the basic multi-arch -framework. It involves - -@itemize @bullet - -@item -The addition of a @code{@var{arch}_gdbarch_init} function@footnote{The -above is from the original example and uses K&R C. @value{GDBN} -has since converted to ISO C but lets ignore that.} that creates -the architecture: -@smallexample -static struct gdbarch * -d10v_gdbarch_init (info, arches) - struct gdbarch_info info; - struct gdbarch_list *arches; -@{ - struct gdbarch *gdbarch; - /* there is only one d10v architecture */ - if (arches != NULL) - return arches->gdbarch; - gdbarch = gdbarch_alloc (&info, NULL); - return gdbarch; -@} -@end smallexample -@noindent -@emph{} - -@item -A per-architecture dump function to print any architecture specific -information: -@smallexample -static void -mips_dump_tdep (struct gdbarch *current_gdbarch, - struct ui_file *file) -@{ - @dots{} code to print architecture specific info @dots{} -@} -@end smallexample - -@item -A change to @code{_initialize_@var{arch}_tdep} to register this new -architecture: -@smallexample -void -_initialize_mips_tdep (void) -@{ - gdbarch_register (bfd_arch_mips, mips_gdbarch_init, - mips_dump_tdep); -@end smallexample - -@item -Add the macro @code{GDB_MULTI_ARCH}, defined as 0 (zero), to the file@* -@file{config/@var{arch}/tm-@var{arch}.h}. - -@end itemize - -@subsection Update multi-arch incompatible mechanisms - -Some mechanisms do not work with multi-arch. They include: - -@table @code -@item FRAME_FIND_SAVED_REGS -Replaced with @code{DEPRECATED_FRAME_INIT_SAVED_REGS} -@end table - -@noindent -At this stage you could also consider converting the macros into -functions. - -@subsection Prepare for multi-arch level to one - -Temporally set @code{GDB_MULTI_ARCH} to @code{GDB_MULTI_ARCH_PARTIAL} -and then build and start @value{GDBN} (the change should not be -committed). @value{GDBN} may not build, and once built, it may die with -an internal error listing the architecture methods that must be -provided. - -Fix any build problems (patch(es)). - -Convert all the architecture methods listed, which are only macros, into -functions (patch(es)). - -Update @code{@var{arch}_gdbarch_init} to set all the missing -architecture methods and wrap the corresponding macros in @code{#if -!GDB_MULTI_ARCH} (patch(es)). - -@subsection Set multi-arch level one - -Change the value of @code{GDB_MULTI_ARCH} to GDB_MULTI_ARCH_PARTIAL (a -single patch). - -Any problems with throwing ``the switch'' should have been fixed -already. - -@subsection Convert remaining macros - -Suggest converting macros into functions (and setting the corresponding -architecture method) in small batches. - -@subsection Set multi-arch level to two - -This should go smoothly. - -@subsection Delete the TM file - -The @file{tm-@var{arch}.h} can be deleted. @file{@var{arch}.mt} and -@file{configure.in} updated. - - -@node Target Vector Definition - -@chapter Target Vector Definition -@cindex target vector - -The target vector defines the interface between @value{GDBN}'s -abstract handling of target systems, and the nitty-gritty code that -actually exercises control over a process or a serial port. -@value{GDBN} includes some 30-40 different target vectors; however, -each configuration of @value{GDBN} includes only a few of them. - -@section File Targets - -Both executables and core files have target vectors. - -@section Standard Protocol and Remote Stubs - -@value{GDBN}'s file @file{remote.c} talks a serial protocol to code -that runs in the target system. @value{GDBN} provides several sample -@dfn{stubs} that can be integrated into target programs or operating -systems for this purpose; they are named @file{*-stub.c}. - -The @value{GDBN} user's manual describes how to put such a stub into -your target code. What follows is a discussion of integrating the -SPARC stub into a complicated operating system (rather than a simple -program), by Stu Grossman, the author of this stub. - -The trap handling code in the stub assumes the following upon entry to -@code{trap_low}: - -@enumerate -@item -%l1 and %l2 contain pc and npc respectively at the time of the trap; - -@item -traps are disabled; - -@item -you are in the correct trap window. -@end enumerate - -As long as your trap handler can guarantee those conditions, then there -is no reason why you shouldn't be able to ``share'' traps with the stub. -The stub has no requirement that it be jumped to directly from the -hardware trap vector. That is why it calls @code{exceptionHandler()}, -which is provided by the external environment. For instance, this could -set up the hardware traps to actually execute code which calls the stub -first, and then transfers to its own trap handler. - -For the most point, there probably won't be much of an issue with -``sharing'' traps, as the traps we use are usually not used by the kernel, -and often indicate unrecoverable error conditions. Anyway, this is all -controlled by a table, and is trivial to modify. The most important -trap for us is for @code{ta 1}. Without that, we can't single step or -do breakpoints. Everything else is unnecessary for the proper operation -of the debugger/stub. - -From reading the stub, it's probably not obvious how breakpoints work. -They are simply done by deposit/examine operations from @value{GDBN}. - -@section ROM Monitor Interface - -@section Custom Protocols - -@section Transport Layer - -@section Builtin Simulator - - -@node Native Debugging - -@chapter Native Debugging -@cindex native debugging - -Several files control @value{GDBN}'s configuration for native support: - -@table @file -@vindex NATDEPFILES -@item gdb/config/@var{arch}/@var{xyz}.mh -Specifies Makefile fragments needed by a @emph{native} configuration on -machine @var{xyz}. In particular, this lists the required -native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}. -Also specifies the header file which describes native support on -@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also -define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, -@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}. - -@emph{Maintainer's note: The @file{.mh} suffix is because this file -originally contained @file{Makefile} fragments for hosting @value{GDBN} -on machine @var{xyz}. While the file is no longer used for this -purpose, the @file{.mh} suffix remains. Perhaps someone will -eventually rename these fragments so that they have a @file{.mn} -suffix.} - -@item gdb/config/@var{arch}/nm-@var{xyz}.h -(@file{nm.h} is a link to this file, created by @code{configure}). Contains C -macro definitions describing the native system environment, such as -child process control and core file support. - -@item gdb/@var{xyz}-nat.c -Contains any miscellaneous C code required for this native support of -this machine. On some machines it doesn't exist at all. -@end table - -There are some ``generic'' versions of routines that can be used by -various systems. These can be customized in various ways by macros -defined in your @file{nm-@var{xyz}.h} file. If these routines work for -the @var{xyz} host, you can just include the generic file's name (with -@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}. - -Otherwise, if your machine needs custom support routines, you will need -to write routines that perform the same functions as the generic file. -Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o} -into @code{NATDEPFILES}. - -@table @file -@item inftarg.c -This contains the @emph{target_ops vector} that supports Unix child -processes on systems which use ptrace and wait to control the child. - -@item procfs.c -This contains the @emph{target_ops vector} that supports Unix child -processes on systems which use /proc to control the child. - -@item fork-child.c -This does the low-level grunge that uses Unix system calls to do a ``fork -and exec'' to start up a child process. - -@item infptrace.c -This is the low level interface to inferior processes for systems using -the Unix @code{ptrace} call in a vanilla way. -@end table - -@section Native core file Support -@cindex native core files - -@table @file -@findex fetch_core_registers -@item core-aout.c::fetch_core_registers() -Support for reading registers out of a core file. This routine calls -@code{register_addr()}, see below. Now that BFD is used to read core -files, virtually all machines should use @code{core-aout.c}, and should -just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or -@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}). - -@item core-aout.c::register_addr() -If your @code{nm-@var{xyz}.h} file defines the macro -@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to -set @code{addr} to the offset within the @samp{user} struct of @value{GDBN} -register number @code{regno}. @code{blockend} is the offset within the -``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined, -@file{core-aout.c} will define the @code{register_addr()} function and -use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but -you are using the standard @code{fetch_core_registers()}, you will need -to define your own version of @code{register_addr()}, put it into your -@code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in -the @code{NATDEPFILES} list. If you have your own -@code{fetch_core_registers()}, you may not need a separate -@code{register_addr()}. Many custom @code{fetch_core_registers()} -implementations simply locate the registers themselves.@refill -@end table - -When making @value{GDBN} run native on a new operating system, to make it -possible to debug core files, you will need to either write specific -code for parsing your OS's core files, or customize -@file{bfd/trad-core.c}. First, use whatever @code{#include} files your -machine uses to define the struct of registers that is accessible -(possibly in the u-area) in a core file (rather than -@file{machine/reg.h}), and an include file that defines whatever header -exists on a core file (e.g. the u-area or a @code{struct core}). Then -modify @code{trad_unix_core_file_p} to use these values to set up the -section information for the data segment, stack segment, any other -segments in the core file (perhaps shared library contents or control -information), ``registers'' segment, and if there are two discontiguous -sets of registers (e.g. integer and float), the ``reg2'' segment. This -section information basically delimits areas in the core file in a -standard way, which the section-reading routines in BFD know how to seek -around in. - -Then back in @value{GDBN}, you need a matching routine called -@code{fetch_core_registers}. If you can use the generic one, it's in -@file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file. -It will be passed a char pointer to the entire ``registers'' segment, -its length, and a zero; or a char pointer to the entire ``regs2'' -segment, its length, and a 2. The routine should suck out the supplied -register values and install them into @value{GDBN}'s ``registers'' array. - -If your system uses @file{/proc} to control processes, and uses ELF -format core files, then you may be able to use the same routines for -reading the registers out of processes and out of core files. - -@section ptrace - -@section /proc - -@section win32 - -@section shared libraries - -@section Native Conditionals -@cindex native conditionals - -When @value{GDBN} is configured and compiled, various macros are -defined or left undefined, to control compilation when the host and -target systems are the same. These macros should be defined (or left -undefined) in @file{nm-@var{system}.h}. - -@table @code -@item ATTACH_DETACH -@findex ATTACH_DETACH -If defined, then @value{GDBN} will include support for the @code{attach} and -@code{detach} commands. - -@item CHILD_PREPARE_TO_STORE -@findex CHILD_PREPARE_TO_STORE -If the machine stores all registers at once in the child process, then -define this to ensure that all values are correct. This usually entails -a read from the child. - -[Note that this is incorrectly defined in @file{xm-@var{system}.h} files -currently.] - -@item FETCH_INFERIOR_REGISTERS -@findex FETCH_INFERIOR_REGISTERS -Define this if the native-dependent code will provide its own routines -@code{fetch_inferior_registers} and @code{store_inferior_registers} in -@file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and -@file{infptrace.c} is included in this configuration, the default -routines in @file{infptrace.c} are used for these functions. - -@item FILES_INFO_HOOK -@findex FILES_INFO_HOOK -(Only defined for Convex.) - -@item FP0_REGNUM -@findex FP0_REGNUM -This macro is normally defined to be the number of the first floating -point register, if the machine has such registers. As such, it would -appear only in target-specific code. However, @file{/proc} support uses this -to decide whether floats are in use on this target. - -@item GET_LONGJMP_TARGET -@findex GET_LONGJMP_TARGET -For most machines, this is a target-dependent parameter. On the -DECstation and the Iris, this is a native-dependent parameter, since -@file{setjmp.h} is needed to define it. - -This macro determines the target PC address that @code{longjmp} will jump to, -assuming that we have just stopped at a longjmp breakpoint. It takes a -@code{CORE_ADDR *} as argument, and stores the target PC value through this -pointer. It examines the current state of the machine as needed. - -@item I386_USE_GENERIC_WATCHPOINTS -An x86-based machine can define this to use the generic x86 watchpoint -support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}. - -@item KERNEL_U_ADDR -@findex KERNEL_U_ADDR -Define this to the address of the @code{u} structure (the ``user -struct'', also known as the ``u-page'') in kernel virtual memory. @value{GDBN} -needs to know this so that it can subtract this address from absolute -addresses in the upage, that are obtained via ptrace or from core files. -On systems that don't need this value, set it to zero. - -@item KERNEL_U_ADDR_BSD -@findex KERNEL_U_ADDR_BSD -Define this to cause @value{GDBN} to determine the address of @code{u} at -runtime, by using Berkeley-style @code{nlist} on the kernel's image in -the root directory. - -@item KERNEL_U_ADDR_HPUX -@findex KERNEL_U_ADDR_HPUX -Define this to cause @value{GDBN} to determine the address of @code{u} at -runtime, by using HP-style @code{nlist} on the kernel's image in the -root directory. - -@item ONE_PROCESS_WRITETEXT -@findex ONE_PROCESS_WRITETEXT -Define this to be able to, when a breakpoint insertion fails, warn the -user that another process may be running with the same executable. - -@item PROC_NAME_FMT -@findex PROC_NAME_FMT -Defines the format for the name of a @file{/proc} device. Should be -defined in @file{nm.h} @emph{only} in order to override the default -definition in @file{procfs.c}. - -@item PTRACE_FP_BUG -@findex PTRACE_FP_BUG -See @file{mach386-xdep.c}. - -@item PTRACE_ARG3_TYPE -@findex PTRACE_ARG3_TYPE -The type of the third argument to the @code{ptrace} system call, if it -exists and is different from @code{int}. - -@item REGISTER_U_ADDR -@findex REGISTER_U_ADDR -Defines the offset of the registers in the ``u area''. - -@item SHELL_COMMAND_CONCAT -@findex SHELL_COMMAND_CONCAT -If defined, is a string to prefix on the shell command used to start the -inferior. - -@item SHELL_FILE -@findex SHELL_FILE -If defined, this is the name of the shell to use to run the inferior. -Defaults to @code{"/bin/sh"}. - -@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms}) -@findex SOLIB_ADD -Define this to expand into an expression that will cause the symbols in -@var{filename} to be added to @value{GDBN}'s symbol table. If -@var{readsyms} is zero symbols are not read but any necessary low level -processing for @var{filename} is still done. - -@item SOLIB_CREATE_INFERIOR_HOOK -@findex SOLIB_CREATE_INFERIOR_HOOK -Define this to expand into any shared-library-relocation code that you -want to be run just after the child process has been forked. - -@item START_INFERIOR_TRAPS_EXPECTED -@findex START_INFERIOR_TRAPS_EXPECTED -When starting an inferior, @value{GDBN} normally expects to trap -twice; once when -the shell execs, and once when the program itself execs. If the actual -number of traps is something other than 2, then define this macro to -expand into the number expected. - -@item SVR4_SHARED_LIBS -@findex SVR4_SHARED_LIBS -Define this to indicate that SVR4-style shared libraries are in use. - -@item USE_PROC_FS -@findex USE_PROC_FS -This determines whether small routines in @file{*-tdep.c}, which -translate register values between @value{GDBN}'s internal -representation and the @file{/proc} representation, are compiled. - -@item U_REGS_OFFSET -@findex U_REGS_OFFSET -This is the offset of the registers in the upage. It need only be -defined if the generic ptrace register access routines in -@file{infptrace.c} are being used (that is, @file{infptrace.c} is -configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If -the default value from @file{infptrace.c} is good enough, leave it -undefined. - -The default value means that u.u_ar0 @emph{points to} the location of -the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means -that @code{u.u_ar0} @emph{is} the location of the registers. - -@item CLEAR_SOLIB -@findex CLEAR_SOLIB -See @file{objfiles.c}. - -@item DEBUG_PTRACE -@findex DEBUG_PTRACE -Define this to debug @code{ptrace} calls. -@end table - - -@node Support Libraries - -@chapter Support Libraries - -@section BFD -@cindex BFD library - -BFD provides support for @value{GDBN} in several ways: - -@table @emph -@item identifying executable and core files -BFD will identify a variety of file types, including a.out, coff, and -several variants thereof, as well as several kinds of core files. - -@item access to sections of files -BFD parses the file headers to determine the names, virtual addresses, -sizes, and file locations of all the various named sections in files -(such as the text section or the data section). @value{GDBN} simply -calls BFD to read or write section @var{x} at byte offset @var{y} for -length @var{z}. - -@item specialized core file support -BFD provides routines to determine the failing command name stored in a -core file, the signal with which the program failed, and whether a core -file matches (i.e.@: could be a core dump of) a particular executable -file. - -@item locating the symbol information -@value{GDBN} uses an internal interface of BFD to determine where to find the -symbol information in an executable file or symbol-file. @value{GDBN} itself -handles the reading of symbols, since BFD does not ``understand'' debug -symbols, but @value{GDBN} uses BFD's cached information to find the symbols, -string table, etc. -@end table - -@section opcodes -@cindex opcodes library - -The opcodes library provides @value{GDBN}'s disassembler. (It's a separate -library because it's also used in binutils, for @file{objdump}). - -@section readline - -@section mmalloc - -@section libiberty -@cindex @code{libiberty} library - -The @code{libiberty} library provides a set of functions and features -that integrate and improve on functionality found in modern operating -systems. Broadly speaking, such features can be divided into three -groups: supplemental functions (functions that may be missing in some -environments and operating systems), replacement functions (providing -a uniform and easier to use interface for commonly used standard -functions), and extensions (which provide additional functionality -beyond standard functions). - -@value{GDBN} uses various features provided by the @code{libiberty} -library, for instance the C@t{++} demangler, the @acronym{IEEE} -floating format support functions, the input options parser -@samp{getopt}, the @samp{obstack} extension, and other functions. - -@subsection @code{obstacks} in @value{GDBN} -@cindex @code{obstacks} - -The obstack mechanism provides a convenient way to allocate and free -chunks of memory. Each obstack is a pool of memory that is managed -like a stack. Objects (of any nature, size and alignment) are -allocated and freed in a @acronym{LIFO} fashion on an obstack (see -@code{libiberty}'s documenatation for a more detailed explanation of -@code{obstacks}). - -The most noticeable use of the @code{obstacks} in @value{GDBN} is in -object files. There is an obstack associated with each internal -representation of an object file. Lots of things get allocated on -these @code{obstacks}: dictionary entries, blocks, blockvectors, -symbols, minimal symbols, types, vectors of fundamental types, class -fields of types, object files section lists, object files section -offets lists, line tables, symbol tables, partial symbol tables, -string tables, symbol table private data, macros tables, debug -information sections and entries, import and export lists (som), -unwind information (hppa), dwarf2 location expressions data. Plus -various strings such as directory names strings, debug format strings, -names of types. - -An essential and convenient property of all data on @code{obstacks} is -that memory for it gets allocated (with @code{obstack_alloc}) at -various times during a debugging sesssion, but it is released all at -once using the @code{obstack_free} function. The @code{obstack_free} -function takes a pointer to where in the stack it must start the -deletion from (much like the cleanup chains have a pointer to where to -start the cleanups). Because of the stack like structure of the -@code{obstacks}, this allows to free only a top portion of the -obstack. There are a few instances in @value{GDBN} where such thing -happens. Calls to @code{obstack_free} are done after some local data -is allocated to the obstack. Only the local data is deleted from the -obstack. Of course this assumes that nothing between the -@code{obstack_alloc} and the @code{obstack_free} allocates anything -else on the same obstack. For this reason it is best and safest to -use temporary @code{obstacks}. - -Releasing the whole obstack is also not safe per se. It is safe only -under the condition that we know the @code{obstacks} memory is no -longer needed. In @value{GDBN} we get rid of the @code{obstacks} only -when we get rid of the whole objfile(s), for instance upon reading a -new symbol file. - -@section gnu-regex -@cindex regular expressions library - -Regex conditionals. - -@table @code -@item C_ALLOCA - -@item NFAILURES - -@item RE_NREGS - -@item SIGN_EXTEND_CHAR - -@item SWITCH_ENUM_BUG - -@item SYNTAX_TABLE - -@item Sword - -@item sparc -@end table - -@section include - -@node Coding - -@chapter Coding - -This chapter covers topics that are lower-level than the major -algorithms of @value{GDBN}. - -@section Cleanups -@cindex cleanups - -Cleanups are a structured way to deal with things that need to be done -later. - -When your code does something (e.g., @code{xmalloc} some memory, or -@code{open} a file) that needs to be undone later (e.g., @code{xfree} -the memory or @code{close} the file), it can make a cleanup. The -cleanup will be done at some future point: when the command is finished -and control returns to the top level; when an error occurs and the stack -is unwound; or when your code decides it's time to explicitly perform -cleanups. Alternatively you can elect to discard the cleanups you -created. - -Syntax: - -@table @code -@item struct cleanup *@var{old_chain}; -Declare a variable which will hold a cleanup chain handle. - -@findex make_cleanup -@item @var{old_chain} = make_cleanup (@var{function}, @var{arg}); -Make a cleanup which will cause @var{function} to be called with -@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a -handle that can later be passed to @code{do_cleanups} or -@code{discard_cleanups}. Unless you are going to call -@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result -from @code{make_cleanup}. - -@findex do_cleanups -@item do_cleanups (@var{old_chain}); -Do all cleanups added to the chain since the corresponding -@code{make_cleanup} call was made. - -@findex discard_cleanups -@item discard_cleanups (@var{old_chain}); -Same as @code{do_cleanups} except that it just removes the cleanups from -the chain and does not call the specified functions. -@end table - -Cleanups are implemented as a chain. The handle returned by -@code{make_cleanups} includes the cleanup passed to the call and any -later cleanups appended to the chain (but not yet discarded or -performed). E.g.: - -@smallexample -make_cleanup (a, 0); -@{ - struct cleanup *old = make_cleanup (b, 0); - make_cleanup (c, 0) - ... - do_cleanups (old); -@} -@end smallexample - -@noindent -will call @code{c()} and @code{b()} but will not call @code{a()}. The -cleanup that calls @code{a()} will remain in the cleanup chain, and will -be done later unless otherwise discarded.@refill - -Your function should explicitly do or discard the cleanups it creates. -Failing to do this leads to non-deterministic behavior since the caller -will arbitrarily do or discard your functions cleanups. This need leads -to two common cleanup styles. - -The first style is try/finally. Before it exits, your code-block calls -@code{do_cleanups} with the old cleanup chain and thus ensures that your -code-block's cleanups are always performed. For instance, the following -code-segment avoids a memory leak problem (even when @code{error} is -called and a forced stack unwind occurs) by ensuring that the -@code{xfree} will always be called: - -@smallexample -struct cleanup *old = make_cleanup (null_cleanup, 0); -data = xmalloc (sizeof blah); -make_cleanup (xfree, data); -... blah blah ... -do_cleanups (old); -@end smallexample - -The second style is try/except. Before it exits, your code-block calls -@code{discard_cleanups} with the old cleanup chain and thus ensures that -any created cleanups are not performed. For instance, the following -code segment, ensures that the file will be closed but only if there is -an error: - -@smallexample -FILE *file = fopen ("afile", "r"); -struct cleanup *old = make_cleanup (close_file, file); -... blah blah ... -discard_cleanups (old); -return file; -@end smallexample - -Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify -that they ``should not be called when cleanups are not in place''. This -means that any actions you need to reverse in the case of an error or -interruption must be on the cleanup chain before you call these -functions, since they might never return to your code (they -@samp{longjmp} instead). - -@section Per-architecture module data -@cindex per-architecture module data -@cindex multi-arch data -@cindex data-pointer, per-architecture/per-module - -The multi-arch framework includes a mechanism for adding module specific -per-architecture data-pointers to the @code{struct gdbarch} architecture -object. - -A module registers one or more per-architecture data-pointers using the -function @code{register_gdbarch_data}: - -@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}) - -The @var{init} function is used to obtain an initial value for a -per-architecture data-pointer. The function is called, after the -architecture has been created, when the data-pointer is still -uninitialized (@code{NULL}) and its value has been requested via a call -to @code{gdbarch_data}. A data-pointer can also be initialize -explicitly using @code{set_gdbarch_data}. - -Any memory required by the @var{init} function should be allocated -using @code{GDBARCH_OBSTACK_ZALLOC}. That memory is automatically -released when the corresponding architecture is deleted. - -The function @code{register_gdbarch_data} returns a @code{struct -gdbarch_data} that is used to identify the data-pointer that was added -to the module. - -@end deftypefun - -A typical module has an @code{init} function of the form: - -@smallexample -struct nozel @{ int total; @}; -static struct gdbarch_data *nozel_handle; -static void * -nozel_init (struct gdbarch *gdbarch) -@{ - struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel); - @dots{} - return data; -@} -@end smallexample - -Since uninitialized (@code{NULL}) data-pointers are initialized -on-demand, an @code{init} function is free to call other modules that -use data-pointers. Those modules data-pointers will be initialized as -needed. Care should be taken to ensure that the @code{init} call graph -does not contain cycles. - -The data-pointer is registered with the call: - -@smallexample -void -_initialize_nozel (void) -@{ - nozel_handle = register_gdbarch_data (nozel_init); -@dots{} -@end smallexample - -The per-architecture data-pointer is accessed using the function: - -@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle}) -Given the architecture @var{arch} and module data handle -@var{data_handle} (returned by @code{register_gdbarch_data}, this -function returns the current value of the per-architecture data-pointer. -@end deftypefun - -The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should -be saved in a local variable and then used directly: - -@smallexample -int -nozel_total (struct gdbarch *gdbarch) -@{ - int total; - struct nozel *data = gdbarch_data (gdbarch, nozel_handle); - @dots{} - return total; -@} -@end smallexample - -It is also possible to directly initialize the data-pointer using: - -@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{handle}, void *@var{pointer}) -Set the still @code{NULL} data-pointer corresponding to @var{handle} -to the non-@code{NULL} @var{pointer} value. -@end deftypefun - -This function is used by modules that require a mechanism for explicitly -setting the per-architecture data-pointer during architecture creation: - -@smallexample -/* Always return a non-NULL nozel. */ -static struct nozel * -gdbarch_nozel (struct gdbarch *gdbarch) -@{ - struct nozel *nozel = gdbarch_data (gdbarch, nozel_handle); - if (nozel == NULL) - @{ - nozel = nozel_init (gdbarch); - set_gdbarch_data (gdbarch, nozel_handle, nozel); - @} - return nozel; -@} -@end smallexample - -@smallexample -/* Called during architecture creation. */ -extern void -set_gdbarch_nozel (struct gdbarch *gdbarch, int total) -@{ - struct nozel *data = gdbarch_nozel (gdbarch); - @dots{} - data->total = total; -@} -@end smallexample - -@smallexample -void -_initialize_nozel (void) -@{ - nozel_handle = register_gdbarch_data (nozel_init); - @dots{} -@end smallexample - -@noindent -Note that an @code{init} function still needs to be registered. It is -used to initialize the data-pointer when the architecture creation phase -fail to set an initial value. - - -@section Wrapping Output Lines -@cindex line wrap in output - -@findex wrap_here -Output that goes through @code{printf_filtered} or @code{fputs_filtered} -or @code{fputs_demangled} needs only to have calls to @code{wrap_here} -added in places that would be good breaking points. The utility -routines will take care of actually wrapping if the line width is -exceeded. - -The argument to @code{wrap_here} is an indentation string which is -printed @emph{only} if the line breaks there. This argument is saved -away and used later. It must remain valid until the next call to -@code{wrap_here} or until a newline has been printed through the -@code{*_filtered} functions. Don't pass in a local variable and then -return! - -It is usually best to call @code{wrap_here} after printing a comma or -space. If you call it before printing a space, make sure that your -indentation properly accounts for the leading space that will print if -the line wraps there. - -Any function or set of functions that produce filtered output must -finish by printing a newline, to flush the wrap buffer, before switching -to unfiltered (@code{printf}) output. Symbol reading routines that -print warnings are a good example. - -@section @value{GDBN} Coding Standards -@cindex coding standards - -@value{GDBN} follows the GNU coding standards, as described in -@file{etc/standards.texi}. This file is also available for anonymous -FTP from GNU archive sites. @value{GDBN} takes a strict interpretation -of the standard; in general, when the GNU standard recommends a practice -but does not require it, @value{GDBN} requires it. - -@value{GDBN} follows an additional set of coding standards specific to -@value{GDBN}, as described in the following sections. - - -@subsection ISO C - -@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant -compiler. - -@value{GDBN} does not assume an ISO C or POSIX compliant C library. - - -@subsection Memory Management - -@value{GDBN} does not use the functions @code{malloc}, @code{realloc}, -@code{calloc}, @code{free} and @code{asprintf}. - -@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and -@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@: -these functions do not return when the memory pool is empty. Instead, -they unwind the stack using cleanups. These functions return -@code{NULL} when requested to allocate a chunk of memory of size zero. - -@emph{Pragmatics: By using these functions, the need to check every -memory allocation is removed. These functions provide portable -behavior.} - -@value{GDBN} does not use the function @code{free}. - -@value{GDBN} uses the function @code{xfree} to return memory to the -memory pool. Consistent with ISO-C, this function ignores a request to -free a @code{NULL} pointer. - -@emph{Pragmatics: On some systems @code{free} fails when passed a -@code{NULL} pointer.} - -@value{GDBN} can use the non-portable function @code{alloca} for the -allocation of small temporary values (such as strings). - -@emph{Pragmatics: This function is very non-portable. Some systems -restrict the memory being allocated to no more than a few kilobytes.} - -@value{GDBN} uses the string function @code{xstrdup} and the print -function @code{xasprintf}. - -@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print -functions such as @code{sprintf} are very prone to buffer overflow -errors.} - - -@subsection Compiler Warnings -@cindex compiler warnings - -With few exceptions, developers should include the configuration option -@samp{--enable-gdb-build-warnings=,-Werror} when building @value{GDBN}. -The exceptions are listed in the file @file{gdb/MAINTAINERS}. - -This option causes @value{GDBN} (when built using GCC) to be compiled -with a carefully selected list of compiler warning flags. Any warnings -from those flags being treated as errors. - -The current list of warning flags includes: - -@table @samp -@item -Wimplicit -Since @value{GDBN} coding standard requires all functions to be declared -using a prototype, the flag has the side effect of ensuring that -prototyped functions are always visible with out resorting to -@samp{-Wstrict-prototypes}. - -@item -Wreturn-type -Such code often appears to work except on instruction set architectures -that use register windows. - -@item -Wcomment - -@item -Wtrigraphs - -@item -Wformat -@itemx -Wformat-nonliteral -Since @value{GDBN} uses the @code{format printf} attribute on all -@code{printf} like functions these check not just @code{printf} calls -but also calls to functions such as @code{fprintf_unfiltered}. - -@item -Wparentheses -This warning includes uses of the assignment operator within an -@code{if} statement. - -@item -Wpointer-arith - -@item -Wuninitialized - -@item -Wunused-label -This warning has the additional benefit of detecting the absence of the -@code{case} reserved word in a switch statement: -@smallexample -enum @{ FD_SCHEDULED, NOTHING_SCHEDULED @} sched; -@dots{} -switch (sched) - @{ - case FD_SCHEDULED: - @dots{}; - break; - NOTHING_SCHEDULED: - @dots{}; - break; - @} -@end smallexample - -@item -Wunused-function -@end table - -@emph{Pragmatics: Due to the way that @value{GDBN} is implemented most -functions have unused parameters. Consequently the warning -@samp{-Wunused-parameter} is precluded from the list. The macro -@code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives --- -it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that -is being used. The options @samp{-Wall} and @samp{-Wunused} are also -precluded because they both include @samp{-Wunused-parameter}.} - -@emph{Pragmatics: @value{GDBN} has not simply accepted the warnings -enabled by @samp{-Wall -Werror -W...}. Instead it is selecting warnings -when and where their benefits can be demonstrated.} - -@subsection Formatting - -@cindex source code formatting -The standard GNU recommendations for formatting must be followed -strictly. - -A function declaration should not have its name in column zero. A -function definition should have its name in column zero. - -@smallexample -/* Declaration */ -static void foo (void); -/* Definition */ -void -foo (void) -@{ -@} -@end smallexample - -@emph{Pragmatics: This simplifies scripting. Function definitions can -be found using @samp{^function-name}.} - -There must be a space between a function or macro name and the opening -parenthesis of its argument list (except for macro definitions, as -required by C). There must not be a space after an open paren/bracket -or before a close paren/bracket. - -While additional whitespace is generally helpful for reading, do not use -more than one blank line to separate blocks, and avoid adding whitespace -after the end of a program line (as of 1/99, some 600 lines had -whitespace after the semicolon). Excess whitespace causes difficulties -for @code{diff} and @code{patch} utilities. - -Pointers are declared using the traditional K&R C style: - -@smallexample -void *foo; -@end smallexample - -@noindent -and not: - -@smallexample -void * foo; -void* foo; -@end smallexample - -@subsection Comments - -@cindex comment formatting -The standard GNU requirements on comments must be followed strictly. - -Block comments must appear in the following form, with no @code{/*}- or -@code{*/}-only lines, and no leading @code{*}: - -@smallexample -/* Wait for control to return from inferior to debugger. If inferior - gets a signal, we may decide to start it up again instead of - returning. That is why there is a loop in this function. When - this function actually returns it means the inferior should be left - stopped and @value{GDBN} should read more commands. */ -@end smallexample - -(Note that this format is encouraged by Emacs; tabbing for a multi-line -comment works correctly, and @kbd{M-q} fills the block consistently.) - -Put a blank line between the block comments preceding function or -variable definitions, and the definition itself. - -In general, put function-body comments on lines by themselves, rather -than trying to fit them into the 20 characters left at the end of a -line, since either the comment or the code will inevitably get longer -than will fit, and then somebody will have to move it anyhow. - -@subsection C Usage - -@cindex C data types -Code must not depend on the sizes of C data types, the format of the -host's floating point numbers, the alignment of anything, or the order -of evaluation of expressions. - -@cindex function usage -Use functions freely. There are only a handful of compute-bound areas -in @value{GDBN} that might be affected by the overhead of a function -call, mainly in symbol reading. Most of @value{GDBN}'s performance is -limited by the target interface (whether serial line or system call). - -However, use functions with moderation. A thousand one-line functions -are just as hard to understand as a single thousand-line function. - -@emph{Macros are bad, M'kay.} -(But if you have to use a macro, make sure that the macro arguments are -protected with parentheses.) - -@cindex types - -Declarations like @samp{struct foo *} should be used in preference to -declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}. - - -@subsection Function Prototypes -@cindex function prototypes - -Prototypes must be used when both @emph{declaring} and @emph{defining} -a function. Prototypes for @value{GDBN} functions must include both the -argument type and name, with the name matching that used in the actual -function definition. - -All external functions should have a declaration in a header file that -callers include, except for @code{_initialize_*} functions, which must -be external so that @file{init.c} construction works, but shouldn't be -visible to random source files. - -Where a source file needs a forward declaration of a static function, -that declaration must appear in a block near the top of the source file. - - -@subsection Internal Error Recovery - -During its execution, @value{GDBN} can encounter two types of errors. -User errors and internal errors. User errors include not only a user -entering an incorrect command but also problems arising from corrupt -object files and system errors when interacting with the target. -Internal errors include situations where @value{GDBN} has detected, at -run time, a corrupt or erroneous situation. - -When reporting an internal error, @value{GDBN} uses -@code{internal_error} and @code{gdb_assert}. - -@value{GDBN} must not call @code{abort} or @code{assert}. - -@emph{Pragmatics: There is no @code{internal_warning} function. Either -the code detected a user error, recovered from it and issued a -@code{warning} or the code failed to correctly recover from the user -error and issued an @code{internal_error}.} - -@subsection File Names - -Any file used when building the core of @value{GDBN} must be in lower -case. Any file used when building the core of @value{GDBN} must be 8.3 -unique. These requirements apply to both source and generated files. - -@emph{Pragmatics: The core of @value{GDBN} must be buildable on many -platforms including DJGPP and MacOS/HFS. Every time an unfriendly file -is introduced to the build process both @file{Makefile.in} and -@file{configure.in} need to be modified accordingly. Compare the -convoluted conversion process needed to transform @file{COPYING} into -@file{copying.c} with the conversion needed to transform -@file{version.in} into @file{version.c}.} - -Any file non 8.3 compliant file (that is not used when building the core -of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}. - -@emph{Pragmatics: This is clearly a compromise.} - -When @value{GDBN} has a local version of a system header file (ex -@file{string.h}) the file name based on the POSIX header prefixed with -@file{gdb_} (@file{gdb_string.h}). These headers should be relatively -independent: they should use only macros defined by @file{configure}, -the compiler, or the host; they should include only system headers; they -should refer only to system types. They may be shared between multiple -programs, e.g.@: @value{GDBN} and @sc{gdbserver}. - -For other files @samp{-} is used as the separator. - - -@subsection Include Files - -A @file{.c} file should include @file{defs.h} first. - -A @file{.c} file should directly include the @code{.h} file of every -declaration and/or definition it directly refers to. It cannot rely on -indirect inclusion. - -A @file{.h} file should directly include the @code{.h} file of every -declaration and/or definition it directly refers to. It cannot rely on -indirect inclusion. Exception: The file @file{defs.h} does not need to -be directly included. - -An external declaration should only appear in one include file. - -An external declaration should never appear in a @code{.c} file. -Exception: a declaration for the @code{_initialize} function that -pacifies @option{-Wmissing-declaration}. - -A @code{typedef} definition should only appear in one include file. - -An opaque @code{struct} declaration can appear in multiple @file{.h} -files. Where possible, a @file{.h} file should use an opaque -@code{struct} declaration instead of an include. - -All @file{.h} files should be wrapped in: - -@smallexample -#ifndef INCLUDE_FILE_NAME_H -#define INCLUDE_FILE_NAME_H -header body -#endif -@end smallexample - - -@subsection Clean Design and Portable Implementation - -@cindex design -In addition to getting the syntax right, there's the little question of -semantics. Some things are done in certain ways in @value{GDBN} because long -experience has shown that the more obvious ways caused various kinds of -trouble. - -@cindex assumptions about targets -You can't assume the byte order of anything that comes from a target -(including @var{value}s, object files, and instructions). Such things -must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in -@value{GDBN}, or one of the swap routines defined in @file{bfd.h}, -such as @code{bfd_get_32}. - -You can't assume that you know what interface is being used to talk to -the target system. All references to the target must go through the -current @code{target_ops} vector. - -You can't assume that the host and target machines are the same machine -(except in the ``native'' support modules). In particular, you can't -assume that the target machine's header files will be available on the -host machine. Target code must bring along its own header files -- -written from scratch or explicitly donated by their owner, to avoid -copyright problems. - -@cindex portability -Insertion of new @code{#ifdef}'s will be frowned upon. It's much better -to write the code portably than to conditionalize it for various -systems. - -@cindex system dependencies -New @code{#ifdef}'s which test for specific compilers or manufacturers -or operating systems are unacceptable. All @code{#ifdef}'s should test -for features. The information about which configurations contain which -features should be segregated into the configuration files. Experience -has proven far too often that a feature unique to one particular system -often creeps into other systems; and that a conditional based on some -predefined macro for your current system will become worthless over -time, as new versions of your system come out that behave differently -with regard to this feature. - -Adding code that handles specific architectures, operating systems, -target interfaces, or hosts, is not acceptable in generic code. - -@cindex portable file name handling -@cindex file names, portability -One particularly notorious area where system dependencies tend to -creep in is handling of file names. The mainline @value{GDBN} code -assumes Posix semantics of file names: absolute file names begin with -a forward slash @file{/}, slashes are used to separate leading -directories, case-sensitive file names. These assumptions are not -necessarily true on non-Posix systems such as MS-Windows. To avoid -system-dependent code where you need to take apart or construct a file -name, use the following portable macros: - -@table @code -@findex HAVE_DOS_BASED_FILE_SYSTEM -@item HAVE_DOS_BASED_FILE_SYSTEM -This preprocessing symbol is defined to a non-zero value on hosts -whose filesystems belong to the MS-DOS/MS-Windows family. Use this -symbol to write conditional code which should only be compiled for -such hosts. - -@findex IS_DIR_SEPARATOR -@item IS_DIR_SEPARATOR (@var{c}) -Evaluates to a non-zero value if @var{c} is a directory separator -character. On Unix and GNU/Linux systems, only a slash @file{/} is -such a character, but on Windows, both @file{/} and @file{\} will -pass. - -@findex IS_ABSOLUTE_PATH -@item IS_ABSOLUTE_PATH (@var{file}) -Evaluates to a non-zero value if @var{file} is an absolute file name. -For Unix and GNU/Linux hosts, a name which begins with a slash -@file{/} is absolute. On DOS and Windows, @file{d:/foo} and -@file{x:\bar} are also absolute file names. - -@findex FILENAME_CMP -@item FILENAME_CMP (@var{f1}, @var{f2}) -Calls a function which compares file names @var{f1} and @var{f2} as -appropriate for the underlying host filesystem. For Posix systems, -this simply calls @code{strcmp}; on case-insensitive filesystems it -will call @code{strcasecmp} instead. - -@findex DIRNAME_SEPARATOR -@item DIRNAME_SEPARATOR -Evaluates to a character which separates directories in -@code{PATH}-style lists, typically held in environment variables. -This character is @samp{:} on Unix, @samp{;} on DOS and Windows. - -@findex SLASH_STRING -@item SLASH_STRING -This evaluates to a constant string you should use to produce an -absolute filename from leading directories and the file's basename. -@code{SLASH_STRING} is @code{"/"} on most systems, but might be -@code{"\\"} for some Windows-based ports. -@end table - -In addition to using these macros, be sure to use portable library -functions whenever possible. For example, to extract a directory or a -basename part from a file name, use the @code{dirname} and -@code{basename} library functions (available in @code{libiberty} for -platforms which don't provide them), instead of searching for a slash -with @code{strrchr}. - -Another way to generalize @value{GDBN} along a particular interface is with an -attribute struct. For example, @value{GDBN} has been generalized to handle -multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but -by defining the @code{target_ops} structure and having a current target (as -well as a stack of targets below it, for memory references). Whenever -something needs to be done that depends on which remote interface we are -using, a flag in the current target_ops structure is tested (e.g., -@code{target_has_stack}), or a function is called through a pointer in the -current target_ops structure. In this way, when a new remote interface -is added, only one module needs to be touched---the one that actually -implements the new remote interface. Other examples of -attribute-structs are BFD access to multiple kinds of object file -formats, or @value{GDBN}'s access to multiple source languages. - -Please avoid duplicating code. For example, in @value{GDBN} 3.x all -the code interfacing between @code{ptrace} and the rest of -@value{GDBN} was duplicated in @file{*-dep.c}, and so changing -something was very painful. In @value{GDBN} 4.x, these have all been -consolidated into @file{infptrace.c}. @file{infptrace.c} can deal -with variations between systems the same way any system-independent -file would (hooks, @code{#if defined}, etc.), and machines which are -radically different don't need to use @file{infptrace.c} at all. - -All debugging code must be controllable using the @samp{set debug -@var{module}} command. Do not use @code{printf} to print trace -messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use -@code{#ifdef DEBUG}. - - -@node Porting GDB - -@chapter Porting @value{GDBN} -@cindex porting to new machines - -Most of the work in making @value{GDBN} compile on a new machine is in -specifying the configuration of the machine. This is done in a -dizzying variety of header files and configuration scripts, which we -hope to make more sensible soon. Let's say your new host is called an -@var{xyz} (e.g., @samp{sun4}), and its full three-part configuration -name is @code{@var{arch}-@var{xvend}-@var{xos}} (e.g., -@samp{sparc-sun-sunos4}). In particular: - -@itemize @bullet -@item -In the top level directory, edit @file{config.sub} and add @var{arch}, -@var{xvend}, and @var{xos} to the lists of supported architectures, -vendors, and operating systems near the bottom of the file. Also, add -@var{xyz} as an alias that maps to -@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by -running - -@smallexample -./config.sub @var{xyz} -@end smallexample - -@noindent -and - -@smallexample -./config.sub @code{@var{arch}-@var{xvend}-@var{xos}} -@end smallexample - -@noindent -which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}} -and no error messages. - -@noindent -You need to port BFD, if that hasn't been done already. Porting BFD is -beyond the scope of this manual. - -@item -To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize -your system and set @code{gdb_host} to @var{xyz}, and (unless your -desired target is already available) also edit @file{gdb/configure.tgt}, -setting @code{gdb_target} to something appropriate (for instance, -@var{xyz}). - -@emph{Maintainer's note: Work in progress. The file -@file{gdb/configure.host} originally needed to be modified when either a -new native target or a new host machine was being added to @value{GDBN}. -Recent changes have removed this requirement. The file now only needs -to be modified when adding a new native configuration. This will likely -changed again in the future.} - -@item -Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and -target-dependent @file{.h} and @file{.c} files used for your -configuration. -@end itemize - -@node Releasing GDB - -@chapter Releasing @value{GDBN} -@cindex making a new release of gdb - -@section Versions and Branches - -@subsection Version Identifiers - -@value{GDBN}'s version is determined by the file @file{gdb/version.in}. - -@value{GDBN}'s mainline uses ISO dates to differentiate between -versions. The CVS repository uses @var{YYYY}-@var{MM}-@var{DD}-cvs -while the corresponding snapshot uses @var{YYYYMMDD}. - -@value{GDBN}'s release branch uses a slightly more complicated scheme. -When the branch is first cut, the mainline version identifier is -prefixed with the @var{major}.@var{minor} from of the previous release -series but with .90 appended. As draft releases are drawn from the -branch, the minor minor number (.90) is incremented. Once the first -release (@var{M}.@var{N}) has been made, the version prefix is updated -to @var{M}.@var{N}.0.90 (dot zero, dot ninety). Follow on releases have -an incremented minor minor version number (.0). - -Using 5.1 (previous) and 5.2 (current), the example below illustrates a -typical sequence of version identifiers: - -@table @asis -@item 5.1.1 -final release from previous branch -@item 2002-03-03-cvs -main-line the day the branch is cut -@item 5.1.90-2002-03-03-cvs -corresponding branch version -@item 5.1.91 -first draft release candidate -@item 5.1.91-2002-03-17-cvs -updated branch version -@item 5.1.92 -second draft release candidate -@item 5.1.92-2002-03-31-cvs -updated branch version -@item 5.1.93 -final release candidate (see below) -@item 5.2 -official release -@item 5.2.0.90-2002-04-07-cvs -updated CVS branch version -@item 5.2.1 -second official release -@end table - -Notes: - -@itemize @bullet -@item -Minor minor minor draft release candidates such as 5.2.0.91 have been -omitted from the example. Such release candidates are, typically, never -made. -@item -For 5.1.93 the bziped tar ball @file{gdb-5.1.93.tar.bz2} is just the -official @file{gdb-5.2.tar} renamed and compressed. -@end itemize - -To avoid version conflicts, vendors are expected to modify the file -@file{gdb/version.in} to include a vendor unique alphabetic identifier -(an official @value{GDBN} release never uses alphabetic characters in -its version identifer). - -Since @value{GDBN} does not make minor minor minor releases (e.g., -5.1.0.1) the conflict between that and a minor minor draft release -identifier (e.g., 5.1.0.90) is avoided. - - -@subsection Branches - -@value{GDBN} draws a release series (5.2, 5.2.1, @dots{}) from a single -release branch (gdb_5_2-branch). Since minor minor minor releases -(5.1.0.1) are not made, the need to branch the release branch is avoided -(it also turns out that the effort required for such a a branch and -release is significantly greater than the effort needed to create a new -release from the head of the release branch). - -Releases 5.0 and 5.1 used branch and release tags of the form: - -@smallexample -gdb_N_M-YYYY-MM-DD-branchpoint -gdb_N_M-YYYY-MM-DD-branch -gdb_M_N-YYYY-MM-DD-release -@end smallexample - -Release 5.2 is trialing the branch and release tags: - -@smallexample -gdb_N_M-YYYY-MM-DD-branchpoint -gdb_N_M-branch -gdb_M_N-YYYY-MM-DD-release -@end smallexample - -@emph{Pragmatics: The branchpoint and release tags need to identify when -a branch and release are made. The branch tag, denoting the head of the -branch, does not have this criteria.} - - -@section Branch Commit Policy - -The branch commit policy is pretty slack. @value{GDBN} releases 5.0, -5.1 and 5.2 all used the below: - -@itemize @bullet -@item -The @file{gdb/MAINTAINERS} file still holds. -@item -Don't fix something on the branch unless/until it is also fixed in the -trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS} -file is better than committing a hack. -@item -When considering a patch for the branch, suggested criteria include: -Does it fix a build? Does it fix the sequence @kbd{break main; run} -when debugging a static binary? -@item -The further a change is from the core of @value{GDBN}, the less likely -the change will worry anyone (e.g., target specific code). -@item -Only post a proposal to change the core of @value{GDBN} after you've -sent individual bribes to all the people listed in the -@file{MAINTAINERS} file @t{;-)} -@end itemize - -@emph{Pragmatics: Provided updates are restricted to non-core -functionality there is little chance that a broken change will be fatal. -This means that changes such as adding a new architectures or (within -reason) support for a new host are considered acceptable.} - - -@section Obsoleting code - -Before anything else, poke the other developers (and around the source -code) to see if there is anything that can be removed from @value{GDBN} -(an old target, an unused file). - -Obsolete code is identified by adding an @code{OBSOLETE} prefix to every -line. Doing this means that it is easy to identify something that has -been obsoleted when greping through the sources. - -The process is done in stages --- this is mainly to ensure that the -wider @value{GDBN} community has a reasonable opportunity to respond. -Remember, everything on the Internet takes a week. - -@enumerate -@item -Post the proposal on @email{gdb@@sources.redhat.com, the GDB mailing -list} Creating a bug report to track the task's state, is also highly -recommended. -@item -Wait a week or so. -@item -Post the proposal on @email{gdb-announce@@sources.redhat.com, the GDB -Announcement mailing list}. -@item -Wait a week or so. -@item -Go through and edit all relevant files and lines so that they are -prefixed with the word @code{OBSOLETE}. -@item -Wait until the next GDB version, containing this obsolete code, has been -released. -@item -Remove the obsolete code. -@end enumerate - -@noindent -@emph{Maintainer note: While removing old code is regrettable it is -hopefully better for @value{GDBN}'s long term development. Firstly it -helps the developers by removing code that is either no longer relevant -or simply wrong. Secondly since it removes any history associated with -the file (effectively clearing the slate) the developer has a much freer -hand when it comes to fixing broken files.} - - - -@section Before the Branch - -The most important objective at this stage is to find and fix simple -changes that become a pain to track once the branch is created. For -instance, configuration problems that stop @value{GDBN} from even -building. If you can't get the problem fixed, document it in the -@file{gdb/PROBLEMS} file. - -@subheading Prompt for @file{gdb/NEWS} - -People always forget. Send a post reminding them but also if you know -something interesting happened add it yourself. The @code{schedule} -script will mention this in its e-mail. - -@subheading Review @file{gdb/README} - -Grab one of the nightly snapshots and then walk through the -@file{gdb/README} looking for anything that can be improved. The -@code{schedule} script will mention this in its e-mail. - -@subheading Refresh any imported files. - -A number of files are taken from external repositories. They include: - -@itemize @bullet -@item -@file{texinfo/texinfo.tex} -@item -@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS} -file) -@item -@file{etc/standards.texi}, @file{etc/make-stds.texi} -@end itemize - -@subheading Check the ARI - -@uref{http://sources.redhat.com/gdb/ari,,A.R.I.} is an @code{awk} script -(Awk Regression Index ;-) that checks for a number of errors and coding -conventions. The checks include things like using @code{malloc} instead -of @code{xmalloc} and file naming problems. There shouldn't be any -regressions. - -@subsection Review the bug data base - -Close anything obviously fixed. - -@subsection Check all cross targets build - -The targets are listed in @file{gdb/MAINTAINERS}. - - -@section Cut the Branch - -@subheading Create the branch - -@smallexample -$ u=5.1 -$ v=5.2 -$ V=`echo $v | sed 's/\./_/g'` -$ D=`date -u +%Y-%m-%d` -$ echo $u $V $D -5.1 5_2 2002-03-03 -$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ --D $D-gmt gdb_$V-$D-branchpoint insight+dejagnu -cvs -f -d :ext:sources.redhat.com:/cvs/src rtag --D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight+dejagnu -$ ^echo ^^ -... -$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ --b -r gdb_$V-$D-branchpoint gdb_$V-branch insight+dejagnu -cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ --b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight+dejagnu -$ ^echo ^^ -... -$ -@end smallexample - -@itemize @bullet -@item -by using @kbd{-D YYYY-MM-DD-gmt} the branch is forced to an exact -date/time. -@item -the trunk is first taged so that the branch point can easily be found -@item -Insight (which includes GDB) and dejagnu are all tagged at the same time -@item -@file{version.in} gets bumped to avoid version number conflicts -@item -the reading of @file{.cvsrc} is disabled using @file{-f} -@end itemize - -@subheading Update @file{version.in} - -@smallexample -$ u=5.1 -$ v=5.2 -$ V=`echo $v | sed 's/\./_/g'` -$ echo $u $v$V -5.1 5_2 -$ cd /tmp -$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src co \ --r gdb_$V-branch src/gdb/version.in -cvs -f -d :ext:sources.redhat.com:/cvs/src co - -r gdb_5_2-branch src/gdb/version.in -$ ^echo ^^ -U src/gdb/version.in -$ cd src/gdb -$ echo $u.90-0000-00-00-cvs > version.in -$ cat version.in -5.1.90-0000-00-00-cvs -$ cvs -f commit version.in -@end smallexample - -@itemize @bullet -@item -@file{0000-00-00} is used as a date to pump prime the version.in update -mechanism -@item -@file{.90} and the previous branch version are used as fairly arbitrary -initial branch version number -@end itemize - - -@subheading Update the web and news pages - -Something? - -@subheading Tweak cron to track the new branch - -The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table. -This file needs to be updated so that: - -@itemize @bullet -@item -a daily timestamp is added to the file @file{version.in} -@item -the new branch is included in the snapshot process -@end itemize - -@noindent -See the file @file{gdbadmin/cron/README} for how to install the updated -cron table. - -The file @file{gdbadmin/ss/README} should also be reviewed to reflect -any changes. That file is copied to both the branch/ and current/ -snapshot directories. - - -@subheading Update the NEWS and README files - -The @file{NEWS} file needs to be updated so that on the branch it refers -to @emph{changes in the current release} while on the trunk it also -refers to @emph{changes since the current release}. - -The @file{README} file needs to be updated so that it refers to the -current release. - -@subheading Post the branch info - -Send an announcement to the mailing lists: - -@itemize @bullet -@item -@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list} -@item -@email{gdb@@sources.redhat.com, GDB Discsussion mailing list} and -@email{gdb-testers@@sources.redhat.com, GDB Discsussion mailing list} -@end itemize - -@emph{Pragmatics: The branch creation is sent to the announce list to -ensure that people people not subscribed to the higher volume discussion -list are alerted.} - -The announcement should include: - -@itemize @bullet -@item -the branch tag -@item -how to check out the branch using CVS -@item -the date/number of weeks until the release -@item -the branch commit policy -still holds. -@end itemize - -@section Stabilize the branch - -Something goes here. - -@section Create a Release - -The process of creating and then making available a release is broken -down into a number of stages. The first part addresses the technical -process of creating a releasable tar ball. The later stages address the -process of releasing that tar ball. - -When making a release candidate just the first section is needed. - -@subsection Create a release candidate - -The objective at this stage is to create a set of tar balls that can be -made available as a formal release (or as a less formal release -candidate). - -@subsubheading Freeze the branch - -Send out an e-mail notifying everyone that the branch is frozen to -@email{gdb-patches@@sources.redhat.com}. - -@subsubheading Establish a few defaults. - -@smallexample -$ b=gdb_5_2-branch -$ v=5.2 -$ t=/sourceware/snapshot-tmp/gdbadmin-tmp -$ echo $t/$b/$v -/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2 -$ mkdir -p $t/$b/$v -$ cd $t/$b/$v -$ pwd -/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2 -$ which autoconf -/home/gdbadmin/bin/autoconf -$ -@end smallexample - -@noindent -Notes: - -@itemize @bullet -@item -Check the @code{autoconf} version carefully. You want to be using the -version taken from the @file{binutils} snapshot directory, which can be -found at @uref{ftp://sources.redhat.com/pub/binutils/}. It is very -unlikely that a system installed version of @code{autoconf} (e.g., -@file{/usr/bin/autoconf}) is correct. -@end itemize - -@subsubheading Check out the relevant modules: - -@smallexample -$ for m in gdb insight dejagnu -do -( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m ) -done -$ -@end smallexample - -@noindent -Note: - -@itemize @bullet -@item -The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't -any confusion between what is written here and what your local -@code{cvs} really does. -@end itemize - -@subsubheading Update relevant files. - -@table @file - -@item gdb/NEWS - -Major releases get their comments added as part of the mainline. Minor -releases should probably mention any significant bugs that were fixed. - -Don't forget to include the @file{ChangeLog} entry. - -@smallexample -$ emacs gdb/src/gdb/NEWS -... -c-x 4 a -... -c-x c-s c-x c-c -$ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS -$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog -@end smallexample - -@item gdb/README - -You'll need to update: - -@itemize @bullet -@item -the version -@item -the update date -@item -who did it -@end itemize - -@smallexample -$ emacs gdb/src/gdb/README -... -c-x 4 a -... -c-x c-s c-x c-c -$ cp gdb/src/gdb/README insight/src/gdb/README -$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog -@end smallexample - -@emph{Maintainer note: Hopefully the @file{README} file was reviewed -before the initial branch was cut so just a simple substitute is needed -to get it updated.} - -@emph{Maintainer note: Other projects generate @file{README} and -@file{INSTALL} from the core documentation. This might be worth -pursuing.} - -@item gdb/version.in - -@smallexample -$ echo $v > gdb/src/gdb/version.in -$ cat gdb/src/gdb/version.in -5.2 -$ emacs gdb/src/gdb/version.in -... -c-x 4 a -... Bump to version ... -c-x c-s c-x c-c -$ cp gdb/src/gdb/version.in insight/src/gdb/version.in -$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog -@end smallexample - -@item dejagnu/src/dejagnu/configure.in - -Dejagnu is more complicated. The version number is a parameter to -@code{AM_INIT_AUTOMAKE}. Tweak it to read something like gdb-5.1.91. - -Don't forget to re-generate @file{configure}. - -Don't forget to include a @file{ChangeLog} entry. - -@smallexample -$ emacs dejagnu/src/dejagnu/configure.in -... -c-x 4 a -... -c-x c-s c-x c-c -$ ( cd dejagnu/src/dejagnu && autoconf ) -@end smallexample - -@end table - -@subsubheading Do the dirty work - -This is identical to the process used to create the daily snapshot. - -@smallexample -$ for m in gdb insight -do -( cd $m/src && gmake -f src-release $m.tar ) -done -$ ( m=dejagnu; cd $m/src && gmake -f src-release $m.tar.bz2 ) -@end smallexample - -If the top level source directory does not have @file{src-release} -(@value{GDBN} version 5.3.1 or earlier), try these commands instead: - -@smallexample -$ for m in gdb insight -do -( cd $m/src && gmake -f Makefile.in $m.tar ) -done -$ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 ) -@end smallexample - -@subsubheading Check the source files - -You're looking for files that have mysteriously disappeared. -@kbd{distclean} has the habit of deleting files it shouldn't. Watch out -for the @file{version.in} update @kbd{cronjob}. - -@smallexample -$ ( cd gdb/src && cvs -f -q -n update ) -M djunpack.bat -? gdb-5.1.91.tar -? proto-toplev -@dots{} lots of generated files @dots{} -M gdb/ChangeLog -M gdb/NEWS -M gdb/README -M gdb/version.in -@dots{} lots of generated files @dots{} -$ -@end smallexample - -@noindent -@emph{Don't worry about the @file{gdb.info-??} or -@file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1} -was also generated only something strange with CVS means that they -didn't get supressed). Fixing it would be nice though.} - -@subsubheading Create compressed versions of the release - -@smallexample -$ cp */src/*.tar . -$ cp */src/*.bz2 . -$ ls -F -dejagnu/ dejagnu-gdb-5.2.tar.bz2 gdb/ gdb-5.2.tar insight/ insight-5.2.tar -$ for m in gdb insight -do -bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2 -gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz -done -$ -@end smallexample - -@noindent -Note: - -@itemize @bullet -@item -A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} is not since, -in that mode, @code{gzip} does not know the name of the file and, hence, -can not include it in the compressed file. This is also why the release -process runs @code{tar} and @code{bzip2} as separate passes. -@end itemize - -@subsection Sanity check the tar ball - -Pick a popular machine (Solaris/PPC?) and try the build on that. - -@smallexample -$ bunzip2 < gdb-5.2.tar.bz2 | tar xpf - -$ cd gdb-5.2 -$ ./configure -$ make -@dots{} -$ ./gdb/gdb ./gdb/gdb -GNU gdb 5.2 -@dots{} -(gdb) b main -Breakpoint 1 at 0x80732bc: file main.c, line 734. -(gdb) run -Starting program: /tmp/gdb-5.2/gdb/gdb - -Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734 -734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL); -(gdb) print args -$1 = @{argc = 136426532, argv = 0x821b7f0@} -(gdb) -@end smallexample - -@subsection Make a release candidate available - -If this is a release candidate then the only remaining steps are: - -@enumerate -@item -Commit @file{version.in} and @file{ChangeLog} -@item -Tweak @file{version.in} (and @file{ChangeLog} to read -@var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update -process can restart. -@item -Make the release candidate available in -@uref{ftp://sources.redhat.com/pub/gdb/snapshots/branch} -@item -Notify the relevant mailing lists ( @email{gdb@@sources.redhat.com} and -@email{gdb-testers@@sources.redhat.com} that the candidate is available. -@end enumerate - -@subsection Make a formal release available - -(And you thought all that was required was to post an e-mail.) - -@subsubheading Install on sware - -Copy the new files to both the release and the old release directory: - -@smallexample -$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/ -$ cp *.bz2 *.gz ~ftp/pub/gdb/releases -@end smallexample - -@noindent -Clean up the releases directory so that only the most recent releases -are available (e.g. keep 5.2 and 5.2.1 but remove 5.1): - -@smallexample -$ cd ~ftp/pub/gdb/releases -$ rm @dots{} -@end smallexample - -@noindent -Update the file @file{README} and @file{.message} in the releases -directory: - -@smallexample -$ vi README -@dots{} -$ rm -f .message -$ ln README .message -@end smallexample - -@subsubheading Update the web pages. - -@table @file - -@item htdocs/download/ANNOUNCEMENT -This file, which is posted as the official announcement, includes: -@itemize @bullet -@item -General announcement -@item -News. If making an @var{M}.@var{N}.1 release, retain the news from -earlier @var{M}.@var{N} release. -@item -Errata -@end itemize - -@item htdocs/index.html -@itemx htdocs/news/index.html -@itemx htdocs/download/index.html -These files include: -@itemize @bullet -@item -announcement of the most recent release -@item -news entry (remember to update both the top level and the news directory). -@end itemize -These pages also need to be regenerate using @code{index.sh}. - -@item download/onlinedocs/ -You need to find the magic command that is used to generate the online -docs from the @file{.tar.bz2}. The best way is to look in the output -from one of the nightly @code{cron} jobs and then just edit accordingly. -Something like: - -@smallexample -$ ~/ss/update-web-docs \ - ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \ - $PWD/www \ - /www/sourceware/htdocs/gdb/download/onlinedocs \ - gdb -@end smallexample - -@item download/ari/ -Just like the online documentation. Something like: - -@smallexample -$ /bin/sh ~/ss/update-web-ari \ - ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \ - $PWD/www \ - /www/sourceware/htdocs/gdb/download/ari \ - gdb -@end smallexample - -@end table - -@subsubheading Shadow the pages onto gnu - -Something goes here. - - -@subsubheading Install the @value{GDBN} tar ball on GNU - -At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in -@file{~ftp/gnu/gdb}. - -@subsubheading Make the @file{ANNOUNCEMENT} - -Post the @file{ANNOUNCEMENT} file you created above to: - -@itemize @bullet -@item -@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list} -@item -@email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a -day or so to let things get out) -@item -@email{bug-gdb@@gnu.org, GDB Bug Report mailing list} -@end itemize - -@subsection Cleanup - -The release is out but you're still not finished. - -@subsubheading Commit outstanding changes - -In particular you'll need to commit any changes to: - -@itemize @bullet -@item -@file{gdb/ChangeLog} -@item -@file{gdb/version.in} -@item -@file{gdb/NEWS} -@item -@file{gdb/README} -@end itemize - -@subsubheading Tag the release - -Something like: - -@smallexample -$ d=`date -u +%Y-%m-%d` -$ echo $d -2002-01-24 -$ ( cd insight/src/gdb && cvs -f -q update ) -$ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release ) -@end smallexample - -Insight is used since that contains more of the release than -@value{GDBN} (@code{dejagnu} doesn't get tagged but I think we can live -with that). - -@subsubheading Mention the release on the trunk - -Just put something in the @file{ChangeLog} so that the trunk also -indicates when the release was made. - -@subsubheading Restart @file{gdb/version.in} - -If @file{gdb/version.in} does not contain an ISO date such as -@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having -committed all the release changes it can be set to -@file{5.2.0_0000-00-00-cvs} which will restart things (yes the @kbd{_} -is important - it affects the snapshot process). - -Don't forget the @file{ChangeLog}. - -@subsubheading Merge into trunk - -The files committed to the branch may also need changes merged into the -trunk. - -@subsubheading Revise the release schedule - -Post a revised release schedule to @email{gdb@@sources.redhat.com, GDB -Discussion List} with an updated announcement. The schedule can be -generated by running: - -@smallexample -$ ~/ss/schedule `date +%s` schedule -@end smallexample - -@noindent -The first parameter is approximate date/time in seconds (from the epoch) -of the most recent release. - -Also update the schedule @code{cronjob}. - -@section Post release - -Remove any @code{OBSOLETE} code. - -@node Testsuite - -@chapter Testsuite -@cindex test suite - -The testsuite is an important component of the @value{GDBN} package. -While it is always worthwhile to encourage user testing, in practice -this is rarely sufficient; users typically use only a small subset of -the available commands, and it has proven all too common for a change -to cause a significant regression that went unnoticed for some time. - -The @value{GDBN} testsuite uses the DejaGNU testing framework. -DejaGNU is built using @code{Tcl} and @code{expect}. The tests -themselves are calls to various @code{Tcl} procs; the framework runs all the -procs and summarizes the passes and fails. - -@section Using the Testsuite - -@cindex running the test suite -To run the testsuite, simply go to the @value{GDBN} object directory (or to the -testsuite's objdir) and type @code{make check}. This just sets up some -environment variables and invokes DejaGNU's @code{runtest} script. While -the testsuite is running, you'll get mentions of which test file is in use, -and a mention of any unexpected passes or fails. When the testsuite is -finished, you'll get a summary that looks like this: - -@smallexample - === gdb Summary === - -# of expected passes 6016 -# of unexpected failures 58 -# of unexpected successes 5 -# of expected failures 183 -# of unresolved testcases 3 -# of untested testcases 5 -@end smallexample - -The ideal test run consists of expected passes only; however, reality -conspires to keep us from this ideal. Unexpected failures indicate -real problems, whether in @value{GDBN} or in the testsuite. Expected -failures are still failures, but ones which have been decided are too -hard to deal with at the time; for instance, a test case might work -everywhere except on AIX, and there is no prospect of the AIX case -being fixed in the near future. Expected failures should not be added -lightly, since you may be masking serious bugs in @value{GDBN}. -Unexpected successes are expected fails that are passing for some -reason, while unresolved and untested cases often indicate some minor -catastrophe, such as the compiler being unable to deal with a test -program. - -When making any significant change to @value{GDBN}, you should run the -testsuite before and after the change, to confirm that there are no -regressions. Note that truly complete testing would require that you -run the testsuite with all supported configurations and a variety of -compilers; however this is more than really necessary. In many cases -testing with a single configuration is sufficient. Other useful -options are to test one big-endian (Sparc) and one little-endian (x86) -host, a cross config with a builtin simulator (powerpc-eabi, -mips-elf), or a 64-bit host (Alpha). - -If you add new functionality to @value{GDBN}, please consider adding -tests for it as well; this way future @value{GDBN} hackers can detect -and fix their changes that break the functionality you added. -Similarly, if you fix a bug that was not previously reported as a test -failure, please add a test case for it. Some cases are extremely -difficult to test, such as code that handles host OS failures or bugs -in particular versions of compilers, and it's OK not to try to write -tests for all of those. - -@section Testsuite Organization - -@cindex test suite organization -The testsuite is entirely contained in @file{gdb/testsuite}. While the -testsuite includes some makefiles and configury, these are very minimal, -and used for little besides cleaning up, since the tests themselves -handle the compilation of the programs that @value{GDBN} will run. The file -@file{testsuite/lib/gdb.exp} contains common utility procs useful for -all @value{GDBN} tests, while the directory @file{testsuite/config} contains -configuration-specific files, typically used for special-purpose -definitions of procs like @code{gdb_load} and @code{gdb_start}. - -The tests themselves are to be found in @file{testsuite/gdb.*} and -subdirectories of those. The names of the test files must always end -with @file{.exp}. DejaGNU collects the test files by wildcarding -in the test directories, so both subdirectories and individual files -get chosen and run in alphabetical order. - -The following table lists the main types of subdirectories and what they -are for. Since DejaGNU finds test files no matter where they are -located, and since each test file sets up its own compilation and -execution environment, this organization is simply for convenience and -intelligibility. - -@table @file -@item gdb.base -This is the base testsuite. The tests in it should apply to all -configurations of @value{GDBN} (but generic native-only tests may live here). -The test programs should be in the subset of C that is valid K&R, -ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance -for prototypes). - -@item gdb.@var{lang} -Language-specific tests for any language @var{lang} besides C. Examples are -@file{gdb.cp} and @file{gdb.java}. - -@item gdb.@var{platform} -Non-portable tests. The tests are specific to a specific configuration -(host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for -HP-UX. - -@item gdb.@var{compiler} -Tests specific to a particular compiler. As of this writing (June -1999), there aren't currently any groups of tests in this category that -couldn't just as sensibly be made platform-specific, but one could -imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC -extensions. - -@item gdb.@var{subsystem} -Tests that exercise a specific @value{GDBN} subsystem in more depth. For -instance, @file{gdb.disasm} exercises various disassemblers, while -@file{gdb.stabs} tests pathways through the stabs symbol reader. -@end table - -@section Writing Tests -@cindex writing tests - -In many areas, the @value{GDBN} tests are already quite comprehensive; you -should be able to copy existing tests to handle new cases. - -You should try to use @code{gdb_test} whenever possible, since it -includes cases to handle all the unexpected errors that might happen. -However, it doesn't cost anything to add new test procedures; for -instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that -calls @code{gdb_test} multiple times. - -Only use @code{send_gdb} and @code{gdb_expect} when absolutely -necessary, such as when @value{GDBN} has several valid responses to a command. - -The source language programs do @emph{not} need to be in a consistent -style. Since @value{GDBN} is used to debug programs written in many different -styles, it's worth having a mix of styles in the testsuite; for -instance, some @value{GDBN} bugs involving the display of source lines would -never manifest themselves if the programs used GNU coding style -uniformly. - -@node Hints - -@chapter Hints - -Check the @file{README} file, it often has useful information that does not -appear anywhere else in the directory. - -@menu -* Getting Started:: Getting started working on @value{GDBN} -* Debugging GDB:: Debugging @value{GDBN} with itself -@end menu - -@node Getting Started,,, Hints - -@section Getting Started - -@value{GDBN} is a large and complicated program, and if you first starting to -work on it, it can be hard to know where to start. Fortunately, if you -know how to go about it, there are ways to figure out what is going on. - -This manual, the @value{GDBN} Internals manual, has information which applies -generally to many parts of @value{GDBN}. - -Information about particular functions or data structures are located in -comments with those functions or data structures. If you run across a -function or a global variable which does not have a comment correctly -explaining what is does, this can be thought of as a bug in @value{GDBN}; feel -free to submit a bug report, with a suggested comment if you can figure -out what the comment should say. If you find a comment which is -actually wrong, be especially sure to report that. - -Comments explaining the function of macros defined in host, target, or -native dependent files can be in several places. Sometimes they are -repeated every place the macro is defined. Sometimes they are where the -macro is used. Sometimes there is a header file which supplies a -default definition of the macro, and the comment is there. This manual -also documents all the available macros. -@c (@pxref{Host Conditionals}, @pxref{Target -@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete -@c Conditionals}) - -Start with the header files. Once you have some idea of how -@value{GDBN}'s internal symbol tables are stored (see @file{symtab.h}, -@file{gdbtypes.h}), you will find it much easier to understand the -code which uses and creates those symbol tables. - -You may wish to process the information you are getting somehow, to -enhance your understanding of it. Summarize it, translate it to another -language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use -the code to predict what a test case would do and write the test case -and verify your prediction, etc. If you are reading code and your eyes -are starting to glaze over, this is a sign you need to use a more active -approach. - -Once you have a part of @value{GDBN} to start with, you can find more -specifically the part you are looking for by stepping through each -function with the @code{next} command. Do not use @code{step} or you -will quickly get distracted; when the function you are stepping through -calls another function try only to get a big-picture understanding -(perhaps using the comment at the beginning of the function being -called) of what it does. This way you can identify which of the -functions being called by the function you are stepping through is the -one which you are interested in. You may need to examine the data -structures generated at each stage, with reference to the comments in -the header files explaining what the data structures are supposed to -look like. - -Of course, this same technique can be used if you are just reading the -code, rather than actually stepping through it. The same general -principle applies---when the code you are looking at calls something -else, just try to understand generally what the code being called does, -rather than worrying about all its details. - -@cindex command implementation -A good place to start when tracking down some particular area is with -a command which invokes that feature. Suppose you want to know how -single-stepping works. As a @value{GDBN} user, you know that the -@code{step} command invokes single-stepping. The command is invoked -via command tables (see @file{command.h}); by convention the function -which actually performs the command is formed by taking the name of -the command and adding @samp{_command}, or in the case of an -@code{info} subcommand, @samp{_info}. For example, the @code{step} -command invokes the @code{step_command} function and the @code{info -display} command invokes @code{display_info}. When this convention is -not followed, you might have to use @code{grep} or @kbd{M-x -tags-search} in emacs, or run @value{GDBN} on itself and set a -breakpoint in @code{execute_command}. - -@cindex @code{bug-gdb} mailing list -If all of the above fail, it may be appropriate to ask for information -on @code{bug-gdb}. But @emph{never} post a generic question like ``I was -wondering if anyone could give me some tips about understanding -@value{GDBN}''---if we had some magic secret we would put it in this manual. -Suggestions for improving the manual are always welcome, of course. - -@node Debugging GDB,,,Hints - -@section Debugging @value{GDBN} with itself -@cindex debugging @value{GDBN} - -If @value{GDBN} is limping on your machine, this is the preferred way to get it -fully functional. Be warned that in some ancient Unix systems, like -Ultrix 4.2, a program can't be running in one process while it is being -debugged in another. Rather than typing the command @kbd{@w{./gdb -./gdb}}, which works on Suns and such, you can copy @file{gdb} to -@file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}. - -When you run @value{GDBN} in the @value{GDBN} source directory, it will read a -@file{.gdbinit} file that sets up some simple things to make debugging -gdb easier. The @code{info} command, when executed without a subcommand -in a @value{GDBN} being debugged by gdb, will pop you back up to the top level -gdb. See @file{.gdbinit} for details. - -If you use emacs, you will probably want to do a @code{make TAGS} after -you configure your distribution; this will put the machine dependent -routines for your local machine where they will be accessed first by -@kbd{M-.} - -Also, make sure that you've either compiled @value{GDBN} with your local cc, or -have run @code{fixincludes} if you are compiling with gcc. - -@section Submitting Patches - -@cindex submitting patches -Thanks for thinking of offering your changes back to the community of -@value{GDBN} users. In general we like to get well designed enhancements. -Thanks also for checking in advance about the best way to transfer the -changes. - -The @value{GDBN} maintainers will only install ``cleanly designed'' patches. -This manual summarizes what we believe to be clean design for @value{GDBN}. - -If the maintainers don't have time to put the patch in when it arrives, -or if there is any question about a patch, it goes into a large queue -with everyone else's patches and bug reports. - -@cindex legal papers for code contributions -The legal issue is that to incorporate substantial changes requires a -copyright assignment from you and/or your employer, granting ownership -of the changes to the Free Software Foundation. You can get the -standard documents for doing this by sending mail to @code{gnu@@gnu.org} -and asking for it. We recommend that people write in "All programs -owned by the Free Software Foundation" as "NAME OF PROGRAM", so that -changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC, -etc) can be -contributed with only one piece of legalese pushed through the -bureaucracy and filed with the FSF. We can't start merging changes until -this paperwork is received by the FSF (their rules, which we follow -since we maintain it for them). - -Technically, the easiest way to receive changes is to receive each -feature as a small context diff or unidiff, suitable for @code{patch}. -Each message sent to me should include the changes to C code and -header files for a single feature, plus @file{ChangeLog} entries for -each directory where files were modified, and diffs for any changes -needed to the manuals (@file{gdb/doc/gdb.texinfo} or -@file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a -single feature, they can be split down into multiple messages. - -In this way, if we read and like the feature, we can add it to the -sources with a single patch command, do some testing, and check it in. -If you leave out the @file{ChangeLog}, we have to write one. If you leave -out the doc, we have to puzzle out what needs documenting. Etc., etc. - -The reason to send each change in a separate message is that we will not -install some of the changes. They'll be returned to you with questions -or comments. If we're doing our job correctly, the message back to you -will say what you have to fix in order to make the change acceptable. -The reason to have separate messages for separate features is so that -the acceptable changes can be installed while one or more changes are -being reworked. If multiple features are sent in a single message, we -tend to not put in the effort to sort out the acceptable changes from -the unacceptable, so none of the features get installed until all are -acceptable. - -If this sounds painful or authoritarian, well, it is. But we get a lot -of bug reports and a lot of patches, and many of them don't get -installed because we don't have the time to finish the job that the bug -reporter or the contributor could have done. Patches that arrive -complete, working, and well designed, tend to get installed on the day -they arrive. The others go into a queue and get installed as time -permits, which, since the maintainers have many demands to meet, may not -be for quite some time. - -Please send patches directly to -@email{gdb-patches@@sources.redhat.com, the @value{GDBN} maintainers}. - -@section Obsolete Conditionals -@cindex obsolete code - -Fragments of old code in @value{GDBN} sometimes reference or set the following -configuration macros. They should not be used by new code, and old uses -should be removed as those parts of the debugger are otherwise touched. - -@table @code -@item STACK_END_ADDR -This macro used to define where the end of the stack appeared, for use -in interpreting core file formats that don't record this address in the -core file itself. This information is now configured in BFD, and @value{GDBN} -gets the info portably from there. The values in @value{GDBN}'s configuration -files should be moved into BFD configuration files (if needed there), -and deleted from all of @value{GDBN}'s config files. - -Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR -is so old that it has never been converted to use BFD. Now that's old! - -@end table - -@include observer.texi -@raisesections -@include fdl.texi -@lowersections - -@node Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/contrib/gdb/gdb/doc/gpl.texi b/contrib/gdb/gdb/doc/gpl.texi deleted file mode 100644 index be7ddc2fc086..000000000000 --- a/contrib/gdb/gdb/doc/gpl.texi +++ /dev/null @@ -1,409 +0,0 @@ -@ignore -@c Set file name and title for man page. -@setfilename gpl -@settitle GNU General Public License -@c man begin SEEALSO -gfdl(7), fsf-funding(7). -@c man end -@c man begin COPYRIGHT -Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@c man end -@end ignore -@node Copying -@c man begin DESCRIPTION -@appendix GNU GENERAL PUBLIC LICENSE -@center Version 2, June 1991 - -@display -Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@unnumberedsec Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software---to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - -@iftex -@unnumberedsec TERMS AND CONDITIONS FOR COPYING,@*DISTRIBUTION AND MODIFICATION -@end iftex -@ifnottex -@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end ifnottex - -@enumerate 0 -@item -This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The ``Program'', below, -refers to any such program or work, and a ``work based on the Program'' -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term ``modification''.) Each licensee is addressed as ``you''. - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - -@item -You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - -@item -You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - -@enumerate a -@item -You must cause the modified files to carry prominent notices -stating that you changed the files and the date of any change. - -@item -You must cause any work that you distribute or publish, that in -whole or in part contains or is derived from the Program or any -part thereof, to be licensed as a whole at no charge to all third -parties under the terms of this License. - -@item -If the modified program normally reads commands interactively -when run, you must cause it, when started running for such -interactive use in the most ordinary way, to print or display an -announcement including an appropriate copyright notice and a -notice that there is no warranty (or else, saying that you provide -a warranty) and that users may redistribute the program under -these conditions, and telling the user how to view a copy of this -License. (Exception: if the Program itself is interactive but -does not normally print such an announcement, your work based on -the Program is not required to print an announcement.) -@end enumerate - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - -@item -You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - -@enumerate a -@item -Accompany it with the complete corresponding machine-readable -source code, which must be distributed under the terms of Sections -1 and 2 above on a medium customarily used for software interchange; or, - -@item -Accompany it with a written offer, valid for at least three -years, to give any third party, for a charge no more than your -cost of physically performing source distribution, a complete -machine-readable copy of the corresponding source code, to be -distributed under the terms of Sections 1 and 2 above on a medium -customarily used for software interchange; or, - -@item -Accompany it with the information you received as to the offer -to distribute corresponding source code. (This alternative is -allowed only for noncommercial distribution and only if you -received the program in object code or executable form with such -an offer, in accord with Subsection b above.) -@end enumerate - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - -@item -You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - -@item -You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - -@item -Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - -@item -If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - -@item -If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - -@item -The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and ``any -later version'', you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - -@item -If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - -@iftex -@heading NO WARRANTY -@end iftex -@ifnottex -@center NO WARRANTY -@end ifnottex - -@item -BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - -@item -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. -@end enumerate - -@iftex -@heading END OF TERMS AND CONDITIONS -@end iftex -@ifnottex -@center END OF TERMS AND CONDITIONS -@end ifnottex - -@page -@unnumberedsec How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program; if not, write to the Free Software -Foundation, Inc., 59 Temple Place - Suite 330, -Boston, MA 02111-1307, USA. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - -@smallexample -Gnomovision version 69, Copyright (C) @var{year} @var{name of author} -Gnomovision comes with ABSOLUTELY NO WARRANTY; for details -type `show w'. -This is free software, and you are welcome to redistribute it -under certain conditions; type `show c' for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, the -commands you use may be called something other than @samp{show w} and -@samp{show c}; they could even be mouse-clicks or menu items---whatever -suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a ``copyright disclaimer'' for the program, if -necessary. Here is a sample; alter the names: - -@smallexample -Yoyodyne, Inc., hereby disclaims all copyright interest in the program -`Gnomovision' (which makes passes at compilers) written by James Hacker. - -@var{signature of Ty Coon}, 1 April 1989 -Ty Coon, President of Vice -@end smallexample - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. -@c man end diff --git a/contrib/gdb/gdb/doc/lpsrc.sed b/contrib/gdb/gdb/doc/lpsrc.sed deleted file mode 100644 index 1c7af4aaf48f..000000000000 --- a/contrib/gdb/gdb/doc/lpsrc.sed +++ /dev/null @@ -1,13 +0,0 @@ -/font defs: ---/,/end font defs ---/c\ -%-------------------- PostScript (long names) font defs: -----------------\ -\\font\\bbf=Times-Bold at 10pt\ -\\font\\vbbf=Times-Bold at 12pt\ -\\font\\smrm=Times-Roman at 6pt\ -\\font\\brm=Times-Roman at 10pt\ -\\font\\rm=Times-Roman at 8pt\ -\\font\\it=Times-Italic at 8pt\ -\\font\\tt=Courier at 8pt\ -% Used only for \copyright, replacing plain TeX macro.\ -\\font\\sym=Symbol at 7pt\ -\\def\\copyright{{\\sym\\char'323}}\ -%-------------------- end font defs --------------------------------- diff --git a/contrib/gdb/gdb/doc/observer.texi b/contrib/gdb/gdb/doc/observer.texi deleted file mode 100644 index de48a192a36f..000000000000 --- a/contrib/gdb/gdb/doc/observer.texi +++ /dev/null @@ -1,70 +0,0 @@ -@c -*-texinfo-*- -@node GDB Observers -@appendix @value{GDBN} Currently available observers - -@section Implementation rationale -@cindex observers implementation rationale - -An @dfn{observer} is an entity which is interested in being notified -when GDB reaches certain states, or certain events occur in GDB. -The entity being observed is called the @dfn{subject}. To receive -notifications, the observer attaches a callback to the subject. -One subject can have several observers. - -@file{observer.c} implements an internal generic low-level event -notification mechanism. This generic event notification mechanism is -then re-used to implement the exported high-level notification -management routines for all possible notifications. - -The current implementation of the generic observer provides support -for contextual data. This contextual data is given to the subject -when attaching the callback. In return, the subject will provide -this contextual data back to the observer as a parameter of the -callback. - -Note that the current support for the contextual data is only partial, -as it lacks a mechanism that would deallocate this data when the -callback is detached. This is not a problem so far, as this contextual -data is only used internally to hold a function pointer. Later on, if -a certain observer needs to provide support for user-level contextual -data, then the generic notification mechanism will need to be -enhanced to allow the observer to provide a routine to deallocate the -data when attaching the callback. - -The observer implementation is also currently not reentrant. -In particular, it is therefore not possible to call the attach -or detach routines during a notification. - -@section @code{normal_stop} Notifications -@cindex @code{normal_stop} observer -@cindex notification about inferior execution stop - -@value{GDBN} notifies all @code{normal_stop} observers when the -inferior execution has just stopped, the associated messages and -annotations have been printed, and the control is about to be returned -to the user. - -Note that the @code{normal_stop} notification is not emitted when -the execution stops due to a breakpoint, and this breakpoint has -a condition that is not met. If the breakpoint has any associated -commands list, the commands are executed after the notification -is emitted. - -The following interface is available to manage @code{normal_stop} -observers: - -@deftypefun extern struct observer *observer_attach_normal_stop (observer_normal_stop_ftype *@var{f}) -Attach the given @code{normal_stop} callback function @var{f} and -return the associated observer. -@end deftypefun - -@deftypefun extern void observer_detach_normal_stop (struct observer *@var{observer}); -Remove @var{observer} from the list of observers to be notified when -a @code{normal_stop} event occurs. -@end deftypefun - -@deftypefun extern void observer_notify_normal_stop (void); -Send a notification to all @code{normal_stop} observers. -@end deftypefun - - diff --git a/contrib/gdb/gdb/doc/psrc.sed b/contrib/gdb/gdb/doc/psrc.sed deleted file mode 100644 index 9bb557eae21e..000000000000 --- a/contrib/gdb/gdb/doc/psrc.sed +++ /dev/null @@ -1,13 +0,0 @@ -/font defs: ---/,/end font defs ---/c\ -%-------------------- PostScript (K Berry names) font defs: --------------\ -\\font\\bbf=ptmb at 10pt\ -\\font\\vbbf=ptmb at 12pt\ -\\font\\smrm=ptmr at 6pt\ -\\font\\brm=ptmr at 10pt\ -\\font\\rm=ptmr at 8pt\ -\\font\\it=ptmri at 8pt\ -\\font\\tt=pcrr at 8pt\ -% Used only for \copyright, replacing plain TeX macro.\ -\\font\\sym=psyr at 7pt\ -\\def\\copyright{{\\sym\\char'323}}\ -%-------------------- end font defs --------------------------------- diff --git a/contrib/gdb/gdb/doc/refcard.tex b/contrib/gdb/gdb/doc/refcard.tex deleted file mode 100644 index a8de9005d9d4..000000000000 --- a/contrib/gdb/gdb/doc/refcard.tex +++ /dev/null @@ -1,647 +0,0 @@ -%%%%%%%%%%%%%%%% gdb-refcard.tex %%%%%%%%%%%%%%%% - -%This file is TeX source for a reference card describing GDB, the GNU debugger. -%Copyright 1991, 1992, 1993, 1996, 1998, 1999, 2000 -%Free Software Foundation, Inc. -%Permission is granted to make and distribute verbatim copies of -%this reference provided the copyright notices and permission notices -%are preserved on all copies. -% -%TeX markup is a programming language; accordingly this file is source -%for a program to generate a reference. -% -%This program is free software; you can redistribute it and/or modify -%it under the terms of the GNU General Public License as published by -%the Free Software Foundation; either version 2, or (at your option) -%any later version. -% -%This program is distributed in the hope that it will be useful, but -%WITHOUT ANY WARRANTY; without even the implied warranty of -%MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -%General Public License for more details. -% -%You can find a copy of the GNU General Public License at the URL -%http://www.gnu.org/copyleft/gpl.html; or write to the Free Software -%Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -% -%You can contact the maintainer at: doc@cygnus.com -% -% Documentation Department -% Cygnus Solutions -% 1325 Chesapeake Terrace -% Sunnyvale, CA 94089 USA -% -% +1 800 CYGNUS-1 -% -% -% -% 22-AUG-1993 Andreas Vogel -% -% Modifications made in order to handle different papersizes correctly. -% You only have to set the total width and height of the paper, the -% horizontal and vertical margin space measured from *paper edge* -% and the interline and interspec spacing. -% In order to support a new papersize, you have to fiddle with the -% latter four dimensions. Just try out a few values. -% All other values will be computed at process time so it should be -% quite easy to support different paper sizes - only four values to -% guess :-) -% -% To find the configuration places, just search for the string -% "CONFIGURATION". -% -% Andreas Vogel (av@ssw.de) -% -% -% -% Uncomment the following `magnification' command if you want to print -% out in a larger font. Caution! You may need larger paper. You had -% best avoid using 3-column output if you try this. See the ``Three -% column format'' section below if you want to print in three column -% format. -% -%\magnification=\magstep 1 -% -% NOTE ON INTENTIONAL OMISSIONS: This reference card includes most GDB -% commands, but due to space constraints there are some things I chose -% to omit. In general, not all synonyms for commands are covered, nor -% all variations of a command. -% The GDB-under-Emacs section omits gdb-mode functions without default -% keybindings. GDB startup options are not described. -% set print sevenbit-strings, set symbol-reloading omitted. -% printsyms, printpsyms, omitted since they're for GDB maintenance primarily -% share omitted due to obsolescence -% set check range/type omitted at least til code is in GDB. -% -%-------------------- Three column format ----------------------- - -%%%% --- To disable three column format, comment out this entire section - -% Three-column format for landscape printing - -%-------- Papersize defs: - -\newdimen\totalwidth \newdimen\totalheight -\newdimen\hmargin \newdimen\vmargin -\newdimen\secskip \newdimen\lskip -\newdimen\barwidth \newdimen\barheight -\newdimen\intersecwidth - -%% -%% START CONFIGURATION - PAPERSIZE DEFINITIONS -%------- Papersize params: -%% US letter paper (8.5x11in) -%% -\totalwidth=11in % total width of paper -\totalheight=8.5in % total height of paper -\hmargin=.25in % horizontal margin width -\vmargin=.25in % vertical margin width -\secskip=1pc % space between refcard secs -\lskip=2pt % extra skip between \sec entries -%------- end papersize params -%% -%% change according to personal taste, not papersize dependent -%% -\barwidth=.1pt % width of the cropmark bar -\barheight=2pt % height of the cropmark bar -\intersecwidth=0.5em % width between \itmwid and \dfnwid -%% -%% END CONFIGURATION - PAPERSIZE DEFINITIONS -%% - -%% -%% values to be computed - nothing to configure -%% -\newdimen\fullhsize % width of area without margins -\newdimen\itmwid % width of item column -\newdimen\dfnwid % width of definition column -\newdimen\temp % only for temporary use - -%% -%% adjust the offsets so the margins are measured *from paper edge* -%% -\hoffset=-1in \advance \hoffset by \hmargin -\voffset=-1in \advance \voffset by \vmargin - -%% -%% fullhsize = totalwidth - (2 * hmargin) -%% -\fullhsize=\totalwidth -\temp=\hmargin \multiply \temp by 2 \advance \fullhsize by -\temp - -%% -%% hsize = (fullhsize - (4 * hmargin) - (2 * barwidth)) / 3 -%% -\hsize=\fullhsize -\temp=\hmargin \multiply \temp by 4 \advance \hsize by -\temp -\temp=\barwidth \multiply \temp by 2 \advance \hsize by -\temp -\divide \hsize by 3 - -%% -%% vsize = totalheight - (2 * vmargin) -%% -\vsize=\totalheight -\temp=\vmargin \multiply \temp by 2 \advance \vsize by -\temp - -%% -%% itmwid = (hsize - intersecwidth) * 1/3 -%% dfnwid = (hsize - intersecwidth) * 2/3 -%% -\temp=\hsize \advance \temp by -\intersecwidth \divide \temp by 3 -\itmwid=\temp -\dfnwid=\hsize \advance \dfnwid by -\itmwid - -%-------- end papersize defs - - -\def\fulline{\hbox to \fullhsize} -\let\lcr=L \newbox\leftcolumn\newbox\centercolumn -\output={\if L\lcr - \global\setbox\leftcolumn=\columnbox \global\let\lcr=C - \else - \if C\lcr - \global\setbox\centercolumn=\columnbox \global\let\lcr=R - \else \tripleformat \global\let\lcr=L - \fi - \fi -% \ifnum\outputpenalty>-20000 \else\dosupereject\fi - } - -%% -%% START CONFIGURATION - ALTERNATIVE FOLDING GUIDES -%% -%% For NO printed folding guide, -%% comment out other \def\vdecor's and uncomment: - -%\def\vdecor{\hskip\hmargin plus1fil\hskip\barwidth plus1fil\hskip\hmargin plus1fil} - -%% For SOLID LINE folding guide, -%% comment out other \def\vdecor's and uncomment: - -%\def\vdecor{\hskip\hmargin plus1fil \vrule width \barwidth \hskip\hmargin plus1fil} - -%% For SMALL MARKS NEAR TOP AND BOTTOM as folding guide, -%% comment out other \def\vdecor's and uncomment: - -\def\vdecor{\hskip\hmargin plus1fil -\vbox to \vsize{\hbox to \barwidth{\vrule height\barheight width\barwidth}\vfill -\hbox to \barwidth{\vrule height\barheight width\barwidth}}%THIS PERCENT SIGN IS ESSENTIAL -\hskip\hmargin plus1fil} - -%% -%% END CONFIGURATION - ALTERNATIVES FOR FOLDING GUIDES -%% - -\def\tripleformat{\shipout\vbox{\fulline{\box\leftcolumn\vdecor - \box\centercolumn\vdecor - \columnbox} - } - \advancepageno} -\def\columnbox{\leftline{\pagebody}} -\def\bye{\par\vfill - \supereject - \if R\lcr \null\vfill\eject\fi - \end} - -%-------------------- end three column format ----------------------- - -%-------------------- Computer Modern font defs: -------------------- -\font\bbf=cmbx10 -\font\vbbf=cmbx12 -\font\smrm=cmr6 -\font\brm=cmr10 -\font\rm=cmr7 -\font\it=cmti7 -\font\tt=cmtt8 -%-------------------- end font defs --------------------------------- - -% -\hyphenpenalty=5000\tolerance=2000\raggedright\raggedbottom -\normalbaselineskip=9pt\baselineskip=9pt -% -\parindent=0pt -\parskip=0pt -\footline={\vbox to0pt{\hss}} -% -\def\ctl#1{{\tt C-#1}} -\def\opt#1{{\brm[{\rm #1}]}} -\def\xtra#1{\noalign{\smallskip{\tt#1}}} -% -\long\def\sec#1;#2\endsec{\vskip \secskip -\halign{% -%COL 1 (of halign): -\vtop{\hsize=\itmwid\tt -##\par\vskip \lskip }\hfil -%COL 2 (of halign): -&\vtop{\hsize=\dfnwid\hangafter=1\hangindent=\intersecwidth -\rm ##\par\vskip \lskip}\cr -%Tail of \long\def fills in halign body with \sec args: -\noalign{{\bbf #1}\vskip \lskip} -#2 -} -} - -{\vbbf GDB QUICK REFERENCE}\hfil{\smrm GDB Version 5}\qquad - -\sec Essential Commands; -gdb {\it program} \opt{{\it core}}&debug {\it program} \opt{using -coredump {\it core}}\cr -b \opt{\it file\tt:}{\it function}&set breakpoint at {\it function} \opt{in \it file}\cr -run \opt{{\it arglist}}&start your program \opt{with {\it arglist}}\cr -bt& backtrace: display program stack\cr -p {\it expr}&display the value of an expression\cr -c &continue running your program\cr -n &next line, stepping over function calls\cr -s &next line, stepping into function calls\cr -\endsec - -\sec Starting GDB; -gdb&start GDB, with no debugging files\cr -gdb {\it program}&begin debugging {\it program}\cr -gdb {\it program core}&debug coredump {\it core} produced by {\it -program}\cr -gdb --help&describe command line options\cr -\endsec - -\sec Stopping GDB; -quit&exit GDB; also {\tt q} or {\tt EOF} (eg \ctl{d})\cr -INTERRUPT&(eg \ctl{c}) terminate current command, or send to running process\cr -\endsec - -\sec Getting Help; -help&list classes of commands\cr -help {\it class}&one-line descriptions for commands in {\it class}\cr -help {\it command}&describe {\it command}\cr -\endsec - -\sec Executing your Program; -run {\it arglist}&start your program with {\it arglist}\cr -run&start your program with current argument list\cr -run $\ldots$ <{\it inf} >{\it outf}&start your program with input, output -redirected\cr -\cr -kill&kill running program\cr -\cr -tty {\it dev}&use {\it dev} as stdin and stdout for next {\tt run}\cr -set args {\it arglist}&specify {\it arglist} for next -{\tt run}\cr -set args&specify empty argument list\cr -show args&display argument list\cr -\cr -show env&show all environment variables\cr -show env {\it var}&show value of environment variable {\it var}\cr -set env {\it var} {\it string}&set environment variable {\it var}\cr -unset env {\it var}&remove {\it var} from environment\cr -\endsec - -\sec Shell Commands; -cd {\it dir}&change working directory to {\it dir}\cr -pwd&Print working directory\cr -make $\ldots$&call ``{\tt make}''\cr -shell {\it cmd}&execute arbitrary shell command string\cr -\endsec - -\vfill -\line{\smrm \opt{ } surround optional arguments \hfill $\ldots$ show -one or more arguments} -\vskip\baselineskip -\centerline{\smrm \copyright 1998,2000 Free Software Foundation, Inc.\qquad Permissions on back} -\eject -\sec Breakpoints and Watchpoints; -break \opt{\it file\tt:}{\it line}\par -b \opt{\it file\tt:}{\it line}&set breakpoint at {\it line} number \opt{in \it file}\par -eg:\quad{\tt break main.c:37}\quad\cr -break \opt{\it file\tt:}{\it func}&set breakpoint at {\it -func} \opt{in \it file}\cr -break +{\it offset}\par -break -{\it offset}&set break at {\it offset} lines from current stop\cr -break *{\it addr}&set breakpoint at address {\it addr}\cr -break&set breakpoint at next instruction\cr -break $\ldots$ if {\it expr}&break conditionally on nonzero {\it expr}\cr -cond {\it n} \opt{\it expr}&new conditional expression on breakpoint -{\it n}; make unconditional if no {\it expr}\cr -tbreak $\ldots$&temporary break; disable when reached\cr -rbreak {\it regex}&break on all functions matching {\it regex}\cr -watch {\it expr}&set a watchpoint for expression {\it expr}\cr -catch {\it event}&break at {\it event}, which may be {\tt catch}, {\tt throw}, -{\tt exec}, {\tt fork}, {\tt vfork}, {\tt load}, or {\tt unload}.\cr -\cr -info break&show defined breakpoints\cr -info watch&show defined watchpoints\cr -\cr -clear&delete breakpoints at next instruction\cr -clear \opt{\it file\tt:}{\it fun}&delete breakpoints at entry to {\it fun}()\cr -clear \opt{\it file\tt:}{\it line}&delete breakpoints on source line \cr -delete \opt{{\it n}}&delete breakpoints -\opt{or breakpoint {\it n}}\cr -\cr -disable \opt{{\it n}}&disable breakpoints -\opt{or breakpoint {\it n}} -\cr -enable \opt{{\it n}}&enable breakpoints -\opt{or breakpoint {\it n}} -\cr -enable once \opt{{\it n}}&enable breakpoints \opt{or breakpoint {\it n}}; -disable again when reached -\cr -enable del \opt{{\it n}}&enable breakpoints \opt{or breakpoint {\it n}}; -delete when reached -\cr -\cr -ignore {\it n} {\it count}&ignore breakpoint {\it n}, {\it count} -times\cr -\cr -commands {\it n}\par -\qquad \opt{\tt silent}\par -\qquad {\it command-list}&execute GDB {\it command-list} every time breakpoint {\it n} is reached. \opt{{\tt silent} suppresses default -display}\cr -end&end of {\it command-list}\cr -\endsec - -\sec Program Stack; -backtrace \opt{\it n}\par -bt \opt{\it n}&print trace of all frames in stack; or of {\it n} -frames---innermost if {\it n}{\tt >0}, outermost if {\it n}{\tt <0}\cr -frame \opt{\it n}&select frame number {\it n} or frame at address {\it -n}; if no {\it n}, display current frame\cr -up {\it n}&select frame {\it n} frames up\cr -down {\it n}&select frame {\it n} frames down\cr -info frame \opt{\it addr}&describe selected frame, or frame at -{\it addr}\cr -info args&arguments of selected frame\cr -info locals&local variables of selected frame\cr -info reg \opt{\it rn}$\ldots$\par -info all-reg \opt{\it rn}®ister values \opt{for regs {\it rn\/}} in -selected frame; {\tt all-reg} includes floating point\cr -\endsec - -\vfill\eject -\sec Execution Control; -continue \opt{\it count}\par -c \opt{\it count}&continue running; if {\it count} specified, ignore -this breakpoint next {\it count} times\cr -\cr -step \opt{\it count}\par -s \opt{\it count}&execute until another line reached; repeat {\it count} times if -specified\cr -stepi \opt{\it count}\par -si \opt{\it count}&step by machine instructions rather than source -lines\cr -\cr -next \opt{\it count}\par -n \opt{\it count}&execute next line, including any function calls\cr -nexti \opt{\it count}\par -ni \opt{\it count}&next machine instruction rather than source -line\cr -\cr -until \opt{\it location}&run until next instruction (or {\it -location})\cr -finish&run until selected stack frame returns\cr -return \opt{\it expr}&pop selected stack frame without executing -\opt{setting return value}\cr -signal {\it num}&resume execution with signal {\it s} (none if {\tt 0})\cr -jump {\it line}\par -jump *{\it address}&resume execution at specified {\it line} number or -{\it address}\cr -set var={\it expr}&evaluate {\it expr} without displaying it; use for -altering program variables\cr -\endsec - -\sec Display; -print \opt{\tt/{\it f}\/} \opt{\it expr}\par -p \opt{\tt/{\it f}\/} \opt{\it expr}&show value of {\it expr} \opt{or -last value \tt \$} according to format {\it f}:\cr -\qquad x&hexadecimal\cr -\qquad d&signed decimal\cr -\qquad u&unsigned decimal\cr -\qquad o&octal\cr -\qquad t&binary\cr -\qquad a&address, absolute and relative\cr -\qquad c&character\cr -\qquad f&floating point\cr -call \opt{\tt /{\it f}\/} {\it expr}&like {\tt print} but does not display -{\tt void}\cr -x \opt{\tt/{\it Nuf}\/} {\it expr}&examine memory at address {\it expr}; -optional format spec follows slash\cr -\quad {\it N}&count of how many units to display\cr -\quad {\it u}&unit size; one of\cr -&{\tt\qquad b}\ individual bytes\cr -&{\tt\qquad h}\ halfwords (two bytes)\cr -&{\tt\qquad w}\ words (four bytes)\cr -&{\tt\qquad g}\ giant words (eight bytes)\cr -\quad {\it f}&printing format. Any {\tt print} format, or\cr -&{\tt\qquad s}\ null-terminated string\cr -&{\tt\qquad i}\ machine instructions\cr -disassem \opt{\it addr}&display memory as machine instructions\cr -\endsec - -\sec Automatic Display; -display \opt{\tt/\it f\/} {\it expr}&show value of {\it expr} each time -program stops \opt{according to format {\it f}\/}\cr -display&display all enabled expressions on list\cr -undisplay {\it n}&remove number(s) {\it n} from list of -automatically displayed expressions\cr -disable disp {\it n}&disable display for expression(s) number {\it -n}\cr -enable disp {\it n}&enable display for expression(s) number {\it -n}\cr -info display&numbered list of display expressions\cr -\endsec - -\vfill\eject - -\sec Expressions; -{\it expr}&an expression in C, C++, or Modula-2 (including function calls), or:\cr -{\it addr\/}@{\it len}&an array of {\it len} elements beginning at {\it -addr}\cr -{\it file}::{\it nm}&a variable or function {\it nm} defined in {\it -file}\cr -$\tt\{${\it type}$\tt\}${\it addr}&read memory at {\it addr} as specified -{\it type}\cr -\$&most recent displayed value\cr -\${\it n}&{\it n}th displayed value\cr -\$\$&displayed value previous to \$\cr -\$\${\it n}&{\it n}th displayed value back from \$\cr -\$\_&last address examined with {\tt x}\cr -\$\_\_&value at address \$\_\cr -\${\it var}&convenience variable; assign any value\cr -\cr -show values \opt{{\it n}}&show last 10 values \opt{or surrounding -\${\it n}}\cr -show conv&display all convenience variables\cr -\endsec - -\sec Symbol Table; -info address {\it s}&show where symbol {\it s} is stored\cr -info func \opt{\it regex}&show names, types of defined functions -(all, or matching {\it regex})\cr -info var \opt{\it regex}&show names, types of global variables (all, -or matching {\it regex})\cr -whatis \opt{\it expr}\par -ptype \opt{\it expr}&show data type of {\it expr} \opt{or \tt \$} -without evaluating; {\tt ptype} gives more detail\cr -ptype {\it type}&describe type, struct, union, or enum\cr -\endsec - -\sec GDB Scripts; -source {\it script}&read, execute GDB commands from file {\it -script}\cr -\cr -define {\it cmd}\par -\qquad {\it command-list}&create new GDB command {\it cmd}; -execute script defined by {\it command-list}\cr -end&end of {\it command-list}\cr -document {\it cmd}\par -\qquad {\it help-text}&create online documentation -for new GDB command {\it cmd}\cr -end&end of {\it help-text}\cr -\endsec - -\sec Signals; -handle {\it signal} {\it act}&specify GDB actions for {\it signal}:\cr -\quad print&announce signal\cr -\quad noprint&be silent for signal\cr -\quad stop&halt execution on signal\cr -\quad nostop&do not halt execution\cr -\quad pass&allow your program to handle signal\cr -\quad nopass&do not allow your program to see signal\cr -info signals&show table of signals, GDB action for each\cr -\endsec - -\sec Debugging Targets; -target {\it type} {\it param}&connect to target machine, process, or file\cr -help target&display available targets\cr -attach {\it param}&connect to another process\cr -detach&release target from GDB control\cr -\endsec - -\vfill\eject -\sec Controlling GDB; -set {\it param} {\it value}&set one of GDB's internal parameters\cr -show {\it param}&display current setting of parameter\cr -\xtra{\rm Parameters understood by {\tt set} and {\tt show}:} -\quad complaint {\it limit}&number of messages on unusual symbols\cr -\quad confirm {\it on/off}&enable or disable cautionary queries\cr -\quad editing {\it on/off}&control {\tt readline} command-line editing\cr -\quad height {\it lpp}&number of lines before pause in display\cr -\quad language {\it lang}&Language for GDB expressions ({\tt auto}, {\tt c} or -{\tt modula-2})\cr -\quad listsize {\it n}&number of lines shown by {\tt list}\cr -\quad prompt {\it str}&use {\it str} as GDB prompt\cr -\quad radix {\it base}&octal, decimal, or hex number representation\cr -\quad verbose {\it on/off}&control messages when loading -symbols\cr -\quad width {\it cpl}&number of characters before line folded\cr -\quad write {\it on/off}&Allow or forbid patching binary, core files -(when reopened with {\tt exec} or {\tt core}) -\cr -\quad history $\ldots$\par -\quad h $\ldots$&groups with the following options:\cr -\quad h exp {\it off/on}&disable/enable {\tt readline} history expansion\cr -\quad h file {\it filename}&file for recording GDB command history\cr -\quad h size {\it size}&number of commands kept in history list\cr -\quad h save {\it off/on}&control use of external file for -command history\cr -\cr -\quad print $\ldots$\par -\quad p $\ldots$&groups with the following options:\cr -\quad p address {\it on/off}&print memory addresses in stacks, -values\cr -\quad p array {\it off/on}&compact or attractive format for -arrays\cr -\quad p demangl {\it on/off}&source (demangled) or internal form for C++ -symbols\cr -\quad p asm-dem {\it on/off}&demangle C++ symbols in -machine-instruction output\cr -\quad p elements {\it limit}&number of array elements to display\cr -\quad p object {\it on/off}&print C++ derived types for objects\cr -\quad p pretty {\it off/on}&struct display: compact or indented\cr -\quad p union {\it on/off}&display of union members\cr -\quad p vtbl {\it off/on}&display of C++ virtual function -tables\cr -\cr -show commands&show last 10 commands\cr -show commands {\it n}&show 10 commands around number {\it n}\cr -show commands +&show next 10 commands\cr -\endsec - -\sec Working Files; -file \opt{\it file}&use {\it file} for both symbols and executable; -with no arg, discard both\cr -core \opt{\it file}&read {\it file} as coredump; or discard\cr -exec \opt{\it file}&use {\it file} as executable only; or discard\cr -symbol \opt{\it file}&use symbol table from {\it file}; or discard\cr -load {\it file}&dynamically link {\it file\/} and add its symbols\cr -add-sym {\it file} {\it addr}&read additional symbols from {\it file}, -dynamically loaded at {\it addr}\cr -info files&display working files and targets in use\cr -path {\it dirs}&add {\it dirs} to front of path searched for -executable and symbol files\cr -show path&display executable and symbol file path\cr -info share&list names of shared libraries currently loaded\cr -\endsec - -\vfill\eject -\sec Source Files; -dir {\it names}&add directory {\it names} to front of source path\cr -dir&clear source path\cr -show dir&show current source path\cr -\cr -list&show next ten lines of source\cr -list -&show previous ten lines\cr -list {\it lines}&display source surrounding {\it lines}, -specified as:\cr -\quad{\opt{\it file\tt:}\it num}&line number \opt{in named file}\cr -\quad{\opt{\it file\tt:}\it function}&beginning of function \opt{in -named file}\cr -\quad{\tt +\it off}&{\it off} lines after last printed\cr -\quad{\tt -\it off}&{\it off} lines previous to last printed\cr -\quad{\tt*\it address}&line containing {\it address}\cr -list {\it f},{\it l}&from line {\it f} to line {\it l}\cr -info line {\it num}&show starting, ending addresses of compiled code for -source line {\it num}\cr -info source&show name of current source file\cr -info sources&list all source files in use\cr -forw {\it regex}&search following source lines for {\it regex}\cr -rev {\it regex}&search preceding source lines for {\it regex}\cr -\endsec - -\sec GDB under GNU Emacs; -M-x gdb&run GDB under Emacs\cr -\ctl{h} m&describe GDB mode\cr -M-s&step one line ({\tt step})\cr -M-n&next line ({\tt next})\cr -M-i&step one instruction ({\tt stepi})\cr -\ctl{c} \ctl{f}&finish current stack frame ({\tt finish})\cr -M-c&continue ({\tt cont})\cr -M-u&up {\it arg} frames ({\tt up})\cr -M-d&down {\it arg} frames ({\tt down})\cr -\ctl{x} \&© number from point, insert at end\cr -\ctl{x} SPC&(in source file) set break at point\cr -\endsec - -\sec GDB License; -show copying&Display GNU General Public License\cr -show warranty&There is NO WARRANTY for GDB. Display full no-warranty -statement.\cr -\endsec - - -\vfill -{\smrm\parskip=6pt -Copyright \copyright 1991,'92,'93,'98,2000 Free Software Foundation, Inc. -Author: Roland H. Pesch - -The author assumes no responsibility for any errors on this card. - -This card may be freely distributed under the terms of the GNU -General Public License. - -Please contribute to development of this card by -annotating it. Improvements can be sent to bug-gdb@gnu.org. - -GDB itself is free software; you are welcome to distribute copies of -it under the terms of the GNU General Public License. There is -absolutely no warranty for GDB. -} -\end diff --git a/contrib/gdb/gdb/doc/stabs.texinfo b/contrib/gdb/gdb/doc/stabs.texinfo deleted file mode 100644 index d43ef372c30d..000000000000 --- a/contrib/gdb/gdb/doc/stabs.texinfo +++ /dev/null @@ -1,4046 +0,0 @@ -\input texinfo -@setfilename stabs.info - -@c @finalout - -@c This is a dir.info fragment to support semi-automated addition of -@c manuals to an info tree. -@dircategory Software development -@direntry -* Stabs: (stabs). The "stabs" debugging information format. -@end direntry - -@ifinfo -This document describes the stabs debugging symbol tables. - -Copyright 1992,1993,1994,1995,1997,1998,2000,2001 - Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, -and David MacKenzie. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end ifinfo - -@setchapternewpage odd -@settitle STABS -@titlepage -@title The ``stabs'' debug format -@author Julia Menapace, Jim Kingdon, David MacKenzie -@author Cygnus Support -@page -@tex -\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 2.130 $} % For use in headers, footers too -{\parskip=0pt -\hfill Cygnus Support\par -\hfill \manvers\par -\hfill \TeX{}info \texinfoversion\par -} -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 1992,1993,1994,1995,1997,1998,2000,2001 Free Software Foundation, Inc. -Contributed by Cygnus Support. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end titlepage - -@ifinfo -@node Top -@top The "stabs" representation of debugging information - -This document describes the stabs debugging format. - -@menu -* Overview:: Overview of stabs -* Program Structure:: Encoding of the structure of the program -* Constants:: Constants -* Variables:: -* Types:: Type definitions -* Symbol Tables:: Symbol information in symbol tables -* Cplusplus:: Stabs specific to C++ -* Stab Types:: Symbol types in a.out files -* Symbol Descriptors:: Table of symbol descriptors -* Type Descriptors:: Table of type descriptors -* Expanded Reference:: Reference information by stab type -* Questions:: Questions and anomalies -* Stab Sections:: In some object file formats, stabs are - in sections. -* Symbol Types Index:: Index of symbolic stab symbol type names. -* GNU Free Documentation License:: The license for this documentation -@end menu -@end ifinfo - -@c TeX can handle the contents at the start but makeinfo 3.12 can not -@iftex -@contents -@end iftex - -@node Overview -@chapter Overview of Stabs - -@dfn{Stabs} refers to a format for information that describes a program -to a debugger. This format was apparently invented by -Peter Kessler at -the University of California at Berkeley, for the @code{pdx} Pascal -debugger; the format has spread widely since then. - -This document is one of the few published sources of documentation on -stabs. It is believed to be comprehensive for stabs used by C. The -lists of symbol descriptors (@pxref{Symbol Descriptors}) and type -descriptors (@pxref{Type Descriptors}) are believed to be completely -comprehensive. Stabs for COBOL-specific features and for variant -records (used by Pascal and Modula-2) are poorly documented here. - -@c FIXME: Need to document all OS9000 stuff in GDB; see all references -@c to os9k_stabs in stabsread.c. - -Other sources of information on stabs are @cite{Dbx and Dbxtool -Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files -Reference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in -the a.out section, page 2-31. This document is believed to incorporate -the information from those two sources except where it explicitly directs -you to them for more information. - -@menu -* Flow:: Overview of debugging information flow -* Stabs Format:: Overview of stab format -* String Field:: The string field -* C Example:: A simple example in C source -* Assembly Code:: The simple example at the assembly level -@end menu - -@node Flow -@section Overview of Debugging Information Flow - -The GNU C compiler compiles C source in a @file{.c} file into assembly -language in a @file{.s} file, which the assembler translates into -a @file{.o} file, which the linker combines with other @file{.o} files and -libraries to produce an executable file. - -With the @samp{-g} option, GCC puts in the @file{.s} file additional -debugging information, which is slightly transformed by the assembler -and linker, and carried through into the final executable. This -debugging information describes features of the source file like line -numbers, the types and scopes of variables, and function names, -parameters, and scopes. - -For some object file formats, the debugging information is encapsulated -in assembler directives known collectively as @dfn{stab} (symbol table) -directives, which are interspersed with the generated code. Stabs are -the native format for debugging information in the a.out and XCOFF -object file formats. The GNU tools can also emit stabs in the COFF and -ECOFF object file formats. - -The assembler adds the information from stabs to the symbol information -it places by default in the symbol table and the string table of the -@file{.o} file it is building. The linker consolidates the @file{.o} -files into one executable file, with one symbol table and one string -table. Debuggers use the symbol and string tables in the executable as -a source of debugging information about the program. - -@node Stabs Format -@section Overview of Stab Format - -There are three overall formats for stab assembler directives, -differentiated by the first word of the stab. The name of the directive -describes which combination of four possible data fields follows. It is -either @code{.stabs} (string), @code{.stabn} (number), or @code{.stabd} -(dot). IBM's XCOFF assembler uses @code{.stabx} (and some other -directives such as @code{.file} and @code{.bi}) instead of -@code{.stabs}, @code{.stabn} or @code{.stabd}. - -The overall format of each class of stab is: - -@example -.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value} -.stabn @var{type},@var{other},@var{desc},@var{value} -.stabd @var{type},@var{other},@var{desc} -.stabx "@var{string}",@var{value},@var{type},@var{sdb-type} -@end example - -@c what is the correct term for "current file location"? My AIX -@c assembler manual calls it "the value of the current location counter". -For @code{.stabn} and @code{.stabd}, there is no @var{string} (the -@code{n_strx} field is zero; see @ref{Symbol Tables}). For -@code{.stabd}, the @var{value} field is implicit and has the value of -the current file location. For @code{.stabx}, the @var{sdb-type} field -is unused for stabs and can always be set to zero. The @var{other} -field is almost always unused and can be set to zero. - -The number in the @var{type} field gives some basic information about -which type of stab this is (or whether it @emph{is} a stab, as opposed -to an ordinary symbol). Each valid type number defines a different stab -type; further, the stab type defines the exact interpretation of, and -possible values for, any remaining @var{string}, @var{desc}, or -@var{value} fields present in the stab. @xref{Stab Types}, for a list -in numeric order of the valid @var{type} field values for stab directives. - -@node String Field -@section The String Field - -For most stabs the string field holds the meat of the -debugging information. The flexible nature of this field -is what makes stabs extensible. For some stab types the string field -contains only a name. For other stab types the contents can be a great -deal more complex. - -The overall format of the string field for most stab types is: - -@example -"@var{name}:@var{symbol-descriptor} @var{type-information}" -@end example - -@var{name} is the name of the symbol represented by the stab; it can -contain a pair of colons (@pxref{Nested Symbols}). @var{name} can be -omitted, which means the stab represents an unnamed object. For -example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does -not give the type a name. Omitting the @var{name} field is supported by -AIX dbx and GDB after about version 4.8, but not other debuggers. GCC -sometimes uses a single space as the name instead of omitting the name -altogether; apparently that is supported by most debuggers. - -The @var{symbol-descriptor} following the @samp{:} is an alphabetic -character that tells more specifically what kind of symbol the stab -represents. If the @var{symbol-descriptor} is omitted, but type -information follows, then the stab represents a local variable. For a -list of symbol descriptors, see @ref{Symbol Descriptors}. The @samp{c} -symbol descriptor is an exception in that it is not followed by type -information. @xref{Constants}. - -@var{type-information} is either a @var{type-number}, or -@samp{@var{type-number}=}. A @var{type-number} alone is a type -reference, referring directly to a type that has already been defined. - -The @samp{@var{type-number}=} form is a type definition, where the -number represents a new type which is about to be defined. The type -definition may refer to other types by number, and those type numbers -may be followed by @samp{=} and nested definitions. Also, the Lucid -compiler will repeat @samp{@var{type-number}=} more than once if it -wants to define several type numbers at once. - -In a type definition, if the character that follows the equals sign is -non-numeric then it is a @var{type-descriptor}, and tells what kind of -type is about to be defined. Any other values following the -@var{type-descriptor} vary, depending on the @var{type-descriptor}. -@xref{Type Descriptors}, for a list of @var{type-descriptor} values. If -a number follows the @samp{=} then the number is a @var{type-reference}. -For a full description of types, @ref{Types}. - -A @var{type-number} is often a single number. The GNU and Sun tools -additionally permit a @var{type-number} to be a pair -(@var{file-number},@var{filetype-number}) (the parentheses appear in the -string, and serve to distinguish the two cases). The @var{file-number} -is 0 for the base source file, 1 for the first included file, 2 for the -next, and so on. The @var{filetype-number} is a number starting with -1 which is incremented for each new type defined in the file. -(Separating the file number and the type number permits the -@code{N_BINCL} optimization to succeed more often; see @ref{Include -Files}). - -There is an AIX extension for type attributes. Following the @samp{=} -are any number of type attributes. Each one starts with @samp{@@} and -ends with @samp{;}. Debuggers, including AIX's dbx and GDB 4.10, skip -any type attributes they do not recognize. GDB 4.9 and other versions -of dbx may not do this. Because of a conflict with C@t{++} -(@pxref{Cplusplus}), new attributes should not be defined which begin -with a digit, @samp{(}, or @samp{-}; GDB may be unable to distinguish -those from the C@t{++} type descriptor @samp{@@}. The attributes are: - -@table @code -@item a@var{boundary} -@var{boundary} is an integer specifying the alignment. I assume it -applies to all variables of this type. - -@item p@var{integer} -Pointer class (for checking). Not sure what this means, or how -@var{integer} is interpreted. - -@item P -Indicate this is a packed type, meaning that structure fields or array -elements are placed more closely in memory, to save memory at the -expense of speed. - -@item s@var{size} -Size in bits of a variable of this type. This is fully supported by GDB -4.11 and later. - -@item S -Indicate that this type is a string instead of an array of characters, -or a bitstring instead of a set. It doesn't change the layout of the -data being represented, but does enable the debugger to know which type -it is. - -@item V -Indicate that this type is a vector instead of an array. The only -major difference between vectors and arrays is that vectors are -passed by value instead of by reference (vector coprocessor extension). - -@end table - -All of this can make the string field quite long. All versions of GDB, -and some versions of dbx, can handle arbitrarily long strings. But many -versions of dbx (or assemblers or linkers, I'm not sure which) -cretinously limit the strings to about 80 characters, so compilers which -must work with such systems need to split the @code{.stabs} directive -into several @code{.stabs} directives. Each stab duplicates every field -except the string field. The string field of every stab except the last -is marked as continued with a backslash at the end (in the assembly code -this may be written as a double backslash, depending on the assembler). -Removing the backslashes and concatenating the string fields of each -stab produces the original, long string. Just to be incompatible (or so -they don't have to worry about what the assembler does with -backslashes), AIX can use @samp{?} instead of backslash. - -@node C Example -@section A Simple Example in C Source - -To get the flavor of how stabs describe source information for a C -program, let's look at the simple program: - -@example -main() -@{ - printf("Hello world"); -@} -@end example - -When compiled with @samp{-g}, the program above yields the following -@file{.s} file. Line numbers have been added to make it easier to refer -to parts of the @file{.s} file in the description of the stabs that -follows. - -@node Assembly Code -@section The Simple Example at the Assembly Level - -This simple ``hello world'' example demonstrates several of the stab -types used to describe C language source files. - -@example -1 gcc2_compiled.: -2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 -3 .stabs "hello.c",100,0,0,Ltext0 -4 .text -5 Ltext0: -6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 -7 .stabs "char:t2=r2;0;127;",128,0,0,0 -8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 -9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 -10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 -11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 -12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 -13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 -14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 -15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 -16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 -17 .stabs "float:t12=r1;4;0;",128,0,0,0 -18 .stabs "double:t13=r1;8;0;",128,0,0,0 -19 .stabs "long double:t14=r1;8;0;",128,0,0,0 -20 .stabs "void:t15=15",128,0,0,0 -21 .align 4 -22 LC0: -23 .ascii "Hello, world!\12\0" -24 .align 4 -25 .global _main -26 .proc 1 -27 _main: -28 .stabn 68,0,4,LM1 -29 LM1: -30 !#PROLOGUE# 0 -31 save %sp,-136,%sp -32 !#PROLOGUE# 1 -33 call ___main,0 -34 nop -35 .stabn 68,0,5,LM2 -36 LM2: -37 LBB2: -38 sethi %hi(LC0),%o1 -39 or %o1,%lo(LC0),%o0 -40 call _printf,0 -41 nop -42 .stabn 68,0,6,LM3 -43 LM3: -44 LBE2: -45 .stabn 68,0,6,LM4 -46 LM4: -47 L1: -48 ret -49 restore -50 .stabs "main:F1",36,0,0,_main -51 .stabn 192,0,0,LBB2 -52 .stabn 224,0,0,LBE2 -@end example - -@node Program Structure -@chapter Encoding the Structure of the Program - -The elements of the program structure that stabs encode include the name -of the main function, the names of the source and include files, the -line numbers, procedure names and types, and the beginnings and ends of -blocks of code. - -@menu -* Main Program:: Indicate what the main program is -* Source Files:: The path and name of the source file -* Include Files:: Names of include files -* Line Numbers:: -* Procedures:: -* Nested Procedures:: -* Block Structure:: -* Alternate Entry Points:: Entering procedures except at the beginning. -@end menu - -@node Main Program -@section Main Program - -@findex N_MAIN -Most languages allow the main program to have any name. The -@code{N_MAIN} stab type tells the debugger the name that is used in this -program. Only the string field is significant; it is the name of -a function which is the main program. Most C compilers do not use this -stab (they expect the debugger to assume that the name is @code{main}), -but some C compilers emit an @code{N_MAIN} stab for the @code{main} -function. I'm not sure how XCOFF handles this. - -@node Source Files -@section Paths and Names of the Source Files - -@findex N_SO -Before any other stabs occur, there must be a stab specifying the source -file. This information is contained in a symbol of stab type -@code{N_SO}; the string field contains the name of the file. The -value of the symbol is the start address of the portion of the -text section corresponding to that file. - -With the Sun Solaris2 compiler, the desc field contains a -source-language code. -@c Do the debuggers use it? What are the codes? -djm - -Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also -include the directory in which the source was compiled, in a second -@code{N_SO} symbol preceding the one containing the file name. This -symbol can be distinguished by the fact that it ends in a slash. Code -from the @code{cfront} C@t{++} compiler can have additional @code{N_SO} symbols for -nonexistent source files after the @code{N_SO} for the real source file; -these are believed to contain no useful information. - -For example: - -@example -.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # @r{100 is N_SO} -.stabs "hello.c",100,0,0,Ltext0 - .text -Ltext0: -@end example - -@findex C_FILE -Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler -directive which assembles to a @code{C_FILE} symbol; explaining this in -detail is outside the scope of this document. - -@c FIXME: Exactly when should the empty N_SO be used? Why? -If it is useful to indicate the end of a source file, this is done with -an @code{N_SO} symbol with an empty string for the name. The value is -the address of the end of the text section for the file. For some -systems, there is no indication of the end of a source file, and you -just need to figure it ended when you see an @code{N_SO} for a different -source file, or a symbol ending in @code{.o} (which at least some -linkers insert to mark the start of a new @code{.o} file). - -@node Include Files -@section Names of Include Files - -There are several schemes for dealing with include files: the -traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the -XCOFF @code{C_BINCL} approach (which despite the similar name has little in -common with @code{N_BINCL}). - -@findex N_SOL -An @code{N_SOL} symbol specifies which include file subsequent symbols -refer to. The string field is the name of the file and the value is the -text address corresponding to the end of the previous include file and -the start of this one. To specify the main source file again, use an -@code{N_SOL} symbol with the name of the main source file. - -@findex N_BINCL -@findex N_EINCL -@findex N_EXCL -The @code{N_BINCL} approach works as follows. An @code{N_BINCL} symbol -specifies the start of an include file. In an object file, only the -string is significant; the linker puts data into some of the other -fields. The end of the include file is marked by an @code{N_EINCL} -symbol (which has no string field). In an object file, there is no -significant data in the @code{N_EINCL} symbol. @code{N_BINCL} and -@code{N_EINCL} can be nested. - -If the linker detects that two source files have identical stabs between -an @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case -for a header file), then it only puts out the stabs once. Each -additional occurrence is replaced by an @code{N_EXCL} symbol. I believe -the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only -ones which supports this feature. - -A linker which supports this feature will set the value of a -@code{N_BINCL} symbol to the total of all the characters in the stabs -strings included in the header file, omitting any file numbers. The -value of an @code{N_EXCL} symbol is the same as the value of the -@code{N_BINCL} symbol it replaces. This information can be used to -match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same -filename. The @code{N_EINCL} value, and the values of the other and -description fields for all three, appear to always be zero. - -@findex C_BINCL -@findex C_EINCL -For the start of an include file in XCOFF, use the @file{.bi} assembler -directive, which generates a @code{C_BINCL} symbol. A @file{.ei} -directive, which generates a @code{C_EINCL} symbol, denotes the end of -the include file. Both directives are followed by the name of the -source file in quotes, which becomes the string for the symbol. -The value of each symbol, produced automatically by the assembler -and linker, is the offset into the executable of the beginning -(inclusive, as you'd expect) or end (inclusive, as you would not expect) -of the portion of the COFF line table that corresponds to this include -file. @code{C_BINCL} and @code{C_EINCL} do not nest. - -@node Line Numbers -@section Line Numbers - -@findex N_SLINE -An @code{N_SLINE} symbol represents the start of a source line. The -desc field contains the line number and the value contains the code -address for the start of that source line. On most machines the address -is absolute; for stabs in sections (@pxref{Stab Sections}), it is -relative to the function in which the @code{N_SLINE} symbol occurs. - -@findex N_DSLINE -@findex N_BSLINE -GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line -numbers in the data or bss segments, respectively. They are identical -to @code{N_SLINE} but are relocated differently by the linker. They -were intended to be used to describe the source location of a variable -declaration, but I believe that GCC2 actually puts the line number in -the desc field of the stab for the variable itself. GDB has been -ignoring these symbols (unless they contain a string field) since -at least GDB 3.5. - -For single source lines that generate discontiguous code, such as flow -of control statements, there may be more than one line number entry for -the same source line. In this case there is a line number entry at the -start of each code range, each with the same line number. - -XCOFF does not use stabs for line numbers. Instead, it uses COFF line -numbers (which are outside the scope of this document). Standard COFF -line numbers cannot deal with include files, but in XCOFF this is fixed -with the @code{C_BINCL} method of marking include files (@pxref{Include -Files}). - -@node Procedures -@section Procedures - -@findex N_FUN, for functions -@findex N_FNAME -@findex N_STSYM, for functions (Sun acc) -@findex N_GSYM, for functions (Sun acc) -All of the following stabs normally use the @code{N_FUN} symbol type. -However, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and -@code{N_STSYM}, which means that the value of the stab for the function -is useless and the debugger must get the address of the function from -the non-stab symbols instead. On systems where non-stab symbols have -leading underscores, the stabs will lack underscores and the debugger -needs to know about the leading underscore to match up the stab and the -non-stab symbol. BSD Fortran is said to use @code{N_FNAME} with the -same restriction; the value of the symbol is not useful (I'm not sure it -really does use this, because GDB doesn't handle this and no one has -complained). - -@findex C_FUN -A function is represented by an @samp{F} symbol descriptor for a global -(extern) function, and @samp{f} for a static (local) function. For -a.out, the value of the symbol is the address of the start of the -function; it is already relocated. For stabs in ELF, the SunPRO -compiler version 2.0.1 and GCC put out an address which gets relocated -by the linker. In a future release SunPRO is planning to put out zero, -in which case the address can be found from the ELF (non-stab) symbol. -Because looking things up in the ELF symbols would probably be slow, I'm -not sure how to find which symbol of that name is the right one, and -this doesn't provide any way to deal with nested functions, it would -probably be better to make the value of the stab an address relative to -the start of the file, or just absolute. See @ref{ELF Linker -Relocation} for more information on linker relocation of stabs in ELF -files. For XCOFF, the stab uses the @code{C_FUN} storage class and the -value of the stab is meaningless; the address of the function can be -found from the csect symbol (XTY_LD/XMC_PR). - -The type information of the stab represents the return type of the -function; thus @samp{foo:f5} means that foo is a function returning type -5. There is no need to try to get the line number of the start of the -function from the stab for the function; it is in the next -@code{N_SLINE} symbol. - -@c FIXME: verify whether the "I suspect" below is true or not. -Some compilers (such as Sun's Solaris compiler) support an extension for -specifying the types of the arguments. I suspect this extension is not -used for old (non-prototyped) function definitions in C. If the -extension is in use, the type information of the stab for the function -is followed by type information for each argument, with each argument -preceded by @samp{;}. An argument type of 0 means that additional -arguments are being passed, whose types and number may vary (@samp{...} -in ANSI C). GDB has tolerated this extension (parsed the syntax, if not -necessarily used the information) since at least version 4.8; I don't -know whether all versions of dbx tolerate it. The argument types given -here are not redundant with the symbols for the formal parameters -(@pxref{Parameters}); they are the types of the arguments as they are -passed, before any conversions might take place. For example, if a C -function which is declared without a prototype takes a @code{float} -argument, the value is passed as a @code{double} but then converted to a -@code{float}. Debuggers need to use the types given in the arguments -when printing values, but when calling the function they need to use the -types given in the symbol defining the function. - -If the return type and types of arguments of a function which is defined -in another source file are specified (i.e., a function prototype in ANSI -C), traditionally compilers emit no stab; the only way for the debugger -to find the information is if the source file where the function is -defined was also compiled with debugging symbols. As an extension the -Solaris compiler uses symbol descriptor @samp{P} followed by the return -type of the function, followed by the arguments, each preceded by -@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}. -This use of symbol descriptor @samp{P} can be distinguished from its use -for register parameters (@pxref{Register Parameters}) by the fact that it has -symbol type @code{N_FUN}. - -The AIX documentation also defines symbol descriptor @samp{J} as an -internal function. I assume this means a function nested within another -function. It also says symbol descriptor @samp{m} is a module in -Modula-2 or extended Pascal. - -Procedures (functions which do not return values) are represented as -functions returning the @code{void} type in C. I don't see why this couldn't -be used for all languages (inventing a @code{void} type for this purpose if -necessary), but the AIX documentation defines @samp{I}, @samp{P}, and -@samp{Q} for internal, global, and static procedures, respectively. -These symbol descriptors are unusual in that they are not followed by -type information. - -The following example shows a stab for a function @code{main} which -returns type number @code{1}. The @code{_main} specified for the value -is a reference to an assembler label which is used to fill in the start -address of the function. - -@example -.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} -@end example - -The stab representing a procedure is located immediately following the -code of the procedure. This stab is in turn directly followed by a -group of other stabs describing elements of the procedure. These other -stabs describe the procedure's parameters, its block local variables, and -its block structure. - -If functions can appear in different sections, then the debugger may not -be able to find the end of a function. Recent versions of GCC will mark -the end of a function with an @code{N_FUN} symbol with an empty string -for the name. The value is the address of the end of the current -function. Without such a symbol, there is no indication of the address -of the end of a function, and you must assume that it ended at the -starting address of the next function or at the end of the text section -for the program. - -@node Nested Procedures -@section Nested Procedures - -For any of the symbol descriptors representing procedures, after the -symbol descriptor and the type information is optionally a scope -specifier. This consists of a comma, the name of the procedure, another -comma, and the name of the enclosing procedure. The first name is local -to the scope specified, and seems to be redundant with the name of the -symbol (before the @samp{:}). This feature is used by GCC, and -presumably Pascal, Modula-2, etc., compilers, for nested functions. - -If procedures are nested more than one level deep, only the immediately -containing scope is specified. For example, this code: - -@example -int -foo (int x) -@{ - int bar (int y) - @{ - int baz (int z) - @{ - return x + y + z; - @} - return baz (x + 2 * y); - @} - return x + bar (3 * x); -@} -@end example - -@noindent -produces the stabs: - -@example -.stabs "baz:f1,baz,bar",36,0,0,_baz.15 # @r{36 is N_FUN} -.stabs "bar:f1,bar,foo",36,0,0,_bar.12 -.stabs "foo:F1",36,0,0,_foo -@end example - -@node Block Structure -@section Block Structure - -@findex N_LBRAC -@findex N_RBRAC -@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of -@c function relative (as documented below). But GDB has never been able -@c to deal with that (it had wanted them to be relative to the file, but -@c I just fixed that (between GDB 4.12 and 4.13)), so it is function -@c relative just like ELF and SOM and the below documentation. -The program's block structure is represented by the @code{N_LBRAC} (left -brace) and the @code{N_RBRAC} (right brace) stab types. The variables -defined inside a block precede the @code{N_LBRAC} symbol for most -compilers, including GCC. Other compilers, such as the Convex, Acorn -RISC machine, and Sun @code{acc} compilers, put the variables after the -@code{N_LBRAC} symbol. The values of the @code{N_LBRAC} and -@code{N_RBRAC} symbols are the start and end addresses of the code of -the block, respectively. For most machines, they are relative to the -starting address of this source file. For the Gould NP1, they are -absolute. For stabs in sections (@pxref{Stab Sections}), they are -relative to the function in which they occur. - -The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block -scope of a procedure are located after the @code{N_FUN} stab that -represents the procedure itself. - -Sun documents the desc field of @code{N_LBRAC} and -@code{N_RBRAC} symbols as containing the nesting level of the block. -However, dbx seems to not care, and GCC always sets desc to -zero. - -@findex .bb -@findex .be -@findex C_BLOCK -For XCOFF, block scope is indicated with @code{C_BLOCK} symbols. If the -name of the symbol is @samp{.bb}, then it is the beginning of the block; -if the name of the symbol is @samp{.be}; it is the end of the block. - -@node Alternate Entry Points -@section Alternate Entry Points - -@findex N_ENTRY -@findex C_ENTRY -Some languages, like Fortran, have the ability to enter procedures at -some place other than the beginning. One can declare an alternate entry -point. The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN -compiler doesn't use it. According to AIX documentation, only the name -of a @code{C_ENTRY} stab is significant; the address of the alternate -entry point comes from the corresponding external symbol. A previous -revision of this document said that the value of an @code{N_ENTRY} stab -was the address of the alternate entry point, but I don't know the -source for that information. - -@node Constants -@chapter Constants - -The @samp{c} symbol descriptor indicates that this stab represents a -constant. This symbol descriptor is an exception to the general rule -that symbol descriptors are followed by type information. Instead, it -is followed by @samp{=} and one of the following: - -@table @code -@item b @var{value} -Boolean constant. @var{value} is a numeric value; I assume it is 0 for -false or 1 for true. - -@item c @var{value} -Character constant. @var{value} is the numeric value of the constant. - -@item e @var{type-information} , @var{value} -Constant whose value can be represented as integral. -@var{type-information} is the type of the constant, as it would appear -after a symbol descriptor (@pxref{String Field}). @var{value} is the -numeric value of the constant. GDB 4.9 does not actually get the right -value if @var{value} does not fit in a host @code{int}, but it does not -do anything violent, and future debuggers could be extended to accept -integers of any size (whether unsigned or not). This constant type is -usually documented as being only for enumeration constants, but GDB has -never imposed that restriction; I don't know about other debuggers. - -@item i @var{value} -Integer constant. @var{value} is the numeric value. The type is some -sort of generic integer type (for GDB, a host @code{int}); to specify -the type explicitly, use @samp{e} instead. - -@item r @var{value} -Real constant. @var{value} is the real value, which can be @samp{INF} -(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet -NaN (not-a-number), or @samp{SNAN} for a signalling NaN. If it is a -normal number the format is that accepted by the C library function -@code{atof}. - -@item s @var{string} -String constant. @var{string} is a string enclosed in either @samp{'} -(in which case @samp{'} characters within the string are represented as -@samp{\'} or @samp{"} (in which case @samp{"} characters within the -string are represented as @samp{\"}). - -@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern} -Set constant. @var{type-information} is the type of the constant, as it -would appear after a symbol descriptor (@pxref{String Field}). -@var{elements} is the number of elements in the set (does this means -how many bits of @var{pattern} are actually used, which would be -redundant with the type, or perhaps the number of bits set in -@var{pattern}? I don't get it), @var{bits} is the number of bits in the -constant (meaning it specifies the length of @var{pattern}, I think), -and @var{pattern} is a hexadecimal representation of the set. AIX -documentation refers to a limit of 32 bytes, but I see no reason why -this limit should exist. This form could probably be used for arbitrary -constants, not just sets; the only catch is that @var{pattern} should be -understood to be target, not host, byte order and format. -@end table - -The boolean, character, string, and set constants are not supported by -GDB 4.9, but it ignores them. GDB 4.8 and earlier gave an error -message and refused to read symbols from the file containing the -constants. - -The above information is followed by @samp{;}. - -@node Variables -@chapter Variables - -Different types of stabs describe the various ways that variables can be -allocated: on the stack, globally, in registers, in common blocks, -statically, or as arguments to a function. - -@menu -* Stack Variables:: Variables allocated on the stack. -* Global Variables:: Variables used by more than one source file. -* Register Variables:: Variables in registers. -* Common Blocks:: Variables statically allocated together. -* Statics:: Variables local to one source file. -* Based Variables:: Fortran pointer based variables. -* Parameters:: Variables for arguments to functions. -@end menu - -@node Stack Variables -@section Automatic Variables Allocated on the Stack - -If a variable's scope is local to a function and its lifetime is only as -long as that function executes (C calls such variables -@dfn{automatic}), it can be allocated in a register (@pxref{Register -Variables}) or on the stack. - -@findex N_LSYM, for stack variables -@findex C_LSYM -Each variable allocated on the stack has a stab with the symbol -descriptor omitted. Since type information should begin with a digit, -@samp{-}, or @samp{(}, only those characters precluded from being used -for symbol descriptors. However, the Acorn RISC machine (ARM) is said -to get this wrong: it puts out a mere type definition here, without the -preceding @samp{@var{type-number}=}. This is a bad idea; there is no -guarantee that type descriptors are distinct from symbol descriptors. -Stabs for stack variables use the @code{N_LSYM} stab type, or -@code{C_LSYM} for XCOFF. - -The value of the stab is the offset of the variable within the -local variables. On most machines this is an offset from the frame -pointer and is negative. The location of the stab specifies which block -it is defined in; see @ref{Block Structure}. - -For example, the following C code: - -@example -int -main () -@{ - int x; -@} -@end example - -produces the following stabs: - -@example -.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} -.stabs "x:1",128,0,0,-12 # @r{128 is N_LSYM} -.stabn 192,0,0,LBB2 # @r{192 is N_LBRAC} -.stabn 224,0,0,LBE2 # @r{224 is N_RBRAC} -@end example - -See @ref{Procedures} for more information on the @code{N_FUN} stab, and -@ref{Block Structure} for more information on the @code{N_LBRAC} and -@code{N_RBRAC} stabs. - -@node Global Variables -@section Global Variables - -@findex N_GSYM -@findex C_GSYM -@c FIXME: verify for sure that it really is C_GSYM on XCOFF -A variable whose scope is not specific to just one source file is -represented by the @samp{G} symbol descriptor. These stabs use the -@code{N_GSYM} stab type (C_GSYM for XCOFF). The type information for -the stab (@pxref{String Field}) gives the type of the variable. - -For example, the following source code: - -@example -char g_foo = 'c'; -@end example - -@noindent -yields the following assembly code: - -@example -.stabs "g_foo:G2",32,0,0,0 # @r{32 is N_GSYM} - .global _g_foo - .data -_g_foo: - .byte 99 -@end example - -The address of the variable represented by the @code{N_GSYM} is not -contained in the @code{N_GSYM} stab. The debugger gets this information -from the external symbol for the global variable. In the example above, -the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to -produce an external symbol. - -Some compilers, like GCC, output @code{N_GSYM} stabs only once, where -the variable is defined. Other compilers, like SunOS4 /bin/cc, output a -@code{N_GSYM} stab for each compilation unit which references the -variable. - -@node Register Variables -@section Register Variables - -@findex N_RSYM -@findex C_RSYM -@c According to an old version of this manual, AIX uses C_RPSYM instead -@c of C_RSYM. I am skeptical; this should be verified. -Register variables have their own stab type, @code{N_RSYM} -(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}. -The stab's value is the number of the register where the variable data -will be stored. -@c .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc) - -AIX defines a separate symbol descriptor @samp{d} for floating point -registers. This seems unnecessary; why not just just give floating -point registers different register numbers? I have not verified whether -the compiler actually uses @samp{d}. - -If the register is explicitly allocated to a global variable, but not -initialized, as in: - -@example -register int g_bar asm ("%g5"); -@end example - -@noindent -then the stab may be emitted at the end of the object file, with -the other bss symbols. - -@node Common Blocks -@section Common Blocks - -A common block is a statically allocated section of memory which can be -referred to by several source files. It may contain several variables. -I believe Fortran is the only language with this feature. - -@findex N_BCOMM -@findex N_ECOMM -@findex C_BCOMM -@findex C_ECOMM -A @code{N_BCOMM} stab begins a common block and an @code{N_ECOMM} stab -ends it. The only field that is significant in these two stabs is the -string, which names a normal (non-debugging) symbol that gives the -address of the common block. According to IBM documentation, only the -@code{N_BCOMM} has the name of the common block (even though their -compiler actually puts it both places). - -@findex N_ECOML -@findex C_ECOML -The stabs for the members of the common block are between the -@code{N_BCOMM} and the @code{N_ECOMM}; the value of each stab is the -offset within the common block of that variable. IBM uses the -@code{C_ECOML} stab type, and there is a corresponding @code{N_ECOML} -stab type, but Sun's Fortran compiler uses @code{N_GSYM} instead. The -variables within a common block use the @samp{V} symbol descriptor (I -believe this is true of all Fortran variables). Other stabs (at least -type declarations using @code{C_DECL}) can also be between the -@code{N_BCOMM} and the @code{N_ECOMM}. - -@node Statics -@section Static Variables - -Initialized static variables are represented by the @samp{S} and -@samp{V} symbol descriptors. @samp{S} means file scope static, and -@samp{V} means procedure scope static. One exception: in XCOFF, IBM's -xlc compiler always uses @samp{V}, and whether it is file scope or not -is distinguished by whether the stab is located within a function. - -@c This is probably not worth mentioning; it is only true on the sparc -@c for `double' variables which although declared const are actually in -@c the data segment (the text segment can't guarantee 8 byte alignment). -@c (although GCC -@c 2.4.5 has a bug in that it uses @code{N_FUN}, so neither dbx nor GDB can -@c find the variables) -@findex N_STSYM -@findex N_LCSYM -@findex N_FUN, for variables -@findex N_ROSYM -In a.out files, @code{N_STSYM} means the data section, @code{N_FUN} -means the text section, and @code{N_LCSYM} means the bss section. For -those systems with a read-only data section separate from the text -section (Solaris), @code{N_ROSYM} means the read-only data section. - -For example, the source lines: - -@example -static const int var_const = 5; -static int var_init = 2; -static int var_noinit; -@end example - -@noindent -yield the following stabs: - -@example -.stabs "var_const:S1",36,0,0,_var_const # @r{36 is N_FUN} -@dots{} -.stabs "var_init:S1",38,0,0,_var_init # @r{38 is N_STSYM} -@dots{} -.stabs "var_noinit:S1",40,0,0,_var_noinit # @r{40 is N_LCSYM} -@end example - -@findex C_STSYM -@findex C_BSTAT -@findex C_ESTAT -In XCOFF files, the stab type need not indicate the section; -@code{C_STSYM} can be used for all statics. Also, each static variable -is enclosed in a static block. A @code{C_BSTAT} (emitted with a -@samp{.bs} assembler directive) symbol begins the static block; its -value is the symbol number of the csect symbol whose value is the -address of the static block, its section is the section of the variables -in that static block, and its name is @samp{.bs}. A @code{C_ESTAT} -(emitted with a @samp{.es} assembler directive) symbol ends the static -block; its name is @samp{.es} and its value and section are ignored. - -In ECOFF files, the storage class is used to specify the section, so the -stab type need not indicate the section. - -In ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor -@samp{S} means that the address is absolute (the linker relocates it) -and symbol descriptor @samp{V} means that the address is relative to the -start of the relevant section for that compilation unit. SunPRO has -plans to have the linker stop relocating stabs; I suspect that their the -debugger gets the address from the corresponding ELF (not stab) symbol. -I'm not sure how to find which symbol of that name is the right one. -The clean way to do all this would be to have a the value of a symbol -descriptor @samp{S} symbol be an offset relative to the start of the -file, just like everything else, but that introduces obvious -compatibility problems. For more information on linker stab relocation, -@xref{ELF Linker Relocation}. - -@node Based Variables -@section Fortran Based Variables - -Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature -which allows allocating arrays with @code{malloc}, but which avoids -blurring the line between arrays and pointers the way that C does. In -stabs such a variable uses the @samp{b} symbol descriptor. - -For example, the Fortran declarations - -@example -real foo, foo10(10), foo10_5(10,5) -pointer (foop, foo) -pointer (foo10p, foo10) -pointer (foo105p, foo10_5) -@end example - -produce the stabs - -@example -foo:b6 -foo10:bar3;1;10;6 -foo10_5:bar3;1;5;ar3;1;10;6 -@end example - -In this example, @code{real} is type 6 and type 3 is an integral type -which is the type of the subscripts of the array (probably -@code{integer}). - -The @samp{b} symbol descriptor is like @samp{V} in that it denotes a -statically allocated symbol whose scope is local to a function; see -@xref{Statics}. The value of the symbol, instead of being the address -of the variable itself, is the address of a pointer to that variable. -So in the above example, the value of the @code{foo} stab is the address -of a pointer to a real, the value of the @code{foo10} stab is the -address of a pointer to a 10-element array of reals, and the value of -the @code{foo10_5} stab is the address of a pointer to a 5-element array -of 10-element arrays of reals. - -@node Parameters -@section Parameters - -Formal parameters to a function are represented by a stab (or sometimes -two; see below) for each parameter. The stabs are in the order in which -the debugger should print the parameters (i.e., the order in which the -parameters are declared in the source file). The exact form of the stab -depends on how the parameter is being passed. - -@findex N_PSYM -@findex C_PSYM -Parameters passed on the stack use the symbol descriptor @samp{p} and -the @code{N_PSYM} symbol type (or @code{C_PSYM} for XCOFF). The value -of the symbol is an offset used to locate the parameter on the stack; -its exact meaning is machine-dependent, but on most machines it is an -offset from the frame pointer. - -As a simple example, the code: - -@example -main (argc, argv) - int argc; - char **argv; -@end example - -produces the stabs: - -@example -.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} -.stabs "argc:p1",160,0,0,68 # @r{160 is N_PSYM} -.stabs "argv:p20=*21=*2",160,0,0,72 -@end example - -The type definition of @code{argv} is interesting because it contains -several type definitions. Type 21 is pointer to type 2 (char) and -@code{argv} (type 20) is pointer to type 21. - -@c FIXME: figure out what these mean and describe them coherently. -The following symbol descriptors are also said to go with @code{N_PSYM}. -The value of the symbol is said to be an offset from the argument -pointer (I'm not sure whether this is true or not). - -@example -pP (<<??>>) -pF Fortran function parameter -X (function result variable) -@end example - -@menu -* Register Parameters:: -* Local Variable Parameters:: -* Reference Parameters:: -* Conformant Arrays:: -@end menu - -@node Register Parameters -@subsection Passing Parameters in Registers - -If the parameter is passed in a register, then traditionally there are -two symbols for each argument: - -@example -.stabs "arg:p1" . . . ; N_PSYM -.stabs "arg:r1" . . . ; N_RSYM -@end example - -Debuggers use the second one to find the value, and the first one to -know that it is an argument. - -@findex C_RPSYM -@findex N_RSYM, for parameters -Because that approach is kind of ugly, some compilers use symbol -descriptor @samp{P} or @samp{R} to indicate an argument which is in a -register. Symbol type @code{C_RPSYM} is used in XCOFF and @code{N_RSYM} -is used otherwise. The symbol's value is the register number. @samp{P} -and @samp{R} mean the same thing; the difference is that @samp{P} is a -GNU invention and @samp{R} is an IBM (XCOFF) invention. As of version -4.9, GDB should handle either one. - -There is at least one case where GCC uses a @samp{p} and @samp{r} pair -rather than @samp{P}; this is where the argument is passed in the -argument list and then loaded into a register. - -According to the AIX documentation, symbol descriptor @samp{D} is for a -parameter passed in a floating point register. This seems -unnecessary---why not just use @samp{R} with a register number which -indicates that it's a floating point register? I haven't verified -whether the system actually does what the documentation indicates. - -@c FIXME: On the hppa this is for any type > 8 bytes, I think, and not -@c for small structures (investigate). -On the sparc and hppa, for a @samp{P} symbol whose type is a structure -or union, the register contains the address of the structure. On the -sparc, this is also true of a @samp{p} and @samp{r} pair (using Sun -@code{cc}) or a @samp{p} symbol. However, if a (small) structure is -really in a register, @samp{r} is used. And, to top it all off, on the -hppa it might be a structure which was passed on the stack and loaded -into a register and for which there is a @samp{p} and @samp{r} pair! I -believe that symbol descriptor @samp{i} is supposed to deal with this -case (it is said to mean "value parameter by reference, indirect -access"; I don't know the source for this information), but I don't know -details or what compilers or debuggers use it, if any (not GDB or GCC). -It is not clear to me whether this case needs to be dealt with -differently than parameters passed by reference (@pxref{Reference Parameters}). - -@node Local Variable Parameters -@subsection Storing Parameters as Local Variables - -There is a case similar to an argument in a register, which is an -argument that is actually stored as a local variable. Sometimes this -happens when the argument was passed in a register and then the compiler -stores it as a local variable. If possible, the compiler should claim -that it's in a register, but this isn't always done. - -If a parameter is passed as one type and converted to a smaller type by -the prologue (for example, the parameter is declared as a @code{float}, -but the calling conventions specify that it is passed as a -@code{double}), then GCC2 (sometimes) uses a pair of symbols. The first -symbol uses symbol descriptor @samp{p} and the type which is passed. -The second symbol has the type and location which the parameter actually -has after the prologue. For example, suppose the following C code -appears with no prototypes involved: - -@example -void -subr (f) - float f; -@{ -@end example - -if @code{f} is passed as a double at stack offset 8, and the prologue -converts it to a float in register number 0, then the stabs look like: - -@example -.stabs "f:p13",160,0,3,8 # @r{160 is @code{N_PSYM}, here 13 is @code{double}} -.stabs "f:r12",64,0,3,0 # @r{64 is @code{N_RSYM}, here 12 is @code{float}} -@end example - -In both stabs 3 is the line number where @code{f} is declared -(@pxref{Line Numbers}). - -@findex N_LSYM, for parameter -GCC, at least on the 960, has another solution to the same problem. It -uses a single @samp{p} symbol descriptor for an argument which is stored -as a local variable but uses @code{N_LSYM} instead of @code{N_PSYM}. In -this case, the value of the symbol is an offset relative to the local -variables for that function, not relative to the arguments; on some -machines those are the same thing, but not on all. - -@c This is mostly just background info; the part that logically belongs -@c here is the last sentence. -On the VAX or on other machines in which the calling convention includes -the number of words of arguments actually passed, the debugger (GDB at -least) uses the parameter symbols to keep track of whether it needs to -print nameless arguments in addition to the formal parameters which it -has printed because each one has a stab. For example, in - -@example -extern int fprintf (FILE *stream, char *format, @dots{}); -@dots{} -fprintf (stdout, "%d\n", x); -@end example - -there are stabs for @code{stream} and @code{format}. On most machines, -the debugger can only print those two arguments (because it has no way -of knowing that additional arguments were passed), but on the VAX or -other machines with a calling convention which indicates the number of -words of arguments, the debugger can print all three arguments. To do -so, the parameter symbol (symbol descriptor @samp{p}) (not necessarily -@samp{r} or symbol descriptor omitted symbols) needs to contain the -actual type as passed (for example, @code{double} not @code{float} if it -is passed as a double and converted to a float). - -@node Reference Parameters -@subsection Passing Parameters by Reference - -If the parameter is passed by reference (e.g., Pascal @code{VAR} -parameters), then the symbol descriptor is @samp{v} if it is in the -argument list, or @samp{a} if it in a register. Other than the fact -that these contain the address of the parameter rather than the -parameter itself, they are identical to @samp{p} and @samp{R}, -respectively. I believe @samp{a} is an AIX invention; @samp{v} is -supported by all stabs-using systems as far as I know. - -@node Conformant Arrays -@subsection Passing Conformant Array Parameters - -@c Is this paragraph correct? It is based on piecing together patchy -@c information and some guesswork -Conformant arrays are a feature of Modula-2, and perhaps other -languages, in which the size of an array parameter is not known to the -called function until run-time. Such parameters have two stabs: a -@samp{x} for the array itself, and a @samp{C}, which represents the size -of the array. The value of the @samp{x} stab is the offset in the -argument list where the address of the array is stored (it this right? -it is a guess); the value of the @samp{C} stab is the offset in the -argument list where the size of the array (in elements? in bytes?) is -stored. - -@node Types -@chapter Defining Types - -The examples so far have described types as references to previously -defined types, or defined in terms of subranges of or pointers to -previously defined types. This chapter describes the other type -descriptors that may follow the @samp{=} in a type definition. - -@menu -* Builtin Types:: Integers, floating point, void, etc. -* Miscellaneous Types:: Pointers, sets, files, etc. -* Cross-References:: Referring to a type not yet defined. -* Subranges:: A type with a specific range. -* Arrays:: An aggregate type of same-typed elements. -* Strings:: Like an array but also has a length. -* Enumerations:: Like an integer but the values have names. -* Structures:: An aggregate type of different-typed elements. -* Typedefs:: Giving a type a name. -* Unions:: Different types sharing storage. -* Function Types:: -@end menu - -@node Builtin Types -@section Builtin Types - -Certain types are built in (@code{int}, @code{short}, @code{void}, -@code{float}, etc.); the debugger recognizes these types and knows how -to handle them. Thus, don't be surprised if some of the following ways -of specifying builtin types do not specify everything that a debugger -would need to know about the type---in some cases they merely specify -enough information to distinguish the type from other types. - -The traditional way to define builtin types is convoluted, so new ways -have been invented to describe them. Sun's @code{acc} uses special -builtin type descriptors (@samp{b} and @samp{R}), and IBM uses negative -type numbers. GDB accepts all three ways, as of version 4.8; dbx just -accepts the traditional builtin types and perhaps one of the other two -formats. The following sections describe each of these formats. - -@menu -* Traditional Builtin Types:: Put on your seat belts and prepare for kludgery -* Builtin Type Descriptors:: Builtin types with special type descriptors -* Negative Type Numbers:: Builtin types using negative type numbers -@end menu - -@node Traditional Builtin Types -@subsection Traditional Builtin Types - -This is the traditional, convoluted method for defining builtin types. -There are several classes of such type definitions: integer, floating -point, and @code{void}. - -@menu -* Traditional Integer Types:: -* Traditional Other Types:: -@end menu - -@node Traditional Integer Types -@subsubsection Traditional Integer Types - -Often types are defined as subranges of themselves. If the bounding values -fit within an @code{int}, then they are given normally. For example: - -@example -.stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # @r{128 is N_LSYM} -.stabs "char:t2=r2;0;127;",128,0,0,0 -@end example - -Builtin types can also be described as subranges of @code{int}: - -@example -.stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 -@end example - -If the lower bound of a subrange is 0 and the upper bound is -1, -the type is an unsigned integral type whose bounds are too -big to describe in an @code{int}. Traditionally this is only used for -@code{unsigned int} and @code{unsigned long}: - -@example -.stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 -@end example - -For larger types, GCC 2.4.5 puts out bounds in octal, with one or more -leading zeroes. In this case a negative bound consists of a number -which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in -the number (except the sign bit), and a positive bound is one which is a -1 bit for each bit in the number (except possibly the sign bit). All -known versions of dbx and GDB version 4 accept this (at least in the -sense of not refusing to process the file), but GDB 3.5 refuses to read -the whole file containing such symbols. So GCC 2.3.3 did not output the -proper size for these types. As an example of octal bounds, the string -fields of the stabs for 64 bit integer types look like: - -@c .stabs directives, etc., omitted to make it fit on the page. -@example -long int:t3=r1;001000000000000000000000;000777777777777777777777; -long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; -@end example - -If the lower bound of a subrange is 0 and the upper bound is negative, -the type is an unsigned integral type whose size in bytes is the -absolute value of the upper bound. I believe this is a Convex -convention for @code{unsigned long long}. - -If the lower bound of a subrange is negative and the upper bound is 0, -the type is a signed integral type whose size in bytes is -the absolute value of the lower bound. I believe this is a Convex -convention for @code{long long}. To distinguish this from a legitimate -subrange, the type should be a subrange of itself. I'm not sure whether -this is the case for Convex. - -@node Traditional Other Types -@subsubsection Traditional Other Types - -If the upper bound of a subrange is 0 and the lower bound is positive, -the type is a floating point type, and the lower bound of the subrange -indicates the number of bytes in the type: - -@example -.stabs "float:t12=r1;4;0;",128,0,0,0 -.stabs "double:t13=r1;8;0;",128,0,0,0 -@end example - -However, GCC writes @code{long double} the same way it writes -@code{double}, so there is no way to distinguish. - -@example -.stabs "long double:t14=r1;8;0;",128,0,0,0 -@end example - -Complex types are defined the same way as floating-point types; there is -no way to distinguish a single-precision complex from a double-precision -floating-point type. - -The C @code{void} type is defined as itself: - -@example -.stabs "void:t15=15",128,0,0,0 -@end example - -I'm not sure how a boolean type is represented. - -@node Builtin Type Descriptors -@subsection Defining Builtin Types Using Builtin Type Descriptors - -This is the method used by Sun's @code{acc} for defining builtin types. -These are the type descriptors to define builtin types: - -@table @code -@c FIXME: clean up description of width and offset, once we figure out -@c what they mean -@item b @var{signed} @var{char-flag} @var{width} ; @var{offset} ; @var{nbits} ; -Define an integral type. @var{signed} is @samp{u} for unsigned or -@samp{s} for signed. @var{char-flag} is @samp{c} which indicates this -is a character type, or is omitted. I assume this is to distinguish an -integral type from a character type of the same size, for example it -might make sense to set it for the C type @code{wchar_t} so the debugger -can print such variables differently (Solaris does not do this). Sun -sets it on the C types @code{signed char} and @code{unsigned char} which -arguably is wrong. @var{width} and @var{offset} appear to be for small -objects stored in larger ones, for example a @code{short} in an -@code{int} register. @var{width} is normally the number of bytes in the -type. @var{offset} seems to always be zero. @var{nbits} is the number -of bits in the type. - -Note that type descriptor @samp{b} used for builtin types conflicts with -its use for Pascal space types (@pxref{Miscellaneous Types}); they can -be distinguished because the character following the type descriptor -will be a digit, @samp{(}, or @samp{-} for a Pascal space type, or -@samp{u} or @samp{s} for a builtin type. - -@item w -Documented by AIX to define a wide character type, but their compiler -actually uses negative type numbers (@pxref{Negative Type Numbers}). - -@item R @var{fp-type} ; @var{bytes} ; -Define a floating point type. @var{fp-type} has one of the following values: - -@table @code -@item 1 (NF_SINGLE) -IEEE 32-bit (single precision) floating point format. - -@item 2 (NF_DOUBLE) -IEEE 64-bit (double precision) floating point format. - -@item 3 (NF_COMPLEX) -@item 4 (NF_COMPLEX16) -@item 5 (NF_COMPLEX32) -@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying -@c to put that here got an overfull hbox. -These are for complex numbers. A comment in the GDB source describes -them as Fortran @code{complex}, @code{double complex}, and -@code{complex*16}, respectively, but what does that mean? (i.e., Single -precision? Double precision?). - -@item 6 (NF_LDOUBLE) -Long double. This should probably only be used for Sun format -@code{long double}, and new codes should be used for other floating -point formats (@code{NF_DOUBLE} can be used if a @code{long double} is -really just an IEEE double, of course). -@end table - -@var{bytes} is the number of bytes occupied by the type. This allows a -debugger to perform some operations with the type even if it doesn't -understand @var{fp-type}. - -@item g @var{type-information} ; @var{nbits} -Documented by AIX to define a floating type, but their compiler actually -uses negative type numbers (@pxref{Negative Type Numbers}). - -@item c @var{type-information} ; @var{nbits} -Documented by AIX to define a complex type, but their compiler actually -uses negative type numbers (@pxref{Negative Type Numbers}). -@end table - -The C @code{void} type is defined as a signed integral type 0 bits long: -@example -.stabs "void:t19=bs0;0;0",128,0,0,0 -@end example -The Solaris compiler seems to omit the trailing semicolon in this case. -Getting sloppy in this way is not a swift move because if a type is -embedded in a more complex expression it is necessary to be able to tell -where it ends. - -I'm not sure how a boolean type is represented. - -@node Negative Type Numbers -@subsection Negative Type Numbers - -This is the method used in XCOFF for defining builtin types. -Since the debugger knows about the builtin types anyway, the idea of -negative type numbers is simply to give a special type number which -indicates the builtin type. There is no stab defining these types. - -There are several subtle issues with negative type numbers. - -One is the size of the type. A builtin type (for example the C types -@code{int} or @code{long}) might have different sizes depending on -compiler options, the target architecture, the ABI, etc. This issue -doesn't come up for IBM tools since (so far) they just target the -RS/6000; the sizes indicated below for each size are what the IBM -RS/6000 tools use. To deal with differing sizes, either define separate -negative type numbers for each size (which works but requires changing -the debugger, and, unless you get both AIX dbx and GDB to accept the -change, introduces an incompatibility), or use a type attribute -(@pxref{String Field}) to define a new type with the appropriate size -(which merely requires a debugger which understands type attributes, -like AIX dbx or GDB). For example, - -@example -.stabs "boolean:t10=@@s8;-16",128,0,0,0 -@end example - -defines an 8-bit boolean type, and - -@example -.stabs "boolean:t10=@@s64;-16",128,0,0,0 -@end example - -defines a 64-bit boolean type. - -A similar issue is the format of the type. This comes up most often for -floating-point types, which could have various formats (particularly -extended doubles, which vary quite a bit even among IEEE systems). -Again, it is best to define a new negative type number for each -different format; changing the format based on the target system has -various problems. One such problem is that the Alpha has both VAX and -IEEE floating types. One can easily imagine one library using the VAX -types and another library in the same executable using the IEEE types. -Another example is that the interpretation of whether a boolean is true -or false can be based on the least significant bit, most significant -bit, whether it is zero, etc., and different compilers (or different -options to the same compiler) might provide different kinds of boolean. - -The last major issue is the names of the types. The name of a given -type depends @emph{only} on the negative type number given; these do not -vary depending on the language, the target system, or anything else. -One can always define separate type numbers---in the following list you -will see for example separate @code{int} and @code{integer*4} types -which are identical except for the name. But compatibility can be -maintained by not inventing new negative type numbers and instead just -defining a new type with a new name. For example: - -@example -.stabs "CARDINAL:t10=-8",128,0,0,0 -@end example - -Here is the list of negative type numbers. The phrase @dfn{integral -type} is used to mean twos-complement (I strongly suspect that all -machines which use stabs use twos-complement; most machines use -twos-complement these days). - -@table @code -@item -1 -@code{int}, 32 bit signed integral type. - -@item -2 -@code{char}, 8 bit type holding a character. Both GDB and dbx on AIX -treat this as signed. GCC uses this type whether @code{char} is signed -or not, which seems like a bad idea. The AIX compiler (@code{xlc}) seems to -avoid this type; it uses -5 instead for @code{char}. - -@item -3 -@code{short}, 16 bit signed integral type. - -@item -4 -@code{long}, 32 bit signed integral type. - -@item -5 -@code{unsigned char}, 8 bit unsigned integral type. - -@item -6 -@code{signed char}, 8 bit signed integral type. - -@item -7 -@code{unsigned short}, 16 bit unsigned integral type. - -@item -8 -@code{unsigned int}, 32 bit unsigned integral type. - -@item -9 -@code{unsigned}, 32 bit unsigned integral type. - -@item -10 -@code{unsigned long}, 32 bit unsigned integral type. - -@item -11 -@code{void}, type indicating the lack of a value. - -@item -12 -@code{float}, IEEE single precision. - -@item -13 -@code{double}, IEEE double precision. - -@item -14 -@code{long double}, IEEE double precision. The compiler claims the size -will increase in a future release, and for binary compatibility you have -to avoid using @code{long double}. I hope when they increase it they -use a new negative type number. - -@item -15 -@code{integer}. 32 bit signed integral type. - -@item -16 -@code{boolean}. 32 bit type. GDB and GCC assume that zero is false, -one is true, and other values have unspecified meaning. I hope this -agrees with how the IBM tools use the type. - -@item -17 -@code{short real}. IEEE single precision. - -@item -18 -@code{real}. IEEE double precision. - -@item -19 -@code{stringptr}. @xref{Strings}. - -@item -20 -@code{character}, 8 bit unsigned character type. - -@item -21 -@code{logical*1}, 8 bit type. This Fortran type has a split -personality in that it is used for boolean variables, but can also be -used for unsigned integers. 0 is false, 1 is true, and other values are -non-boolean. - -@item -22 -@code{logical*2}, 16 bit type. This Fortran type has a split -personality in that it is used for boolean variables, but can also be -used for unsigned integers. 0 is false, 1 is true, and other values are -non-boolean. - -@item -23 -@code{logical*4}, 32 bit type. This Fortran type has a split -personality in that it is used for boolean variables, but can also be -used for unsigned integers. 0 is false, 1 is true, and other values are -non-boolean. - -@item -24 -@code{logical}, 32 bit type. This Fortran type has a split -personality in that it is used for boolean variables, but can also be -used for unsigned integers. 0 is false, 1 is true, and other values are -non-boolean. - -@item -25 -@code{complex}. A complex type consisting of two IEEE single-precision -floating point values. - -@item -26 -@code{complex}. A complex type consisting of two IEEE double-precision -floating point values. - -@item -27 -@code{integer*1}, 8 bit signed integral type. - -@item -28 -@code{integer*2}, 16 bit signed integral type. - -@item -29 -@code{integer*4}, 32 bit signed integral type. - -@item -30 -@code{wchar}. Wide character, 16 bits wide, unsigned (what format? -Unicode?). - -@item -31 -@code{long long}, 64 bit signed integral type. - -@item -32 -@code{unsigned long long}, 64 bit unsigned integral type. - -@item -33 -@code{logical*8}, 64 bit unsigned integral type. - -@item -34 -@code{integer*8}, 64 bit signed integral type. -@end table - -@node Miscellaneous Types -@section Miscellaneous Types - -@table @code -@item b @var{type-information} ; @var{bytes} -Pascal space type. This is documented by IBM; what does it mean? - -This use of the @samp{b} type descriptor can be distinguished -from its use for builtin integral types (@pxref{Builtin Type -Descriptors}) because the character following the type descriptor is -always a digit, @samp{(}, or @samp{-}. - -@item B @var{type-information} -A volatile-qualified version of @var{type-information}. This is -a Sun extension. References and stores to a variable with a -volatile-qualified type must not be optimized or cached; they -must occur as the user specifies them. - -@item d @var{type-information} -File of type @var{type-information}. As far as I know this is only used -by Pascal. - -@item k @var{type-information} -A const-qualified version of @var{type-information}. This is a Sun -extension. A variable with a const-qualified type cannot be modified. - -@item M @var{type-information} ; @var{length} -Multiple instance type. The type seems to composed of @var{length} -repetitions of @var{type-information}, for example @code{character*3} is -represented by @samp{M-2;3}, where @samp{-2} is a reference to a -character type (@pxref{Negative Type Numbers}). I'm not sure how this -differs from an array. This appears to be a Fortran feature. -@var{length} is a bound, like those in range types; see @ref{Subranges}. - -@item S @var{type-information} -Pascal set type. @var{type-information} must be a small type such as an -enumeration or a subrange, and the type is a bitmask whose length is -specified by the number of elements in @var{type-information}. - -In CHILL, if it is a bitstring instead of a set, also use the @samp{S} -type attribute (@pxref{String Field}). - -@item * @var{type-information} -Pointer to @var{type-information}. -@end table - -@node Cross-References -@section Cross-References to Other Types - -A type can be used before it is defined; one common way to deal with -that situation is just to use a type reference to a type which has not -yet been defined. - -Another way is with the @samp{x} type descriptor, which is followed by -@samp{s} for a structure tag, @samp{u} for a union tag, or @samp{e} for -a enumerator tag, followed by the name of the tag, followed by @samp{:}. -If the name contains @samp{::} between a @samp{<} and @samp{>} pair (for -C@t{++} templates), such a @samp{::} does not end the name---only a single -@samp{:} ends the name; see @ref{Nested Symbols}. - -For example, the following C declarations: - -@example -struct foo; -struct foo *bar; -@end example - -@noindent -produce: - -@example -.stabs "bar:G16=*17=xsfoo:",32,0,0,0 -@end example - -Not all debuggers support the @samp{x} type descriptor, so on some -machines GCC does not use it. I believe that for the above example it -would just emit a reference to type 17 and never define it, but I -haven't verified that. - -Modula-2 imported types, at least on AIX, use the @samp{i} type -descriptor, which is followed by the name of the module from which the -type is imported, followed by @samp{:}, followed by the name of the -type. There is then optionally a comma followed by type information for -the type. This differs from merely naming the type (@pxref{Typedefs}) in -that it identifies the module; I don't understand whether the name of -the type given here is always just the same as the name we are giving -it, or whether this type descriptor is used with a nameless stab -(@pxref{String Field}), or what. The symbol ends with @samp{;}. - -@node Subranges -@section Subrange Types - -The @samp{r} type descriptor defines a type as a subrange of another -type. It is followed by type information for the type of which it is a -subrange, a semicolon, an integral lower bound, a semicolon, an -integral upper bound, and a semicolon. The AIX documentation does not -specify the trailing semicolon, in an effort to specify array indexes -more cleanly, but a subrange which is not an array index has always -included a trailing semicolon (@pxref{Arrays}). - -Instead of an integer, either bound can be one of the following: - -@table @code -@item A @var{offset} -The bound is passed by reference on the stack at offset @var{offset} -from the argument list. @xref{Parameters}, for more information on such -offsets. - -@item T @var{offset} -The bound is passed by value on the stack at offset @var{offset} from -the argument list. - -@item a @var{register-number} -The bound is passed by reference in register number -@var{register-number}. - -@item t @var{register-number} -The bound is passed by value in register number @var{register-number}. - -@item J -There is no bound. -@end table - -Subranges are also used for builtin types; see @ref{Traditional Builtin Types}. - -@node Arrays -@section Array Types - -Arrays use the @samp{a} type descriptor. Following the type descriptor -is the type of the index and the type of the array elements. If the -index type is a range type, it ends in a semicolon; otherwise -(for example, if it is a type reference), there does not -appear to be any way to tell where the types are separated. In an -effort to clean up this mess, IBM documents the two types as being -separated by a semicolon, and a range type as not ending in a semicolon -(but this is not right for range types which are not array indexes, -@pxref{Subranges}). I think probably the best solution is to specify -that a semicolon ends a range type, and that the index type and element -type of an array are separated by a semicolon, but that if the index -type is a range type, the extra semicolon can be omitted. GDB (at least -through version 4.9) doesn't support any kind of index type other than a -range anyway; I'm not sure about dbx. - -It is well established, and widely used, that the type of the index, -unlike most types found in the stabs, is merely a type definition, not -type information (@pxref{String Field}) (that is, it need not start with -@samp{@var{type-number}=} if it is defining a new type). According to a -comment in GDB, this is also true of the type of the array elements; it -gives @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two -dimensional array. According to AIX documentation, the element type -must be type information. GDB accepts either. - -The type of the index is often a range type, expressed as the type -descriptor @samp{r} and some parameters. It defines the size of the -array. In the example below, the range @samp{r1;0;2;} defines an index -type which is a subrange of type 1 (integer), with a lower bound of 0 -and an upper bound of 2. This defines the valid range of subscripts of -a three-element C array. - -For example, the definition: - -@example -char char_vec[3] = @{'a','b','c'@}; -@end example - -@noindent -produces the output: - -@example -.stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 - .global _char_vec - .align 4 -_char_vec: - .byte 97 - .byte 98 - .byte 99 -@end example - -If an array is @dfn{packed}, the elements are spaced more -closely than normal, saving memory at the expense of speed. For -example, an array of 3-byte objects might, if unpacked, have each -element aligned on a 4-byte boundary, but if packed, have no padding. -One way to specify that something is packed is with type attributes -(@pxref{String Field}). In the case of arrays, another is to use the -@samp{P} type descriptor instead of @samp{a}. Other than specifying a -packed array, @samp{P} is identical to @samp{a}. - -@c FIXME-what is it? A pointer? -An open array is represented by the @samp{A} type descriptor followed by -type information specifying the type of the array elements. - -@c FIXME: what is the format of this type? A pointer to a vector of pointers? -An N-dimensional dynamic array is represented by - -@example -D @var{dimensions} ; @var{type-information} -@end example - -@c Does dimensions really have this meaning? The AIX documentation -@c doesn't say. -@var{dimensions} is the number of dimensions; @var{type-information} -specifies the type of the array elements. - -@c FIXME: what is the format of this type? A pointer to some offsets in -@c another array? -A subarray of an N-dimensional array is represented by - -@example -E @var{dimensions} ; @var{type-information} -@end example - -@c Does dimensions really have this meaning? The AIX documentation -@c doesn't say. -@var{dimensions} is the number of dimensions; @var{type-information} -specifies the type of the array elements. - -@node Strings -@section Strings - -Some languages, like C or the original Pascal, do not have string types, -they just have related things like arrays of characters. But most -Pascals and various other languages have string types, which are -indicated as follows: - -@table @code -@item n @var{type-information} ; @var{bytes} -@var{bytes} is the maximum length. I'm not sure what -@var{type-information} is; I suspect that it means that this is a string -of @var{type-information} (thus allowing a string of integers, a string -of wide characters, etc., as well as a string of characters). Not sure -what the format of this type is. This is an AIX feature. - -@item z @var{type-information} ; @var{bytes} -Just like @samp{n} except that this is a gstring, not an ordinary -string. I don't know the difference. - -@item N -Pascal Stringptr. What is this? This is an AIX feature. -@end table - -Languages, such as CHILL which have a string type which is basically -just an array of characters use the @samp{S} type attribute -(@pxref{String Field}). - -@node Enumerations -@section Enumerations - -Enumerations are defined with the @samp{e} type descriptor. - -@c FIXME: Where does this information properly go? Perhaps it is -@c redundant with something we already explain. -The source line below declares an enumeration type at file scope. -The type definition is located after the @code{N_RBRAC} that marks the end of -the previous procedure's block scope, and before the @code{N_FUN} that marks -the beginning of the next procedure's block scope. Therefore it does not -describe a block local symbol, but a file local one. - -The source line: - -@example -enum e_places @{first,second=3,last@}; -@end example - -@noindent -generates the following stab: - -@example -.stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 -@end example - -The symbol descriptor (@samp{T}) says that the stab describes a -structure, enumeration, or union tag. The type descriptor @samp{e}, -following the @samp{22=} of the type definition narrows it down to an -enumeration type. Following the @samp{e} is a list of the elements of -the enumeration. The format is @samp{@var{name}:@var{value},}. The -list of elements ends with @samp{;}. The fact that @var{value} is -specified as an integer can cause problems if the value is large. GCC -2.5.2 tries to output it in octal in that case with a leading zero, -which is probably a good thing, although GDB 4.11 supports octal only in -cases where decimal is perfectly good. Negative decimal values are -supported by both GDB and dbx. - -There is no standard way to specify the size of an enumeration type; it -is determined by the architecture (normally all enumerations types are -32 bits). Type attributes can be used to specify an enumeration type of -another size for debuggers which support them; see @ref{String Field}. - -Enumeration types are unusual in that they define symbols for the -enumeration values (@code{first}, @code{second}, and @code{third} in the -above example), and even though these symbols are visible in the file as -a whole (rather than being in a more local namespace like structure -member names), they are defined in the type definition for the -enumeration type rather than each having their own symbol. In order to -be fast, GDB will only get symbols from such types (in its initial scan -of the stabs) if the type is the first thing defined after a @samp{T} or -@samp{t} symbol descriptor (the above example fulfills this -requirement). If the type does not have a name, the compiler should -emit it in a nameless stab (@pxref{String Field}); GCC does this. - -@node Structures -@section Structures - -The encoding of structures in stabs can be shown with an example. - -The following source code declares a structure tag and defines an -instance of the structure in global scope. Then a @code{typedef} equates the -structure tag with a new type. Separate stabs are generated for the -structure tag, the structure @code{typedef}, and the structure instance. The -stabs for the tag and the @code{typedef} are emitted when the definitions are -encountered. Since the structure elements are not initialized, the -stab and code for the structure variable itself is located at the end -of the program in the bss section. - -@example -struct s_tag @{ - int s_int; - float s_float; - char s_char_vec[8]; - struct s_tag* s_next; -@} g_an_s; - -typedef struct s_tag s_typedef; -@end example - -The structure tag has an @code{N_LSYM} stab type because, like the -enumeration, the symbol has file scope. Like the enumeration, the -symbol descriptor is @samp{T}, for enumeration, structure, or tag type. -The type descriptor @samp{s} following the @samp{16=} of the type -definition narrows the symbol type to structure. - -Following the @samp{s} type descriptor is the number of bytes the -structure occupies, followed by a description of each structure element. -The structure element descriptions are of the form -@samp{@var{name}:@var{type}, @var{bit offset from the start of the -struct}, @var{number of bits in the element}}. - -@c FIXME: phony line break. Can probably be fixed by using an example -@c with fewer fields. -@example -# @r{128 is N_LSYM} -.stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; - s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 -@end example - -In this example, the first two structure elements are previously defined -types. For these, the type following the @samp{@var{name}:} part of the -element description is a simple type reference. The other two structure -elements are new types. In this case there is a type definition -embedded after the @samp{@var{name}:}. The type definition for the -array element looks just like a type definition for a stand-alone array. -The @code{s_next} field is a pointer to the same kind of structure that -the field is an element of. So the definition of structure type 16 -contains a type definition for an element which is a pointer to type 16. - -If a field is a static member (this is a C@t{++} feature in which a single -variable appears to be a field of every structure of a given type) it -still starts out with the field name, a colon, and the type, but then -instead of a comma, bit position, comma, and bit size, there is a colon -followed by the name of the variable which each such field refers to. - -If the structure has methods (a C@t{++} feature), they follow the non-method -fields; see @ref{Cplusplus}. - -@node Typedefs -@section Giving a Type a Name - -@findex N_LSYM, for types -@findex C_DECL, for types -To give a type a name, use the @samp{t} symbol descriptor. The type -is specified by the type information (@pxref{String Field}) for the stab. -For example, - -@example -.stabs "s_typedef:t16",128,0,0,0 # @r{128 is N_LSYM} -@end example - -specifies that @code{s_typedef} refers to type number 16. Such stabs -have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF). (The Sun -documentation mentions using @code{N_GSYM} in some cases). - -If you are specifying the tag name for a structure, union, or -enumeration, use the @samp{T} symbol descriptor instead. I believe C is -the only language with this feature. - -If the type is an opaque type (I believe this is a Modula-2 feature), -AIX provides a type descriptor to specify it. The type descriptor is -@samp{o} and is followed by a name. I don't know what the name -means---is it always the same as the name of the type, or is this type -descriptor used with a nameless stab (@pxref{String Field})? There -optionally follows a comma followed by type information which defines -the type of this type. If omitted, a semicolon is used in place of the -comma and the type information, and the type is much like a generic -pointer type---it has a known size but little else about it is -specified. - -@node Unions -@section Unions - -@example -union u_tag @{ - int u_int; - float u_float; - char* u_char; -@} an_u; -@end example - -This code generates a stab for a union tag and a stab for a union -variable. Both use the @code{N_LSYM} stab type. If a union variable is -scoped locally to the procedure in which it is defined, its stab is -located immediately preceding the @code{N_LBRAC} for the procedure's block -start. - -The stab for the union tag, however, is located preceding the code for -the procedure in which it is defined. The stab type is @code{N_LSYM}. This -would seem to imply that the union type is file scope, like the struct -type @code{s_tag}. This is not true. The contents and position of the stab -for @code{u_type} do not convey any information about its procedure local -scope. - -@c FIXME: phony line break. Can probably be fixed by using an example -@c with fewer fields. -@smallexample -# @r{128 is N_LSYM} -.stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", - 128,0,0,0 -@end smallexample - -The symbol descriptor @samp{T}, following the @samp{name:} means that -the stab describes an enumeration, structure, or union tag. The type -descriptor @samp{u}, following the @samp{23=} of the type definition, -narrows it down to a union type definition. Following the @samp{u} is -the number of bytes in the union. After that is a list of union element -descriptions. Their format is @samp{@var{name}:@var{type}, @var{bit -offset into the union}, @var{number of bytes for the element};}. - -The stab for the union variable is: - -@example -.stabs "an_u:23",128,0,0,-20 # @r{128 is N_LSYM} -@end example - -@samp{-20} specifies where the variable is stored (@pxref{Stack -Variables}). - -@node Function Types -@section Function Types - -Various types can be defined for function variables. These types are -not used in defining functions (@pxref{Procedures}); they are used for -things like pointers to functions. - -The simple, traditional, type is type descriptor @samp{f} is followed by -type information for the return type of the function, followed by a -semicolon. - -This does not deal with functions for which the number and types of the -parameters are part of the type, as in Modula-2 or ANSI C. AIX provides -extensions to specify these, using the @samp{f}, @samp{F}, @samp{p}, and -@samp{R} type descriptors. - -First comes the type descriptor. If it is @samp{f} or @samp{F}, this -type involves a function rather than a procedure, and the type -information for the return type of the function follows, followed by a -comma. Then comes the number of parameters to the function and a -semicolon. Then, for each parameter, there is the name of the parameter -followed by a colon (this is only present for type descriptors @samp{R} -and @samp{F} which represent Pascal function or procedure parameters), -type information for the parameter, a comma, 0 if passed by reference or -1 if passed by value, and a semicolon. The type definition ends with a -semicolon. - -For example, this variable definition: - -@example -int (*g_pf)(); -@end example - -@noindent -generates the following code: - -@example -.stabs "g_pf:G24=*25=f1",32,0,0,0 - .common _g_pf,4,"bss" -@end example - -The variable defines a new type, 24, which is a pointer to another new -type, 25, which is a function returning @code{int}. - -@node Symbol Tables -@chapter Symbol Information in Symbol Tables - -This chapter describes the format of symbol table entries -and how stab assembler directives map to them. It also describes the -transformations that the assembler and linker make on data from stabs. - -@menu -* Symbol Table Format:: -* Transformations On Symbol Tables:: -@end menu - -@node Symbol Table Format -@section Symbol Table Format - -Each time the assembler encounters a stab directive, it puts -each field of the stab into a corresponding field in a symbol table -entry of its output file. If the stab contains a string field, the -symbol table entry for that stab points to a string table entry -containing the string data from the stab. Assembler labels become -relocatable addresses. Symbol table entries in a.out have the format: - -@c FIXME: should refer to external, not internal. -@example -struct internal_nlist @{ - unsigned long n_strx; /* index into string table of name */ - unsigned char n_type; /* type of symbol */ - unsigned char n_other; /* misc info (usually empty) */ - unsigned short n_desc; /* description field */ - bfd_vma n_value; /* value of symbol */ -@}; -@end example - -If the stab has a string, the @code{n_strx} field holds the offset in -bytes of the string within the string table. The string is terminated -by a NUL character. If the stab lacks a string (for example, it was -produced by a @code{.stabn} or @code{.stabd} directive), the -@code{n_strx} field is zero. - -Symbol table entries with @code{n_type} field values greater than 0x1f -originated as stabs generated by the compiler (with one random -exception). The other entries were placed in the symbol table of the -executable by the assembler or the linker. - -@node Transformations On Symbol Tables -@section Transformations on Symbol Tables - -The linker concatenates object files and does fixups of externally -defined symbols. - -You can see the transformations made on stab data by the assembler and -linker by examining the symbol table after each pass of the build. To -do this, use @samp{nm -ap}, which dumps the symbol table, including -debugging information, unsorted. For stab entries the columns are: -@var{value}, @var{other}, @var{desc}, @var{type}, @var{string}. For -assembler and linker symbols, the columns are: @var{value}, @var{type}, -@var{string}. - -The low 5 bits of the stab type tell the linker how to relocate the -value of the stab. Thus for stab types like @code{N_RSYM} and -@code{N_LSYM}, where the value is an offset or a register number, the -low 5 bits are @code{N_ABS}, which tells the linker not to relocate the -value. - -Where the value of a stab contains an assembly language label, -it is transformed by each build step. The assembler turns it into a -relocatable address and the linker turns it into an absolute address. - -@menu -* Transformations On Static Variables:: -* Transformations On Global Variables:: -* Stab Section Transformations:: For some object file formats, - things are a bit different. -@end menu - -@node Transformations On Static Variables -@subsection Transformations on Static Variables - -This source line defines a static variable at file scope: - -@example -static int s_g_repeat -@end example - -@noindent -The following stab describes the symbol: - -@example -.stabs "s_g_repeat:S1",38,0,0,_s_g_repeat -@end example - -@noindent -The assembler transforms the stab into this symbol table entry in the -@file{.o} file. The location is expressed as a data segment offset. - -@example -00000084 - 00 0000 STSYM s_g_repeat:S1 -@end example - -@noindent -In the symbol table entry from the executable, the linker has made the -relocatable address absolute. - -@example -0000e00c - 00 0000 STSYM s_g_repeat:S1 -@end example - -@node Transformations On Global Variables -@subsection Transformations on Global Variables - -Stabs for global variables do not contain location information. In -this case, the debugger finds location information in the assembler or -linker symbol table entry describing the variable. The source line: - -@example -char g_foo = 'c'; -@end example - -@noindent -generates the stab: - -@example -.stabs "g_foo:G2",32,0,0,0 -@end example - -The variable is represented by two symbol table entries in the object -file (see below). The first one originated as a stab. The second one -is an external symbol. The upper case @samp{D} signifies that the -@code{n_type} field of the symbol table contains 7, @code{N_DATA} with -local linkage. The stab's value is zero since the value is not used for -@code{N_GSYM} stabs. The value of the linker symbol is the relocatable -address corresponding to the variable. - -@example -00000000 - 00 0000 GSYM g_foo:G2 -00000080 D _g_foo -@end example - -@noindent -These entries as transformed by the linker. The linker symbol table -entry now holds an absolute address: - -@example -00000000 - 00 0000 GSYM g_foo:G2 -@dots{} -0000e008 D _g_foo -@end example - -@node Stab Section Transformations -@subsection Transformations of Stabs in separate sections - -For object file formats using stabs in separate sections (@pxref{Stab -Sections}), use @code{objdump --stabs} instead of @code{nm} to show the -stabs in an object or executable file. @code{objdump} is a GNU utility; -Sun does not provide any equivalent. - -The following example is for a stab whose value is an address is -relative to the compilation unit (@pxref{ELF Linker Relocation}). For -example, if the source line - -@example -static int ld = 5; -@end example - -appears within a function, then the assembly language output from the -compiler contains: - -@example -.Ddata.data: -@dots{} - .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # @r{0x26 is N_STSYM} -@dots{} -.L18: - .align 4 - .word 0x5 -@end example - -Because the value is formed by subtracting one symbol from another, the -value is absolute, not relocatable, and so the object file contains - -@example -Symnum n_type n_othr n_desc n_value n_strx String -31 STSYM 0 4 00000004 680 ld:V(0,3) -@end example - -without any relocations, and the executable file also contains - -@example -Symnum n_type n_othr n_desc n_value n_strx String -31 STSYM 0 4 00000004 680 ld:V(0,3) -@end example - -@node Cplusplus -@chapter GNU C@t{++} Stabs - -@menu -* Class Names:: C++ class names are both tags and typedefs. -* Nested Symbols:: C++ symbol names can be within other types. -* Basic Cplusplus Types:: -* Simple Classes:: -* Class Instance:: -* Methods:: Method definition -* Method Type Descriptor:: The @samp{#} type descriptor -* Member Type Descriptor:: The @samp{@@} type descriptor -* Protections:: -* Method Modifiers:: -* Virtual Methods:: -* Inheritance:: -* Virtual Base Classes:: -* Static Members:: -@end menu - -@node Class Names -@section C@t{++} Class Names - -In C@t{++}, a class name which is declared with @code{class}, @code{struct}, -or @code{union}, is not only a tag, as in C, but also a type name. Thus -there should be stabs with both @samp{t} and @samp{T} symbol descriptors -(@pxref{Typedefs}). - -To save space, there is a special abbreviation for this case. If the -@samp{T} symbol descriptor is followed by @samp{t}, then the stab -defines both a type name and a tag. - -For example, the C@t{++} code - -@example -struct foo @{int x;@}; -@end example - -can be represented as either - -@example -.stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # @r{128 is N_LSYM} -.stabs "foo:t19",128,0,0,0 -@end example - -or - -@example -.stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 -@end example - -@node Nested Symbols -@section Defining a Symbol Within Another Type - -In C@t{++}, a symbol (such as a type name) can be defined within another type. -@c FIXME: Needs example. - -In stabs, this is sometimes represented by making the name of a symbol -which contains @samp{::}. Such a pair of colons does not end the name -of the symbol, the way a single colon would (@pxref{String Field}). I'm -not sure how consistently used or well thought out this mechanism is. -So that a pair of colons in this position always has this meaning, -@samp{:} cannot be used as a symbol descriptor. - -For example, if the string for a stab is @samp{foo::bar::baz:t5=*6}, -then @code{foo::bar::baz} is the name of the symbol, @samp{t} is the -symbol descriptor, and @samp{5=*6} is the type information. - -@node Basic Cplusplus Types -@section Basic Types For C@t{++} - -<< the examples that follow are based on a01.C >> - - -C@t{++} adds two more builtin types to the set defined for C. These are -the unknown type and the vtable record type. The unknown type, type -16, is defined in terms of itself like the void type. - -The vtable record type, type 17, is defined as a structure type and -then as a structure tag. The structure has four fields: delta, index, -pfn, and delta2. pfn is the function pointer. - -<< In boilerplate $vtbl_ptr_type, what are the fields delta, -index, and delta2 used for? >> - -This basic type is present in all C@t{++} programs even if there are no -virtual methods defined. - -@display -.stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) - elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); - elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); - elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), - bit_offset(32),field_bits(32); - elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" - N_LSYM, NIL, NIL -@end display - -@smallexample -.stabs "$vtbl_ptr_type:t17=s8 - delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" - ,128,0,0,0 -@end smallexample - -@display -.stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL -@end display - -@example -.stabs "$vtbl_ptr_type:T17",128,0,0,0 -@end example - -@node Simple Classes -@section Simple Class Definition - -The stabs describing C@t{++} language features are an extension of the -stabs describing C. Stabs representing C@t{++} class types elaborate -extensively on the stab format used to describe structure types in C. -Stabs representing class type variables look just like stabs -representing C language variables. - -Consider the following very simple class definition. - -@example -class baseA @{ -public: - int Adat; - int Ameth(int in, char other); -@}; -@end example - -The class @code{baseA} is represented by two stabs. The first stab describes -the class as a structure type. The second stab describes a structure -tag of the class type. Both stabs are of stab type @code{N_LSYM}. Since the -stab is not located between an @code{N_FUN} and an @code{N_LBRAC} stab this indicates -that the class is defined at file scope. If it were, then the @code{N_LSYM} -would signify a local variable. - -A stab describing a C@t{++} class type is similar in format to a stab -describing a C struct, with each class member shown as a field in the -structure. The part of the struct format describing fields is -expanded to include extra information relevant to C@t{++} class members. -In addition, if the class has multiple base classes or virtual -functions the struct format outside of the field parts is also -augmented. - -In this simple example the field part of the C@t{++} class stab -representing member data looks just like the field part of a C struct -stab. The section on protections describes how its format is -sometimes extended for member data. - -The field part of a C@t{++} class stab representing a member function -differs substantially from the field part of a C struct stab. It -still begins with @samp{name:} but then goes on to define a new type number -for the member function, describe its return type, its argument types, -its protection level, any qualifiers applied to the method definition, -and whether the method is virtual or not. If the method is virtual -then the method description goes on to give the vtable index of the -method, and the type number of the first base class defining the -method. - -When the field name is a method name it is followed by two colons rather -than one. This is followed by a new type definition for the method. -This is a number followed by an equal sign and the type of the method. -Normally this will be a type declared using the @samp{#} type -descriptor; see @ref{Method Type Descriptor}; static member functions -are declared using the @samp{f} type descriptor instead; see -@ref{Function Types}. - -The format of an overloaded operator method name differs from that of -other methods. It is @samp{op$::@var{operator-name}.} where -@var{operator-name} is the operator name such as @samp{+} or @samp{+=}. -The name ends with a period, and any characters except the period can -occur in the @var{operator-name} string. - -The next part of the method description represents the arguments to the -method, preceded by a colon and ending with a semi-colon. The types of -the arguments are expressed in the same way argument types are expressed -in C@t{++} name mangling. In this example an @code{int} and a @code{char} -map to @samp{ic}. - -This is followed by a number, a letter, and an asterisk or period, -followed by another semicolon. The number indicates the protections -that apply to the member function. Here the 2 means public. The -letter encodes any qualifier applied to the method definition. In -this case, @samp{A} means that it is a normal function definition. The dot -shows that the method is not virtual. The sections that follow -elaborate further on these fields and describe the additional -information present for virtual methods. - - -@display -.stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) - field_name(Adat):type(int),bit_offset(0),field_bits(32); - - method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); - :arg_types(int char); - protection(public)qualifier(normal)virtual(no);;" - N_LSYM,NIL,NIL,NIL -@end display - -@smallexample -.stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 - -.stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL - -.stabs "baseA:T20",128,0,0,0 -@end smallexample - -@node Class Instance -@section Class Instance - -As shown above, describing even a simple C@t{++} class definition is -accomplished by massively extending the stab format used in C to -describe structure types. However, once the class is defined, C stabs -with no modifications can be used to describe class instances. The -following source: - -@example -main () @{ - baseA AbaseA; -@} -@end example - -@noindent -yields the following stab describing the class instance. It looks no -different from a standard C stab describing a local variable. - -@display -.stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset -@end display - -@example -.stabs "AbaseA:20",128,0,0,-20 -@end example - -@node Methods -@section Method Definition - -The class definition shown above declares Ameth. The C@t{++} source below -defines Ameth: - -@example -int -baseA::Ameth(int in, char other) -@{ - return in; -@}; -@end example - - -This method definition yields three stabs following the code of the -method. One stab describes the method itself and following two describe -its parameters. Although there is only one formal argument all methods -have an implicit argument which is the @code{this} pointer. The @code{this} -pointer is a pointer to the object on which the method was called. Note -that the method name is mangled to encode the class name and argument -types. Name mangling is described in the @sc{arm} (@cite{The Annotated -C++ Reference Manual}, by Ellis and Stroustrup, @sc{isbn} -0-201-51459-1); @file{gpcompare.texi} in Cygnus GCC distributions -describes the differences between GNU mangling and @sc{arm} -mangling. -@c FIXME: Use @xref, especially if this is generally installed in the -@c info tree. -@c FIXME: This information should be in a net release, either of GCC or -@c GDB. But gpcompare.texi doesn't seem to be in the FSF GCC. - -@example -.stabs "name:symbol_descriptor(global function)return_type(int)", - N_FUN, NIL, NIL, code_addr_of_method_start - -.stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic -@end example - -Here is the stab for the @code{this} pointer implicit argument. The -name of the @code{this} pointer is always @code{this}. Type 19, the -@code{this} pointer is defined as a pointer to type 20, @code{baseA}, -but a stab defining @code{baseA} has not yet been emitted. Since the -compiler knows it will be emitted shortly, here it just outputs a cross -reference to the undefined symbol, by prefixing the symbol name with -@samp{xs}. - -@example -.stabs "name:sym_desc(register param)type_def(19)= - type_desc(ptr to)type_ref(baseA)= - type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number - -.stabs "this:P19=*20=xsbaseA:",64,0,0,8 -@end example - -The stab for the explicit integer argument looks just like a parameter -to a C function. The last field of the stab is the offset from the -argument pointer, which in most systems is the same as the frame -pointer. - -@example -.stabs "name:sym_desc(value parameter)type_ref(int)", - N_PSYM,NIL,NIL,offset_from_arg_ptr - -.stabs "in:p1",160,0,0,72 -@end example - -<< The examples that follow are based on A1.C >> - -@node Method Type Descriptor -@section The @samp{#} Type Descriptor - -This is used to describe a class method. This is a function which takes -an extra argument as its first argument, for the @code{this} pointer. - -If the @samp{#} is immediately followed by another @samp{#}, the second -one will be followed by the return type and a semicolon. The class and -argument types are not specified, and must be determined by demangling -the name of the method if it is available. - -Otherwise, the single @samp{#} is followed by the class type, a comma, -the return type, a comma, and zero or more parameter types separated by -commas. The list of arguments is terminated by a semicolon. In the -debugging output generated by gcc, a final argument type of @code{void} -indicates a method which does not take a variable number of arguments. -If the final argument type of @code{void} does not appear, the method -was declared with an ellipsis. - -Note that although such a type will normally be used to describe fields -in structures, unions, or classes, for at least some versions of the -compiler it can also be used in other contexts. - -@node Member Type Descriptor -@section The @samp{@@} Type Descriptor - -The @samp{@@} type descriptor is used together with the @samp{*} type -descriptor for a pointer-to-non-static-member-data type. It is followed -by type information for the class (or union), a comma, and type -information for the member data. - -The following C@t{++} source: - -@smallexample -typedef int A::*int_in_a; -@end smallexample - -generates the following stab: - -@smallexample -.stabs "int_in_a:t20=*21=@@19,1",128,0,0,0 -@end smallexample - -Note that there is a conflict between this and type attributes -(@pxref{String Field}); both use type descriptor @samp{@@}. -Fortunately, the @samp{@@} type descriptor used in this C@t{++} sense always -will be followed by a digit, @samp{(}, or @samp{-}, and type attributes -never start with those things. - -@node Protections -@section Protections - -In the simple class definition shown above all member data and -functions were publicly accessible. The example that follows -contrasts public, protected and privately accessible fields and shows -how these protections are encoded in C@t{++} stabs. - -If the character following the @samp{@var{field-name}:} part of the -string is @samp{/}, then the next character is the visibility. @samp{0} -means private, @samp{1} means protected, and @samp{2} means public. -Debuggers should ignore visibility characters they do not recognize, and -assume a reasonable default (such as public) (GDB 4.11 does not, but -this should be fixed in the next GDB release). If no visibility is -specified the field is public. The visibility @samp{9} means that the -field has been optimized out and is public (there is no way to specify -an optimized out field with a private or protected visibility). -Visibility @samp{9} is not supported by GDB 4.11; this should be fixed -in the next GDB release. - -The following C@t{++} source: - -@example -class vis @{ -private: - int priv; -protected: - char prot; -public: - float pub; -@}; -@end example - -@noindent -generates the following stab: - -@example -# @r{128 is N_LSYM} -.stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 -@end example - -@samp{vis:T19=s12} indicates that type number 19 is a 12 byte structure -named @code{vis} The @code{priv} field has public visibility -(@samp{/0}), type int (@samp{1}), and offset and size @samp{,0,32;}. -The @code{prot} field has protected visibility (@samp{/1}), type char -(@samp{2}) and offset and size @samp{,32,8;}. The @code{pub} field has -type float (@samp{12}), and offset and size @samp{,64,32;}. - -Protections for member functions are signified by one digit embedded in -the field part of the stab describing the method. The digit is 0 if -private, 1 if protected and 2 if public. Consider the C@t{++} class -definition below: - -@example -class all_methods @{ -private: - int priv_meth(int in)@{return in;@}; -protected: - char protMeth(char in)@{return in;@}; -public: - float pubMeth(float in)@{return in;@}; -@}; -@end example - -It generates the following stab. The digit in question is to the left -of an @samp{A} in each case. Notice also that in this case two symbol -descriptors apply to the class name struct tag and struct type. - -@display -.stabs "class_name:sym_desc(struct tag&type)type_def(21)= - sym_desc(struct)struct_bytes(1) - meth_name::type_def(22)=sym_desc(method)returning(int); - :args(int);protection(private)modifier(normal)virtual(no); - meth_name::type_def(23)=sym_desc(method)returning(char); - :args(char);protection(protected)modifier(normal)virtual(no); - meth_name::type_def(24)=sym_desc(method)returning(float); - :args(float);protection(public)modifier(normal)virtual(no);;", - N_LSYM,NIL,NIL,NIL -@end display - -@smallexample -.stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.; - pubMeth::24=##12;:f;2A.;;",128,0,0,0 -@end smallexample - -@node Method Modifiers -@section Method Modifiers (@code{const}, @code{volatile}, @code{const volatile}) - -<< based on a6.C >> - -In the class example described above all the methods have the normal -modifier. This method modifier information is located just after the -protection information for the method. This field has four possible -character values. Normal methods use @samp{A}, const methods use -@samp{B}, volatile methods use @samp{C}, and const volatile methods use -@samp{D}. Consider the class definition below: - -@example -class A @{ -public: - int ConstMeth (int arg) const @{ return arg; @}; - char VolatileMeth (char arg) volatile @{ return arg; @}; - float ConstVolMeth (float arg) const volatile @{return arg; @}; -@}; -@end example - -This class is described by the following stab: - -@display -.stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1) - meth_name(ConstMeth)::type_def(21)sym_desc(method) - returning(int);:arg(int);protection(public)modifier(const)virtual(no); - meth_name(VolatileMeth)::type_def(22)=sym_desc(method) - returning(char);:arg(char);protection(public)modifier(volatile)virt(no) - meth_name(ConstVolMeth)::type_def(23)=sym_desc(method) - returning(float);:arg(float);protection(public)modifier(const volatile) - virtual(no);;", @dots{} -@end display - -@example -.stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.; - ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 -@end example - -@node Virtual Methods -@section Virtual Methods - -<< The following examples are based on a4.C >> - -The presence of virtual methods in a class definition adds additional -data to the class description. The extra data is appended to the -description of the virtual method and to the end of the class -description. Consider the class definition below: - -@example -class A @{ -public: - int Adat; - virtual int A_virt (int arg) @{ return arg; @}; -@}; -@end example - -This results in the stab below describing class A. It defines a new -type (20) which is an 8 byte structure. The first field of the class -struct is @samp{Adat}, an integer, starting at structure offset 0 and -occupying 32 bits. - -The second field in the class struct is not explicitly defined by the -C@t{++} class definition but is implied by the fact that the class -contains a virtual method. This field is the vtable pointer. The -name of the vtable pointer field starts with @samp{$vf} and continues with a -type reference to the class it is part of. In this example the type -reference for class A is 20 so the name of its vtable pointer field is -@samp{$vf20}, followed by the usual colon. - -Next there is a type definition for the vtable pointer type (21). -This is in turn defined as a pointer to another new type (22). - -Type 22 is the vtable itself, which is defined as an array, indexed by -a range of integers between 0 and 1, and whose elements are of type -17. Type 17 was the vtable record type defined by the boilerplate C@t{++} -type definitions, as shown earlier. - -The bit offset of the vtable pointer field is 32. The number of bits -in the field are not specified when the field is a vtable pointer. - -Next is the method definition for the virtual member function @code{A_virt}. -Its description starts out using the same format as the non-virtual -member functions described above, except instead of a dot after the -@samp{A} there is an asterisk, indicating that the function is virtual. -Since is is virtual some addition information is appended to the end -of the method description. - -The first number represents the vtable index of the method. This is a -32 bit unsigned number with the high bit set, followed by a -semi-colon. - -The second number is a type reference to the first base class in the -inheritance hierarchy defining the virtual member function. In this -case the class stab describes a base class so the virtual function is -not overriding any other definition of the method. Therefore the -reference is to the type number of the class that the stab is -describing (20). - -This is followed by three semi-colons. One marks the end of the -current sub-section, one marks the end of the method field, and the -third marks the end of the struct definition. - -For classes containing virtual functions the very last section of the -string part of the stab holds a type reference to the first base -class. This is preceded by @samp{~%} and followed by a final semi-colon. - -@display -.stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8) - field_name(Adat):type_ref(int),bit_offset(0),field_bits(32); - field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)= - sym_desc(array)index_type_ref(range of int from 0 to 1); - elem_type_ref(vtbl elem type), - bit_offset(32); - meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int); - :arg_type(int),protection(public)normal(yes)virtual(yes) - vtable_index(1);class_first_defining(A);;;~%first_base(A);", - N_LSYM,NIL,NIL,NIL -@end display - -@c FIXME: bogus line break. -@example -.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; - A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 -@end example - -@node Inheritance -@section Inheritance - -Stabs describing C@t{++} derived classes include additional sections that -describe the inheritance hierarchy of the class. A derived class stab -also encodes the number of base classes. For each base class it tells -if the base class is virtual or not, and if the inheritance is private -or public. It also gives the offset into the object of the portion of -the object corresponding to each base class. - -This additional information is embedded in the class stab following the -number of bytes in the struct. First the number of base classes -appears bracketed by an exclamation point and a comma. - -Then for each base type there repeats a series: a virtual character, a -visibility character, a number, a comma, another number, and a -semi-colon. - -The virtual character is @samp{1} if the base class is virtual and -@samp{0} if not. The visibility character is @samp{2} if the derivation -is public, @samp{1} if it is protected, and @samp{0} if it is private. -Debuggers should ignore virtual or visibility characters they do not -recognize, and assume a reasonable default (such as public and -non-virtual) (GDB 4.11 does not, but this should be fixed in the next -GDB release). - -The number following the virtual and visibility characters is the offset -from the start of the object to the part of the object pertaining to the -base class. - -After the comma, the second number is a type_descriptor for the base -type. Finally a semi-colon ends the series, which repeats for each -base class. - -The source below defines three base classes @code{A}, @code{B}, and -@code{C} and the derived class @code{D}. - - -@example -class A @{ -public: - int Adat; - virtual int A_virt (int arg) @{ return arg; @}; -@}; - -class B @{ -public: - int B_dat; - virtual int B_virt (int arg) @{return arg; @}; -@}; - -class C @{ -public: - int Cdat; - virtual int C_virt (int arg) @{return arg; @}; -@}; - -class D : A, virtual B, public C @{ -public: - int Ddat; - virtual int A_virt (int arg ) @{ return arg+1; @}; - virtual int B_virt (int arg) @{ return arg+2; @}; - virtual int C_virt (int arg) @{ return arg+3; @}; - virtual int D_virt (int arg) @{ return arg; @}; -@}; -@end example - -Class stabs similar to the ones described earlier are generated for -each base class. - -@c FIXME!!! the linebreaks in the following example probably make the -@c examples literally unusable, but I don't know any other way to get -@c them on the page. -@c One solution would be to put some of the type definitions into -@c separate stabs, even if that's not exactly what the compiler actually -@c emits. -@smallexample -.stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; - A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 - -.stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1; - :i;2A*-2147483647;25;;;~%25;",128,0,0,0 - -.stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1; - :i;2A*-2147483647;28;;;~%28;",128,0,0,0 -@end smallexample - -In the stab describing derived class @code{D} below, the information about -the derivation of this class is encoded as follows. - -@display -.stabs "derived_class_name:symbol_descriptors(struct tag&type)= - type_descriptor(struct)struct_bytes(32)!num_bases(3), - base_virtual(no)inheritance_public(no)base_offset(0), - base_class_type_ref(A); - base_virtual(yes)inheritance_public(no)base_offset(NIL), - base_class_type_ref(B); - base_virtual(no)inheritance_public(yes)base_offset(64), - base_class_type_ref(C); @dots{} -@end display - -@c FIXME! fake linebreaks. -@smallexample -.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat: - 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt: - :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647; - 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 -@end smallexample - -@node Virtual Base Classes -@section Virtual Base Classes - -A derived class object consists of a concatenation in memory of the data -areas defined by each base class, starting with the leftmost and ending -with the rightmost in the list of base classes. The exception to this -rule is for virtual inheritance. In the example above, class @code{D} -inherits virtually from base class @code{B}. This means that an -instance of a @code{D} object will not contain its own @code{B} part but -merely a pointer to a @code{B} part, known as a virtual base pointer. - -In a derived class stab, the base offset part of the derivation -information, described above, shows how the base class parts are -ordered. The base offset for a virtual base class is always given as 0. -Notice that the base offset for @code{B} is given as 0 even though -@code{B} is not the first base class. The first base class @code{A} -starts at offset 0. - -The field information part of the stab for class @code{D} describes the field -which is the pointer to the virtual base class @code{B}. The vbase pointer -name is @samp{$vb} followed by a type reference to the virtual base class. -Since the type id for @code{B} in this example is 25, the vbase pointer name -is @samp{$vb25}. - -@c FIXME!! fake linebreaks below -@smallexample -.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1, - 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i; - 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt: - :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 -@end smallexample - -Following the name and a semicolon is a type reference describing the -type of the virtual base class pointer, in this case 24. Type 24 was -defined earlier as the type of the @code{B} class @code{this} pointer. The -@code{this} pointer for a class is a pointer to the class type. - -@example -.stabs "this:P24=*25=xsB:",64,0,0,8 -@end example - -Finally the field offset part of the vbase pointer field description -shows that the vbase pointer is the first field in the @code{D} object, -before any data fields defined by the class. The layout of a @code{D} -class object is a follows, @code{Adat} at 0, the vtable pointer for -@code{A} at 32, @code{Cdat} at 64, the vtable pointer for C at 96, the -virtual base pointer for @code{B} at 128, and @code{Ddat} at 160. - - -@node Static Members -@section Static Members - -The data area for a class is a concatenation of the space used by the -data members of the class. If the class has virtual methods, a vtable -pointer follows the class data. The field offset part of each field -description in the class stab shows this ordering. - -<< How is this reflected in stabs? See Cygnus bug #677 for some info. >> - -@node Stab Types -@appendix Table of Stab Types - -The following are all the possible values for the stab type field, for -a.out files, in numeric order. This does not apply to XCOFF, but -it does apply to stabs in sections (@pxref{Stab Sections}). Stabs in -ECOFF use these values but add 0x8f300 to distinguish them from non-stab -symbols. - -The symbolic names are defined in the file @file{include/aout/stabs.def}. - -@menu -* Non-Stab Symbol Types:: Types from 0 to 0x1f -* Stab Symbol Types:: Types from 0x20 to 0xff -@end menu - -@node Non-Stab Symbol Types -@appendixsec Non-Stab Symbol Types - -The following types are used by the linker and assembler, not by stab -directives. Since this document does not attempt to describe aspects of -object file format other than the debugging format, no details are -given. - -@c Try to get most of these to fit on a single line. -@iftex -@tableindent=1.5in -@end iftex - -@table @code -@item 0x0 N_UNDF -Undefined symbol - -@item 0x2 N_ABS -File scope absolute symbol - -@item 0x3 N_ABS | N_EXT -External absolute symbol - -@item 0x4 N_TEXT -File scope text symbol - -@item 0x5 N_TEXT | N_EXT -External text symbol - -@item 0x6 N_DATA -File scope data symbol - -@item 0x7 N_DATA | N_EXT -External data symbol - -@item 0x8 N_BSS -File scope BSS symbol - -@item 0x9 N_BSS | N_EXT -External BSS symbol - -@item 0x0c N_FN_SEQ -Same as @code{N_FN}, for Sequent compilers - -@item 0x0a N_INDR -Symbol is indirected to another symbol - -@item 0x12 N_COMM -Common---visible after shared library dynamic link - -@item 0x14 N_SETA -@itemx 0x15 N_SETA | N_EXT -Absolute set element - -@item 0x16 N_SETT -@itemx 0x17 N_SETT | N_EXT -Text segment set element - -@item 0x18 N_SETD -@itemx 0x19 N_SETD | N_EXT -Data segment set element - -@item 0x1a N_SETB -@itemx 0x1b N_SETB | N_EXT -BSS segment set element - -@item 0x1c N_SETV -@itemx 0x1d N_SETV | N_EXT -Pointer to set vector - -@item 0x1e N_WARNING -Print a warning message during linking - -@item 0x1f N_FN -File name of a @file{.o} file -@end table - -@node Stab Symbol Types -@appendixsec Stab Symbol Types - -The following symbol types indicate that this is a stab. This is the -full list of stab numbers, including stab types that are used in -languages other than C. - -@table @code -@item 0x20 N_GSYM -Global symbol; see @ref{Global Variables}. - -@item 0x22 N_FNAME -Function name (for BSD Fortran); see @ref{Procedures}. - -@item 0x24 N_FUN -Function name (@pxref{Procedures}) or text segment variable -(@pxref{Statics}). - -@item 0x26 N_STSYM -Data segment file-scope variable; see @ref{Statics}. - -@item 0x28 N_LCSYM -BSS segment file-scope variable; see @ref{Statics}. - -@item 0x2a N_MAIN -Name of main routine; see @ref{Main Program}. - -@item 0x2c N_ROSYM -Variable in @code{.rodata} section; see @ref{Statics}. - -@item 0x30 N_PC -Global symbol (for Pascal); see @ref{N_PC}. - -@item 0x32 N_NSYMS -Number of symbols (according to Ultrix V4.0); see @ref{N_NSYMS}. - -@item 0x34 N_NOMAP -No DST map; see @ref{N_NOMAP}. - -@c FIXME: describe this solaris feature in the body of the text (see -@c comments in include/aout/stab.def). -@item 0x38 N_OBJ -Object file (Solaris2). - -@c See include/aout/stab.def for (a little) more info. -@item 0x3c N_OPT -Debugger options (Solaris2). - -@item 0x40 N_RSYM -Register variable; see @ref{Register Variables}. - -@item 0x42 N_M2C -Modula-2 compilation unit; see @ref{N_M2C}. - -@item 0x44 N_SLINE -Line number in text segment; see @ref{Line Numbers}. - -@item 0x46 N_DSLINE -Line number in data segment; see @ref{Line Numbers}. - -@item 0x48 N_BSLINE -Line number in bss segment; see @ref{Line Numbers}. - -@item 0x48 N_BROWS -Sun source code browser, path to @file{.cb} file; see @ref{N_BROWS}. - -@item 0x4a N_DEFD -GNU Modula2 definition module dependency; see @ref{N_DEFD}. - -@item 0x4c N_FLINE -Function start/body/end line numbers (Solaris2). - -@item 0x50 N_EHDECL -GNU C@t{++} exception variable; see @ref{N_EHDECL}. - -@item 0x50 N_MOD2 -Modula2 info "for imc" (according to Ultrix V4.0); see @ref{N_MOD2}. - -@item 0x54 N_CATCH -GNU C@t{++} @code{catch} clause; see @ref{N_CATCH}. - -@item 0x60 N_SSYM -Structure of union element; see @ref{N_SSYM}. - -@item 0x62 N_ENDM -Last stab for module (Solaris2). - -@item 0x64 N_SO -Path and name of source file; see @ref{Source Files}. - -@item 0x80 N_LSYM -Stack variable (@pxref{Stack Variables}) or type (@pxref{Typedefs}). - -@item 0x82 N_BINCL -Beginning of an include file (Sun only); see @ref{Include Files}. - -@item 0x84 N_SOL -Name of include file; see @ref{Include Files}. - -@item 0xa0 N_PSYM -Parameter variable; see @ref{Parameters}. - -@item 0xa2 N_EINCL -End of an include file; see @ref{Include Files}. - -@item 0xa4 N_ENTRY -Alternate entry point; see @ref{Alternate Entry Points}. - -@item 0xc0 N_LBRAC -Beginning of a lexical block; see @ref{Block Structure}. - -@item 0xc2 N_EXCL -Place holder for a deleted include file; see @ref{Include Files}. - -@item 0xc4 N_SCOPE -Modula2 scope information (Sun linker); see @ref{N_SCOPE}. - -@item 0xe0 N_RBRAC -End of a lexical block; see @ref{Block Structure}. - -@item 0xe2 N_BCOMM -Begin named common block; see @ref{Common Blocks}. - -@item 0xe4 N_ECOMM -End named common block; see @ref{Common Blocks}. - -@item 0xe8 N_ECOML -Member of a common block; see @ref{Common Blocks}. - -@c FIXME: How does this really work? Move it to main body of document. -@item 0xea N_WITH -Pascal @code{with} statement: type,,0,0,offset (Solaris2). - -@item 0xf0 N_NBTEXT -Gould non-base registers; see @ref{Gould}. - -@item 0xf2 N_NBDATA -Gould non-base registers; see @ref{Gould}. - -@item 0xf4 N_NBBSS -Gould non-base registers; see @ref{Gould}. - -@item 0xf6 N_NBSTS -Gould non-base registers; see @ref{Gould}. - -@item 0xf8 N_NBLCS -Gould non-base registers; see @ref{Gould}. -@end table - -@c Restore the default table indent -@iftex -@tableindent=.8in -@end iftex - -@node Symbol Descriptors -@appendix Table of Symbol Descriptors - -The symbol descriptor is the character which follows the colon in many -stabs, and which tells what kind of stab it is. @xref{String Field}, -for more information about their use. - -@c Please keep this alphabetical -@table @code -@c In TeX, this looks great, digit is in italics. But makeinfo insists -@c on putting it in `', not realizing that @var should override @code. -@c I don't know of any way to make makeinfo do the right thing. Seems -@c like a makeinfo bug to me. -@item @var{digit} -@itemx ( -@itemx - -Variable on the stack; see @ref{Stack Variables}. - -@item : -C@t{++} nested symbol; see @xref{Nested Symbols}. - -@item a -Parameter passed by reference in register; see @ref{Reference Parameters}. - -@item b -Based variable; see @ref{Based Variables}. - -@item c -Constant; see @ref{Constants}. - -@item C -Conformant array bound (Pascal, maybe other languages); @ref{Conformant -Arrays}. Name of a caught exception (GNU C@t{++}). These can be -distinguished because the latter uses @code{N_CATCH} and the former uses -another symbol type. - -@item d -Floating point register variable; see @ref{Register Variables}. - -@item D -Parameter in floating point register; see @ref{Register Parameters}. - -@item f -File scope function; see @ref{Procedures}. - -@item F -Global function; see @ref{Procedures}. - -@item G -Global variable; see @ref{Global Variables}. - -@item i -@xref{Register Parameters}. - -@item I -Internal (nested) procedure; see @ref{Nested Procedures}. - -@item J -Internal (nested) function; see @ref{Nested Procedures}. - -@item L -Label name (documented by AIX, no further information known). - -@item m -Module; see @ref{Procedures}. - -@item p -Argument list parameter; see @ref{Parameters}. - -@item pP -@xref{Parameters}. - -@item pF -Fortran Function parameter; see @ref{Parameters}. - -@item P -Unfortunately, three separate meanings have been independently invented -for this symbol descriptor. At least the GNU and Sun uses can be -distinguished by the symbol type. Global Procedure (AIX) (symbol type -used unknown); see @ref{Procedures}. Register parameter (GNU) (symbol -type @code{N_PSYM}); see @ref{Parameters}. Prototype of function -referenced by this file (Sun @code{acc}) (symbol type @code{N_FUN}). - -@item Q -Static Procedure; see @ref{Procedures}. - -@item R -Register parameter; see @ref{Register Parameters}. - -@item r -Register variable; see @ref{Register Variables}. - -@item S -File scope variable; see @ref{Statics}. - -@item s -Local variable (OS9000). - -@item t -Type name; see @ref{Typedefs}. - -@item T -Enumeration, structure, or union tag; see @ref{Typedefs}. - -@item v -Parameter passed by reference; see @ref{Reference Parameters}. - -@item V -Procedure scope static variable; see @ref{Statics}. - -@item x -Conformant array; see @ref{Conformant Arrays}. - -@item X -Function return variable; see @ref{Parameters}. -@end table - -@node Type Descriptors -@appendix Table of Type Descriptors - -The type descriptor is the character which follows the type number and -an equals sign. It specifies what kind of type is being defined. -@xref{String Field}, for more information about their use. - -@table @code -@item @var{digit} -@itemx ( -Type reference; see @ref{String Field}. - -@item - -Reference to builtin type; see @ref{Negative Type Numbers}. - -@item # -Method (C@t{++}); see @ref{Method Type Descriptor}. - -@item * -Pointer; see @ref{Miscellaneous Types}. - -@item & -Reference (C@t{++}). - -@item @@ -Type Attributes (AIX); see @ref{String Field}. Member (class and variable) -type (GNU C@t{++}); see @ref{Member Type Descriptor}. - -@item a -Array; see @ref{Arrays}. - -@item A -Open array; see @ref{Arrays}. - -@item b -Pascal space type (AIX); see @ref{Miscellaneous Types}. Builtin integer -type (Sun); see @ref{Builtin Type Descriptors}. Const and volatile -qualified type (OS9000). - -@item B -Volatile-qualified type; see @ref{Miscellaneous Types}. - -@item c -Complex builtin type (AIX); see @ref{Builtin Type Descriptors}. -Const-qualified type (OS9000). - -@item C -COBOL Picture type. See AIX documentation for details. - -@item d -File type; see @ref{Miscellaneous Types}. - -@item D -N-dimensional dynamic array; see @ref{Arrays}. - -@item e -Enumeration type; see @ref{Enumerations}. - -@item E -N-dimensional subarray; see @ref{Arrays}. - -@item f -Function type; see @ref{Function Types}. - -@item F -Pascal function parameter; see @ref{Function Types} - -@item g -Builtin floating point type; see @ref{Builtin Type Descriptors}. - -@item G -COBOL Group. See AIX documentation for details. - -@item i -Imported type (AIX); see @ref{Cross-References}. Volatile-qualified -type (OS9000). - -@item k -Const-qualified type; see @ref{Miscellaneous Types}. - -@item K -COBOL File Descriptor. See AIX documentation for details. - -@item M -Multiple instance type; see @ref{Miscellaneous Types}. - -@item n -String type; see @ref{Strings}. - -@item N -Stringptr; see @ref{Strings}. - -@item o -Opaque type; see @ref{Typedefs}. - -@item p -Procedure; see @ref{Function Types}. - -@item P -Packed array; see @ref{Arrays}. - -@item r -Range type; see @ref{Subranges}. - -@item R -Builtin floating type; see @ref{Builtin Type Descriptors} (Sun). Pascal -subroutine parameter; see @ref{Function Types} (AIX). Detecting this -conflict is possible with careful parsing (hint: a Pascal subroutine -parameter type will always contain a comma, and a builtin type -descriptor never will). - -@item s -Structure type; see @ref{Structures}. - -@item S -Set type; see @ref{Miscellaneous Types}. - -@item u -Union; see @ref{Unions}. - -@item v -Variant record. This is a Pascal and Modula-2 feature which is like a -union within a struct in C. See AIX documentation for details. - -@item w -Wide character; see @ref{Builtin Type Descriptors}. - -@item x -Cross-reference; see @ref{Cross-References}. - -@item Y -Used by IBM's xlC C@t{++} compiler (for structures, I think). - -@item z -gstring; see @ref{Strings}. -@end table - -@node Expanded Reference -@appendix Expanded Reference by Stab Type - -@c FIXME: This appendix should go away; see N_PSYM or N_SO for an example. - -For a full list of stab types, and cross-references to where they are -described, see @ref{Stab Types}. This appendix just covers certain -stabs which are not yet described in the main body of this document; -eventually the information will all be in one place. - -Format of an entry: - -The first line is the symbol type (see @file{include/aout/stab.def}). - -The second line describes the language constructs the symbol type -represents. - -The third line is the stab format with the significant stab fields -named and the rest NIL. - -Subsequent lines expand upon the meaning and possible values for each -significant stab field. - -Finally, any further information. - -@menu -* N_PC:: Pascal global symbol -* N_NSYMS:: Number of symbols -* N_NOMAP:: No DST map -* N_M2C:: Modula-2 compilation unit -* N_BROWS:: Path to .cb file for Sun source code browser -* N_DEFD:: GNU Modula2 definition module dependency -* N_EHDECL:: GNU C++ exception variable -* N_MOD2:: Modula2 information "for imc" -* N_CATCH:: GNU C++ "catch" clause -* N_SSYM:: Structure or union element -* N_SCOPE:: Modula2 scope information (Sun only) -* Gould:: non-base register symbols used on Gould systems -* N_LENG:: Length of preceding entry -@end menu - -@node N_PC -@section N_PC - -@deffn @code{.stabs} N_PC -@findex N_PC -Global symbol (for Pascal). - -@example -"name" -> "symbol_name" <<?>> -value -> supposedly the line number (stab.def is skeptical) -@end example - -@display -@file{stabdump.c} says: - -global pascal symbol: name,,0,subtype,line -<< subtype? >> -@end display -@end deffn - -@node N_NSYMS -@section N_NSYMS - -@deffn @code{.stabn} N_NSYMS -@findex N_NSYMS -Number of symbols (according to Ultrix V4.0). - -@display - 0, files,,funcs,lines (stab.def) -@end display -@end deffn - -@node N_NOMAP -@section N_NOMAP - -@deffn @code{.stabs} N_NOMAP -@findex N_NOMAP -No DST map for symbol (according to Ultrix V4.0). I think this means a -variable has been optimized out. - -@display - name, ,0,type,ignored (stab.def) -@end display -@end deffn - -@node N_M2C -@section N_M2C - -@deffn @code{.stabs} N_M2C -@findex N_M2C -Modula-2 compilation unit. - -@example -"string" -> "unit_name,unit_time_stamp[,code_time_stamp]" -desc -> unit_number -value -> 0 (main unit) - 1 (any other unit) -@end example - -See @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, for -more information. - -@end deffn - -@node N_BROWS -@section N_BROWS - -@deffn @code{.stabs} N_BROWS -@findex N_BROWS -Sun source code browser, path to @file{.cb} file - -<<?>> -"path to associated @file{.cb} file" - -Note: N_BROWS has the same value as N_BSLINE. -@end deffn - -@node N_DEFD -@section N_DEFD - -@deffn @code{.stabn} N_DEFD -@findex N_DEFD -GNU Modula2 definition module dependency. - -GNU Modula-2 definition module dependency. The value is the -modification time of the definition file. The other field is non-zero -if it is imported with the GNU M2 keyword @code{%INITIALIZE}. Perhaps -@code{N_M2C} can be used if there are enough empty fields? -@end deffn - -@node N_EHDECL -@section N_EHDECL - -@deffn @code{.stabs} N_EHDECL -@findex N_EHDECL -GNU C@t{++} exception variable <<?>>. - -"@var{string} is variable name" - -Note: conflicts with @code{N_MOD2}. -@end deffn - -@node N_MOD2 -@section N_MOD2 - -@deffn @code{.stab?} N_MOD2 -@findex N_MOD2 -Modula2 info "for imc" (according to Ultrix V4.0) - -Note: conflicts with @code{N_EHDECL} <<?>> -@end deffn - -@node N_CATCH -@section N_CATCH - -@deffn @code{.stabn} N_CATCH -@findex N_CATCH -GNU C@t{++} @code{catch} clause - -GNU C@t{++} @code{catch} clause. The value is its address. The desc field -is nonzero if this entry is immediately followed by a @code{CAUGHT} stab -saying what exception was caught. Multiple @code{CAUGHT} stabs means -that multiple exceptions can be caught here. If desc is 0, it means all -exceptions are caught here. -@end deffn - -@node N_SSYM -@section N_SSYM - -@deffn @code{.stabn} N_SSYM -@findex N_SSYM -Structure or union element. - -The value is the offset in the structure. - -<<?looking at structs and unions in C I didn't see these>> -@end deffn - -@node N_SCOPE -@section N_SCOPE - -@deffn @code{.stab?} N_SCOPE -@findex N_SCOPE -Modula2 scope information (Sun linker) -<<?>> -@end deffn - -@node Gould -@section Non-base registers on Gould systems - -@deffn @code{.stab?} N_NBTEXT -@deffnx @code{.stab?} N_NBDATA -@deffnx @code{.stab?} N_NBBSS -@deffnx @code{.stab?} N_NBSTS -@deffnx @code{.stab?} N_NBLCS -@findex N_NBTEXT -@findex N_NBDATA -@findex N_NBBSS -@findex N_NBSTS -@findex N_NBLCS -These are used on Gould systems for non-base registers syms. - -However, the following values are not the values used by Gould; they are -the values which GNU has been documenting for these values for a long -time, without actually checking what Gould uses. I include these values -only because perhaps some someone actually did something with the GNU -information (I hope not, why GNU knowingly assigned wrong values to -these in the header file is a complete mystery to me). - -@example -240 0xf0 N_NBTEXT ?? -242 0xf2 N_NBDATA ?? -244 0xf4 N_NBBSS ?? -246 0xf6 N_NBSTS ?? -248 0xf8 N_NBLCS ?? -@end example -@end deffn - -@node N_LENG -@section N_LENG - -@deffn @code{.stabn} N_LENG -@findex N_LENG -Second symbol entry containing a length-value for the preceding entry. -The value is the length. -@end deffn - -@node Questions -@appendix Questions and Anomalies - -@itemize @bullet -@item -@c I think this is changed in GCC 2.4.5 to put the line number there. -For GNU C stabs defining local and global variables (@code{N_LSYM} and -@code{N_GSYM}), the desc field is supposed to contain the source -line number on which the variable is defined. In reality the desc -field is always 0. (This behavior is defined in @file{dbxout.c} and -putting a line number in desc is controlled by @samp{#ifdef -WINNING_GDB}, which defaults to false). GDB supposedly uses this -information if you say @samp{list @var{var}}. In reality, @var{var} can -be a variable defined in the program and GDB says @samp{function -@var{var} not defined}. - -@item -In GNU C stabs, there seems to be no way to differentiate tag types: -structures, unions, and enums (symbol descriptor @samp{T}) and typedefs -(symbol descriptor @samp{t}) defined at file scope from types defined locally -to a procedure or other more local scope. They all use the @code{N_LSYM} -stab type. Types defined at procedure scope are emitted after the -@code{N_RBRAC} of the preceding function and before the code of the -procedure in which they are defined. This is exactly the same as -types defined in the source file between the two procedure bodies. -GDB over-compensates by placing all types in block #1, the block for -symbols of file scope. This is true for default, @samp{-ansi} and -@samp{-traditional} compiler options. (Bugs gcc/1063, gdb/1066.) - -@item -What ends the procedure scope? Is it the proc block's @code{N_RBRAC} or the -next @code{N_FUN}? (I believe its the first.) -@end itemize - -@node Stab Sections -@appendix Using Stabs in Their Own Sections - -Many object file formats allow tools to create object files with custom -sections containing any arbitrary data. For any such object file -format, stabs can be embedded in special sections. This is how stabs -are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs -are used with COFF. - -@menu -* Stab Section Basics:: How to embed stabs in sections -* ELF Linker Relocation:: Sun ELF hacks -@end menu - -@node Stab Section Basics -@appendixsec How to Embed Stabs in Sections - -The assembler creates two custom sections, a section named @code{.stab} -which contains an array of fixed length structures, one struct per stab, -and a section named @code{.stabstr} containing all the variable length -strings that are referenced by stabs in the @code{.stab} section. The -byte order of the stabs binary data depends on the object file format. -For ELF, it matches the byte order of the ELF file itself, as determined -from the @code{EI_DATA} field in the @code{e_ident} member of the ELF -header. For SOM, it is always big-endian (is this true??? FIXME). For -COFF, it matches the byte order of the COFF headers. The meaning of the -fields is the same as for a.out (@pxref{Symbol Table Format}), except -that the @code{n_strx} field is relative to the strings for the current -compilation unit (which can be found using the synthetic N_UNDF stab -described below), rather than the entire string table. - -The first stab in the @code{.stab} section for each compilation unit is -synthetic, generated entirely by the assembler, with no corresponding -@code{.stab} directive as input to the assembler. This stab contains -the following fields: - -@table @code -@item n_strx -Offset in the @code{.stabstr} section to the source filename. - -@item n_type -@code{N_UNDF}. - -@item n_other -Unused field, always zero. -This may eventually be used to hold overflows from the count in -the @code{n_desc} field. - -@item n_desc -Count of upcoming symbols, i.e., the number of remaining stabs for this -source file. - -@item n_value -Size of the string table fragment associated with this source file, in -bytes. -@end table - -The @code{.stabstr} section always starts with a null byte (so that string -offsets of zero reference a null string), followed by random length strings, -each of which is null byte terminated. - -The ELF section header for the @code{.stab} section has its -@code{sh_link} member set to the section number of the @code{.stabstr} -section, and the @code{.stabstr} section has its ELF section -header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a -string table. SOM and COFF have no way of linking the sections together -or marking them as string tables. - -For COFF, the @code{.stab} and @code{.stabstr} sections may be simply -concatenated by the linker. GDB then uses the @code{n_desc} fields to -figure out the extent of the original sections. Similarly, the -@code{n_value} fields of the header symbols are added together in order -to get the actual position of the strings in a desired @code{.stabstr} -section. Although this design obviates any need for the linker to -relocate or otherwise manipulate @code{.stab} and @code{.stabstr} -sections, it also requires some care to ensure that the offsets are -calculated correctly. For instance, if the linker were to pad in -between the @code{.stabstr} sections before concatenating, then the -offsets to strings in the middle of the executable's @code{.stabstr} -section would be wrong. - -The GNU linker is able to optimize stabs information by merging -duplicate strings and removing duplicate header file information -(@pxref{Include Files}). When some versions of the GNU linker optimize -stabs in sections, they remove the leading @code{N_UNDF} symbol and -arranges for all the @code{n_strx} fields to be relative to the start of -the @code{.stabstr} section. - -@node ELF Linker Relocation -@appendixsec Having the Linker Relocate Stabs in ELF - -This section describes some Sun hacks for Stabs in ELF; it does not -apply to COFF or SOM. - -To keep linking fast, you don't want the linker to have to relocate very -many stabs. Making sure this is done for @code{N_SLINE}, -@code{N_RBRAC}, and @code{N_LBRAC} stabs is the most important thing -(see the descriptions of those stabs for more information). But Sun's -stabs in ELF has taken this further, to make all addresses in the -@code{n_value} field (functions and static variables) relative to the -source file. For the @code{N_SO} symbol itself, Sun simply omits the -address. To find the address of each section corresponding to a given -source file, the compiler puts out symbols giving the address of each -section for a given source file. Since these are ELF (not stab) -symbols, the linker relocates them correctly without having to touch the -stabs section. They are named @code{Bbss.bss} for the bss section, -@code{Ddata.data} for the data section, and @code{Drodata.rodata} for -the rodata section. For the text section, there is no such symbol (but -there should be, see below). For an example of how these symbols work, -@xref{Stab Section Transformations}. GCC does not provide these symbols; -it instead relies on the stabs getting relocated. Thus addresses which -would normally be relative to @code{Bbss.bss}, etc., are already -relocated. The Sun linker provided with Solaris 2.2 and earlier -relocates stabs using normal ELF relocation information, as it would do -for any section. Sun has been threatening to kludge their linker to not -do this (to speed up linking), even though the correct way to avoid -having the linker do these relocations is to have the compiler no longer -output relocatable values. Last I heard they had been talked out of the -linker kludge. See Sun point patch 101052-01 and Sun bug 1142109. With -the Sun compiler this affects @samp{S} symbol descriptor stabs -(@pxref{Statics}) and functions (@pxref{Procedures}). In the latter -case, to adopt the clean solution (making the value of the stab relative -to the start of the compilation unit), it would be necessary to invent a -@code{Ttext.text} symbol, analogous to the @code{Bbss.bss}, etc., -symbols. I recommend this rather than using a zero value and getting -the address from the ELF symbols. - -Finding the correct @code{Bbss.bss}, etc., symbol is difficult, because -the linker simply concatenates the @code{.stab} sections from each -@file{.o} file without including any information about which part of a -@code{.stab} section comes from which @file{.o} file. The way GDB does -this is to look for an ELF @code{STT_FILE} symbol which has the same -name as the last component of the file name from the @code{N_SO} symbol -in the stabs (for example, if the file name is @file{../../gdb/main.c}, -it looks for an ELF @code{STT_FILE} symbol named @code{main.c}). This -loses if different files have the same name (they could be in different -directories, a library could have been copied from one system to -another, etc.). It would be much cleaner to have the @code{Bbss.bss} -symbols in the stabs themselves. Having the linker relocate them there -is no more work than having the linker relocate ELF symbols, and it -solves the problem of having to associate the ELF and stab symbols. -However, no one has yet designed or implemented such a scheme. - -@raisesections -@include fdl.texi -@lowersections - -@node Symbol Types Index -@unnumbered Symbol Types Index - -@printindex fn - -@c TeX can handle the contents at the start but makeinfo 3.12 can not -@ifinfo -@contents -@end ifinfo -@ifhtml -@contents -@end ifhtml - -@bye |