\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
+@c 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
+@c 2010, 2011 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
ISBN 1-882114-77-9 @*
@insertcopying
-@page
-This edition of the GDB manual is dedicated to the memory of Fred
-Fish. Fred was a long-standing contributor to GDB and to Free
-software in general. We will miss him.
@end titlepage
@page
* GDB Bugs:: Reporting bugs in @value{GDBN}
+@ifset SYSTEM_READLINE
+* Command Line Editing: (rluserman). Command Line Editing
+* Using History Interactively: (history). Using History Interactively
+@end ifset
+@ifclear SYSTEM_READLINE
* Command Line Editing:: Command Line Editing
* Using History Interactively:: Using History Interactively
+@end ifclear
+* In Memoriam:: In Memoriam
* Formatting Documentation:: How to format and print @value{GDBN} documentation
* Installing GDB:: Installing GDB
* Maintenance Commands:: Maintenance Commands
* Operating System Information:: Getting additional information from
the operating system
* Trace File Format:: GDB trace file format
+* Index Section Format:: .gdb_index section format
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
Support for Modula-2 is partial. For information on Modula-2, see
@ref{Modula-2,,Modula-2}.
+Support for OpenCL C is partial. For information on OpenCL C, see
+@ref{OpenCL C,,OpenCL C}.
+
@cindex Pascal
Debugging Pascal programs which use sets, subranges, file variables, or
nested functions does not currently work. @value{GDBN} does not support
Run @value{GDBN} using @var{directory} as its working directory,
instead of the current directory.
+@item -data-directory @var{directory}
+@cindex @code{--data-directory}
+Run @value{GDBN} using @var{directory} as its data directory.
+The data directory is where @value{GDBN} searches for its
+auxiliary files. @xref{Data Files}.
+
@item -fullname
@itemx -f
@cindex @code{--fullname}
to the program you are debugging, in the directory where you invoke
@value{GDBN}.
+@item
+If the command line specified a program to debug, or a process to
+attach to, or a core file, @value{GDBN} loads any auto-loaded
+scripts provided for the program or for its loaded shared libraries.
+@xref{Auto-loading}.
+
+If you wish to disable the auto-loading during startup,
+you must do something like the following:
+
+@smallexample
+$ gdb -ex "set auto-load-scripts off" -ex "file myprogram"
+@end smallexample
+
+The following does not work because the auto-loading is turned off too late:
+
+@smallexample
+$ gdb -ex "set auto-load-scripts off" myprogram
+@end smallexample
+
@item
Reads command files specified by the @samp{-x} option. @xref{Command
Files}, for more details about @value{GDBN} command files.
@smallexample
(@value{GDBP}) p gdb_stdout.@kbd{M-?}
-magic to_delete to_fputs to_put to_rewind
-to_data to_flush to_isatty to_read to_write
+magic to_fputs to_rewind
+to_data to_isatty to_write
+to_delete to_put to_write_async_safe
+to_flush to_read
@end smallexample
@noindent
int *magic;
ui_file_flush_ftype *to_flush;
ui_file_write_ftype *to_write;
+ ui_file_write_async_safe_ftype *to_write_async_safe;
ui_file_fputs_ftype *to_fputs;
ui_file_read_ftype *to_read;
ui_file_delete_ftype *to_delete;
systems @value{GDBN} can add inferiors to the debug session
automatically by following calls to @code{fork} and @code{exec}. To
remove inferiors from the debugging session use the
-@w{@code{remove-inferior}} command.
+@w{@code{remove-inferiors}} command.
@table @code
@kindex add-inferior
You can now simply switch focus to inferior 2 and run it.
-@kindex remove-inferior
-@item remove-inferior @var{infno}
-Removes the inferior @var{infno}. It is not possible to remove an
-inferior that is running with this command. For those, use the
-@code{kill} or @code{detach} command first.
+@kindex remove-inferiors
+@item remove-inferiors @var{infno}@dots{}
+Removes the inferior or inferiors @var{infno}@dots{}. It is not
+possible to remove an inferior that is running with this command. For
+those, use the @code{kill} or @code{detach} command first.
@end table
To quit debugging one of the running inferiors that is not the current
inferior, you can either detach from it by using the @w{@code{detach
inferior}} command (allowing it to run independently), or kill it
-using the @w{@code{kill inferior}} command:
+using the @w{@code{kill inferiors}} command:
@table @code
-@kindex detach inferior @var{infno}
-@item detach inferior @var{infno}
-Detach from the inferior identified by @value{GDBN} inferior number
-@var{infno}. Note that the inferior's entry still stays on the list
-of inferiors shown by @code{info inferiors}, but its Description will
-show @samp{<null>}.
+@kindex detach inferiors @var{infno}@dots{}
+@item detach inferior @var{infno}@dots{}
+Detach from the inferior or inferiors identified by @value{GDBN}
+inferior number(s) @var{infno}@dots{}. Note that the inferior's entry
+still stays on the list of inferiors shown by @code{info inferiors},
+but its Description will show @samp{<null>}.
-@kindex kill inferior @var{infno}
-@item kill inferior @var{infno}
-Kill the inferior identified by @value{GDBN} inferior number
-@var{infno}. Note that the inferior's entry still stays on the list
-of inferiors shown by @code{info inferiors}, but its Description will
-show @samp{<null>}.
+@kindex kill inferiors @var{infno}@dots{}
+@item kill inferiors @var{infno}@dots{}
+Kill the inferior or inferiors identified by @value{GDBN} inferior
+number(s) @var{infno}@dots{}. Note that the inferior's entry still
+stays on the list of inferiors shown by @code{info inferiors}, but its
+Description will show @samp{<null>}.
@end table
After the successful completion of a command such as @code{detach},
-@code{detach inferior}, @code{kill} or @code{kill inferior}, or after
+@code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after
a normal process exit, the inferior is still valid and listed with
@code{info inferiors}, ready to be restarted.
@sc{gnu}/Linux, you might see
@smallexample
-[New Thread 46912507313328 (LWP 25582)]
+[New Thread 0x41e02940 (LWP 25582)]
@end smallexample
@noindent
@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):
+@item info threads @r{[}@var{id}@dots{}@r{]}
+Display a summary of all threads currently in your program. Optional
+argument @var{id}@dots{} is one or more thread ids separated by spaces, and
+means to print information only about the specified thread or threads.
+@value{GDBN} displays for each thread (in this order):
@enumerate
@item
@item
the target system's thread identifier (@var{systag})
+@item
+the thread's name, if one is known. A thread can either be named by
+the user (see @code{thread name}, below), or, in some cases, by the
+program itself.
+
@item
the current stack frame summary for that thread
@end enumerate
@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)
+ Id Target Id Frame
+ 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 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.
-
-@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 (HP-UX)
-@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
-
On Solaris, you can display more information about user threads with a
Solaris-specific command:
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 ()
+[Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]
+#0 some_function (ignore=0x0) at example.c:8
+8 printf ("hello\n");
@end smallexample
@noindent
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{threadno}] [@var{all}] @var{command}
+@item thread apply [@var{threadno} | all] @var{command}
The @code{thread apply} command allows you to apply the named
@var{command} to one or more threads. Specify the numbers of the
threads that you want affected with the command argument
could be a range of thread numbers, as in @code{2-4}. To apply a
command to all threads, type @kbd{thread apply all @var{command}}.
+@kindex thread name
+@cindex name a thread
+@item thread name [@var{name}]
+This command assigns a name to the current thread. If no argument is
+given, any existing user-specified name is removed. The thread name
+appears in the @samp{info threads} display.
+
+On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to
+determine the name of the thread as given by the OS. On these
+systems, a name specified with @samp{thread name} will override the
+system-give name, and removing the user-specified name will cause
+@value{GDBN} to once again display the system-specified name.
+
+@kindex thread find
+@cindex search for a thread
+@item thread find [@var{regexp}]
+Search for and display thread ids whose name or @var{systag}
+matches the supplied regular expression.
+
+As well as being the complement to the @samp{thread name} command,
+this command also allows you to identify a thread by its target
+@var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag}
+is the LWP id.
+
+@smallexample
+(@value{GDBN}) thread find 26688
+Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
+(@value{GDBN}) info thread 4
+ Id Target Id Frame
+ 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()
+@end smallexample
+
@kindex set print thread-events
@cindex print messages on thread start and exit
@item set print thread-events
If this variable is set, @var{path} is a colon-separated list of
directories @value{GDBN} will use to search for @code{libthread_db}.
If you omit @var{path}, @samp{libthread-db-search-path} will be reset to
-an empty list.
+its default value.
On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper''
@code{libthread_db} library to obtain information about threads in the
Programs, ,Debugging Multiple Inferiors and Programs}).
To quit debugging one of the forked processes, you can either detach
-from it by using the @w{@code{detach inferior}} command (allowing it
-to run independently), or kill it using the @w{@code{kill inferior}}
+from it by using the @w{@code{detach inferiors}} command (allowing it
+to run independently), or kill it using the @w{@code{kill inferiors}}
command. @xref{Inferiors and Programs, ,Debugging Multiple Inferiors
and Programs}.
@kindex info breakpoints
@cindex @code{$_} and @code{info breakpoints}
-@item info breakpoints @r{[}@var{n}@r{]}
-@itemx info break @r{[}@var{n}@r{]}
+@item info breakpoints @r{[}@var{n}@dots{}@r{]}
+@itemx info break @r{[}@var{n}@dots{}@r{]}
Print a table of all breakpoints, watchpoints, and catchpoints set and
not deleted. Optional argument @var{n} means print information only
-about the specified breakpoint (or watchpoint or catchpoint). For
-each breakpoint, following columns are printed:
+about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)).
+For each breakpoint, following columns are printed:
@table @emph
@item Breakpoint Numbers
@table @code
@kindex watch
-@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]}
+@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint for an expression. @value{GDBN} will break when the
expression @var{expr} is written into by the program and its value
changes. The simplest (and the most popular) use of this command is
@end smallexample
If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
-clause, @value{GDBN} breaks only when the thread identified by
+argument, @value{GDBN} breaks only when the thread identified by
@var{threadnum} changes the value of @var{expr}. If any other threads
change the value of @var{expr}, @value{GDBN} will not break. Note
that watchpoints restricted to a single thread in this way only work
result does not have an address, then @value{GDBN} will print an
error.
+The @code{@r{[}mask @var{maskvalue}@r{]}} argument allows creation
+of masked watchpoints, if the current architecture supports this
+feature (e.g., PowerPC Embedded architecture, see @ref{PowerPC
+Embedded}.) A @dfn{masked watchpoint} specifies a mask in addition
+to an address to watch. The mask specifies that some bits of an address
+(the bits which are reset in the mask) should be ignored when matching
+the address accessed by the inferior against the watchpoint address.
+Thus, a masked watchpoint watches many addresses simultaneously---those
+addresses whose unmasked bits are identical to the unmasked bits in the
+watchpoint address. The @code{mask} argument implies @code{-location}.
+Examples:
+
+@smallexample
+(@value{GDBP}) watch foo mask 0xffff00ff
+(@value{GDBP}) watch *0xdeadbeef mask 0xffffff00
+@end smallexample
+
@kindex rwatch
-@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]}
+@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint that will break when the value of @var{expr} is read
by the program.
@kindex awatch
-@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]}
+@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
-@kindex info watchpoints @r{[}@var{n}@r{]}
-@item info watchpoints
+@kindex info watchpoints @r{[}@var{n}@dots{}@r{]}
+@item info watchpoints @r{[}@var{n}@dots{}@r{]}
This command prints a list of watchpoints, using the same format as
@code{info break} (@pxref{Set Breaks}).
@end table
@kbd{set print frame-arguments} in @ref{Print Settings} for more details
on how to configure the way function parameter values are printed.
-@cindex value optimized out, in backtrace
+@cindex optimized out, in backtrace
@cindex function call arguments, optimized out
If your program was compiled with optimizations, some compilers will
optimize away arguments passed to functions if those arguments are
@group
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
-#1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242
-#2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08)
+#1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242
+#2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08)
at macro.c:71
(More stack frames follow...)
@end group
@noindent
The values of arguments that were not saved in their stack frames are
-shown as @samp{<value optimized out>}.
+shown as @samp{<optimized out>}.
If you need to display the values of such optimized-out arguments,
either deduce that from other variables whose values depend on the one
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{function}:@var{label}
+Specifies the line where @var{label} appears in @var{function}.
+
@item @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
@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 set directories @var{path-list}
+@kindex set directories
+Set the source path to @var{path-list}.
+@samp{$cdir:$cwd} are added if missing.
+
@item show directories
@kindex show directories
Print the source path: show which directories it contains.
@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.
+Remove items from the list of expressions to display. Specify the
+numbers of the displays that you want affected with the command
+argument @var{dnums}. It can be a single display number, one of the
+numbers shown in the first field of the @samp{info display} display;
+or it could be a range of display numbers, as in @code{2-4}.
@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{}}.)
@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.
+enabled again later. Specify the numbers of the displays that you
+want affected with the command argument @var{dnums}. It can be a
+single display number, one of the numbers shown in the first field of
+the @samp{info display} display; or it could be a range of display
+numbers, as in @code{2-4}.
@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.
+Specify the numbers of the displays that you want affected with the
+command argument @var{dnums}. It can be a single display number, one
+of the numbers shown in the first field of the @samp{info display}
+display; or it could be a range of display numbers, as in @code{2-4}.
@item display
Display the current values of the expressions on the list, just as is
Python code. It greatly simplifies the display of complex objects. This
mechanism works for both MI and the CLI.
-For example, here is how a C@t{++} @code{std::string} looks without a
-pretty-printer:
+@menu
+* Pretty-Printer Introduction:: Introduction to pretty-printers
+* Pretty-Printer Example:: An example pretty-printer
+* Pretty-Printer Commands:: Pretty-printer commands
+@end menu
+
+@node Pretty-Printer Introduction
+@subsection Pretty-Printer Introduction
+
+When @value{GDBN} prints a value, it first sees if there is a pretty-printer
+registered for the value. If there is then @value{GDBN} invokes the
+pretty-printer to print the value. Otherwise the value is printed normally.
+
+Pretty-printers are normally named. This makes them easy to manage.
+The @samp{info pretty-printer} command will list all the installed
+pretty-printers with their names.
+If a pretty-printer can handle multiple data types, then its
+@dfn{subprinters} are the printers for the individual data types.
+Each such subprinter has its own name.
+The format of the name is @var{printer-name};@var{subprinter-name}.
+
+Pretty-printers are installed by @dfn{registering} them with @value{GDBN}.
+Typically they are automatically loaded and registered when the corresponding
+debug information is loaded, thus making them available without having to
+do anything special.
+
+There are three places where a pretty-printer can be registered.
+
+@itemize @bullet
+@item
+Pretty-printers registered globally are available when debugging
+all inferiors.
+
+@item
+Pretty-printers registered with a program space are available only
+when debugging that program.
+@xref{Progspaces In Python}, for more details on program spaces in Python.
+
+@item
+Pretty-printers registered with an objfile are loaded and unloaded
+with the corresponding objfile (e.g., shared library).
+@xref{Objfiles In Python}, for more details on objfiles in Python.
+@end itemize
+
+@xref{Selecting Pretty-Printers}, for further information on how
+pretty-printers are selected,
+
+@xref{Writing a Pretty-Printer}, for implementing pretty printers
+for new types.
+
+@node Pretty-Printer Example
+@subsection Pretty-Printer Example
+
+Here is how a C@t{++} @code{std::string} looks without a pretty-printer:
@smallexample
(@value{GDBP}) print s
$2 = "abcd"
@end smallexample
-For implementing pretty printers for new types you should read the Python API
-details (@pxref{Pretty Printing API}).
+@node Pretty-Printer Commands
+@subsection Pretty-Printer Commands
+@cindex pretty-printer commands
+
+@table @code
+@kindex info pretty-printer
+@item info pretty-printer [@var{object-regexp} [@var{name-regexp}]]
+Print the list of installed pretty-printers.
+This includes disabled pretty-printers, which are marked as such.
+
+@var{object-regexp} is a regular expression matching the objects
+whose pretty-printers to list.
+Objects can be @code{global}, the program space's file
+(@pxref{Progspaces In Python}),
+and the object files within that program space (@pxref{Objfiles In Python}).
+@xref{Selecting Pretty-Printers}, for details on how @value{GDBN}
+looks up a printer from these three objects.
+
+@var{name-regexp} is a regular expression matching the name of the printers
+to list.
+
+@kindex disable pretty-printer
+@item disable pretty-printer [@var{object-regexp} [@var{name-regexp}]]
+Disable pretty-printers matching @var{object-regexp} and @var{name-regexp}.
+A disabled pretty-printer is not forgotten, it may be enabled again later.
+
+@kindex enable pretty-printer
+@item enable pretty-printer [@var{object-regexp} [@var{name-regexp}]]
+Enable pretty-printers matching @var{object-regexp} and @var{name-regexp}.
+@end table
+
+Example:
+
+Suppose we have three pretty-printers installed: one from library1.so
+named @code{foo} that prints objects of type @code{foo}, and
+another from library2.so named @code{bar} that prints two types of objects,
+@code{bar1} and @code{bar2}.
+
+@smallexample
+(gdb) info pretty-printer
+library1.so:
+ foo
+library2.so:
+ bar
+ bar1
+ bar2
+(gdb) info pretty-printer library2
+library2.so:
+ bar
+ bar1
+ bar2
+(gdb) disable pretty-printer library1
+1 printer disabled
+2 of 3 printers enabled
+(gdb) info pretty-printer
+library1.so:
+ foo [disabled]
+library2.so:
+ bar
+ bar1
+ bar2
+(gdb) disable pretty-printer library2 bar:bar1
+1 printer disabled
+1 of 3 printers enabled
+(gdb) info pretty-printer library2
+library1.so:
+ foo [disabled]
+library2.so:
+ bar
+ bar1 [disabled]
+ bar2
+(gdb) disable pretty-printer library2 bar
+1 printer disabled
+0 of 3 printers enabled
+(gdb) info pretty-printer library2
+library1.so:
+ foo [disabled]
+library2.so:
+ bar [disabled]
+ bar1 [disabled]
+ bar2
+@end smallexample
+
+Note that for @code{bar} the entire printer can be disabled,
+as can each individual subprinter.
@node Value History
@section Value History
support for static tracing includes being able to list instrumentation
points, and attach them with @value{GDBN} defined high level
tracepoints that expose the whole range of convenience of
-@value{GDBN}'s tracepoints support. Namelly, support for collecting
+@value{GDBN}'s tracepoints support. Namely, support for collecting
registers values and values of global or local (to the instrumentation
point) variables; tracepoint conditions and trace state variables.
The act of installing a @value{GDBN} static tracepoint on an
@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 trace experiment, but it is not forgotten. You can re-enable
a disabled tracepoint using the @code{enable tracepoint} command.
+If the command is issued during a trace experiment and the debug target
+has support for disabling tracepoints during a trace experiment, then the
+change will be effective immediately. Otherwise, it will be applied to the
+next trace experiment.
@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.
+Enable tracepoint @var{num}, or all tracepoints. If this command is
+issued during a trace experiment and the debug target supports enabling
+tracepoints during a trace experiment, then the enabled tracepoints will
+become effective immediately. Otherwise, they will become effective the
+next time a trace experiment is run.
@end table
@node Tracepoint Passcounts
Unlike breakpoint conditions, @value{GDBN} does not actually evaluate
the conditional expression itself. Instead, @value{GDBN} encodes the
-expression into an agent expression (@pxref{Agent Expressions}
+expression into an agent expression (@pxref{Agent Expressions})
suitable for execution on the target, independently of @value{GDBN}.
Global variables become raw memory locations, locals become stack
accesses, and so forth.
@subsection Listing Tracepoints
@table @code
-@kindex info tracepoints
-@kindex info tp
+@kindex info tracepoints @r{[}@var{n}@dots{}@r{]}
+@kindex info tp @r{[}@var{n}@dots{}@r{]}
@cindex information about tracepoints
-@item info tracepoints @r{[}@var{num}@r{]}
+@item info tracepoints @r{[}@var{num}@dots{}@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. The format is similar to that used for
(@value{GDBP}) @b{tstop}
@end smallexample
+@anchor{disconnected tracing}
@cindex disconnected tracing
You can choose to continue running the trace experiment even if
@value{GDBN} disconnects from the target, voluntarily or
collecting. This is especially useful if your tracepoints are being
hit too often, and your trace gets terminated prematurely because the
buffer is full. To ask for a circular trace buffer, simply set
-@samp{circular_trace_buffer} to on. You can set this at any time,
+@samp{circular-trace-buffer} to on. You can set this at any time,
including during tracing; if the agent can do it, it will change
buffer handling on the fly, otherwise it will not take effect until
the next run.
@node Supported Languages
@section Supported Languages
-@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, Pascal,
+@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, OpenCL C, Pascal,
assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
* C:: C and C@t{++}
* D:: D
* Objective-C:: Objective-C
+* OpenCL C:: OpenCL C
* Fortran:: Fortran
* Pascal:: Pascal
* Modula-2:: Modula-2
with certain Objective-C libraries that have a particular hook
function, @code{_NSPrintForDebugger}, defined.
+@node OpenCL C
+@subsection OpenCL C
+
+@cindex OpenCL C
+This section provides information about @value{GDBN}s OpenCL C support.
+
+@menu
+* OpenCL C Datatypes::
+* OpenCL C Expressions::
+* OpenCL C Operators::
+@end menu
+
+@node OpenCL C Datatypes
+@subsubsection OpenCL C Datatypes
+
+@cindex OpenCL C Datatypes
+@value{GDBN} supports the builtin scalar and vector datatypes specified
+by OpenCL 1.1. In addition the half- and double-precision floating point
+data types of the @code{cl_khr_fp16} and @code{cl_khr_fp64} OpenCL
+extensions are also known to @value{GDBN}.
+
+@node OpenCL C Expressions
+@subsubsection OpenCL C Expressions
+
+@cindex OpenCL C Expressions
+@value{GDBN} supports accesses to vector components including the access as
+lvalue where possible. Since OpenCL C is based on C99 most C expressions
+supported by @value{GDBN} can be used as well.
+
+@node OpenCL C Operators
+@subsubsection OpenCL C Operators
+
+@cindex OpenCL C Operators
+@value{GDBN} supports the operators specified by OpenCL 1.1 for scalar and
+vector data types.
+
@node Fortran
@subsection Fortran
@cindex Fortran-specific support in @value{GDBN}
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.
automatically if the installed @value{GDBN} is moved to a new
location.
+The data directory may also be specified with the
+@code{--data-directory} command line option.
+@xref{Mode Options}.
+
@node Targets
@chapter Specifying a Debugging Target
@subsection Running @code{gdbserver}
@cindex arguments, to @code{gdbserver}
+@cindex @code{gdbserver}, command-line arguments
Run @code{gdbserver} on the target system. You need a copy of the
program you want to debug, including any libraries it requires.
@code{target remote} command.
@subsubsection Attaching to a Running Program
+@cindex attach to a program, @code{gdbserver}
+@cindex @option{--attach}, @code{gdbserver} option
On some targets, @code{gdbserver} can also attach to running programs.
This is accomplished via the @code{--attach} argument. The syntax is:
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:
@code{-s} option to only return the first process ID.
@subsubsection Multi-Process Mode for @code{gdbserver}
-@cindex gdbserver, multiple processes
-@cindex multiple processes with gdbserver
+@cindex @code{gdbserver}, multiple processes
+@cindex multiple processes with @code{gdbserver}
When you connect to @code{gdbserver} using @code{target remote},
@code{gdbserver} debugs the specified program only once. When the
arguments are supported, except for wildcard expansion and I/O
redirection (@pxref{Arguments}).
+@cindex @option{--multi}, @code{gdbserver} option
To start @code{gdbserver} without supplying an initial command to run
or process ID to attach, use the @option{--multi} command line option.
Then you can connect using @kbd{target extended-remote} and start
the program you want to debug.
-@code{gdbserver} does not automatically exit in multi-process mode.
-You can terminate it by using @code{monitor exit}
-(@pxref{Monitor Commands for gdbserver}).
+In multi-process mode @code{gdbserver} does not automatically exit unless you
+use the option @option{--once}. You can terminate it by using
+@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the
+conditions under which @code{gdbserver} terminates depend on how @value{GDBN}
+connects to it (@kbd{target remote} or @kbd{target extended-remote}). The
+@option{--multi} option to @code{gdbserver} has no influence on that.
+
+@subsubsection TCP port allocation lifecycle of @code{gdbserver}
+
+This section applies only when @code{gdbserver} is run to listen on a TCP port.
+
+@code{gdbserver} normally terminates after all of its debugged processes have
+terminated in @kbd{target remote} mode. On the other hand, for @kbd{target
+extended-remote}, @code{gdbserver} stays running even with no processes left.
+@value{GDBN} normally terminates the spawned debugged process on its exit,
+which normally also terminates @code{gdbserver} in the @kbd{target remote}
+mode. Therefore, when the connection drops unexpectedly, and @value{GDBN}
+cannot ask @code{gdbserver} to kill its debugged processes, @code{gdbserver}
+stays running even in the @kbd{target remote} mode.
+
+When @code{gdbserver} stays running, @value{GDBN} can connect to it again later.
+Such reconnecting is useful for features like @ref{disconnected tracing}. For
+completeness, at most one @value{GDBN} can be connected at a time.
+
+@cindex @option{--once}, @code{gdbserver} option
+By default, @code{gdbserver} keeps the listening TCP port open, so that
+additional connections are possible. However, if you start @code{gdbserver}
+with the @option{--once} option, it will stop listening for any further
+connection attempts after connecting to the first @value{GDBN} session. This
+means no further connections to @code{gdbserver} will be possible after the
+first one. It also means @code{gdbserver} will terminate after the first
+connection with remote @value{GDBN} has closed, even for unexpectedly closed
+connections and even in the @kbd{target extended-remote} mode. The
+@option{--once} option allows reusing the same port number for connecting to
+multiple instances of @code{gdbserver} running on the same host, since each
+instance closes its port after the first connection.
@subsubsection Other Command-Line Arguments for @code{gdbserver}
+@cindex @option{--debug}, @code{gdbserver} option
The @option{--debug} option tells @code{gdbserver} to display extra
-status information about the debugging process. The
-@option{--remote-debug} option tells @code{gdbserver} to display
+status information about the debugging process.
+@cindex @option{--remote-debug}, @code{gdbserver} option
+The @option{--remote-debug} option tells @code{gdbserver} to display
remote protocol debug output. These options are intended for
@code{gdbserver} development and for bug reports to the developers.
+@cindex @option{--wrapper}, @code{gdbserver} option
The @option{--wrapper} option specifies a wrapper to launch programs
for debugging. The option should be followed by the name of the
wrapper, then any command-line arguments to pass to the wrapper, then
When this command is issued, @var{path} is a colon-separated list of
directories to search for @code{libthread_db} (@pxref{Threads,,set
libthread-db-search-path}). If you omit @var{path},
-@samp{libthread-db-search-path} will be reset to an empty list.
+@samp{libthread-db-search-path} will be reset to its default value.
@item monitor exit
Tell gdbserver to exit immediately. This command should be followed by
@item @code{query-attached}
@tab @code{qAttached}
@tab Querying remote process attach state.
+
+@item @code{traceframe-info}
+@tab @code{qXfer:traceframe-info:read}
+@tab Traceframe info
@end multitable
@node Remote Stub
if @var{ADDRESS|VARIABLE} == @var{CONSTANT EXPRESSION}
@end smallexample
-The DVC register will be automatically used whenever @value{GDBN} detects
-such pattern in a condition expression. This feature is available in native
-@value{GDBN} running on a Linux kernel version 2.6.34 or newer.
+The DVC register will be automatically used when @value{GDBN} detects
+such pattern in a condition expression, and the created watchpoint uses one
+debug register (either the @code{exact-watchpoints} option is on and the
+variable is scalar, or the variable has a length of one byte). This feature
+is available in native @value{GDBN} running on a Linux kernel version 2.6.34
+or newer.
+
+When running on PowerPC embedded processors, @value{GDBN} automatically uses
+ranged hardware watchpoints, unless the @code{exact-watchpoints} option is on,
+in which case watchpoints using only one debug register are created when
+watching variables of scalar types.
+
+You can create an artificial array to watch an arbitrary memory
+region using one of the following commands (@pxref{Expressions}):
+
+@smallexample
+(@value{GDBP}) watch *((char *) @var{address})@@@var{length}
+(@value{GDBP}) watch @{char[@var{length}]@} @var{address}
+@end smallexample
+
+PowerPC embedded processors support masked watchpoints. See the discussion
+about the @code{mask} argument in @ref{Set Watchpoints}.
+
+@cindex ranged breakpoint
+PowerPC embedded processors support hardware accelerated
+@dfn{ranged breakpoints}. A ranged breakpoint stops execution of
+the inferior whenever it executes an instruction at any address within
+the range it specifies. To set a ranged breakpoint in @value{GDBN},
+use the @code{break-range} command.
@value{GDBN} provides the following PowerPC-specific commands:
@table @code
+@kindex break-range
+@item break-range @var{start-location}, @var{end-location}
+Set a breakpoint for an address range.
+@var{start-location} and @var{end-location} can specify a function name,
+a line number, an offset of lines from the current line or from the start
+location, or an address of an instruction (see @ref{Specify Location},
+for a list of all the possible ways to specify a @var{location}.)
+The breakpoint will stop execution of the inferior whenever it
+executes an instruction at any address within the specified range,
+(including @var{start-location} and @var{end-location}.)
+
@kindex set powerpc
@item set powerpc soft-float
@itemx show powerpc soft-float
registers. By default, @value{GDBN} selects the calling convention
based on the selected architecture and the provided executable file.
+@item set powerpc exact-watchpoints
+@itemx show powerpc exact-watchpoints
+Allow @value{GDBN} to use only one debug register when watching a variable
+of scalar type, thus assuming that the variable is accessed through the
+address of its first byte.
+
@kindex target dink32
@item target dink32 @var{dev}
DINK32 ROM monitor.
Show whether command line editing is enabled.
@end table
-@xref{Command Line Editing}, for more details about the Readline
+@ifset SYSTEM_READLINE
+@xref{Command Line Editing, , , rluserman, GNU Readline Library},
+@end ifset
+@ifclear SYSTEM_READLINE
+@xref{Command Line Editing},
+@end ifclear
+for more details about the Readline
interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
encouraged to read that chapter.
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.
+package, to provide the history facility.
+@ifset SYSTEM_READLINE
+@xref{Using History Interactively, , , history, GNU History Library},
+@end ifset
+@ifclear SYSTEM_READLINE
+@xref{Using History Interactively},
+@end ifclear
+for the detailed description of the History library.
To issue a command to @value{GDBN} without affecting certain aspects of
the state which is seen by users, prefix it with @samp{server }
@end table
History expansion assigns special meaning to the character @kbd{!}.
-@xref{Event Designators}, for more details.
+@ifset SYSTEM_READLINE
+@xref{Event Designators, , , history, GNU History Library},
+@end ifset
+@ifclear SYSTEM_READLINE
+@xref{Event Designators},
+@end ifclear
+for more details.
@cindex history expansion, turn on/off
Since @kbd{!} is also the logical not operator in C, history expansion
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 jit
+@cindex just-in-time compilation, debugging messages
+Turns on or off debugging messages from JIT debug support.
+@item show debug jit
+Displays the current state of @value{GDBN} JIT debugging.
@item set debug lin-lwp
@cindex @sc{gnu}/Linux LWP debug messages
@cindex Linux lightweight processes
Turns on or off debugging messages from the Linux LWP debug support.
@item show debug lin-lwp
Show the current state of Linux LWP debugging messages.
-@item set debug lin-lwp-async
-@cindex @sc{gnu}/Linux LWP async debug messages
-@cindex Linux lightweight processes
-Turns on or off debugging messages from the Linux LWP async debug support.
-@item show debug lin-lwp-async
-Show the current state of Linux LWP async debugging messages.
@item set debug observer
@cindex observer debugging info
Turns on or off display of @value{GDBN} observer debugging. This
@table @code
@kindex set interactive-mode
@item set interactive-mode
-If @code{on}, forces @value{GDBN} to operate interactively.
-If @code{off}, forces @value{GDBN} to operate non-interactively,
-If @code{auto} (the default), @value{GDBN} guesses which mode to use,
-based on whether the debugger was started in a terminal or not.
+If @code{on}, forces @value{GDBN} to assume that GDB was started
+in a terminal. In practice, this means that @value{GDBN} should wait
+for the user to answer queries generated by commands entered at
+the command prompt. If @code{off}, forces @value{GDBN} to operate
+in the opposite mode, and it uses the default answers to all queries.
+If @code{auto} (the default), @value{GDBN} tries to determine whether
+its standard input is a terminal, and works in interactive-mode if it
+is, non-interactively otherwise.
In the vast majority of cases, the debugger should be able to guess
correctly which mode should be used. But this setting can be useful
@cindex python directory
Python scripts used by @value{GDBN} should be installed in
@file{@var{data-directory}/python}, where @var{data-directory} is
-the data directory as determined at @value{GDBN} startup (@pxref{Data Files}). This directory, known as the @dfn{python directory},
+the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
+This directory, known as the @dfn{python directory},
is automatically added to the Python Search Path in order to allow
the Python interpreter to locate all scripts installed at this location.
* Python Commands:: Accessing Python from @value{GDBN}.
* Python API:: Accessing @value{GDBN} from Python.
* Auto-loading:: Automatically loading Python code.
+* Python modules:: Python modules provided by @value{GDBN}.
@end menu
@node Python Commands
@menu
* Basic Python:: Basic Python Functions.
-* Exception Handling::
-* Values From Inferior::
+* Exception Handling:: How Python exceptions are translated.
+* Values From Inferior:: Python representation of values.
* Types In Python:: Python representation of types.
* Pretty Printing API:: Pretty-printing values.
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
-* Disabling Pretty-Printers:: Disabling broken printers.
+* Writing a Pretty-Printer:: Writing a Pretty-Printer.
* Inferiors In Python:: Python representation of inferiors (processes)
+* Events In Python:: Listening for events from @value{GDBN}.
* Threads In Python:: Accessing inferior threads from Python.
* Commands In Python:: Implementing new commands in Python.
* Parameters In Python:: Adding new @value{GDBN} parameters.
@samp{print object} is a valid parameter name.
If the named parameter does not exist, this function throws a
-@code{RuntimeError}. Otherwise, the parameter's value is converted to
-a Python value of the appropriate type, and returned.
+@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
+parameter's value is converted to a Python value of the appropriate
+type, and returned.
@end defun
@findex gdb.history
and count backward from the last element (i.e., the most recent element) to
find the value to return. If @var{number} is zero, then @value{GDBN} will
return the most recent element. If the element specified by @var{number}
-doesn't exist in the value history, a @code{RuntimeError} exception will be
+doesn't exist in the value history, a @code{gdb.error} exception will be
raised.
If no exception is raised, the return value is always an instance of
@end smallexample
@end defun
-@findex gdb.write
-@defun write string
-Print a string to @value{GDBN}'s paginated standard output stream.
+@findex gdb.write
+@defun write string @r{[}stream{]}
+Print a string to @value{GDBN}'s paginated output stream. The
+optional @var{stream} determines the stream to print to. The default
+stream is @value{GDBN}'s standard output stream. Possible stream
+values are:
+
+@table @code
+@findex STDOUT
+@findex gdb.STDOUT
+@item STDOUT
+@value{GDBN}'s standard output stream.
+
+@findex STDERR
+@findex gdb.STDERR
+@item STDERR
+@value{GDBN}'s standard error stream.
+
+@findex STDLOG
+@findex gdb.STDLOG
+@item STDLOG
+@value{GDBN}'s log stream (@pxref{Logging Output}).
+@end table
+
Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
-call this function.
+call this function and will automatically direct the output to the
+relevant stream.
@end defun
@findex gdb.flush
@defun flush
-Flush @value{GDBN}'s paginated standard output stream. Flushing
-@code{sys.stdout} or @code{sys.stderr} will automatically call this
-function.
+Flush the buffer of a @value{GDBN} paginated stream so that the
+contents are displayed immediately. @value{GDBN} will flush the
+contents of a stream automatically when it encounters a newline in the
+buffer. The optional @var{stream} determines the stream to flush. The
+default stream is @value{GDBN}'s standard output stream. Possible
+stream values are:
+
+@table @code
+@findex STDOUT
+@findex gdb.STDOUT
+@item STDOUT
+@value{GDBN}'s standard output stream.
+
+@findex STDERR
+@findex gdb.STDERR
+@item STDERR
+@value{GDBN}'s standard error stream.
+
+@findex STDLOG
+@findex gdb.STDLOG
+@item STDLOG
+@value{GDBN}'s log stream (@pxref{Logging Output}).
+
+@end table
+
+Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
+call this function for the relevant stream.
@end defun
@findex gdb.target_charset
NameError: name 'foo' is not defined
@end smallexample
-@value{GDBN} errors that happen in @value{GDBN} commands invoked by Python
-code are converted to Python @code{RuntimeError} exceptions. User
-interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
-prompt) is translated to a Python @code{KeyboardInterrupt}
-exception. If you catch these exceptions in your Python code, your
-exception handler will see @code{RuntimeError} or
-@code{KeyboardInterrupt} as the exception type, the @value{GDBN} error
-message as its value, and the Python call stack backtrace at the
-Python statement closest to where the @value{GDBN} error occured as the
+@value{GDBN} errors that happen in @value{GDBN} commands invoked by
+Python code are converted to Python exceptions. The type of the
+Python exception depends on the error.
+
+@ftable @code
+@item gdb.error
+This is the base class for most exceptions generated by @value{GDBN}.
+It is derived from @code{RuntimeError}, for compatibility with earlier
+versions of @value{GDBN}.
+
+If an error occurring in @value{GDBN} does not fit into some more
+specific category, then the generated exception will have this type.
+
+@item gdb.MemoryError
+This is a subclass of @code{gdb.error} which is thrown when an
+operation tried to access invalid memory in the inferior.
+
+@item KeyboardInterrupt
+User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
+prompt) is translated to a Python @code{KeyboardInterrupt} exception.
+@end ftable
+
+In all cases, your exception handler will see the @value{GDBN} error
+message as its value and the Python call stack backtrace at the Python
+statement closest to where the @value{GDBN} error occured as the
traceback.
@findex gdb.GdbError
Return a Python @code{Tuple} object that contains two elements: the
low bound of the argument type and the high bound of that type. If
the type does not have a range, @value{GDBN} will raise a
-@code{RuntimeError} exception.
+@code{gdb.error} exception (@pxref{Exception Handling}).
@end defmethod
@defmethod Type reference
convenience functions.
@end table
+Further support for types is provided in the @code{gdb.types}
+Python module (@pxref{gdb.types}).
+
@node Pretty Printing API
@subsubsection Pretty Printing API
The Python list @code{gdb.pretty_printers} contains an array of
functions or callable objects that have been registered via addition
-as a pretty-printer.
+as a pretty-printer. Printers in this list are called @code{global}
+printers, they're available when debugging all inferiors.
Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
Each @code{gdb.Objfile} also contains a @code{pretty_printers}
attribute.
-A function on one of these lists is passed a single @code{gdb.Value}
+Each function on these lists is passed a single @code{gdb.Value}
argument and should return a pretty-printer object conforming to the
interface definition above (@pxref{Pretty Printing API}). If a function
cannot create a pretty-printer for the value, it should return
@value{GDBN} first checks the @code{pretty_printers} attribute of each
@code{gdb.Objfile} in the current program space and iteratively calls
-each enabled function (@pxref{Disabling Pretty-Printers})
-in the list for that @code{gdb.Objfile} until it receives
-a pretty-printer object.
+each enabled lookup routine in the list for that @code{gdb.Objfile}
+until it receives a pretty-printer object.
If no pretty-printer is found in the objfile lists, @value{GDBN} then
searches the pretty-printer list of the current program space,
calling each enabled function until an object is returned.
and iterated over sequentially until the end of the list, or a printer
object is returned.
+For various reasons a pretty-printer may not work.
+For example, the underlying data structure may have changed and
+the pretty-printer is out of date.
+
+The consequences of a broken pretty-printer are severe enough that
+@value{GDBN} provides support for enabling and disabling individual
+printers. For example, if @code{print frame-arguments} is on,
+a backtrace can become highly illegible if any argument is printed
+with a broken printer.
+
+Pretty-printers are enabled and disabled by attaching an @code{enabled}
+attribute to the registered function or callable object. If this attribute
+is present and its value is @code{False}, the printer is disabled, otherwise
+the printer is enabled.
+
+@node Writing a Pretty-Printer
+@subsubsection Writing a Pretty-Printer
+@cindex writing a pretty-printer
+
+A pretty-printer consists of two parts: a lookup function to detect
+if the type is supported, and the printer itself.
+
Here is an example showing how a @code{std::string} printer might be
-written:
+written. @xref{Pretty Printing API}, for details on the API this class
+must provide.
@smallexample
-class StdStringPrinter:
+class StdStringPrinter(object):
"Print a std::string"
- def __init__ (self, val):
+ def __init__(self, val):
self.val = val
- def to_string (self):
+ def to_string(self):
return self.val['_M_dataplus']['_M_p']
- def display_hint (self):
+ def display_hint(self):
return 'string'
@end smallexample
example above might be written.
@smallexample
-def str_lookup_function (val):
-
+def str_lookup_function(val):
lookup_tag = val.type.tag
- regex = re.compile ("^std::basic_string<char,.*>$")
if lookup_tag == None:
return None
- if regex.match (lookup_tag):
- return StdStringPrinter (val)
-
+ regex = re.compile("^std::basic_string<char,.*>$")
+ if regex.match(lookup_tag):
+ return StdStringPrinter(val)
return None
@end smallexample
this code might appear in @code{gdb.libstdcxx.v6}:
@smallexample
-def register_printers (objfile):
- objfile.pretty_printers.add (str_lookup_function)
+def register_printers(objfile):
+ objfile.pretty_printers.add(str_lookup_function)
@end smallexample
@noindent
@smallexample
import gdb.libstdcxx.v6
-gdb.libstdcxx.v6.register_printers (gdb.current_objfile ())
+gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
@end smallexample
-@node Disabling Pretty-Printers
-@subsubsection Disabling Pretty-Printers
-@cindex disabling pretty-printers
+The previous example illustrates a basic pretty-printer.
+There are a few things that can be improved on.
+The printer doesn't have a name, making it hard to identify in a
+list of installed printers. The lookup function has a name, but
+lookup functions can have arbitrary, even identical, names.
-For various reasons a pretty-printer may not work.
-For example, the underlying data structure may have changed and
-the pretty-printer is out of date.
+Second, the printer only handles one type, whereas a library typically has
+several types. One could install a lookup function for each desired type
+in the library, but one could also have a single lookup function recognize
+several types. The latter is the conventional way this is handled.
+If a pretty-printer can handle multiple data types, then its
+@dfn{subprinters} are the printers for the individual data types.
-The consequences of a broken pretty-printer are severe enough that
-@value{GDBN} provides support for enabling and disabling individual
-printers. For example, if @code{print frame-arguments} is on,
-a backtrace can become highly illegible if any argument is printed
-with a broken printer.
+The @code{gdb.printing} module provides a formal way of solving these
+problems (@pxref{gdb.printing}).
+Here is another example that handles multiple types.
-Pretty-printers are enabled and disabled by attaching an @code{enabled}
-attribute to the registered function or callable object. If this attribute
-is present and its value is @code{False}, the printer is disabled, otherwise
-the printer is enabled.
+These are the types we are going to pretty-print:
+
+@smallexample
+struct foo @{ int a, b; @};
+struct bar @{ struct foo x, y; @};
+@end smallexample
+
+Here are the printers:
+
+@smallexample
+class fooPrinter:
+ """Print a foo object."""
+
+ def __init__(self, val):
+ self.val = val
+
+ def to_string(self):
+ return ("a=<" + str(self.val["a"]) +
+ "> b=<" + str(self.val["b"]) + ">")
+
+class barPrinter:
+ """Print a bar object."""
+
+ def __init__(self, val):
+ self.val = val
+
+ def to_string(self):
+ return ("x=<" + str(self.val["x"]) +
+ "> y=<" + str(self.val["y"]) + ">")
+@end smallexample
+
+This example doesn't need a lookup function, that is handled by the
+@code{gdb.printing} module. Instead a function is provided to build up
+the object that handles the lookup.
+
+@smallexample
+import gdb.printing
+
+def build_pretty_printer():
+ pp = gdb.printing.RegexpCollectionPrettyPrinter(
+ "my_library")
+ pp.add_printer('foo', '^foo$', fooPrinter)
+ pp.add_printer('bar', '^bar$', barPrinter)
+ return pp
+@end smallexample
+
+And here is the autoload support:
+
+@smallexample
+import gdb.printing
+import my_library
+gdb.printing.register_pretty_printer(
+ gdb.current_objfile(),
+ my_library.build_pretty_printer())
+@end smallexample
+
+Finally, when this printer is loaded into @value{GDBN}, here is the
+corresponding output of @samp{info pretty-printer}:
+
+@smallexample
+(gdb) info pretty-printer
+my_library.so:
+ my_library
+ foo
+ bar
+@end smallexample
@node Inferiors In Python
@subsubsection Inferiors In Python
-@cindex inferiors in python
+@cindex inferiors in Python
@findex gdb.Inferior
Programs which are being run under @value{GDBN} are called inferiors
A @code{gdb.Inferior} object has the following methods:
@table @code
+@defmethod Inferior is_valid
+Returns @code{True} if the @code{gdb.Inferior} object is valid,
+@code{False} if not. A @code{gdb.Inferior} object will become invalid
+if the inferior no longer exists within @value{GDBN}. All other
+@code{gdb.Inferior} methods will throw an exception if it is invalid
+at the time the method is called.
+@end defmethod
+
@defmethod Inferior threads
This method returns a tuple holding all the threads which are valid
when it is called. If there are no valid threads, the method will
@end defmethod
@end table
+@node Events In Python
+@subsubsection Events In Python
+@cindex inferior events in Python
+
+@value{GDBN} provides a general event facility so that Python code can be
+notified of various state changes, particularly changes that occur in
+the inferior.
+
+An @dfn{event} is just an object that describes some state change. The
+type of the object and its attributes will vary depending on the details
+of the change. All the existing events are described below.
+
+In order to be notified of an event, you must register an event handler
+with an @dfn{event registry}. An event registry is an object in the
+@code{gdb.events} module which dispatches particular events. A registry
+provides methods to register and unregister event handlers:
+
+@table @code
+@defmethod EventRegistry connect object
+Add the given callable @var{object} to the registry. This object will be
+called when an event corresponding to this registry occurs.
+@end defmethod
+
+@defmethod EventRegistry disconnect object
+Remove the given @var{object} from the registry. Once removed, the object
+will no longer receive notifications of events.
+@end defmethod
+@end table
+
+Here is an example:
+
+@smallexample
+def exit_handler (event):
+ print "event type: exit"
+ print "exit code: %d" % (event.exit_code)
+
+gdb.events.exited.connect (exit_handler)
+@end smallexample
+
+In the above example we connect our handler @code{exit_handler} to the
+registry @code{events.exited}. Once connected, @code{exit_handler} gets
+called when the inferior exits. The argument @dfn{event} in this example is
+of type @code{gdb.ExitedEvent}. As you can see in the example the
+@code{ExitedEvent} object has an attribute which indicates the exit code of
+the inferior.
+
+The following is a listing of the event registries that are available and
+details of the events they emit:
+
+@table @code
+
+@item events.cont
+Emits @code{gdb.ThreadEvent}.
+
+Some events can be thread specific when @value{GDBN} is running in non-stop
+mode. When represented in Python, these events all extend
+@code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
+events which are emitted by this or other modules might extend this event.
+Examples of these events are @code{gdb.BreakpointEvent} and
+@code{gdb.ContinueEvent}.
+
+@table @code
+@defivar ThreadEvent inferior_thread
+In non-stop mode this attribute will be set to the specific thread which was
+involved in the emitted event. Otherwise, it will be set to @code{None}.
+@end defivar
+@end table
+
+Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
+
+This event indicates that the inferior has been continued after a stop. For
+inherited attribute refer to @code{gdb.ThreadEvent} above.
+
+@item events.exited
+Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
+@code{events.ExitedEvent} has one attribute:
+@table @code
+@defivar ExitedEvent exit_code
+An integer representing the exit code which the inferior has returned.
+@end defivar
+@end table
+
+@item events.stop
+Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
+
+Indicates that the inferior has stopped. All events emitted by this registry
+extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
+will indicate the stopped thread when @value{GDBN} is running in non-stop
+mode. Refer to @code{gdb.ThreadEvent} above for more details.
+
+Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
+
+This event indicates that the inferior or one of its threads has received as
+signal. @code{gdb.SignalEvent} has the following attributes:
+
+@table @code
+@defivar SignalEvent stop_signal
+A string representing the signal received by the inferior. A list of possible
+signal values can be obtained by running the command @code{info signals} in
+the @value{GDBN} command prompt.
+@end defivar
+@end table
+
+Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
+
+@code{gdb.BreakpointEvent} event indicates that a breakpoint has been hit, and
+has the following attributes:
+
+@table @code
+@defivar BreakpointEvent breakpoint
+A reference to the breakpoint that was hit of type @code{gdb.Breakpoint}.
+@xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
+@end defivar
+@end table
+
+@end table
+
@node Threads In Python
@subsubsection Threads In Python
@cindex threads in python
A @code{gdb.InferiorThread} object has the following attributes:
@table @code
+@defivar InferiorThread name
+The name of the thread. If the user specified a name using
+@code{thread name}, then this returns that name. Otherwise, if an
+OS-supplied name is available, then it is returned. Otherwise, this
+returns @code{None}.
+
+This attribute can be assigned to. The new value must be a string
+object, which sets the new name, or @code{None}, which removes any
+user-specified thread name.
+@end defivar
+
@defivar InferiorThread num
ID of the thread, as assigned by GDB.
@end defivar
A @code{gdb.InferiorThread} object has the following methods:
@table @code
+@defmethod InferiorThread is_valid
+Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
+@code{False} if not. A @code{gdb.InferiorThread} object will become
+invalid if the thread exits, or the inferior that the thread belongs
+is deleted. All other @code{gdb.InferiorThread} methods will throw an
+exception if it is invalid at the time the method is called.
+@end defmethod
+
@defmethod InferiorThread switch
This changes @value{GDBN}'s currently selected thread to the one represented
by this object.
attribute. @value{GDBN} does validation when assignments are made.
@end defivar
+There are two methods that should be implemented in any
+@code{Parameter} class. These are:
+
+@defop Operation {parameter} get_set_string self
+@value{GDBN} will call this method when a @var{parameter}'s value has
+been changed via the @code{set} API (for example, @kbd{set foo off}).
+The @code{value} attribute has already been populated with the new
+value and may be used in output. This method must return a string.
+@end defop
+
+@defop Operation {parameter} get_show_string self svalue
+@value{GDBN} will call this method when a @var{parameter}'s
+@code{show} API has been invoked (for example, @kbd{show foo}). The
+argument @code{svalue} receives the string representation of the
+current value. This method must return a string.
+@end defop
When a new parameter is defined, its type must be specified. The
available types are represented by constants defined in the @code{gdb}
information.
@end defivar
+A @code{gdb.Objfile} object has the following methods:
+
+@defmethod Objfile is_valid
+Returns @code{True} if the @code{gdb.Objfile} object is valid,
+@code{False} if not. A @code{gdb.Objfile} object can become invalid
+if the object file it refers to is not loaded in @value{GDBN} any
+longer. All other @code{gdb.Objfile} methods will throw an exception
+if it is invalid at the time the method is called.
+@end defmethod
+
@node Frames In Python
@subsubsection Accessing inferior stack frames from Python.
stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
represents a frame in the stack. A @code{gdb.Frame} object is only valid
while its corresponding frame exists in the inferior's stack. If you try
-to use an invalid frame object, @value{GDBN} will throw a @code{RuntimeError}
-exception.
+to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
+exception (@pxref{Exception Handling}).
Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
operator, like:
Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
@end defun
+@findex gdb.newest_frame
+@defun newest_frame
+Return the newest frame object for the selected thread.
+@end defun
+
@defun frame_stop_reason_string reason
Return a string explaining the reason why @value{GDBN} stopped unwinding
frames, as expressed by the given @var{reason} code (an integer, see the
@end defmethod
@defmethod Frame type
-Returns the type of the frame. The value can be one of
-@code{gdb.NORMAL_FRAME}, @code{gdb.DUMMY_FRAME}, @code{gdb.SIGTRAMP_FRAME}
-or @code{gdb.SENTINEL_FRAME}.
+Returns the type of the frame. The value can be one of:
+@table @code
+@item gdb.NORMAL_FRAME
+An ordinary stack frame.
+
+@item gdb.DUMMY_FRAME
+A fake stack frame that was created by @value{GDBN} when performing an
+inferior function call.
+
+@item gdb.INLINE_FRAME
+A frame representing an inlined function. The function was inlined
+into a @code{gdb.NORMAL_FRAME} that is older than this one.
+
+@item gdb.SIGTRAMP_FRAME
+A signal trampoline frame. This is the frame created by the OS when
+it calls into a signal handler.
+
+@item gdb.ARCH_FRAME
+A fake stack frame representing a cross-architecture call.
+
+@item gdb.SENTINEL_FRAME
+This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
+newest frame.
+@end table
@end defmethod
@defmethod Frame unwind_stop_reason
will return @code{None}.
@end defun
+A @code{gdb.Block} object has the following methods:
+
+@table @code
+@defmethod Block is_valid
+Returns @code{True} if the @code{gdb.Block} object is valid,
+@code{False} if not. A block object can become invalid if the block it
+refers to doesn't exist anymore in the inferior. All other
+@code{gdb.Block} methods will throw an exception if it is invalid at
+the time the method is called. This method is also made available to
+the Python iterator object that @code{gdb.Block} provides in an iteration
+context and via the Python @code{iter} built-in function.
+@end defmethod
+@end table
+
A @code{gdb.Block} object has the following attributes:
@table @code
module:
@findex gdb.lookup_symbol
-@defun lookup_symbol name [block] [domain]
+@defun lookup_symbol name @r{[}block@r{]} @r{[}domain@r{]}
This function searches for a symbol by name. The search scope can be
restricted to the parameters defined in the optional domain and block
arguments.
@var{name} is the name of the symbol. It must be a string. The
optional @var{block} argument restricts the search to symbols visible
in that @var{block}. The @var{block} argument must be a
-@code{gdb.Block} object. The optional @var{domain} argument restricts
+@code{gdb.Block} object. If omitted, the block for the current frame
+is used. The optional @var{domain} argument restricts
the search to the domain type. The @var{domain} argument must be a
domain constant defined in the @code{gdb} module and described later
in this chapter.
+
+The result is a tuple of two elements.
+The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
+is not found.
+If the symbol is found, the second element is @code{True} if the symbol
+is a field of a method's object (e.g., @code{this} in C@t{++}),
+otherwise it is @code{False}.
+If the symbol is not found, the second element is @code{False}.
+@end defun
+
+@findex gdb.lookup_global_symbol
+@defun lookup_global_symbol name @r{[}domain@r{]}
+This function searches for a global symbol by name.
+The search scope can be restricted to by the domain argument.
+
+@var{name} is the name of the symbol. It must be a string.
+The optional @var{domain} argument restricts the search to the domain type.
+The @var{domain} argument must be a domain constant defined in the @code{gdb}
+module and described later in this chapter.
+
+The result is a @code{gdb.Symbol} object or @code{None} if the symbol
+is not found.
@end defun
A @code{gdb.Symbol} object has the following attributes:
@end defivar
@end table
+A @code{gdb.Symbol} object has the following methods:
+
+@table @code
+@defmethod Symbol is_valid
+Returns @code{True} if the @code{gdb.Symbol} object is valid,
+@code{False} if not. A @code{gdb.Symbol} object can become invalid if
+the symbol it refers to does not exist in @value{GDBN} any longer.
+All other @code{gdb.Symbol} methods will throw an exception if it is
+invalid at the time the method is called.
+@end defmethod
+@end table
+
The available domain categories in @code{gdb.Symbol} are represented
as constants in the @code{gdb} module:
@end defivar
@end table
+A @code{gdb.Symtab_and_line} object has the following methods:
+
+@table @code
+@defmethod Symtab_and_line is_valid
+Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
+@code{False} if not. A @code{gdb.Symtab_and_line} object can become
+invalid if the Symbol table and line object it refers to does not
+exist in @value{GDBN} any longer. All other
+@code{gdb.Symtab_and_line} methods will throw an exception if it is
+invalid at the time the method is called.
+@end defmethod
+@end table
+
A @code{gdb.Symtab} object has the following attributes:
@table @code
@end defivar
@end table
-The following methods are provided:
+A @code{gdb.Symtab} object has the following methods:
@table @code
+@defmethod Symtab is_valid
+Returns @code{True} if the @code{gdb.Symtab} object is valid,
+@code{False} if not. A @code{gdb.Symtab} object can become invalid if
+the symbol table it refers to does not exist in @value{GDBN} any
+longer. All other @code{gdb.Symtab} methods will throw an exception
+if it is invalid at the time the method is called.
+@end defmethod
+
@defmethod Symtab fullname
Return the symbol table's source absolute file name.
@end defmethod
Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
class.
-@defmethod Breakpoint __init__ spec @r{[}type@r{]} @r{[}wp_class@r{]}
+@defmethod Breakpoint __init__ spec @r{[}type@r{]} @r{[}wp_class@r{]} @r{[}internal@r{]}
Create a new breakpoint. @var{spec} is a string naming the
location of the breakpoint, or an expression that defines a
watchpoint. The contents can be any location recognized by the
command. The optional @var{type} denotes the breakpoint to create
from the types defined later in this chapter. This argument can be
either: @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}. @var{type}
-defaults to @code{BP_BREAKPOINT}. The optional @var{wp_class}
+defaults to @code{BP_BREAKPOINT}. The optional @var{internal} argument
+allows the breakpoint to become invisible to the user. The breakpoint
+will neither be reported when created, nor will it be listed in the
+output from @code{info breakpoints} (but will be listed with the
+@code{maint info breakpoints} command). The optional @var{wp_class}
argument defines the class of watchpoint to create, if @var{type} is
-defined as @code{BP_WATCHPOINT}. If a watchpoint class is not
-provided, it is assumed to be a @var{WP_WRITE} class.
+@code{BP_WATCHPOINT}. If a watchpoint class is not provided, it is
+assumed to be a @var{WP_WRITE} class.
@end defmethod
+@defop Operation {gdb.Breakpoint} stop (self)
+The @code{gdb.Breakpoint} class can be sub-classed and, in
+particular, you may choose to implement the @code{stop} method.
+If this method is defined as a sub-class of @code{gdb.Breakpoint},
+it will be called when the inferior reaches any location of a
+breakpoint which instantiates that sub-class. If the method returns
+@code{True}, the inferior will be stopped at the location of the
+breakpoint, otherwise the inferior will continue.
+
+If there are multiple breakpoints at the same location with a
+@code{stop} method, each one will be called regardless of the
+return status of the previous. This ensures that all @code{stop}
+methods have a chance to execute at that location. In this scenario
+if one of the methods returns @code{True} but the others return
+@code{False}, the inferior will still be stopped.
+
+Example @code{stop} implementation:
+
+@smallexample
+class MyBreakpoint (gdb.Breakpoint):
+ def stop (self):
+ inf_val = gdb.parse_and_eval("foo")
+ if inf_val == 3:
+ return True
+ return False
+@end smallexample
+@end defop
+
The available watchpoint types represented by constants are defined in the
@code{gdb} module:
inferior leaves the scope of that watchpoint.
@end defmethod
+@defmethod Breakpoint delete
+Permanently deletes the @value{GDBN} breakpoint. This also
+invalidates the Python @code{Breakpoint} object. Any further access
+to this object's attributes or methods will raise an error.
+@end defmethod
+
@defivar Breakpoint enabled
This attribute is @code{True} if the breakpoint is enabled, and
@code{False} otherwise. This attribute is writable.
writable.
@end defivar
+@defivar Breakpoint visible
+This attribute tells whether the breakpoint is visible to the user
+when set, or when the @samp{info breakpoints} command is run. This
+attribute is not writable.
+@end defivar
+
The available types are represented by constants defined in the @code{gdb}
module:
Auto-loading can be enabled or disabled.
@table @code
-@kindex maint set python auto-load
-@item maint set python auto-load [yes|no]
-Enable or disable the Python auto-loading feature.
+@kindex set auto-load-scripts
+@item set auto-load-scripts [yes|no]
+Enable or disable the auto-loading of Python scripts.
-@kindex maint show python auto-load
-@item maint show python auto-load
-Show whether Python auto-loading is enabled or disabled.
+@kindex show auto-load-scripts
+@item show auto-load-scripts
+Show whether auto-loading of Python scripts is enabled or disabled.
@end table
When reading an auto-loaded file, @value{GDBN} sets the
top of the source tree to the source search path.
@end itemize
+@node Python modules
+@subsection Python modules
+@cindex python modules
+
+@value{GDBN} comes with a module to assist writing Python code.
+
+@menu
+* gdb.printing:: Building and registering pretty-printers.
+* gdb.types:: Utilities for working with types.
+@end menu
+
+@node gdb.printing
+@subsubsection gdb.printing
+@cindex gdb.printing
+
+This module provides a collection of utilities for working with
+pretty-printers.
+
+@table @code
+@item PrettyPrinter (@var{name}, @var{subprinters}=None)
+This class specifies the API that makes @samp{info pretty-printer},
+@samp{enable pretty-printer} and @samp{disable pretty-printer} work.
+Pretty-printers should generally inherit from this class.
+
+@item SubPrettyPrinter (@var{name})
+For printers that handle multiple types, this class specifies the
+corresponding API for the subprinters.
+
+@item RegexpCollectionPrettyPrinter (@var{name})
+Utility class for handling multiple printers, all recognized via
+regular expressions.
+@xref{Writing a Pretty-Printer}, for an example.
+
+@item register_pretty_printer (@var{obj}, @var{printer})
+Register @var{printer} with the pretty-printer list of @var{obj}.
+@end table
+
+@node gdb.types
+@subsubsection gdb.types
+@cindex gdb.types
+
+This module provides a collection of utilities for working with
+@code{gdb.Types} objects.
+
+@table @code
+@item get_basic_type (@var{type})
+Return @var{type} with const and volatile qualifiers stripped,
+and with typedefs and C@t{++} references converted to the underlying type.
+
+C@t{++} example:
+
+@smallexample
+typedef const int const_int;
+const_int foo (3);
+const_int& foo_ref (foo);
+int main () @{ return 0; @}
+@end smallexample
+
+Then in gdb:
+
+@smallexample
+(gdb) start
+(gdb) python import gdb.types
+(gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
+(gdb) python print gdb.types.get_basic_type(foo_ref.type)
+int
+@end smallexample
+
+@item has_field (@var{type}, @var{field})
+Return @code{True} if @var{type}, assumed to be a type with fields
+(e.g., a structure or union), has field @var{field}.
+
+@item make_enum_dict (@var{enum_type})
+Return a Python @code{dictionary} type produced from @var{enum_type}.
+@end table
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
@cindex TUI key bindings
The TUI installs several key bindings in the readline keymaps
-(@pxref{Command Line Editing}). The following key bindings
-are installed for both TUI mode and the @value{GDBN} standard mode.
+@ifset SYSTEM_READLINE
+(@pxref{Command Line Editing, , , rluserman, GNU Readline Library}).
+@end ifset
+@ifclear SYSTEM_READLINE
+(@pxref{Command Line Editing}).
+@end ifclear
+The following key bindings are installed for both TUI mode and the
+@value{GDBN} standard mode.
@table @kbd
@kindex C-x C-a
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
+sets your current working directory 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
* GDB/MI Async Records::
* GDB/MI Frame Information::
* GDB/MI Thread Information::
+* GDB/MI Ada Exception Information::
@end menu
@node GDB/MI Result Records
@var{target-name} and @var{host-name} fields give the name of the
library file on the target, and on the host respectively. For native
debugging, both those fields have the same value. The
-@var{symbols-loaded} field reports if the debug symbols for this
-library are loaded. The @var{thread-group} field, if present,
-specifies the id of the thread group in whose context the library was loaded.
-If the field is absent, it means the library was loaded in the context
-of all present thread groups.
+@var{symbols-loaded} field is emitted only for backward compatibility
+and should not be relied on to convey any useful information. The
+@var{thread-group} field, if present, specifies the id of the thread
+group in whose context the library was loaded. If the field is
+absent, it means the library was loaded in the context of all present
+thread groups.
@item =library-unloaded,...
Reports that a library was unloaded by the program. This notification
absent, it means the library was unloaded in the context of all present
thread groups.
+@item =breakpoint-created,bkpt=@{...@}
+@itemx =breakpoint-modified,bkpt=@{...@}
+@itemx =breakpoint-deleted,bkpt=@{...@}
+Reports that a breakpoint was created, modified, or deleted,
+respectively. Only user-visible breakpoints are reported to the MI
+user.
+
+The @var{bkpt} argument is of the same form as returned by the various
+breakpoint commands; @xref{GDB/MI Breakpoint Commands}.
+
+Note that if a breakpoint is emitted in the result record of a
+command, then it will not also be emitted in an async record.
+
@end table
@node GDB/MI Frame Information
thread was last seen on. This field is optional.
@end table
+@node GDB/MI Ada Exception Information
+@subsection @sc{gdb/mi} Ada Exception Information
+
+Whenever a @code{*stopped} record is emitted because the program
+stopped after hitting an exception catchpoint (@pxref{Set Catchpoints}),
+@value{GDBN} provides the name of the exception that was raised via
+the @code{exception-name} field.
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Simple Examples
The @samp{info thread} command prints the same information
about all threads.
-@subsubheading Example
+@subsubheading Result
-@smallexample
--thread-info
-^done,threads=[
-@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
- frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
-@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
- frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
- file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}],
-current-thread-id="1"
-(gdb)
-@end smallexample
+The result is a list of threads. The following attributes are
+defined for a given thread:
-The @samp{state} field may have the following values:
+@table @samp
+@item current
+This field exists only for the current thread. It has the value @samp{*}.
+
+@item id
+The identifier that @value{GDBN} uses to refer to the thread.
+
+@item target-id
+The identifier that the target uses to refer to the thread.
+
+@item details
+Extra information about the thread, in a target-specific format. This
+field is optional.
+
+@item name
+The name of the thread. If the user specified a name using the
+@code{thread name} command, then this name is given. Otherwise, if
+@value{GDBN} can extract the thread name from the target, then that
+name is given. If @value{GDBN} cannot find the thread name, then this
+field is omitted.
+
+@item frame
+The stack frame currently executing in the thread.
+
+@item state
+The thread's state. The @samp{state} field may have the following
+values:
@table @code
@item stopped
@end table
+@item core
+If @value{GDBN} can find the CPU core on which this thread is running,
+then this field is the core identifier. This field is optional.
+
+@end table
+
+@subsubheading Example
+
+@smallexample
+-thread-info
+^done,threads=[
+@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
+ frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",
+ args=[]@},state="running"@},
+@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
+ frame=@{level="0",addr="0x0804891f",func="foo",
+ args=[@{name="i",value="10"@}],
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},
+ state="running"@}],
+current-thread-id="1"
+(gdb)
+@end smallexample
+
@subheading The @code{-thread-list-ids} Command
@findex -thread-list-ids
@end smallexample
If a fixed variable object for the @code{state} variable is created in
-this function, and we enter the recursive call, the the variable
+this function, and we enter the recursive call, the variable
object will report the value of @code{state} in the top-level
@code{do_work} invocation. On the other hand, a floating variable
object will report the value of @code{state} in the current frame.
@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).
+is either 0 (meaning only disassembly), 1 (meaning mixed source and
+disassembly), 2 (meaning disassembly with raw opcodes), or 3 (meaning
+mixed source and disassembly with raw opcodes).
@end table
@subsubheading Result
@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 rluser.texi
+@c hsuser.texi
@c Use -I with makeinfo to point to the appropriate directory,
@c environment var TEXINPUTS with TeX.
+@ifclear SYSTEM_READLINE
@include rluser.texi
-@include inc-hist.texinfo
+@include hsuser.texi
+@end ifclear
+
+@node In Memoriam
+@appendix In Memoriam
+
+The @value{GDBN} project mourns the loss of the following long-time
+contributors:
+
+@table @code
+@item Fred Fish
+Fred was a long-standing contributor to @value{GDBN} (1991-2006), and
+to Free Software in general. Outside of @value{GDBN}, he was known in
+the Amiga world for his series of Fish Disks, and the GeekGadget project.
+
+@item Michael Snyder
+Michael was one of the Global Maintainers of the @value{GDBN} project,
+with contributions recorded as early as 1996, until 2011. In addition
+to his day to day participation, he was a large driving force behind
+adding Reverse Debugging to @value{GDBN}.
+@end table
+Beyond their technical contributions to the project, they were also
+enjoyable members of the Free Software Community. We will miss them.
@node Formatting Documentation
@appendix Formatting Documentation
Remote shared library lists (@pxref{Library List Format})
@item
MS-Windows shared libraries (@pxref{Shared Libraries})
+@item
+Traceframe info (@pxref{Traceframe Info Format})
@end itemize
@item zlib
on a GNU system, then this is provided by the GNU C Library. Some
other systems also provide a working @code{iconv}.
-On systems with @code{iconv}, you can install GNU Libiconv. If you
+If @value{GDBN} is using the @code{iconv} program which is installed
+in a non-standard place, you will need to tell @value{GDBN} where to find it.
+This is done with @option{--with-iconv-bin} which specifies the
+directory that contains the @code{iconv} program.
+
+On systems without @code{iconv}, you can install GNU Libiconv. If you
have previously installed Libiconv, you can use the
@option{--with-libiconv-prefix} option to configure.
@kindex maint print raw-registers
@kindex maint print cooked-registers
@kindex maint print register-groups
+@kindex maint print remote-registers
@item maint print registers @r{[}@var{file}@r{]}
@itemx maint print raw-registers @r{[}@var{file}@r{]}
@itemx maint print cooked-registers @r{[}@var{file}@r{]}
@itemx maint print register-groups @r{[}@var{file}@r{]}
+@itemx maint print remote-registers @r{[}@var{file}@r{]}
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, including registers which
-aren't available on the target nor visible to user; and the
-command @code{maint print register-groups} includes the groups that each
-register is a member of. @xref{Registers,, Registers, gdbint,
+the raw register cache; the command @code{maint print
+cooked-registers} includes the (cooked) value of all registers,
+including registers which aren't available on the target nor visible
+to user; the command @code{maint print register-groups} includes the
+groups that each register is a member of; and the command @code{maint
+print remote-registers} includes the remote target's register numbers
+and offsets in the `G' packets. @xref{Registers,, Registers, gdbint,
@value{GDBN} Internals}.
These commands take an optional parameter, a file name to which to
* Library List Format::
* Memory Map Format::
* Thread List Format::
+* Traceframe Info Format::
@end menu
@node Overview
determined by the @value{GDBN} internal gdbarch functions
@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The
specification of several standard @samp{g} packets is specified below.
+
+When reading registers from a trace frame (@pxref{Analyze Collected
+Data,,Using the Collected Data}), the stub may also return a string of
+literal @samp{x}'s in place of the register data digits, to indicate
+that the corresponding register has not been collected, thus its value
+is unavailable. For example, for an architecture with 4 registers of
+4 bytes each, the following reply indicates to @value{GDBN} that
+registers 0 and 2 have not been collected, while registers 1 and 3
+have been collected, and both have zero value:
+
+@smallexample
+-> @code{g}
+<- @code{xxxxxxxx00000000xxxxxxxx00000000}
+@end smallexample
+
@item E @var{NN}
for an error.
@end table
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,
+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
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:traceframe-info:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab No
+@item @samp{EnableDisableTracepoints}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub understands the @samp{qXfer:threads:read} packet
(@pxref{qXfer threads read}).
+@item qXfer:traceframe-info:read
+The remote stub understands the @samp{qXfer:traceframe-info:read}
+packet (@pxref{qXfer traceframe info read}).
+
@item QNonStop
The remote stub understands the @samp{QNonStop} packet
(@pxref{QNonStop}).
@cindex static tracepoints, in remote protocol
The remote stub supports static tracepoints.
+@item EnableDisableTracepoints
+The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and
+@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints
+to be enabled and disabled while a trace experiment is running.
+
@end table
@item qSymbol::
@item qTsV
@itemx QTStart
@itemx QTStop
+@itemx QTEnable
+@itemx QTDisable
@itemx QTinit
@itemx QTro
@itemx qTStatus
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:traceframe-info:read::@var{offset},@var{length}
+@anchor{qXfer traceframe info read}
+
+Return a description of the current traceframe's contents.
+@xref{Traceframe Info Format}. The annex part of the generic
+@samp{qXfer} packet must be empty (@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:osdata:read::@var{offset},@var{length}
@anchor{qXfer osdata read}
Access the target's @dfn{operating system information}.
@item QTStop
End the tracepoint experiment. Stop collecting trace frames.
+@item QTEnable:@var{n}:@var{addr}
+@anchor{QTEnable}
+Enable tracepoint @var{n} at address @var{addr} in a started tracepoint
+experiment. If the tracepoint was previously disabled, then collection
+of data from it will resume.
+
+@item QTDisable:@var{n}:@var{addr}
+@anchor{QTDisable}
+Disable tracepoint @var{n} at address @var{addr} in a started tracepoint
+experiment. No more data will be collected from the tracepoint unless
+@samp{QTEnable:@var{n}:@var{addr}} is subsequently issued.
+
@item QTinit
Clear the table of tracepoints, and empty the trace frame buffer.
the thread was last executing on. The content of the of @samp{thread}
element is interpreted as human-readable auxilliary information.
-@include agentexpr.texi
+@node Traceframe Info Format
+@section Traceframe Info Format
+@cindex traceframe info format
-@node Trace File Format
-@appendix Trace File Format
-@cindex trace file format
+To be able to know which objects in the inferior can be examined when
+inspecting a tracepoint hit, @value{GDBN} needs to obtain the list of
+memory ranges, registers and trace state variables that have been
+collected in a traceframe.
-The trace file comes in three parts: a header, a textual description
-section, and a trace frame section with binary data.
+This list is obtained using the @samp{qXfer:traceframe-info:read}
+(@pxref{qXfer traceframe info read}) packet and is an XML document.
-The header has the form @code{\x7fTRACE0\n}. The first byte is
-@code{0x7f} so as to indicate that the file contains binary data,
-while the @code{0} is a version number that may have different values
-in the future.
+@value{GDBN} must be linked with the Expat library to support XML
+traceframe info discovery. @xref{Expat}.
-The description section consists of multiple lines of @sc{ascii} text
-separated by newline characters (@code{0xa}). The lines may include a
-variety of optional descriptive or context-setting information, such
-as tracepoint definitions or register set size. @value{GDBN} will
-ignore any line that it does not recognize. An empty line marks the end
-of this section.
+The top-level structure of the document is shown below:
-@c FIXME add some specific types of data
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE traceframe-info
+ PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+ "http://sourceware.org/gdb/gdb-traceframe-info.dtd">
+<traceframe-info>
+ block...
+</traceframe-info>
+@end smallexample
-The trace frame section consists of a number of consecutive frames.
-Each frame begins with a two-byte tracepoint number, followed by a
-four-byte size giving the amount of data in the frame. The data in
-the frame consists of a number of blocks, each introduced by a
-character indicating its type (at least register, memory, and trace
-state variable). The data in this section is raw binary, not a
-hexadecimal or other encoding; its endianness matches the target's
-endianness.
+Each traceframe block can be either:
-@c FIXME bi-arch may require endianness/arch info in description section
+@itemize
-@table @code
-@item R @var{bytes}
-Register block. The number and ordering of bytes matches that of a
-@code{g} packet in the remote protocol. Note that these are the
-actual bytes, in target order and @value{GDBN} register order, not a
-hexadecimal encoding.
+@item
+A region of collected memory starting at @var{addr} and extending for
+@var{length} bytes from there:
-@item M @var{address} @var{length} @var{bytes}...
-Memory block. This is a contiguous block of memory, at the 8-byte
-address @var{address}, with a 2-byte length @var{length}, followed by
-@var{length} bytes.
+@smallexample
+<memory start="@var{addr}" length="@var{length}"/>
+@end smallexample
-@item V @var{number} @var{value}
-Trace state variable block. This records the 8-byte signed value
-@var{value} of trace state variable numbered @var{number}.
+@end itemize
-@end table
+The formal DTD for the traceframe info format is given below:
-Future enhancements of the trace file format may include additional types
-of blocks.
+@smallexample
+<!ELEMENT traceframe-info (memory)* >
+<!ATTLIST traceframe-info version CDATA #FIXED "1.0">
+
+<!ELEMENT memory EMPTY>
+<!ATTLIST memory start CDATA #REQUIRED
+ length CDATA #REQUIRED>
+@end smallexample
+
+@include agentexpr.texi
@node Target Descriptions
@appendix Target Descriptions
is running on. Target may provide additional columns,
which @value{GDBN} currently ignores.
+@node Trace File Format
+@appendix Trace File Format
+@cindex trace file format
+
+The trace file comes in three parts: a header, a textual description
+section, and a trace frame section with binary data.
+
+The header has the form @code{\x7fTRACE0\n}. The first byte is
+@code{0x7f} so as to indicate that the file contains binary data,
+while the @code{0} is a version number that may have different values
+in the future.
+
+The description section consists of multiple lines of @sc{ascii} text
+separated by newline characters (@code{0xa}). The lines may include a
+variety of optional descriptive or context-setting information, such
+as tracepoint definitions or register set size. @value{GDBN} will
+ignore any line that it does not recognize. An empty line marks the end
+of this section.
+
+@c FIXME add some specific types of data
+
+The trace frame section consists of a number of consecutive frames.
+Each frame begins with a two-byte tracepoint number, followed by a
+four-byte size giving the amount of data in the frame. The data in
+the frame consists of a number of blocks, each introduced by a
+character indicating its type (at least register, memory, and trace
+state variable). The data in this section is raw binary, not a
+hexadecimal or other encoding; its endianness matches the target's
+endianness.
+
+@c FIXME bi-arch may require endianness/arch info in description section
+
+@table @code
+@item R @var{bytes}
+Register block. The number and ordering of bytes matches that of a
+@code{g} packet in the remote protocol. Note that these are the
+actual bytes, in target order and @value{GDBN} register order, not a
+hexadecimal encoding.
+
+@item M @var{address} @var{length} @var{bytes}...
+Memory block. This is a contiguous block of memory, at the 8-byte
+address @var{address}, with a 2-byte length @var{length}, followed by
+@var{length} bytes.
+
+@item V @var{number} @var{value}
+Trace state variable block. This records the 8-byte signed value
+@var{value} of trace state variable numbered @var{number}.
+
+@end table
+
+Future enhancements of the trace file format may include additional types
+of blocks.
+
+@node Index Section Format
+@appendix @code{.gdb_index} section format
+@cindex .gdb_index section format
+@cindex index section format
+
+This section documents the index section that is created by @code{save
+gdb-index} (@pxref{Index Files}). The index section is
+DWARF-specific; some knowledge of DWARF is assumed in this
+description.
+
+The mapped index file format is designed to be directly
+@code{mmap}able on any architecture. In most cases, a datum is
+represented using a little-endian 32-bit integer value, called an
+@code{offset_type}. Big endian machines must byte-swap the values
+before using them. Exceptions to this rule are noted. The data is
+laid out such that alignment is always respected.
+
+A mapped index consists of several areas, laid out in order.
+
+@enumerate
+@item
+The file header. This is a sequence of values, of @code{offset_type}
+unless otherwise noted:
+
+@enumerate
+@item
+The version number, currently 5. Versions 1, 2 and 3 are obsolete.
+Version 4 differs by its hashing function.
+
+@item
+The offset, from the start of the file, of the CU list.
+
+@item
+The offset, from the start of the file, of the types CU list. Note
+that this area can be empty, in which case this offset will be equal
+to the next offset.
+
+@item
+The offset, from the start of the file, of the address area.
+
+@item
+The offset, from the start of the file, of the symbol table.
+
+@item
+The offset, from the start of the file, of the constant pool.
+@end enumerate
+
+@item
+The CU list. This is a sequence of pairs of 64-bit little-endian
+values, sorted by the CU offset. The first element in each pair is
+the offset of a CU in the @code{.debug_info} section. The second
+element in each pair is the length of that CU. References to a CU
+elsewhere in the map are done using a CU index, which is just the
+0-based index into this table. Note that if there are type CUs, then
+conceptually CUs and type CUs form a single list for the purposes of
+CU indices.
+
+@item
+The types CU list. This is a sequence of triplets of 64-bit
+little-endian values. In a triplet, the first value is the CU offset,
+the second value is the type offset in the CU, and the third value is
+the type signature. The types CU list is not sorted.
+
+@item
+The address area. The address area consists of a sequence of address
+entries. Each address entry has three elements:
+
+@enumerate
+@item
+The low address. This is a 64-bit little-endian value.
+
+@item
+The high address. This is a 64-bit little-endian value. Like
+@code{DW_AT_high_pc}, the value is one byte beyond the end.
+
+@item
+The CU index. This is an @code{offset_type} value.
+@end enumerate
+
+@item
+The symbol table. This is an open-addressed hash table. The size of
+the hash table is always a power of 2.
+
+Each slot in the hash table consists of a pair of @code{offset_type}
+values. The first value is the offset of the symbol's name in the
+constant pool. The second value is the offset of the CU vector in the
+constant pool.
+
+If both values are 0, then this slot in the hash table is empty. This
+is ok because while 0 is a valid constant pool index, it cannot be a
+valid index for both a string and a CU vector.
+
+The hash value for a table entry is computed by applying an
+iterative hash function to the symbol's name. Starting with an
+initial value of @code{r = 0}, each (unsigned) character @samp{c} in
+the string is incorporated into the hash using the formula depending on the
+index version:
+
+@table @asis
+@item Version 4
+The formula is @code{r = r * 67 + c - 113}.
+
+@item Version 5
+The formula is @code{r = r * 67 + tolower (c) - 113}.
+@end table
+
+The terminating @samp{\0} is not incorporated into the hash.
+
+The step size used in the hash table is computed via
+@code{((hash * 17) & (size - 1)) | 1}, where @samp{hash} is the hash
+value, and @samp{size} is the size of the hash table. The step size
+is used to find the next candidate slot when handling a hash
+collision.
+
+The names of C@t{++} symbols in the hash table are canonicalized. We
+don't currently have a simple description of the canonicalization
+algorithm; if you intend to create new index sections, you must read
+the code.
+
+@item
+The constant pool. This is simply a bunch of bytes. It is organized
+so that alignment is correct: CU vectors are stored first, followed by
+strings.
+
+A CU vector in the constant pool is a sequence of @code{offset_type}
+values. The first value is the number of CU indices in the vector.
+Each subsequent value is the index of a CU in the CU list. This
+element in the hash table is used to indicate which CUs define the
+symbol.
+
+A string in the constant pool is zero-terminated.
+@end enumerate
+
@include gpl.texi
@node GNU Free Documentation License
projects / deliverable / binutils-gdb.git / blobdiff