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
Set the line speed (baud rate or bits per second) of any serial
interface used by @value{GDBN} for remote debugging.
+@item -l @var{timeout}
+@cindex @code{-l}
+Set the timeout (in seconds) of any communication used by @value{GDBN}
+for remote debugging.
+
@item -tty @var{device}
@itemx -t @var{device}
@cindex @code{--tty}
@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!).
+@xref{Variables}, for more information about debugging optimized code.
Older versions of the @sc{gnu} C compiler permitted a variant option
@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
breakpoint at the beginning of the main procedure and then invoking
the @samp{run} command.
-Some programs contain an elaboration phase where some startup code is
-executed before the main program is called. This depends on the
-languages used to write your program. In C@t{++} for instance,
+@cindex elaboration phase
+Some programs contain an @dfn{elaboration} phase where some startup code is
+executed before the main procedure is called. This depends on the
+languages used to write your program. In C@t{++}, for instance,
constructors for static and global objects are executed before
@code{main} is called. It is therefore possible that the debugger stops
before reaching the main procedure. However, the temporary breakpoint
Print the @value{GDBN} working directory.
@end table
+It is generally impossible to find the current working directory of
+the process being debugged (since a program can change its directory
+during its run). If you work on a system where @value{GDBN} is
+configured with the @file{/proc} support, you can use the @code{info
+proc} command (@pxref{SVR4 Process Information}) to find out the
+current working directory of the debuggee.
+
@node Input/Output
@section Your program's input and output
On HP-UX systems:
-@cindex thread number
-@cindex thread identifier (GDB)
+@cindex debugging multithreaded programs (on HP-UX)
+@cindex thread identifier (GDB), on HP-UX
For debugging purposes, @value{GDBN} associates its own thread
number---a small integer assigned in thread-creation order---with each
thread in your program.
when @value{GDBN} notices a new thread.
@table @code
-@kindex info threads
+@kindex info threads (HP-UX)
@item info threads
Display a summary of all threads currently in your
program. @value{GDBN} displays for each thread (in this order):
@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
@code{.*} leading and trailing the regular expression you supply, so to
match only functions that begin with @code{foo}, use @code{^foo}.
+@cindex non-member C@t{++} functions, set breakpoint in
When debugging C@t{++} programs, @code{rbreak} is useful for setting
breakpoints on overloaded functions that are not members of any special
classes.
+@cindex set breakpoints on all functions
+The @code{rbreak} command can be used to set breakpoints in
+@strong{all} the functions in a program, like this:
+
+@smallexample
+(@value{GDBP}) rbreak .
+@end smallexample
+
@kindex info breakpoints
@cindex @code{$_} and @code{info breakpoints}
@item info breakpoints @r{[}@var{n}@r{]}
Stop when @var{event} occurs. @var{event} can be any of the following:
@table @code
@item throw
-@kindex catch throw
+@cindex stop on C@t{++} exceptions
The throwing of a C@t{++} exception.
@item catch
-@kindex catch catch
The catching of a C@t{++} exception.
@item exec
-@kindex catch exec
+@cindex break on fork/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
+@cindex break on load/unload of shared library
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
@node Disabling
@subsection Disabling breakpoints
-@kindex disable breakpoints
-@kindex enable breakpoints
+@cindex enable/disable a breakpoint
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
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{]}
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
@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}.
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
@table @code
@item set backtrace past-main
@itemx set backtrace past-main on
+@kindex set backtrace
Backtraces will continue past the user entry point.
@item set backtrace past-main off
default.
@item show backtrace past-main
+@kindex show backtrace
Display the current user entry point backtrace policy.
+@item set backtrace past-entry
+@itemx set backtrace past-entry on
+Backtraces will continue past the internal entry point of an application.
+This entry point is encoded by the linker when the application is built,
+and is likely before the user entry point @code{main} (or equivalent) is called.
+
+@item set backtrace past-entry off
+Backtraces will stop when they encouter the internal entry point of an
+application. This is the default.
+
+@item show backtrace past-entry
+Display the current internal entry point backtrace policy.
+
@item set backtrace limit @var{n}
@itemx set backtrace limit 0
@cindex backtrace limit
@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
+The optional numeric value +@var{number} specifies the number of the line in
+the file where to start editing.}.
+By default, it is @file{@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 ...
+gdb @dots{}
@end smallexample
or in the @code{csh} shell,
@smallexample
setenv EDITOR /usr/bin/vi
-gdb ...
+gdb @dots{}
@end smallexample
@node Search
@section Searching source files
-@cindex searching
+@cindex searching source files
@kindex reverse-search
There are two commands for searching through the current source file for a
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.
+in the list, until it finds a file with the desired name.
+
+For example, suppose an executable references the file
+@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
+@file{/mnt/cross}. The file is first looked up literally; if this
+fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
+fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
+message is printed. @value{GDBN} does not look up the parts of the
+source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
+Likewise, the subdirectories of the source path are not searched: if
+the source path is @file{/mnt/cross}, and the binary refers to
+@file{foo.c}, @value{GDBN} would not find it under
+@file{/mnt/cross/usr/src/foo-1.0/lib}.
+
+Plain file names, relative file names with leading directories, file
+names containing dots, etc.@: are all treated as described above; for
+instance, if the source path is @file{/mnt/cross}, and the source file
+is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
+@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
+that---@file{/mnt/cross/foo.c}.
+
+Note that the executable search path is @emph{not} used to locate the
+source files. Neither is the current working directory, unless it
+happens to be in the source path.
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
@node Machine Code
@section Source and machine code
+@cindex source line and its code address
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
@end smallexample
@noindent
+@cindex code address and its source line
We can also inquire (using @code{*@var{addr}} as the form for
@var{linespec}) what source line covers a particular address:
@smallexample
@end smallexample
@cindex @code{$_} and @code{info line}
+@cindex @code{x} command, default address
@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
@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}
@item print
@itemx print /@var{f}
+@cindex reprint the last value
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.
* Auxiliary Vector:: Auxiliary data provided by operating system
* Memory Region Attributes:: Memory region attributes
* Dump/Restore Files:: Copy between memory and a file
+* Core File Generation:: Cause a program dump its core
* Character Sets:: Debugging programs that use a different
character set than GDB does
@end menu
you compiled your program to include this information; see
@ref{Compilation}.
+@cindex arrays in expressions
@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
In this section, we discuss operators that you can use in @value{GDBN}
expressions regardless of your programming language.
+@cindex casts, in expressions
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.
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:
+using the colon-colon (@code{::}) notation:
@cindex colon-colon, context for variables/functions
@iftex
@cindex wrong values
@cindex variable values, wrong
+@cindex function entry/exit, wrong values of variables
+@cindex optimized code, wrong values of variables
@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
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
+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}.
-
+@xref{C, , Debugging C++}, for more info about debug info formats
+that are best suited to C@t{++} programs.
@node Arrays
@section Artificial arrays
@cindex artificial array
+@cindex arrays
@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
because they refer to automatic variables not currently available.
@end table
+@cindex display disabled out of scope
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
These settings are useful for debugging programs in any language:
@table @code
-@kindex set print address
+@kindex set print
@item set print address
@itemx set print address on
+@cindex print/don't print memory addresses
@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
@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
+@kindex show print
@item show print address
Show whether or not addresses are to be printed.
@end table
it prints a symbolic address:
@table @code
-@kindex set print symbol-filename
@item set print symbol-filename on
+@cindex closest symbol and offset for an address
Tell @value{GDBN} to print the source file name and line number of a
symbol in the symbolic form of an address.
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.
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}
+@cindex maximum value for offset of closest symbol
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.
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
+@cindex pretty print arrays
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}
+@cindex number of array elements to print
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.
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
+@cindex @sc{null} elements in arrays
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:
@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
+@cindex eight-bit characters in strings
+@cindex octal escapes in strings
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
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
+@cindex unions in structures, printing
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.
These settings are of interest when debugging C@t{++} programs:
@table @code
-@cindex demangling
-@kindex set print demangle
+@cindex demangling C@t{++} names
@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}
@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
+@cindex derived type of an object, printing
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.
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
+@cindex static members of C@t{++} objects
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
+@cindex pretty print C@t{++} virtual function tables
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
@end table
+@node Core File Generation
+@section How to Produce a Core File from Your Program
+@cindex dump core from inferior
+
+A @dfn{core file} or @dfn{core dump} is a file that records the memory
+image of a running process and its process status (register values
+etc.). Its primary use is post-mortem debugging of a program that
+crashed while it ran outside a debugger. A program that crashes
+automatically produces a core file, unless this feature is disabled by
+the user. @xref{Files}, for information on invoking @value{GDBN} in
+the post-mortem debugging mode.
+
+Occasionally, you may wish to produce a core file of the program you
+are debugging in order to preserve a snapshot of its state.
+@value{GDBN} has a special command for that.
+
+@table @code
+@kindex gcore
+@kindex generate-core-file
+@item generate-core-file [@var{file}]
+@itemx gcore [@var{file}]
+Produce a core dump of the inferior process. The optional argument
+@var{file} specifies the file name where to put the core dump. If not
+specified, the file name defaults to @file{core.@var{pid}}, where
+@var{pid} is the inferior process ID.
+
+Note that this command is implemented only for some systems (as of
+this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
+@end table
+
@node Character Sets
@section Character Sets
@cindex character sets
GNU gdb 2001-12-19-cvs
Copyright 2001 Free Software Foundation, Inc.
@dots{}
-(gdb)
+(@value{GDBP})
@end smallexample
We can use the @code{show charset} command to see what character sets
strings:
@smallexample
-(gdb) show charset
+(@value{GDBP}) show charset
The current host and target character set is `ISO-8859-1'.
-(gdb)
+(@value{GDBP})
@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
+(@value{GDBP}) set charset ASCII
+(@value{GDBP}) show charset
The current host and target character set is `ASCII'.
-(gdb)
+(@value{GDBP})
@end smallexample
Let's assume that @sc{ascii} is indeed the correct character set for our
@sc{ascii}, the contents of @code{ascii_hello} print legibly:
@smallexample
-(gdb) print ascii_hello
+(@value{GDBP}) print ascii_hello
$1 = 0x401698 "Hello, world!\n"
-(gdb) print ascii_hello[0]
+(@value{GDBP}) print ascii_hello[0]
$2 = 72 'H'
-(gdb)
+(@value{GDBP})
@end smallexample
@value{GDBN} uses the target character set for character and string
literals you use in expressions:
@smallexample
-(gdb) print '+'
+(@value{GDBP}) print '+'
$3 = 43 '+'
-(gdb)
+(@value{GDBP})
@end smallexample
The @sc{ascii} character set uses the number 43 to encode the @samp{+}
character set is still @sc{ascii}, we get jibberish:
@smallexample
-(gdb) print ibm1047_hello
+(@value{GDBP}) print ibm1047_hello
$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%"
-(gdb) print ibm1047_hello[0]
+(@value{GDBP}) print ibm1047_hello[0]
$5 = 200 '\310'
-(gdb)
+(@value{GDBP})
@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
+(@value{GDBP}) set target-charset
ASCII EBCDIC-US IBM1047 ISO-8859-1
-(gdb) set target-charset
+(@value{GDBP}) set target-charset
@end smallexample
We can select @sc{ibm1047} as our target character set, and examine the
@sc{ascii}, and they display correctly:
@smallexample
-(gdb) set target-charset IBM1047
-(gdb) show charset
+(@value{GDBP}) set target-charset IBM1047
+(@value{GDBP}) show charset
The current host character set is `ASCII'.
The current target character set is `IBM1047'.
-(gdb) print ascii_hello
+(@value{GDBP}) print ascii_hello
$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
-(gdb) print ascii_hello[0]
+(@value{GDBP}) print ascii_hello[0]
$7 = 72 '\110'
-(gdb) print ibm1047_hello
+(@value{GDBP}) print ibm1047_hello
$8 = 0x4016a8 "Hello, world!\n"
-(gdb) print ibm1047_hello[0]
+(@value{GDBP}) print ibm1047_hello[0]
$9 = 200 'H'
-(gdb)
+(@value{GDBP})
@end smallexample
As above, @value{GDBN} uses the target character set for character and
string literals you use in expressions:
@smallexample
-(gdb) print '+'
+(@value{GDBP}) print '+'
$10 = 78 '+'
-(gdb)
+(@value{GDBP})
@end smallexample
The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
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}
+@cindex expand macro once
@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
GNU gdb 2002-05-06-cvs
Copyright 2002 Free Software Foundation, Inc.
GDB is free software, @dots{}
-(gdb)
+(@value{GDBP})
@end smallexample
We can expand macros and examine their definitions, even when the
to decide which macro definitions are in scope:
@smallexample
-(gdb) list main
+(@value{GDBP}) list main
3
4 #define M 42
5 #define ADD(x) (M + x)
10 printf ("Hello, world!\n");
11 #undef N
12 printf ("We're so creative.\n");
-(gdb) info macro ADD
+(@value{GDBP}) info macro ADD
Defined at /home/jimb/gdb/macros/play/sample.c:5
#define ADD(x) (M + x)
-(gdb) info macro Q
+(@value{GDBP}) 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)
+(@value{GDBP}) macro expand ADD(1)
expands to: (42 + 1)
-(gdb) macro expand-once ADD(1)
+(@value{GDBP}) macro expand-once ADD(1)
expands to: once (M + 1)
-(gdb)
+(@value{GDBP})
@end smallexample
In the example above, note that @command{macro expand-once} expands only
the source line of the current stack frame:
@smallexample
-(gdb) break main
+(@value{GDBP}) break main
Breakpoint 1 at 0x8048370: file sample.c, line 10.
-(gdb) run
+(@value{GDBP}) run
Starting program: /home/jimb/gdb/macros/play/sample
Breakpoint 1, main () at sample.c:10
10 printf ("Hello, world!\n");
-(gdb)
+(@value{GDBP})
@end smallexample
At line 10, the definition of the macro @code{N} at line 9 is in force:
@smallexample
-(gdb) info macro N
+(@value{GDBP}) info macro N
Defined at /home/jimb/gdb/macros/play/sample.c:9
#define N 28
-(gdb) macro expand N Q M
+(@value{GDBP}) macro expand N Q M
expands to: 28 < 42
-(gdb) print N Q M
+(@value{GDBP}) print N Q M
$1 = 1
-(gdb)
+(@value{GDBP})
@end smallexample
As we step over directives that remove @code{N}'s definition, and then
thereof) in force at each point:
@smallexample
-(gdb) next
+(@value{GDBP}) next
Hello, world!
12 printf ("We're so creative.\n");
-(gdb) info macro N
+(@value{GDBP}) 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
+(@value{GDBP}) next
We're so creative.
14 printf ("Goodbye, world!\n");
-(gdb) info macro N
+(@value{GDBP}) info macro N
Defined at /home/jimb/gdb/macros/play/sample.c:13
#define N 1729
-(gdb) macro expand N Q M
+(@value{GDBP}) macro expand N Q M
expands to: 1729 < 42
-(gdb) print N Q M
+(@value{GDBP}) print N Q M
$2 = 0
-(gdb)
+(@value{GDBP})
@end smallexample
This command takes no arguments. It ends the trace experiment, and
stops collecting data.
-@strong{Note:} a trace experiment and data collection may stop
+@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.
@table @code
@item overlay off
-@kindex overlay off
+@kindex overlay
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,
@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
@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.
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
@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
of the function the address falls in:
@smallexample
-(gdb) print main
+(@value{GDBP}) print main
$3 = @{int ()@} 0x11a0 <main>
@end smallexample
@noindent
unmapped overlay, @value{GDBN} prints it this way:
@smallexample
-(gdb) overlay list
+(@value{GDBP}) overlay list
No sections are mapped.
-(gdb) print foo
+(@value{GDBP}) print foo
$5 = @{int (int)@} 0x100000 <*foo*>
@end smallexample
@noindent
name normally:
@smallexample
-(gdb) overlay list
+(@value{GDBP}) overlay list
Section .ov.foo.text, loaded at 0x100000 - 0x100034,
mapped at 0x1016 - 0x104a
-(gdb) print foo
+(@value{GDBP}) print foo
$6 = @{int (int)@} 0x1016 <foo>
@end smallexample
@value{GDBN} infers that its language is the one indicated.
@table @file
+@item .ada
+@itemx .ads
+@itemx .adb
+@itemx .a
+Ada source file.
@item .c
C source file
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
build and compute expressions that may involve variables in your program.
@item info frame
+@kindex info frame@r{, show the source language}
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
+@kindex info source@r{, show the source language}
Display the source language of this source file.
@xref{Symbols, ,Examining the Symbol Table}, to identify the other
information listed here.
@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
@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
@node Support
@section Supported languages
-@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, and Modula-2.
+@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, Modula-2, and Ada.
@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,
* C:: C and C@t{++}
* Objective-C:: Objective-C
* Modula-2:: Modula-2
+* Ada:: Ada
@end menu
@node C
with certain Objective-C libraries that have a particular hook
function, @code{_NSPrintForDebugger}, defined.
-@node Modula-2, , Objective-C, Support
+@node Modula-2, Ada, Objective-C, Support
@subsection Modula-2
@cindex Modula-2, @value{GDBN} support
In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
interpreted as the beginning of a comment. Use @code{<>} instead.
+@node Ada
+@subsection Ada
+@cindex Ada
+
+The extensions made to @value{GDBN} for Ada only support
+output from the @sc{gnu} Ada (GNAT) compiler.
+Other Ada compilers are not currently supported, and
+attempting to debug executables produced by them is most likely
+to be difficult.
+
+
+@cindex expressions in Ada
+@menu
+* Ada Mode Intro:: General remarks on the Ada syntax
+ and semantics supported by Ada mode
+ in @value{GDBN}.
+* Omissions from Ada:: Restrictions on the Ada expression syntax.
+* Additions to Ada:: Extensions of the Ada expression syntax.
+* Stopping Before Main Program:: Debugging the program during elaboration.
+* Ada Glitches:: Known peculiarities of Ada mode.
+@end menu
+
+@node Ada Mode Intro
+@subsubsection Introduction
+@cindex Ada mode, general
+
+The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression
+syntax, with some extensions.
+The philosophy behind the design of this subset is
+
+@itemize @bullet
+@item
+That @value{GDBN} should provide basic literals and access to operations for
+arithmetic, dereferencing, field selection, indexing, and subprogram calls,
+leaving more sophisticated computations to subprograms written into the
+program (which therefore may be called from @value{GDBN}).
+
+@item
+That type safety and strict adherence to Ada language restrictions
+are not particularly important to the @value{GDBN} user.
+
+@item
+That brevity is important to the @value{GDBN} user.
+@end itemize
+
+Thus, for brevity, the debugger acts as if there were
+implicit @code{with} and @code{use} clauses in effect for all user-written
+packages, making it unnecessary to fully qualify most names with
+their packages, regardless of context. Where this causes ambiguity,
+@value{GDBN} asks the user's intent.
+
+The debugger will start in Ada mode if it detects an Ada main program.
+As for other languages, it will enter Ada mode when stopped in a program that
+was translated from an Ada source file.
+
+While in Ada mode, you may use `@t{--}' for comments. This is useful
+mostly for documenting command files. The standard @value{GDBN} comment
+(@samp{#}) still works at the beginning of a line in Ada mode, but not in the
+middle (to allow based literals).
+
+The debugger supports limited overloading. Given a subprogram call in which
+the function symbol has multiple definitions, it will use the number of
+actual parameters and some information about their types to attempt to narrow
+the set of definitions. It also makes very limited use of context, preferring
+procedures to functions in the context of the @code{call} command, and
+functions to procedures elsewhere.
+
+@node Omissions from Ada
+@subsubsection Omissions from Ada
+@cindex Ada, omissions from
+
+Here are the notable omissions from the subset:
+
+@itemize @bullet
+@item
+Only a subset of the attributes are supported:
+
+@itemize @minus
+@item
+@t{'First}, @t{'Last}, and @t{'Length}
+ on array objects (not on types and subtypes).
+
+@item
+@t{'Min} and @t{'Max}.
+
+@item
+@t{'Pos} and @t{'Val}.
+
+@item
+@t{'Tag}.
+
+@item
+@t{'Range} on array objects (not subtypes), but only as the right
+operand of the membership (@code{in}) operator.
+
+@item
+@t{'Access}, @t{'Unchecked_Access}, and
+@t{'Unrestricted_Access} (a GNAT extension).
+
+@item
+@t{'Address}.
+@end itemize
+
+@item
+The names in
+@code{Characters.Latin_1} are not available and
+concatenation is not implemented. Thus, escape characters in strings are
+not currently available.
+
+@item
+Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
+equality of representations. They will generally work correctly
+for strings and arrays whose elements have integer or enumeration types.
+They may not work correctly for arrays whose element
+types have user-defined equality, for arrays of real values
+(in particular, IEEE-conformant floating point, because of negative
+zeroes and NaNs), and for arrays whose elements contain unused bits with
+indeterminate values.
+
+@item
+The other component-by-component array operations (@code{and}, @code{or},
+@code{xor}, @code{not}, and relational tests other than equality)
+are not implemented.
+
+@item
+There are no record or array aggregates.
+
+@item
+Calls to dispatching subprograms are not implemented.
+
+@item
+The overloading algorithm is much more limited (i.e., less selective)
+than that of real Ada. It makes only limited use of the context in which a subexpression
+appears to resolve its meaning, and it is much looser in its rules for allowing
+type matches. As a result, some function calls will be ambiguous, and the user
+will be asked to choose the proper resolution.
+
+@item
+The @code{new} operator is not implemented.
+
+@item
+Entry calls are not implemented.
+
+@item
+Aside from printing, arithmetic operations on the native VAX floating-point
+formats are not supported.
+
+@item
+It is not possible to slice a packed array.
+@end itemize
+
+@node Additions to Ada
+@subsubsection Additions to Ada
+@cindex Ada, deviations from
+
+As it does for other languages, @value{GDBN} makes certain generic
+extensions to Ada (@pxref{Expressions}):
+
+@itemize @bullet
+@item
+If the expression @var{E} is a variable residing in memory
+(typically a local variable or array element) and @var{N} is
+a positive integer, then @code{@var{E}@@@var{N}} displays the values of
+@var{E} and the @var{N}-1 adjacent variables following it in memory as an array.
+In Ada, this operator is generally not necessary, since its prime use
+is in displaying parts of an array, and slicing will usually do this in Ada.
+However, there are occasional uses when debugging programs
+in which certain debugging information has been optimized away.
+
+@item
+@code{@var{B}::@var{var}} means ``the variable named @var{var} that appears
+in function or file @var{B}.'' When @var{B} is a file name, you must typically
+surround it in single quotes.
+
+@item
+The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
+@var{type} that appears at address @var{addr}.''
+
+@item
+A name starting with @samp{$} is a convenience variable
+(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
+@end itemize
+
+In addition, @value{GDBN} provides a few other shortcuts and outright additions specific
+to Ada:
+
+@itemize @bullet
+@item
+The assignment statement is allowed as an expression, returning
+its right-hand operand as its value. Thus, you may enter
+
+@smallexample
+set x := y + 3
+print A(tmp := y + 1)
+@end smallexample
+
+@item
+The semicolon is allowed as an ``operator,'' returning as its value
+the value of its right-hand operand.
+This allows, for example,
+complex conditional breaks:
+
+@smallexample
+break f
+condition 1 (report(i); k += 1; A(k) > 100)
+@end smallexample
+
+@item
+Rather than use catenation and symbolic character names to introduce special
+characters into strings, one may instead use a special bracket notation,
+which is also used to print strings. A sequence of characters of the form
+@samp{["@var{XX}"]} within a string or character literal denotes the
+(single) character whose numeric encoding is @var{XX} in hexadecimal. The
+sequence of characters @samp{["""]} also denotes a single quotation mark
+in strings. For example,
+@smallexample
+ "One line.["0a"]Next line.["0a"]"
+@end smallexample
+@noindent
+contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) after each
+period.
+
+@item
+The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
+@t{'Max} is optional (and is ignored in any case). For example, it is valid
+to write
+
+@smallexample
+print 'max(x, y)
+@end smallexample
+
+@item
+When printing arrays, @value{GDBN} uses positional notation when the
+array has a lower bound of 1, and uses a modified named notation otherwise.
+For example, a one-dimensional array of three integers with a lower bound of 3 might print as
+
+@smallexample
+(3 => 10, 17, 1)
+@end smallexample
+
+@noindent
+That is, in contrast to valid Ada, only the first component has a @code{=>}
+clause.
+
+@item
+You may abbreviate attributes in expressions with any unique,
+multi-character subsequence of
+their names (an exact match gets preference).
+For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh}
+in place of @t{a'length}.
+
+@item
+@cindex quoting Ada internal identifiers
+Since Ada is case-insensitive, the debugger normally maps identifiers you type
+to lower case. The GNAT compiler uses upper-case characters for
+some of its internal identifiers, which are normally of no interest to users.
+For the rare occasions when you actually have to look at them,
+enclose them in angle brackets to avoid the lower-case mapping.
+For example,
+@smallexample
+@value{GDBP} print <JMPBUF_SAVE>[0]
+@end smallexample
+
+@item
+Printing an object of class-wide type or dereferencing an
+access-to-class-wide value will display all the components of the object's
+specific type (as indicated by its run-time tag). Likewise, component
+selection on such a value will operate on the specific type of the
+object.
+
+@end itemize
+
+@node Stopping Before Main Program
+@subsubsection Stopping at the Very Beginning
+
+@cindex breakpointing Ada elaboration code
+It is sometimes necessary to debug the program during elaboration, and
+before reaching the main procedure.
+As defined in the Ada Reference
+Manual, the elaboration code is invoked from a procedure called
+@code{adainit}. To run your program up to the beginning of
+elaboration, simply use the following two commands:
+@code{tbreak adainit} and @code{run}.
+
+@node Ada Glitches
+@subsubsection Known Peculiarities of Ada Mode
+@cindex Ada, problems
+
+Besides the omissions listed previously (@pxref{Omissions from Ada}),
+we know of several problems with and limitations of Ada mode in
+@value{GDBN},
+some of which will be fixed with planned future releases of the debugger
+and the GNU Ada compiler.
+
+@itemize @bullet
+@item
+Currently, the debugger
+has insufficient information to determine whether certain pointers represent
+pointers to objects or the objects themselves.
+Thus, the user may have to tack an extra @code{.all} after an expression
+to get it printed properly.
+
+@item
+Static constants that the compiler chooses not to materialize as objects in
+storage are invisible to the debugger.
+
+@item
+Named parameter associations in function argument lists are ignored (the
+argument lists are treated as positional).
+
+@item
+Many useful library packages are currently invisible to the debugger.
+
+@item
+Fixed-point arithmetic, conversions, input, and output is carried out using
+floating-point arithmetic, and may give results that only approximate those on
+the host machine.
+
+@item
+The type of the @t{'Address} attribute may not be @code{System.Address}.
+
+@item
+The GNAT compiler never generates the prefix @code{Standard} for any of
+the standard symbols defined by the Ada language. @value{GDBN} knows about
+this: it will strip the prefix from names when you use it, and will never
+look for a name you have so qualified among local symbols, nor match against
+symbols in other packages or subprograms. If you have
+defined entities anywhere in your program other than parameters and
+local variables whose simple names match names in @code{Standard},
+GNAT's lack of qualification here can cause confusion. When this happens,
+you can usually resolve the confusion
+by qualifying the problematic names with package
+@code{Standard} explicitly.
+@end itemize
+
@node Unsupported languages
@section Unsupported languages
@node Calling
@section Calling program functions
+@table @code
@cindex calling functions
+@cindex inferior functions, calling
+@item print @var{expr}
+Evaluate the expression @var{expr} and displaying the resuling value.
+@var{expr} may include calls to functions in the program being
+debugged.
+
@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.
+execute a function from your program that does not return anything
+(a.k.a.@: @dfn{a void function}), but without cluttering the output
+with @code{void} returned values that @value{GDBN} will otherwise
+print. If the result is not void, it is printed and saved in the
+value history.
+@end table
+
+@cindex weak alias functions
+Sometimes, a function you wish to call is actually a @dfn{weak alias}
+for another function. In such case, @value{GDBN} might not pick up
+the type information, including the types of the function arguments,
+which causes @value{GDBN} to call the inferior function incorrectly.
+As a result, the called function will function erroneously and may
+even crash. A solution to that is to use the name of the aliased
+function instead.
@node Patching
@section Patching programs
@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.
+(available on the command line, see @ref{File Options, , -readnow},
+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
@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{]}
+@itemx core
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
is @code{off}, symbols must be loaded manually, using the
@code{sharedlibrary} command. The default value is @code{on}.
+@cindex memory used for symbol tables
+If your program uses lots of shared libraries with debug info that
+takes large amounts of memory, you can decrease the @value{GDBN}
+memory footprint by preventing it from automatically loading the
+symbols from shared libraries. To that end, type @kbd{set
+auto-solib-add off} before running the inferior, then load each
+library whose debug symbols you do need with @kbd{sharedlibrary
+@var{regexp}}, where @var{regexp} is a regular expresion that matches
+the libraries whose symbols you want to be loaded.
+
@kindex show auto-solib-add
@item show auto-solib-add
Display the current autoloading mode.
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}
+@kindex gnu_debuglink_crc32
@smallexample
unsigned long
gnu_debuglink_crc32 (unsigned long crc,
and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
@end table
+@cindex common targets
Here are some common targets (available, or not, depending on the GDB
configuration):
@table @code
-@kindex target exec
+@kindex target
@item target exec @var{program}
+@cindex executable file target
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}
+@cindex core dump file target
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}
+@cindex remote target
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}
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
+@cindex built-in simulator target
Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
In general,
@smallexample
@table @code
-@kindex target nrom
@item target nrom @var{dev}
+@cindex NetROM ROM emulator target
NetROM ROM emulator. This target only supports downloading.
@end table
@value{GDBN}'s idea of processor endian-ness manually.
@table @code
-@kindex set endian big
+@kindex set endian
@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.
@table @code
@item set_debug_traps
-@kindex set_debug_traps
+@findex 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
+@findex 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
@table @code
@item int getDebugChar()
-@kindex getDebugChar
+@findex 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
+@findex 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.
@table @code
@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
-@kindex exceptionHandler
+@findex 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
help from @code{exceptionHandler}.
@item void flush_i_cache()
-@kindex flush_i_cache
+@findex 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.
@table @code
@item void *memset(void *, int, int)
-@kindex memset
+@findex 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
@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.
+@cindex /proc
+@cindex examine process image
+@cindex process info via @file{/proc}
+
+Many versions of SVR4 and compatible systems 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 information about the process running
+your program, or about any process running on your system. @code{info
+proc} works only on SVR4 systems that include the @code{procfs} code.
+This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
+Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
@table @code
@kindex info proc
+@cindex process ID
@item info proc
-Summarize available information about the process.
+@itemx info proc @var{process-id}
+Summarize available information about any running process. If a
+process ID is specified by @var{process-id}, display information about
+that process; otherwise display information about the program being
+debugged. The summary includes the debugged process ID, the command
+line used to invoke it, its current working directory, and its
+executable file's absolute file name.
+
+On some systems, @var{process-id} can be of the form
+@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID
+within a process. If the optional @var{pid} part is missing, it means
+a thread from the process being debugged (the leading @samp{/} still
+needs to be present, or else @value{GDBN} will interpret the number as
+a process ID rather than a thread ID).
-@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.
+@cindex memory address space mappings
+Report the memory address space ranges accessible in the program, with
+information on whether the process has read, write, or execute access
+rights to each range. On @sc{gnu}/Linux systems, each memory range
+includes the object file which is mapped to that range, instead of the
+memory access rights to that range.
+
+@item info proc stat
+@itemx info proc status
+@cindex process detailed status information
+These subcommands are specific to @sc{gnu}/Linux systems. They show
+the process-related information, including the user ID and group ID;
+how many threads are there in the process; its virtual memory usage;
+the signals that are pending, blocked, and ignored; its TTY; its
+consumption of system and user time; its stack size; its @samp{nice}
+value; etc. For more information, see the @samp{proc(5)} man page
+(type @kbd{man 5 proc} from your shell prompt).
+
+@item info proc all
+Show all the information about the process described under all of the
+above @code{info proc} subcommands.
+
@ignore
@comment These sub-options of 'info proc' were not included when
@comment procfs.c was re-written. Keep their descriptions around
@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
@pxref{Symbols}). Here's an example:
@smallexample
-(gdb) info function CreateFileA
+(@value{GDBP}) info function CreateFileA
All functions matching regular expression "CreateFileA":
Non-debugging symbols:
@end smallexample
@smallexample
-(gdb) info function !
+(@value{GDBP}) info function !
All functions matching regular expression "!":
Non-debugging symbols:
problem:
@smallexample
-(gdb) print 'cygwin1!__argv'
+(@value{GDBP}) print 'cygwin1!__argv'
$1 = 268572168
@end smallexample
@smallexample
-(gdb) x 'cygwin1!__argv'
+(@value{GDBP}) x 'cygwin1!__argv'
0x10021610: "\230y\""
@end smallexample
And two possible solutions:
@smallexample
-(gdb) print ((char **)'cygwin1!__argv')[0]
+(@value{GDBP}) print ((char **)'cygwin1!__argv')[0]
$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
@end smallexample
@smallexample
-(gdb) x/2x &'cygwin1!__argv'
+(@value{GDBP}) x/2x &'cygwin1!__argv'
0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
-(gdb) x/x 0x10021608
+(@value{GDBP}) x/x 0x10021608
0x10021608: 0x0022fd98
-(gdb) x/s 0x0022fd98
+(@value{GDBP}) x/s 0x0022fd98
0x22fd98: "/cygdrive/c/mydirectory/myprogram"
@end smallexample
to set the breakpoint at a raw memory address:
@smallexample
-(gdb) break *&'python22!PyOS_Readline'
+(@value{GDBP}) break *&'python22!PyOS_Readline'
Breakpoint 1 at 0x1e04eff0
@end smallexample
this manual was produced; newer releases of VxWorks may use revised
procedures.
-@kindex INCLUDE_RDB
+@findex 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
@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
-@kindex htrace info
+@kindex htrace
@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.
@cindex readline
@cindex command line editing
-@value{GDBN} reads its input commands via the @dfn{readline} interface. This
+@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
Show whether command line editing is enabled.
@end table
+@xref{Command Line Editing}, for more details about the Readline
+interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
+encouraged to read that chapter.
+
@node History
@section Command history
+@cindex 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.
+@value{GDBN} uses the @sc{gnu} History library, a part of the Readline
+package, to provide the history facility. @xref{Using History
+Interactively}, for the detailed description of the History library.
+
+Here is the description of @value{GDBN} commands related to command
+history.
+
@table @code
@cindex history substitution
@cindex history file
@kindex set history filename
-@kindex GDBHISTFILE
+@cindex @env{GDBHISTFILE}, environment variable
@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
is not set.
@cindex history save
-@kindex set history save
+@kindex set history
@item set history save
@itemx set history save on
Record command history in a file, whose name may be specified with the
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
+@xref{Event Designators}, for more details.
+@cindex history expansion, turn on/off
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
The commands to control history expansion are:
@table @code
-@kindex set history expansion
@item set history expansion on
@itemx set history expansion
+@kindex 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
@node Debugging Output
@section Optional messages about internal happenings
+@cindex optional debugging messages
+
@table @code
-@kindex set debug arch
+@kindex set debug
+@cindex gdbarch debugging info
@item set debug arch
Turns on or off display of gdbarch debugging info. The default is off
-@kindex show debug arch
+@kindex show debug
@item show debug arch
Displays the current state of displaying gdbarch debugging info.
-@kindex set debug event
@item set debug event
+@cindex event debugging info
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
+@cindex expression debugging info
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
+@cindex frame debugging info
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 observer
+@item set debug infrun
+@cindex inferior debugging info
+Turns on or off display of @value{GDBN} debugging info for running the inferior.
+The default is off. @file{infrun.c} contains GDB's runtime state machine used
+for implementing operations such as single-stepping the inferior.
+@item show debug infrun
+Displays the current state of @value{GDBN} inferior debugging.
@item set debug observer
+@cindex observer debugging info
Turns on or off display of @value{GDBN} observer debugging. This
includes info such as the notification of observable events.
-@kindex show debug observer
@item show debug observer
Displays the current state of observer debugging.
-@kindex set debug overload
@item set debug overload
+@cindex C@t{++} overload debugging info
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
+@cindex target debugging info
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 0. Set it to 1 to track events, and to 2 to also track the
value of large memory transfers. Changes to this flag do not take effect
until the next time you connect to a target or use the @code{run} command.
-@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
+@cindex variable object debugging info
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.
@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)
@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
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.
+occurs, the hook is not re-executed, thereby avoiding infinite 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!
List and give the size of all displayed windows.
@item layout next
-@kindex layout next
+@kindex layout
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
@table @code
@item @var{output} @expansion{}
-@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
+@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
@item @var{result-record} @expansion{}
@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
This GDB was configured as "i386-pc-linux-gnu"
^Z^Zpre-prompt
-(gdb)
+(@value{GDBP})
^Z^Zprompt
@kbd{quit}
@value{GDBN} session.
@smallexample
-(gdb) @kbd{maint internal-error testing, 1, 2}
+(@value{GDBP}) @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)
+(@value{GDBP})
@end smallexample
Takes an optional parameter that is used as the text of the error or
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
@smallexample
-(gdb) @kbd{b add}
+(@value{GDBP}) @kbd{b add}
@dots{}
-(gdb) @kbd{print add(2,3)}
+(@value{GDBP}) @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}
+(@value{GDBP}) @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)
+(@value{GDBP})
@end smallexample
Takes an optional file parameter.
Takes an optional file parameter.
@smallexample
-(gdb) @kbd{maint print reggroups}
+(@value{GDBP}) @kbd{maint print reggroups}
Group Type
general user
float user
Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
compiled with the @samp{-pg} compiler option.
+@kindex maint set dwarf2 max-cache-age
+@kindex maint show dwarf2 max-cache-age
+@item maint set dwarf2 max-cache-age
+@itemx maint show dwarf2 max-cache-age
+Control the DWARF 2 compilation unit cache.
+
+In object files with inter-compilation-unit references, such as those
+produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
+reader needs to frequently refer to previously read compilation units.
+This setting controls how long a compilation unit will remain in the cache
+if it is not referenced. Setting it to zero disables caching, which will
+slow down @value{GDBN} startup but reduce memory consumption.
+
@end table
@item @code{O} --- reserved
-Reserved for future use.
-
-@item @code{p}@var{n@dots{}} --- read reg @strong{(reserved)}
+@item @code{p}@var{hex number of register} --- read register packet
@cindex @code{p} packet
-@xref{write register packet}.
+@xref{read registers packet}, for a description of how the returned
+register value is encoded.
Reply:
@table @samp
-@item @var{r@dots{}.}
-The hex encoded value of the register in target byte order.
+@item @var{XX@dots{}}
+the register's value
+@item E@var{NN}
+for an error
+@item
+Indicating an unrecognized @var{query}.
@end table
@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register
@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}.
+escaped using @code{0x7d}, and then XORed with @code{0x20}.
+For example, @code{0x7d} would be transmitted as @code{0x7d 0x5d}.
Reply:
@table @samp
Reply:
@table @samp
@item @code{QC}@var{pid}
-Where @var{pid} is a HEX encoded 16 bit process id.
+Where @var{pid} is an unsigned hexidecimal process id.
@item *
Any other reply implies the old pid.
@end table
@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'}).
+more thread ids, in big-endian unsigned 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
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.
+
+@item @code{qGetTLSAddr}:@var{thread-id},@var{offset},@var{lm} --- get thread local storage address
+
+Fetch the address associated with thread local storage specified
+by @var{thread-id}, @var{offset}, and @var{lm}.
+
+@var{thread-id} is the (big endian, hex encoded) thread id associated with the
+thread for which to fetch the TLS address.
+
+@var{offset} is the (big endian, hex encoded) offset associated with the
+thread local variable. (This offset is obtained from the debug
+information associated with the variable.)
+
+@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
+the load module associated with the thread local storage. For example,
+a @sc{gnu}/Linux system will pass the link map address of the shared
+object associated with the thread local storage under consideration.
+Other operating environments may choose to represent the load module
+differently, so the precise meaning of this parameter will vary.
+
+Reply:
+@table @asis
+@item @var{XX@dots{}}
+Hex encoded (big endian) bytes representing the address of the thread
+local storage requested.
+
+@item @code{E}@var{nn} (where @var{nn} are hex digits)
+An error occurred.
+
+@item @code{""} (empty)
+An empty reply indicates that @code{qGetTLSAddr} is not supported by the stub.
+@end table
+
@end table
@node Register Packet Format
request from @value{GDBN} is required.
@smallexample
-(gdb) continue
+(@value{GDBP}) continue
<- target requests 'system call X'
target is stopped, @value{GDBN} executes system call
-> GDB returns result
projects / deliverable / binutils-gdb.git / blobdiff