Split python docs into separate file.

	* Makefile.in (GDB_DOC_FILES): Add python.texi.
	* gdb.texinfo (Python): Moved to ...
	* python.texi: ... here.  New file.

4 files changed, 4453 insertions, 4432 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index f7a5eab..23823ee 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2014-02-17  Doug Evans  <xdje42@gmail.com>
+
+	* Makefile.in (GDB_DOC_FILES): Add python.texi.
+	* gdb.texinfo (Python): Moved to ...
+	* python.texi: ... here.  New file.
+
 2014-02-17  Ludovic Courtès  <ludo@gnu.org>
 
 	* guile.texi (Writing a Guile Pretty-Printer) <example>:
diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index 4375b20..c2360dd 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -131,6 +131,7 @@ GDB_DOC_BUILD_INCLUDES = \
 GDB_DOC_FILES = \
 	$(srcdir)/gdb.texinfo \
 	$(srcdir)/guile.texi \
+	$(srcdir)/python.texi \
 	$(GDB_DOC_SOURCE_INCLUDES) \
 	$(GDB_DOC_BUILD_INCLUDES)
 
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 035573e..7dc1564 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23528,4438 +23528,8 @@ auto-loaded.
 If @var{regexp} is supplied only canned sequences of commands scripts with
 matching names are printed.
 
-@node Python
-@section Extending @value{GDBN} using Python
-@cindex python scripting
-@cindex scripting with python
-
-You can extend @value{GDBN} using the @uref{http://www.python.org/,
-Python programming language}.  This feature is available only if
-@value{GDBN} was configured using @option{--with-python}.
-
-@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},
-is automatically added to the Python Search Path in order to allow
-the Python interpreter to locate all scripts installed at this location.
-
-Additionally, @value{GDBN} commands and convenience functions which
-are written in Python and are located in the
-@file{@var{data-directory}/python/gdb/command} or
-@file{@var{data-directory}/python/gdb/function} directories are
-automatically imported when @value{GDBN} starts.
-
-@menu
-* Python Commands::             Accessing Python from @value{GDBN}.
-* Python API::                  Accessing @value{GDBN} from Python.
-* Python Auto-loading::         Automatically loading Python code.
-* Python modules::              Python modules provided by @value{GDBN}.
-@end menu
-
-@node Python Commands
-@subsection Python Commands
-@cindex python commands
-@cindex commands to access python
-
-@value{GDBN} provides two commands for accessing the Python interpreter,
-and one related setting:
-
-@table @code
-@kindex python-interactive
-@kindex pi
-@item python-interactive @r{[}@var{command}@r{]}
-@itemx pi @r{[}@var{command}@r{]}
-Without an argument, the @code{python-interactive} command can be used
-to start an interactive Python prompt.  To return to @value{GDBN},
-type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
-
-Alternatively, a single-line Python command can be given as an
-argument and evaluated.  If the command is an expression, the result
-will be printed; otherwise, nothing will be printed.  For example:
-
-@smallexample
-(@value{GDBP}) python-interactive 2 + 3
-5
-@end smallexample
-
-@kindex python
-@kindex py
-@item python @r{[}@var{command}@r{]}
-@itemx py @r{[}@var{command}@r{]}
-The @code{python} command can be used to evaluate Python code.
-
-If given an argument, the @code{python} command will evaluate the
-argument as a Python command.  For example:
-
-@smallexample
-(@value{GDBP}) python print 23
-23
-@end smallexample
-
-If you do not provide an argument to @code{python}, it will act as a
-multi-line command, like @code{define}.  In this case, the Python
-script is made up of subsequent command lines, given after the
-@code{python} command.  This command list is terminated using a line
-containing @code{end}.  For example:
-
-@smallexample
-(@value{GDBP}) python
-Type python script
-End with a line saying just "end".
->print 23
->end
-23
-@end smallexample
-
-@kindex set python print-stack
-@item set python print-stack
-By default, @value{GDBN} will print only the message component of a
-Python exception when an error occurs in a Python script.  This can be
-controlled using @code{set python print-stack}: if @code{full}, then
-full Python stack printing is enabled; if @code{none}, then Python stack
-and message printing is disabled; if @code{message}, the default, only
-the message component of the error is printed.
-@end table
-
-It is also possible to execute a Python script from the @value{GDBN}
-interpreter:
-
-@table @code
-@item source @file{script-name}
-The script name must end with @samp{.py} and @value{GDBN} must be configured
-to recognize the script language based on filename extension using
-the @code{script-extension} setting.  @xref{Extending GDB, ,Extending GDB}.
-
-@item python execfile ("script-name")
-This method is based on the @code{execfile} Python built-in function,
-and thus is always available.
-@end table
-
-@node Python API
-@subsection Python API
-@cindex python api
-@cindex programming in python
-
-You can get quick online help for @value{GDBN}'s Python API by issuing
-the command @w{@kbd{python help (gdb)}}.
-
-Functions and methods which have two or more optional arguments allow
-them to be specified using keyword syntax.  This allows passing some
-optional arguments while skipping others.  Example:
-@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
-
-@menu
-* Basic Python::                Basic Python Functions.
-* 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.
-* Writing a Pretty-Printer::    Writing a Pretty-Printer.
-* Type Printing API::		Pretty-printing types.
-* Frame Filter API::            Filtering Frames.
-* Frame Decorator API::         Decorating Frames.
-* Writing a Frame Filter::      Writing a Frame Filter.
-* 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.
-* Functions In Python::         Writing new convenience functions.
-* Progspaces In Python::        Program spaces.
-* Objfiles In Python::          Object files.
-* Frames In Python::            Accessing inferior stack frames from Python.
-* Blocks In Python::            Accessing blocks from Python.
-* Symbols In Python::           Python representation of symbols.
-* Symbol Tables In Python::     Python representation of symbol tables.
-* Line Tables In Python::       Python representation of line tables.
-* Breakpoints In Python::       Manipulating breakpoints using Python.
-* Finish Breakpoints in Python:: Setting Breakpoints on function return
-                                using Python.
-* Lazy Strings In Python::      Python representation of lazy strings.
-* Architectures In Python::     Python representation of architectures.
-@end menu
-
-@node Basic Python
-@subsubsection Basic Python
-
-@cindex python stdout
-@cindex python pagination
-At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
-@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
-A Python program which outputs to one of these streams may have its
-output interrupted by the user (@pxref{Screen Size}).  In this
-situation, a Python @code{KeyboardInterrupt} exception is thrown.
-
-Some care must be taken when writing Python code to run in
-@value{GDBN}.  Two things worth noting in particular:
-
-@itemize @bullet
-@item
-@value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
-Python code must not override these, or even change the options using
-@code{sigaction}.  If your program changes the handling of these
-signals, @value{GDBN} will most likely stop working correctly.  Note
-that it is unfortunately common for GUI toolkits to install a
-@code{SIGCHLD} handler.
-
-@item
-@value{GDBN} takes care to mark its internal file descriptors as
-close-on-exec.  However, this cannot be done in a thread-safe way on
-all platforms.  Your Python programs should be aware of this and
-should both create new file descriptors with the close-on-exec flag
-set and arrange to close unneeded file descriptors before starting a
-child process.
-@end itemize
-
-@cindex python functions
-@cindex python module
-@cindex gdb module
-@value{GDBN} introduces a new Python module, named @code{gdb}.  All
-methods and classes added by @value{GDBN} are placed in this module.
-@value{GDBN} automatically @code{import}s the @code{gdb} module for
-use in all scripts evaluated by the @code{python} command.
-
-@findex gdb.PYTHONDIR
-@defvar gdb.PYTHONDIR
-A string containing the python directory (@pxref{Python}).
-@end defvar
-
-@findex gdb.execute
-@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
-Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
-If a GDB exception happens while @var{command} runs, it is
-translated as described in @ref{Exception Handling,,Exception Handling}.
-
-@var{from_tty} specifies whether @value{GDBN} ought to consider this
-command as having originated from the user invoking it interactively.
-It must be a boolean value.  If omitted, it defaults to @code{False}.
-
-By default, any output produced by @var{command} is sent to
-@value{GDBN}'s standard output.  If the @var{to_string} parameter is
-@code{True}, then output will be collected by @code{gdb.execute} and
-returned as a string.  The default is @code{False}, in which case the
-return value is @code{None}.  If @var{to_string} is @code{True}, the
-@value{GDBN} virtual terminal will be temporarily set to unlimited width
-and height, and its pagination will be disabled; @pxref{Screen Size}.
-@end defun
-
-@findex gdb.breakpoints
-@defun gdb.breakpoints ()
-Return a sequence holding all of @value{GDBN}'s breakpoints.
-@xref{Breakpoints In Python}, for more information.
-@end defun
-
-@findex gdb.parameter
-@defun gdb.parameter (parameter)
-Return the value of a @value{GDBN} parameter.  @var{parameter} is a
-string naming the parameter to look up; @var{parameter} may contain
-spaces if the parameter has a multi-part name.  For example,
-@samp{print object} is a valid parameter name.
-
-If the named parameter does not exist, this function throws a
-@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
-@defun gdb.history (number)
-Return a value from @value{GDBN}'s value history (@pxref{Value
-History}).  @var{number} indicates which history element to return.
-If @var{number} is negative, then @value{GDBN} will take its absolute value
-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{gdb.error} exception will be
-raised.
-
-If no exception is raised, the return value is always an instance of
-@code{gdb.Value} (@pxref{Values From Inferior}).
-@end defun
-
-@findex gdb.parse_and_eval
-@defun gdb.parse_and_eval (expression)
-Parse @var{expression} as an expression in the current language,
-evaluate it, and return the result as a @code{gdb.Value}.
-@var{expression} must be a string.
-
-This function can be useful when implementing a new command
-(@pxref{Commands In Python}), as it provides a way to parse the
-command's argument as an expression.  It is also useful simply to
-compute values, for example, it is the only way to get the value of a
-convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
-@end defun
-
-@findex gdb.find_pc_line
-@defun gdb.find_pc_line (pc)
-Return the @code{gdb.Symtab_and_line} object corresponding to the
-@var{pc} value.  @xref{Symbol Tables In Python}.  If an invalid
-value of @var{pc} is passed as an argument, then the @code{symtab} and
-@code{line} attributes of the returned @code{gdb.Symtab_and_line} object
-will be @code{None} and 0 respectively.
-@end defun
-
-@findex gdb.post_event
-@defun gdb.post_event (event)
-Put @var{event}, a callable object taking no arguments, into
-@value{GDBN}'s internal event queue.  This callable will be invoked at
-some later point, during @value{GDBN}'s event processing.  Events
-posted using @code{post_event} will be run in the order in which they
-were posted; however, there is no way to know when they will be
-processed relative to other events inside @value{GDBN}.
-
-@value{GDBN} is not thread-safe.  If your Python program uses multiple
-threads, you must be careful to only call @value{GDBN}-specific
-functions in the main @value{GDBN} thread.  @code{post_event} ensures
-this.  For example:
-
-@smallexample
-(@value{GDBP}) python
->import threading
->
->class Writer():
-> def __init__(self, message):
->        self.message = message;
-> def __call__(self):
->        gdb.write(self.message)
->
->class MyThread1 (threading.Thread):
-> def run (self):
->        gdb.post_event(Writer("Hello "))
->
->class MyThread2 (threading.Thread):
-> def run (self):
->        gdb.post_event(Writer("World\n"))
->
->MyThread1().start()
->MyThread2().start()
->end
-(@value{GDBP}) Hello World
-@end smallexample
-@end defun
-
-@findex gdb.write 
-@defun gdb.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 gdb.STDOUT
-@value{GDBN}'s standard output stream.
-
-@findex STDERR
-@findex gdb.STDERR
-@item gdb.STDERR
-@value{GDBN}'s standard error stream.
-
-@findex STDLOG
-@findex gdb.STDLOG
-@item gdb.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 and will automatically direct the output to the
-relevant stream.
-@end defun
-
-@findex gdb.flush
-@defun gdb.flush ()
-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 gdb.STDOUT
-@value{GDBN}'s standard output stream.
-
-@findex STDERR
-@findex gdb.STDERR
-@item gdb.STDERR
-@value{GDBN}'s standard error stream.
-
-@findex STDLOG
-@findex gdb.STDLOG
-@item gdb.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
-@defun gdb.target_charset ()
-Return the name of the current target character set (@pxref{Character
-Sets}).  This differs from @code{gdb.parameter('target-charset')} in
-that @samp{auto} is never returned.
-@end defun
-
-@findex gdb.target_wide_charset
-@defun gdb.target_wide_charset ()
-Return the name of the current target wide character set
-(@pxref{Character Sets}).  This differs from
-@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
-never returned.
-@end defun
-
-@findex gdb.solib_name
-@defun gdb.solib_name (address)
-Return the name of the shared library holding the given @var{address}
-as a string, or @code{None}.
-@end defun
-
-@findex gdb.decode_line 
-@defun gdb.decode_line @r{[}expression@r{]}
-Return locations of the line specified by @var{expression}, or of the
-current line if no argument was given.  This function returns a Python
-tuple containing two elements.  The first element contains a string
-holding any unparsed section of @var{expression} (or @code{None} if
-the expression has been fully parsed).  The second element contains
-either @code{None} or another tuple that contains all the locations
-that match the expression represented as @code{gdb.Symtab_and_line}
-objects (@pxref{Symbol Tables In Python}).  If @var{expression} is
-provided, it is decoded the way that @value{GDBN}'s inbuilt
-@code{break} or @code{edit} commands do (@pxref{Specify Location}).
-@end defun
-
-@defun gdb.prompt_hook (current_prompt)
-@anchor{prompt_hook}
-
-If @var{prompt_hook} is callable, @value{GDBN} will call the method
-assigned to this operation before a prompt is displayed by
-@value{GDBN}.
-
-The parameter @code{current_prompt} contains the current @value{GDBN} 
-prompt.  This method must return a Python string, or @code{None}.  If
-a string is returned, the @value{GDBN} prompt will be set to that
-string.  If @code{None} is returned, @value{GDBN} will continue to use
-the current prompt.
-
-Some prompts cannot be substituted in @value{GDBN}.  Secondary prompts
-such as those used by readline for command input, and annotation
-related prompts are prohibited from being changed.
-@end defun
-
-@node Exception Handling
-@subsubsection Exception Handling
-@cindex python exceptions
-@cindex exceptions, python
-
-When executing the @code{python} command, Python exceptions
-uncaught within the Python code are translated to calls to
-@value{GDBN} error-reporting mechanism.  If the command that called
-@code{python} does not handle the error, @value{GDBN} will
-terminate it and print an error message containing the Python
-exception name, the associated value, and the Python call stack
-backtrace at the point where the exception was raised.  Example:
-
-@smallexample
-(@value{GDBP}) python print foo
-Traceback (most recent call last):
-  File "<string>", line 1, in <module>
-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 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
-When implementing @value{GDBN} commands in Python via @code{gdb.Command},
-it is useful to be able to throw an exception that doesn't cause a
-traceback to be printed.  For example, the user may have invoked the
-command incorrectly.  Use the @code{gdb.GdbError} exception
-to handle this case.  Example:
-
-@smallexample
-(gdb) python
->class HelloWorld (gdb.Command):
->  """Greet the whole world."""
->  def __init__ (self):
->    super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
->  def invoke (self, args, from_tty):
->    argv = gdb.string_to_argv (args)
->    if len (argv) != 0:
->      raise gdb.GdbError ("hello-world takes no arguments")
->    print "Hello, World!"
->HelloWorld ()
->end
-(gdb) hello-world 42
-hello-world takes no arguments
-@end smallexample
-
-@node Values From Inferior
-@subsubsection Values From Inferior
-@cindex values from inferior, with Python
-@cindex python, working with values from inferior
-
-@cindex @code{gdb.Value}
-@value{GDBN} provides values it obtains from the inferior program in
-an object of type @code{gdb.Value}.  @value{GDBN} uses this object
-for its internal bookkeeping of the inferior's values, and for
-fetching values when necessary.
-
-Inferior values that are simple scalars can be used directly in
-Python expressions that are valid for the value's data type.  Here's
-an example for an integer or floating-point value @code{some_val}:
-
-@smallexample
-bar = some_val + 2
-@end smallexample
-
-@noindent
-As result of this, @code{bar} will also be a @code{gdb.Value} object
-whose values are of the same type as those of @code{some_val}.
-
-Inferior values that are structures or instances of some class can
-be accessed using the Python @dfn{dictionary syntax}.  For example, if
-@code{some_val} is a @code{gdb.Value} instance holding a structure, you
-can access its @code{foo} element with:
-
-@smallexample
-bar = some_val['foo']
-@end smallexample
-
-@cindex getting structure elements using gdb.Field objects as subscripts
-Again, @code{bar} will also be a @code{gdb.Value} object.  Structure
-elements can also be accessed by using @code{gdb.Field} objects as
-subscripts (@pxref{Types In Python}, for more information on
-@code{gdb.Field} objects).  For example, if @code{foo_field} is a
-@code{gdb.Field} object corresponding to element @code{foo} of the above
-structure, then @code{bar} can also be accessed as follows:
-
-@smallexample
-bar = some_val[foo_field]
-@end smallexample
-
-A @code{gdb.Value} that represents a function can be executed via
-inferior function call.  Any arguments provided to the call must match
-the function's prototype, and must be provided in the order specified
-by that prototype.
-
-For example, @code{some_val} is a @code{gdb.Value} instance
-representing a function that takes two integers as arguments.  To
-execute this function, call it like so:
-
-@smallexample
-result = some_val (10,20)
-@end smallexample
-
-Any values returned from a function call will be stored as a
-@code{gdb.Value}.
-
-The following attributes are provided:
-
-@defvar Value.address
-If this object is addressable, this read-only attribute holds a
-@code{gdb.Value} object representing the address.  Otherwise,
-this attribute holds @code{None}.
-@end defvar
-
-@cindex optimized out value in Python
-@defvar Value.is_optimized_out
-This read-only boolean attribute is true if the compiler optimized out
-this value, thus it is not available for fetching from the inferior.
-@end defvar
-
-@defvar Value.type
-The type of this @code{gdb.Value}.  The value of this attribute is a
-@code{gdb.Type} object (@pxref{Types In Python}).
-@end defvar
-
-@defvar Value.dynamic_type
-The dynamic type of this @code{gdb.Value}.  This uses C@t{++} run-time
-type information (@acronym{RTTI}) to determine the dynamic type of the
-value.  If this value is of class type, it will return the class in
-which the value is embedded, if any.  If this value is of pointer or
-reference to a class type, it will compute the dynamic type of the
-referenced object, and return a pointer or reference to that type,
-respectively.  In all other cases, it will return the value's static
-type.
-
-Note that this feature will only work when debugging a C@t{++} program
-that includes @acronym{RTTI} for the object in question.  Otherwise,
-it will just return the static type of the value as in @kbd{ptype foo}
-(@pxref{Symbols, ptype}).
-@end defvar
-
-@defvar Value.is_lazy
-The value of this read-only boolean attribute is @code{True} if this
-@code{gdb.Value} has not yet been fetched from the inferior.  
-@value{GDBN} does not fetch values until necessary, for efficiency.  
-For example:
-
-@smallexample
-myval = gdb.parse_and_eval ('somevar')
-@end smallexample
-
-The value of @code{somevar} is not fetched at this time.  It will be 
-fetched when the value is needed, or when the @code{fetch_lazy}
-method is invoked.  
-@end defvar
-
-The following methods are provided:
-
-@defun Value.__init__ (@var{val})
-Many Python values can be converted directly to a @code{gdb.Value} via
-this object initializer.  Specifically:
-
-@table @asis
-@item Python boolean
-A Python boolean is converted to the boolean type from the current
-language.
-
-@item Python integer
-A Python integer is converted to the C @code{long} type for the
-current architecture.
-
-@item Python long
-A Python long is converted to the C @code{long long} type for the
-current architecture.
-
-@item Python float
-A Python float is converted to the C @code{double} type for the
-current architecture.
-
-@item Python string
-A Python string is converted to a target string, using the current
-target encoding.
-
-@item @code{gdb.Value}
-If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
-
-@item @code{gdb.LazyString}
-If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
-Python}), then the lazy string's @code{value} method is called, and
-its result is used.
-@end table
-@end defun
-
-@defun Value.cast (type)
-Return a new instance of @code{gdb.Value} that is the result of
-casting this instance to the type described by @var{type}, which must
-be a @code{gdb.Type} object.  If the cast cannot be performed for some
-reason, this method throws an exception.
-@end defun
-
-@defun Value.dereference ()
-For pointer data types, this method returns a new @code{gdb.Value} object
-whose contents is the object pointed to by the pointer.  For example, if
-@code{foo} is a C pointer to an @code{int}, declared in your C program as
-
-@smallexample
-int *foo;
-@end smallexample
-
-@noindent
-then you can use the corresponding @code{gdb.Value} to access what
-@code{foo} points to like this:
-
-@smallexample
-bar = foo.dereference ()
-@end smallexample
-
-The result @code{bar} will be a @code{gdb.Value} object holding the
-value pointed to by @code{foo}.
-
-A similar function @code{Value.referenced_value} exists which also
-returns @code{gdb.Value} objects corresonding to the values pointed to
-by pointer values (and additionally, values referenced by reference
-values).  However, the behavior of @code{Value.dereference}
-differs from @code{Value.referenced_value} by the fact that the
-behavior of @code{Value.dereference} is identical to applying the C
-unary operator @code{*} on a given value.  For example, consider a
-reference to a pointer @code{ptrref}, declared in your C@t{++} program
-as
-
-@smallexample
-typedef int *intptr;
-...
-int val = 10;
-intptr ptr = &val;
-intptr &ptrref = ptr;
-@end smallexample
-
-Though @code{ptrref} is a reference value, one can apply the method
-@code{Value.dereference} to the @code{gdb.Value} object corresponding
-to it and obtain a @code{gdb.Value} which is identical to that
-corresponding to @code{val}.  However, if you apply the method
-@code{Value.referenced_value}, the result would be a @code{gdb.Value}
-object identical to that corresponding to @code{ptr}.
-
-@smallexample
-py_ptrref = gdb.parse_and_eval ("ptrref")
-py_val = py_ptrref.dereference ()
-py_ptr = py_ptrref.referenced_value ()
-@end smallexample
-
-The @code{gdb.Value} object @code{py_val} is identical to that
-corresponding to @code{val}, and @code{py_ptr} is identical to that
-corresponding to @code{ptr}.  In general, @code{Value.dereference} can
-be applied whenever the C unary operator @code{*} can be applied
-to the corresponding C value.  For those cases where applying both
-@code{Value.dereference} and @code{Value.referenced_value} is allowed,
-the results obtained need not be identical (as we have seen in the above
-example).  The results are however identical when applied on
-@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
-objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
-@end defun
-
-@defun Value.referenced_value ()
-For pointer or reference data types, this method returns a new
-@code{gdb.Value} object corresponding to the value referenced by the
-pointer/reference value.  For pointer data types,
-@code{Value.dereference} and @code{Value.referenced_value} produce
-identical results.  The difference between these methods is that
-@code{Value.dereference} cannot get the values referenced by reference
-values.  For example, consider a reference to an @code{int}, declared
-in your C@t{++} program as
-
-@smallexample
-int val = 10;
-int &ref = val;
-@end smallexample
-
-@noindent
-then applying @code{Value.dereference} to the @code{gdb.Value} object
-corresponding to @code{ref} will result in an error, while applying
-@code{Value.referenced_value} will result in a @code{gdb.Value} object
-identical to that corresponding to @code{val}.
-
-@smallexample
-py_ref = gdb.parse_and_eval ("ref")
-er_ref = py_ref.dereference ()       # Results in error
-py_val = py_ref.referenced_value ()  # Returns the referenced value
-@end smallexample
-
-The @code{gdb.Value} object @code{py_val} is identical to that
-corresponding to @code{val}.
-@end defun
-
-@defun Value.dynamic_cast (type)
-Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
-operator were used.  Consult a C@t{++} reference for details.
-@end defun
-
-@defun Value.reinterpret_cast (type)
-Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
-operator were used.  Consult a C@t{++} reference for details.
-@end defun
-
-@defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
-If this @code{gdb.Value} represents a string, then this method
-converts the contents to a Python string.  Otherwise, this method will
-throw an exception.
-
-Strings are recognized in a language-specific way; whether a given
-@code{gdb.Value} represents a string is determined by the current
-language.
-
-For C-like languages, a value is a string if it is a pointer to or an
-array of characters or ints.  The string is assumed to be terminated
-by a zero of the appropriate width.  However if the optional length
-argument is given, the string will be converted to that given length,
-ignoring any embedded zeros that the string may contain.
-
-If the optional @var{encoding} argument is given, it must be a string
-naming the encoding of the string in the @code{gdb.Value}, such as
-@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}.  It accepts
-the same encodings as the corresponding argument to Python's
-@code{string.decode} method, and the Python codec machinery will be used
-to convert the string.  If @var{encoding} is not given, or if
-@var{encoding} is the empty string, then either the @code{target-charset}
-(@pxref{Character Sets}) will be used, or a language-specific encoding
-will be used, if the current language is able to supply one.
-
-The optional @var{errors} argument is the same as the corresponding
-argument to Python's @code{string.decode} method.
-
-If the optional @var{length} argument is given, the string will be
-fetched and converted to the given length.
-@end defun
-
-@defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
-If this @code{gdb.Value} represents a string, then this method
-converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
-In Python}).  Otherwise, this method will throw an exception.
-
-If the optional @var{encoding} argument is given, it must be a string
-naming the encoding of the @code{gdb.LazyString}.  Some examples are:
-@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}.  If the
-@var{encoding} argument is an encoding that @value{GDBN} does
-recognize, @value{GDBN} will raise an error.
-
-When a lazy string is printed, the @value{GDBN} encoding machinery is
-used to convert the string during printing.  If the optional
-@var{encoding} argument is not provided, or is an empty string,
-@value{GDBN} will automatically select the encoding most suitable for
-the string type.  For further information on encoding in @value{GDBN}
-please see @ref{Character Sets}.
-
-If the optional @var{length} argument is given, the string will be
-fetched and encoded to the length of characters specified.  If
-the @var{length} argument is not provided, the string will be fetched
-and encoded until a null of appropriate width is found.
-@end defun
-
-@defun Value.fetch_lazy ()
-If the @code{gdb.Value} object is currently a lazy value 
-(@code{gdb.Value.is_lazy} is @code{True}), then the value is
-fetched from the inferior.  Any errors that occur in the process
-will produce a Python exception.
-
-If the @code{gdb.Value} object is not a lazy value, this method
-has no effect.
-
-This method does not return a value.
-@end defun
-
-
-@node Types In Python
-@subsubsection Types In Python
-@cindex types in Python
-@cindex Python, working with types
-
-@tindex gdb.Type
-@value{GDBN} represents types from the inferior using the class
-@code{gdb.Type}.
-
-The following type-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.lookup_type
-@defun gdb.lookup_type (name @r{[}, block@r{]})
-This function looks up a type by name.  @var{name} is the name of the
-type to look up.  It must be a string.
-
-If @var{block} is given, then @var{name} is looked up in that scope.
-Otherwise, it is searched for globally.
-
-Ordinarily, this function will return an instance of @code{gdb.Type}.
-If the named type cannot be found, it will throw an exception.
-@end defun
-
-If the type is a structure or class type, or an enum type, the fields
-of that type can be accessed using the Python @dfn{dictionary syntax}.
-For example, if @code{some_type} is a @code{gdb.Type} instance holding
-a structure type, you can access its @code{foo} field with:
-
-@smallexample
-bar = some_type['foo']
-@end smallexample
-
-@code{bar} will be a @code{gdb.Field} object; see below under the
-description of the @code{Type.fields} method for a description of the
-@code{gdb.Field} class.
-
-An instance of @code{Type} has the following attributes:
-
-@defvar Type.code
-The type code for this type.  The type code will be one of the
-@code{TYPE_CODE_} constants defined below.
-@end defvar
-
-@defvar Type.name
-The name of this type.  If this type has no name, then @code{None}
-is returned.
-@end defvar
-
-@defvar Type.sizeof
-The size of this type, in target @code{char} units.  Usually, a
-target's @code{char} type will be an 8-bit byte.  However, on some
-unusual platforms, this type may have a different size.
-@end defvar
-
-@defvar Type.tag
-The tag name for this type.  The tag name is the name after
-@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
-languages have this concept.  If this type has no tag name, then
-@code{None} is returned.
-@end defvar
-
-The following methods are provided:
-
-@defun Type.fields ()
-For structure and union types, this method returns the fields.  Range
-types have two fields, the minimum and maximum values.  Enum types
-have one field per enum constant.  Function and method types have one
-field per parameter.  The base types of C@t{++} classes are also
-represented as fields.  If the type has no fields, or does not fit
-into one of these categories, an empty sequence will be returned.
-
-Each field is a @code{gdb.Field} object, with some pre-defined attributes:
-@table @code
-@item bitpos
-This attribute is not available for @code{enum} or @code{static}
-(as in C@t{++} or Java) fields.  The value is the position, counting
-in bits, from the start of the containing type.
-
-@item enumval
-This attribute is only available for @code{enum} fields, and its value
-is the enumeration member's integer representation.
-
-@item name
-The name of the field, or @code{None} for anonymous fields.
-
-@item artificial
-This is @code{True} if the field is artificial, usually meaning that
-it was provided by the compiler and not the user.  This attribute is
-always provided, and is @code{False} if the field is not artificial.
-
-@item is_base_class
-This is @code{True} if the field represents a base class of a C@t{++}
-structure.  This attribute is always provided, and is @code{False}
-if the field is not a base class of the type that is the argument of
-@code{fields}, or if that type was not a C@t{++} class.
-
-@item bitsize
-If the field is packed, or is a bitfield, then this will have a
-non-zero value, which is the size of the field in bits.  Otherwise,
-this will be zero; in this case the field's size is given by its type.
-
-@item type
-The type of the field.  This is usually an instance of @code{Type},
-but it can be @code{None} in some situations.
-
-@item parent_type
-The type which contains this field.  This is an instance of
-@code{gdb.Type}.
-@end table
-@end defun
-
-@defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
-Return a new @code{gdb.Type} object which represents an array of this
-type.  If one argument is given, it is the inclusive upper bound of
-the array; in this case the lower bound is zero.  If two arguments are
-given, the first argument is the lower bound of the array, and the
-second argument is the upper bound of the array.  An array's length
-must not be negative, but the bounds can be.
-@end defun
-
-@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
-Return a new @code{gdb.Type} object which represents a vector of this
-type.  If one argument is given, it is the inclusive upper bound of
-the vector; in this case the lower bound is zero.  If two arguments are
-given, the first argument is the lower bound of the vector, and the
-second argument is the upper bound of the vector.  A vector's length
-must not be negative, but the bounds can be.
-
-The difference between an @code{array} and a @code{vector} is that
-arrays behave like in C: when used in expressions they decay to a pointer
-to the first element whereas vectors are treated as first class values.
-@end defun
-
-@defun Type.const ()
-Return a new @code{gdb.Type} object which represents a
-@code{const}-qualified variant of this type.
-@end defun
-
-@defun Type.volatile ()
-Return a new @code{gdb.Type} object which represents a
-@code{volatile}-qualified variant of this type.
-@end defun
-
-@defun Type.unqualified ()
-Return a new @code{gdb.Type} object which represents an unqualified
-variant of this type.  That is, the result is neither @code{const} nor
-@code{volatile}.
-@end defun
-
-@defun Type.range ()
-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{gdb.error} exception (@pxref{Exception Handling}).
-@end defun
-
-@defun Type.reference ()
-Return a new @code{gdb.Type} object which represents a reference to this
-type.
-@end defun
-
-@defun Type.pointer ()
-Return a new @code{gdb.Type} object which represents a pointer to this
-type.
-@end defun
-
-@defun Type.strip_typedefs ()
-Return a new @code{gdb.Type} that represents the real type,
-after removing all layers of typedefs.
-@end defun
-
-@defun Type.target ()
-Return a new @code{gdb.Type} object which represents the target type
-of this type.
-
-For a pointer type, the target type is the type of the pointed-to
-object.  For an array type (meaning C-like arrays), the target type is
-the type of the elements of the array.  For a function or method type,
-the target type is the type of the return value.  For a complex type,
-the target type is the type of the elements.  For a typedef, the
-target type is the aliased type.
-
-If the type does not have a target, this method will throw an
-exception.
-@end defun
-
-@defun Type.template_argument (n @r{[}, block@r{]})
-If this @code{gdb.Type} is an instantiation of a template, this will
-return a new @code{gdb.Type} which represents the type of the
-@var{n}th template argument.
-
-If this @code{gdb.Type} is not a template type, this will throw an
-exception.  Ordinarily, only C@t{++} code will have template types.
-
-If @var{block} is given, then @var{name} is looked up in that scope.
-Otherwise, it is searched for globally.
-@end defun
-
-
-Each type has a code, which indicates what category this type falls
-into.  The available type categories are represented by constants
-defined in the @code{gdb} module:
-
-@table @code
-@findex TYPE_CODE_PTR
-@findex gdb.TYPE_CODE_PTR
-@item gdb.TYPE_CODE_PTR
-The type is a pointer.
-
-@findex TYPE_CODE_ARRAY
-@findex gdb.TYPE_CODE_ARRAY
-@item gdb.TYPE_CODE_ARRAY
-The type is an array.
-
-@findex TYPE_CODE_STRUCT
-@findex gdb.TYPE_CODE_STRUCT
-@item gdb.TYPE_CODE_STRUCT
-The type is a structure.
-
-@findex TYPE_CODE_UNION
-@findex gdb.TYPE_CODE_UNION
-@item gdb.TYPE_CODE_UNION
-The type is a union.
-
-@findex TYPE_CODE_ENUM
-@findex gdb.TYPE_CODE_ENUM
-@item gdb.TYPE_CODE_ENUM
-The type is an enum.
-
-@findex TYPE_CODE_FLAGS
-@findex gdb.TYPE_CODE_FLAGS
-@item gdb.TYPE_CODE_FLAGS
-A bit flags type, used for things such as status registers.
-
-@findex TYPE_CODE_FUNC
-@findex gdb.TYPE_CODE_FUNC
-@item gdb.TYPE_CODE_FUNC
-The type is a function.
-
-@findex TYPE_CODE_INT
-@findex gdb.TYPE_CODE_INT
-@item gdb.TYPE_CODE_INT
-The type is an integer type.
-
-@findex TYPE_CODE_FLT
-@findex gdb.TYPE_CODE_FLT
-@item gdb.TYPE_CODE_FLT
-A floating point type.
-
-@findex TYPE_CODE_VOID
-@findex gdb.TYPE_CODE_VOID
-@item gdb.TYPE_CODE_VOID
-The special type @code{void}.
-
-@findex TYPE_CODE_SET
-@findex gdb.TYPE_CODE_SET
-@item gdb.TYPE_CODE_SET
-A Pascal set type.
-
-@findex TYPE_CODE_RANGE
-@findex gdb.TYPE_CODE_RANGE
-@item gdb.TYPE_CODE_RANGE
-A range type, that is, an integer type with bounds.
-
-@findex TYPE_CODE_STRING
-@findex gdb.TYPE_CODE_STRING
-@item gdb.TYPE_CODE_STRING
-A string type.  Note that this is only used for certain languages with
-language-defined string types; C strings are not represented this way.
-
-@findex TYPE_CODE_BITSTRING
-@findex gdb.TYPE_CODE_BITSTRING
-@item gdb.TYPE_CODE_BITSTRING
-A string of bits.  It is deprecated.
-
-@findex TYPE_CODE_ERROR
-@findex gdb.TYPE_CODE_ERROR
-@item gdb.TYPE_CODE_ERROR
-An unknown or erroneous type.
-
-@findex TYPE_CODE_METHOD
-@findex gdb.TYPE_CODE_METHOD
-@item gdb.TYPE_CODE_METHOD
-A method type, as found in C@t{++} or Java.
-
-@findex TYPE_CODE_METHODPTR
-@findex gdb.TYPE_CODE_METHODPTR
-@item gdb.TYPE_CODE_METHODPTR
-A pointer-to-member-function.
-
-@findex TYPE_CODE_MEMBERPTR
-@findex gdb.TYPE_CODE_MEMBERPTR
-@item gdb.TYPE_CODE_MEMBERPTR
-A pointer-to-member.
-
-@findex TYPE_CODE_REF
-@findex gdb.TYPE_CODE_REF
-@item gdb.TYPE_CODE_REF
-A reference type.
-
-@findex TYPE_CODE_CHAR
-@findex gdb.TYPE_CODE_CHAR
-@item gdb.TYPE_CODE_CHAR
-A character type.
-
-@findex TYPE_CODE_BOOL
-@findex gdb.TYPE_CODE_BOOL
-@item gdb.TYPE_CODE_BOOL
-A boolean type.
-
-@findex TYPE_CODE_COMPLEX
-@findex gdb.TYPE_CODE_COMPLEX
-@item gdb.TYPE_CODE_COMPLEX
-A complex float type.
-
-@findex TYPE_CODE_TYPEDEF
-@findex gdb.TYPE_CODE_TYPEDEF
-@item gdb.TYPE_CODE_TYPEDEF
-A typedef to some other type.
-
-@findex TYPE_CODE_NAMESPACE
-@findex gdb.TYPE_CODE_NAMESPACE
-@item gdb.TYPE_CODE_NAMESPACE
-A C@t{++} namespace.
-
-@findex TYPE_CODE_DECFLOAT
-@findex gdb.TYPE_CODE_DECFLOAT
-@item gdb.TYPE_CODE_DECFLOAT
-A decimal floating point type.
-
-@findex TYPE_CODE_INTERNAL_FUNCTION
-@findex gdb.TYPE_CODE_INTERNAL_FUNCTION
-@item gdb.TYPE_CODE_INTERNAL_FUNCTION
-A function internal to @value{GDBN}.  This is the type used to represent
-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
-
-An example output is provided (@pxref{Pretty Printing}).
-
-A pretty-printer is just an object that holds a value and implements a
-specific interface, defined here.
-
-@defun pretty_printer.children (self)
-@value{GDBN} will call this method on a pretty-printer to compute the
-children of the pretty-printer's value.
-
-This method must return an object conforming to the Python iterator
-protocol.  Each item returned by the iterator must be a tuple holding
-two elements.  The first element is the ``name'' of the child; the
-second element is the child's value.  The value can be any Python
-object which is convertible to a @value{GDBN} value.
-
-This method is optional.  If it does not exist, @value{GDBN} will act
-as though the value has no children.
-@end defun
-
-@defun pretty_printer.display_hint (self)
-The CLI may call this method and use its result to change the
-formatting of a value.  The result will also be supplied to an MI
-consumer as a @samp{displayhint} attribute of the variable being
-printed.
-
-This method is optional.  If it does exist, this method must return a
-string.
-
-Some display hints are predefined by @value{GDBN}:
-
-@table @samp
-@item array
-Indicate that the object being printed is ``array-like''.  The CLI
-uses this to respect parameters such as @code{set print elements} and
-@code{set print array}.
-
-@item map
-Indicate that the object being printed is ``map-like'', and that the
-children of this value can be assumed to alternate between keys and
-values.
-
-@item string
-Indicate that the object being printed is ``string-like''.  If the
-printer's @code{to_string} method returns a Python string of some
-kind, then @value{GDBN} will call its internal language-specific
-string-printing function to format the string.  For the CLI this means
-adding quotation marks, possibly escaping some characters, respecting
-@code{set print elements}, and the like.
-@end table
-@end defun
-
-@defun pretty_printer.to_string (self)
-@value{GDBN} will call this method to display the string
-representation of the value passed to the object's constructor.
-
-When printing from the CLI, if the @code{to_string} method exists,
-then @value{GDBN} will prepend its result to the values returned by
-@code{children}.  Exactly how this formatting is done is dependent on
-the display hint, and may change as more hints are added.  Also,
-depending on the print settings (@pxref{Print Settings}), the CLI may
-print just the result of @code{to_string} in a stack trace, omitting
-the result of @code{children}.
-
-If this method returns a string, it is printed verbatim.
-
-Otherwise, if this method returns an instance of @code{gdb.Value},
-then @value{GDBN} prints this value.  This may result in a call to
-another pretty-printer.
-
-If instead the method returns a Python value which is convertible to a
-@code{gdb.Value}, then @value{GDBN} performs the conversion and prints
-the resulting value.  Again, this may result in a call to another
-pretty-printer.  Python scalars (integers, floats, and booleans) and
-strings are convertible to @code{gdb.Value}; other types are not.
-
-Finally, if this method returns @code{None} then no further operations
-are peformed in this method and nothing is printed.
-
-If the result is not one of these types, an exception is raised.
-@end defun
-
-@value{GDBN} provides a function which can be used to look up the
-default pretty-printer for a @code{gdb.Value}:
-
-@findex gdb.default_visualizer
-@defun gdb.default_visualizer (value)
-This function takes a @code{gdb.Value} object as an argument.  If a
-pretty-printer for this value exists, then it is returned.  If no such
-printer exists, then this returns @code{None}.
-@end defun
-
-@node Selecting Pretty-Printers
-@subsubsection Selecting Pretty-Printers
-
-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.  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.
-
-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
-@code{None}.
-
-@value{GDBN} first checks the @code{pretty_printers} attribute of each
-@code{gdb.Objfile} in the current program space and iteratively calls
-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.
-After these lists have been exhausted, it tries the global
-@code{gdb.pretty_printers} list, again calling each enabled function until an
-object is returned.
-
-The order in which the objfiles are searched is not specified.  For a
-given list, functions are always invoked from the head of the list,
-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.  @xref{Pretty Printing API}, for details on the API this class
-must provide.
-
-@smallexample
-class StdStringPrinter(object):
-    "Print a std::string"
-
-    def __init__(self, val):
-        self.val = val
-
-    def to_string(self):
-        return self.val['_M_dataplus']['_M_p']
-
-    def display_hint(self):
-        return 'string'
-@end smallexample
-
-And here is an example showing how a lookup function for the printer
-example above might be written.
-
-@smallexample
-def str_lookup_function(val):
-    lookup_tag = val.type.tag
-    if lookup_tag == None:
-        return None
-    regex = re.compile("^std::basic_string<char,.*>$")
-    if regex.match(lookup_tag):
-        return StdStringPrinter(val)
-    return None
-@end smallexample
-
-The example lookup function extracts the value's type, and attempts to
-match it to a type that it can pretty-print.  If it is a type the
-printer can pretty-print, it will return a printer object.  If not, it
-returns @code{None}.
-
-We recommend that you put your core pretty-printers into a Python
-package.  If your pretty-printers are for use with a library, we
-further recommend embedding a version number into the package name.
-This practice will enable @value{GDBN} to load multiple versions of
-your pretty-printers at the same time, because they will have
-different names.
-
-You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
-can be evaluated multiple times without changing its meaning.  An
-ideal auto-load file will consist solely of @code{import}s of your
-printer modules, followed by a call to a register pretty-printers with
-the current objfile.
-
-Taken as a whole, this approach will scale nicely to multiple
-inferiors, each potentially using a different library version.
-Embedding a version number in the Python package name will ensure that
-@value{GDBN} is able to load both sets of printers simultaneously.
-Then, because the search for pretty-printers is done by objfile, and
-because your auto-loaded code took care to register your library's
-printers with a specific objfile, @value{GDBN} will find the correct
-printers for the specific version of the library used by each
-inferior.
-
-To continue the @code{std::string} example (@pxref{Pretty Printing API}),
-this code might appear in @code{gdb.libstdcxx.v6}:
-
-@smallexample
-def register_printers(objfile):
-    objfile.pretty_printers.append(str_lookup_function)
-@end smallexample
-
-@noindent
-And then the corresponding contents of the auto-load file would be:
-
-@smallexample
-import gdb.libstdcxx.v6
-gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
-@end smallexample
-
-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.
-
-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 @code{gdb.printing} module provides a formal way of solving these
-problems (@pxref{gdb.printing}).
-Here is another example that handles multiple types.
-
-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 Type Printing API
-@subsubsection Type Printing API
-@cindex type printing API for Python
-
-@value{GDBN} provides a way for Python code to customize type display.
-This is mainly useful for substituting canonical typedef names for
-types.
-
-@cindex type printer
-A @dfn{type printer} is just a Python object conforming to a certain
-protocol.  A simple base class implementing the protocol is provided;
-see @ref{gdb.types}.  A type printer must supply at least:
-
-@defivar type_printer enabled
-A boolean which is True if the printer is enabled, and False
-otherwise.  This is manipulated by the @code{enable type-printer}
-and @code{disable type-printer} commands.
-@end defivar
-
-@defivar type_printer name
-The name of the type printer.  This must be a string.  This is used by
-the @code{enable type-printer} and @code{disable type-printer}
-commands.
-@end defivar
-
-@defmethod type_printer instantiate (self)
-This is called by @value{GDBN} at the start of type-printing.  It is
-only called if the type printer is enabled.  This method must return a
-new object that supplies a @code{recognize} method, as described below.
-@end defmethod
-
-
-When displaying a type, say via the @code{ptype} command, @value{GDBN}
-will compute a list of type recognizers.  This is done by iterating
-first over the per-objfile type printers (@pxref{Objfiles In Python}),
-followed by the per-progspace type printers (@pxref{Progspaces In
-Python}), and finally the global type printers.
-
-@value{GDBN} will call the @code{instantiate} method of each enabled
-type printer.  If this method returns @code{None}, then the result is
-ignored; otherwise, it is appended to the list of recognizers.
-
-Then, when @value{GDBN} is going to display a type name, it iterates
-over the list of recognizers.  For each one, it calls the recognition
-function, stopping if the function returns a non-@code{None} value.
-The recognition function is defined as:
-
-@defmethod type_recognizer recognize (self, type)
-If @var{type} is not recognized, return @code{None}.  Otherwise,
-return a string which is to be printed as the name of @var{type}.
-@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
-Python}).
-@end defmethod
-
-@value{GDBN} uses this two-pass approach so that type printers can
-efficiently cache information without holding on to it too long.  For
-example, it can be convenient to look up type information in a type
-printer and hold it for a recognizer's lifetime; if a single pass were
-done then type printers would have to make use of the event system in
-order to avoid holding information that could become stale as the
-inferior changed.
-
-@node Frame Filter API
-@subsubsection Filtering Frames.
-@cindex frame filters api
-
-Frame filters are Python objects that manipulate the visibility of a
-frame or frames when a backtrace (@pxref{Backtrace}) is printed by
-@value{GDBN}.
-
-Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
-commands (@pxref{GDB/MI}), those that return a collection of frames
-are affected.  The commands that work with frame filters are:
-
-@code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
-@code{-stack-list-frames}
-(@pxref{-stack-list-frames,, The -stack-list-frames command}),
-@code{-stack-list-variables} (@pxref{-stack-list-variables,, The
--stack-list-variables command}), @code{-stack-list-arguments}
-@pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
-@code{-stack-list-locals} (@pxref{-stack-list-locals,, The
--stack-list-locals command}).
-
-A frame filter works by taking an iterator as an argument, applying
-actions to the contents of that iterator, and returning another
-iterator (or, possibly, the same iterator it was provided in the case
-where the filter does not perform any operations).  Typically, frame
-filters utilize tools such as the Python's @code{itertools} module to
-work with and create new iterators from the source iterator.
-Regardless of how a filter chooses to apply actions, it must not alter
-the underlying @value{GDBN} frame or frames, or attempt to alter the
-call-stack within @value{GDBN}.  This preserves data integrity within
-@value{GDBN}.  Frame filters are executed on a priority basis and care
-should be taken that some frame filters may have been executed before,
-and that some frame filters will be executed after.
-
-An important consideration when designing frame filters, and well
-worth reflecting upon, is that frame filters should avoid unwinding
-the call stack if possible.  Some stacks can run very deep, into the
-tens of thousands in some cases.  To search every frame when a frame
-filter executes may be too expensive at that step.  The frame filter
-cannot know how many frames it has to iterate over, and it may have to
-iterate through them all.  This ends up duplicating effort as
-@value{GDBN} performs this iteration when it prints the frames.  If
-the filter can defer unwinding frames until frame decorators are
-executed, after the last filter has executed, it should.  @xref{Frame
-Decorator API}, for more information on decorators.  Also, there are
-examples for both frame decorators and filters in later chapters.
-@xref{Writing a Frame Filter}, for more information.
-
-The Python dictionary @code{gdb.frame_filters} contains key/object
-pairings that comprise a frame filter.  Frame filters in this
-dictionary are called @code{global} frame filters, and they are
-available when debugging all inferiors.  These frame filters must
-register with the dictionary directly.  In addition to the
-@code{global} dictionary, there are other dictionaries that are loaded
-with different inferiors via auto-loading (@pxref{Python
-Auto-loading}).  The two other areas where frame filter dictionaries
-can be found are: @code{gdb.Progspace} which contains a
-@code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
-object which also contains a @code{frame_filters} dictionary
-attribute.
-
-When a command is executed from @value{GDBN} that is compatible with
-frame filters, @value{GDBN} combines the @code{global},
-@code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
-loaded.  All of the @code{gdb.Objfile} dictionaries are combined, as
-several frames, and thus several object files, might be in use.
-@value{GDBN} then prunes any frame filter whose @code{enabled}
-attribute is @code{False}.  This pruned list is then sorted according
-to the @code{priority} attribute in each filter.
-
-Once the dictionaries are combined, pruned and sorted, @value{GDBN}
-creates an iterator which wraps each frame in the call stack in a
-@code{FrameDecorator} object, and calls each filter in order.  The
-output from the previous filter will always be the input to the next
-filter, and so on.
-
-Frame filters have a mandatory interface which each frame filter must
-implement, defined here:
-
-@defun FrameFilter.filter (iterator)
-@value{GDBN} will call this method on a frame filter when it has
-reached the order in the priority list for that filter.
-
-For example, if there are four frame filters:
-
-@smallexample
-Name         Priority
-
-Filter1      5
-Filter2      10
-Filter3      100
-Filter4      1
-@end smallexample
-
-The order that the frame filters will be called is:
-
-@smallexample
-Filter3 -> Filter2 -> Filter1 -> Filter4
-@end smallexample
-
-Note that the output from @code{Filter3} is passed to the input of
-@code{Filter2}, and so on.
-
-This @code{filter} method is passed a Python iterator.  This iterator
-contains a sequence of frame decorators that wrap each
-@code{gdb.Frame}, or a frame decorator that wraps another frame
-decorator.  The first filter that is executed in the sequence of frame
-filters will receive an iterator entirely comprised of default
-@code{FrameDecorator} objects.  However, after each frame filter is
-executed, the previous frame filter may have wrapped some or all of
-the frame decorators with their own frame decorator.  As frame
-decorators must also conform to a mandatory interface, these
-decorators can be assumed to act in a uniform manner (@pxref{Frame
-Decorator API}).
-
-This method must return an object conforming to the Python iterator
-protocol.  Each item in the iterator must be an object conforming to
-the frame decorator interface.  If a frame filter does not wish to
-perform any operations on this iterator, it should return that
-iterator untouched.
-
-This method is not optional.  If it does not exist, @value{GDBN} will
-raise and print an error.
-@end defun
-
-@defvar FrameFilter.name
-The @code{name} attribute must be Python string which contains the
-name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
-Management}).  This attribute may contain any combination of letters
-or numbers.  Care should be taken to ensure that it is unique.  This
-attribute is mandatory.
-@end defvar
-
-@defvar FrameFilter.enabled
-The @code{enabled} attribute must be Python boolean.  This attribute
-indicates to @value{GDBN} whether the frame filter is enabled, and
-should be considered when frame filters are executed.  If
-@code{enabled} is @code{True}, then the frame filter will be executed
-when any of the backtrace commands detailed earlier in this chapter
-are executed.  If @code{enabled} is @code{False}, then the frame
-filter will not be executed.  This attribute is mandatory.
-@end defvar
-
-@defvar FrameFilter.priority
-The @code{priority} attribute must be Python integer.  This attribute
-controls the order of execution in relation to other frame filters.
-There are no imposed limits on the range of @code{priority} other than
-it must be a valid integer.  The higher the @code{priority} attribute,
-the sooner the frame filter will be executed in relation to other
-frame filters.  Although @code{priority} can be negative, it is
-recommended practice to assume zero is the lowest priority that a
-frame filter can be assigned.  Frame filters that have the same
-priority are executed in unsorted order in that priority slot.  This
-attribute is mandatory.
-@end defvar
-
-@node Frame Decorator API
-@subsubsection Decorating Frames.
-@cindex frame decorator api
-
-Frame decorators are sister objects to frame filters (@pxref{Frame
-Filter API}).  Frame decorators are applied by a frame filter and can
-only be used in conjunction with frame filters.
-
-The purpose of a frame decorator is to customize the printed content
-of each @code{gdb.Frame} in commands where frame filters are executed.
-This concept is called decorating a frame.  Frame decorators decorate
-a @code{gdb.Frame} with Python code contained within each API call.
-This separates the actual data contained in a @code{gdb.Frame} from
-the decorated data produced by a frame decorator.  This abstraction is
-necessary to maintain integrity of the data contained in each
-@code{gdb.Frame}.
-
-Frame decorators have a mandatory interface, defined below.
-
-@value{GDBN} already contains a frame decorator called
-@code{FrameDecorator}.  This contains substantial amounts of
-boilerplate code to decorate the content of a @code{gdb.Frame}.  It is
-recommended that other frame decorators inherit and extend this
-object, and only to override the methods needed.
-
-@defun FrameDecorator.elided (self)
-
-The @code{elided} method groups frames together in a hierarchical
-system.  An example would be an interpreter, where multiple low-level
-frames make up a single call in the interpreted language.  In this
-example, the frame filter would elide the low-level frames and present
-a single high-level frame, representing the call in the interpreted
-language, to the user.
-
-The @code{elided} function must return an iterable and this iterable
-must contain the frames that are being elided wrapped in a suitable
-frame decorator.  If no frames are being elided this function may
-return an empty iterable, or @code{None}.  Elided frames are indented
-from normal frames in a @code{CLI} backtrace, or in the case of
-@code{GDB/MI}, are placed in the @code{children} field of the eliding
-frame.
-
-It is the frame filter's task to also filter out the elided frames from
-the source iterator.  This will avoid printing the frame twice.
-@end defun
-
-@defun FrameDecorator.function (self)
-
-This method returns the name of the function in the frame that is to
-be printed.
-
-This method must return a Python string describing the function, or
-@code{None}.
-
-If this function returns @code{None}, @value{GDBN} will not print any
-data for this field.
-@end defun
-
-@defun FrameDecorator.address (self)
-
-This method returns the address of the frame that is to be printed.
-
-This method must return a Python numeric integer type of sufficient
-size to describe the address of the frame, or @code{None}.
-
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.filename (self)
-
-This method returns the filename and path associated with this frame.
-
-This method must return a Python string containing the filename and
-the path to the object file backing the frame, or @code{None}.
-
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.line (self):
-
-This method returns the line number associated with the current
-position within the function addressed by this frame.
-
-This method must return a Python integer type, or @code{None}.
-
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.frame_args (self)
-@anchor{frame_args}
-
-This method must return an iterable, or @code{None}.  Returning an
-empty iterable, or @code{None} means frame arguments will not be
-printed for this frame.  This iterable must contain objects that
-implement two methods, described here.
-
-This object must implement a @code{argument} method which takes a
-single @code{self} parameter and must return a @code{gdb.Symbol}
-(@pxref{Symbols In Python}), or a Python string.  The object must also
-implement a @code{value} method which takes a single @code{self}
-parameter and must return a @code{gdb.Value} (@pxref{Values From
-Inferior}), a Python value, or @code{None}.  If the @code{value}
-method returns @code{None}, and the @code{argument} method returns a
-@code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
-the @code{gdb.Symbol} automatically.
-
-A brief example:
-
-@smallexample
-class SymValueWrapper():
-
-    def __init__(self, symbol, value):
-        self.sym = symbol
-        self.val = value
-
-    def value(self):
-        return self.val
-
-    def symbol(self):
-        return self.sym
-
-class SomeFrameDecorator()
-...
-...
-    def frame_args(self):
-        args = []
-        try:
-            block = self.inferior_frame.block()
-        except:
-            return None
-
-        # Iterate over all symbols in a block.  Only add
-        # symbols that are arguments.
-        for sym in block:
-            if not sym.is_argument:
-                continue
-            args.append(SymValueWrapper(sym,None))
-
-        # Add example synthetic argument.
-        args.append(SymValueWrapper(``foo'', 42))
-
-        return args
-@end smallexample
-@end defun
-
-@defun FrameDecorator.frame_locals (self)
-
-This method must return an iterable or @code{None}.  Returning an
-empty iterable, or @code{None} means frame local arguments will not be
-printed for this frame.
-
-The object interface, the description of the various strategies for
-reading frame locals, and the example are largely similar to those
-described in the @code{frame_args} function, (@pxref{frame_args,,The
-frame filter frame_args function}).  Below is a modified example:
-
-@smallexample
-class SomeFrameDecorator()
-...
-...
-    def frame_locals(self):
-        vars = []
-        try:
-            block = self.inferior_frame.block()
-        except:
-            return None
-
-        # Iterate over all symbols in a block.  Add all
-        # symbols, except arguments.
-        for sym in block:
-            if sym.is_argument:
-                continue
-            vars.append(SymValueWrapper(sym,None))
-
-        # Add an example of a synthetic local variable.
-        vars.append(SymValueWrapper(``bar'', 99))
-
-        return vars
-@end smallexample
-@end defun
-
-@defun FrameDecorator.inferior_frame (self):
-
-This method must return the underlying @code{gdb.Frame} that this
-frame decorator is decorating.  @value{GDBN} requires the underlying
-frame for internal frame information to determine how to print certain
-values when printing a frame.
-@end defun
-
-@node Writing a Frame Filter
-@subsubsection Writing a Frame Filter
-@cindex writing a frame filter
-
-There are three basic elements that a frame filter must implement: it
-must correctly implement the documented interface (@pxref{Frame Filter
-API}), it must register itself with @value{GDBN}, and finally, it must
-decide if it is to work on the data provided by @value{GDBN}.  In all
-cases, whether it works on the iterator or not, each frame filter must
-return an iterator.  A bare-bones frame filter follows the pattern in
-the following example.
-
-@smallexample
-import gdb
-
-class FrameFilter():
-
-    def __init__(self):
-        # Frame filter attribute creation.
-        #
-        # 'name' is the name of the filter that GDB will display.
-        #
-        # 'priority' is the priority of the filter relative to other
-        # filters.
-        #
-        # 'enabled' is a boolean that indicates whether this filter is
-        # enabled and should be executed.
-
-        self.name = "Foo"
-        self.priority = 100
-        self.enabled = True
-
-        # Register this frame filter with the global frame_filters
-        # dictionary.
-        gdb.frame_filters[self.name] = self
-
-    def filter(self, frame_iter):
-        # Just return the iterator.
-        return frame_iter
-@end smallexample
-
-The frame filter in the example above implements the three
-requirements for all frame filters.  It implements the API, self
-registers, and makes a decision on the iterator (in this case, it just
-returns the iterator untouched).
-
-The first step is attribute creation and assignment, and as shown in
-the comments the filter assigns the following attributes:  @code{name},
-@code{priority} and whether the filter should be enabled with the
-@code{enabled} attribute.
-
-The second step is registering the frame filter with the dictionary or
-dictionaries that the frame filter has interest in.  As shown in the
-comments, this filter just registers itself with the global dictionary
-@code{gdb.frame_filters}.  As noted earlier, @code{gdb.frame_filters}
-is a dictionary that is initialized in the @code{gdb} module when
-@value{GDBN} starts.  What dictionary a filter registers with is an
-important consideration.  Generally, if a filter is specific to a set
-of code, it should be registered either in the @code{objfile} or
-@code{progspace} dictionaries as they are specific to the program
-currently loaded in @value{GDBN}.  The global dictionary is always
-present in @value{GDBN} and is never unloaded.  Any filters registered
-with the global dictionary will exist until @value{GDBN} exits.  To
-avoid filters that may conflict, it is generally better to register
-frame filters against the dictionaries that more closely align with
-the usage of the filter currently in question.  @xref{Python
-Auto-loading}, for further information on auto-loading Python scripts.
-
-@value{GDBN} takes a hands-off approach to frame filter registration,
-therefore it is the frame filter's responsibility to ensure
-registration has occurred, and that any exceptions are handled
-appropriately.  In particular, you may wish to handle exceptions
-relating to Python dictionary key uniqueness.  It is mandatory that
-the dictionary key is the same as frame filter's @code{name}
-attribute.  When a user manages frame filters (@pxref{Frame Filter
-Management}), the names @value{GDBN} will display are those contained
-in the @code{name} attribute.
-
-The final step of this example is the implementation of the
-@code{filter} method.  As shown in the example comments, we define the
-@code{filter} method and note that the method must take an iterator,
-and also must return an iterator.  In this bare-bones example, the
-frame filter is not very useful as it just returns the iterator
-untouched.  However this is a valid operation for frame filters that
-have the @code{enabled} attribute set, but decide not to operate on
-any frames.
-
-In the next example, the frame filter operates on all frames and
-utilizes a frame decorator to perform some work on the frames.
-@xref{Frame Decorator API}, for further information on the frame
-decorator interface.
-
-This example works on inlined frames.  It highlights frames which are
-inlined by tagging them with an ``[inlined]'' tag.  By applying a
-frame decorator to all frames with the Python @code{itertools imap}
-method, the example defers actions to the frame decorator.  Frame
-decorators are only processed when @value{GDBN} prints the backtrace.
-
-This introduces a new decision making topic: whether to perform
-decision making operations at the filtering step, or at the printing
-step.  In this example's approach, it does not perform any filtering
-decisions at the filtering step beyond mapping a frame decorator to
-each frame.  This allows the actual decision making to be performed
-when each frame is printed.  This is an important consideration, and
-well worth reflecting upon when designing a frame filter.  An issue
-that frame filters should avoid is unwinding the stack if possible.
-Some stacks can run very deep, into the tens of thousands in some
-cases.  To search every frame to determine if it is inlined ahead of
-time may be too expensive at the filtering step.  The frame filter
-cannot know how many frames it has to iterate over, and it would have
-to iterate through them all.  This ends up duplicating effort as
-@value{GDBN} performs this iteration when it prints the frames.
-
-In this example decision making can be deferred to the printing step.
-As each frame is printed, the frame decorator can examine each frame
-in turn when @value{GDBN} iterates.  From a performance viewpoint,
-this is the most appropriate decision to make as it avoids duplicating
-the effort that the printing step would undertake anyway.  Also, if
-there are many frame filters unwinding the stack during filtering, it
-can substantially delay the printing of the backtrace which will
-result in large memory usage, and a poor user experience.
-
-@smallexample
-class InlineFilter():
-
-    def __init__(self):
-        self.name = "InlinedFrameFilter"
-        self.priority = 100
-        self.enabled = True
-        gdb.frame_filters[self.name] = self
-
-    def filter(self, frame_iter):
-        frame_iter = itertools.imap(InlinedFrameDecorator,
-                                    frame_iter)
-        return frame_iter
-@end smallexample
-
-This frame filter is somewhat similar to the earlier example, except
-that the @code{filter} method applies a frame decorator object called
-@code{InlinedFrameDecorator} to each element in the iterator.  The
-@code{imap} Python method is light-weight.  It does not proactively
-iterate over the iterator, but rather creates a new iterator which
-wraps the existing one.
-
-Below is the frame decorator for this example.
-
-@smallexample
-class InlinedFrameDecorator(FrameDecorator):
-
-    def __init__(self, fobj):
-        super(InlinedFrameDecorator, self).__init__(fobj)
-
-    def function(self):
-        frame = fobj.inferior_frame()
-        name = str(frame.name())
-
-        if frame.type() == gdb.INLINE_FRAME:
-            name = name + " [inlined]"
-
-        return name
-@end smallexample
-
-This frame decorator only defines and overrides the @code{function}
-method.  It lets the supplied @code{FrameDecorator}, which is shipped
-with @value{GDBN}, perform the other work associated with printing
-this frame.
-
-The combination of these two objects create this output from a
-backtrace:
-
-@smallexample
-#0  0x004004e0 in bar () at inline.c:11
-#1  0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
-#2  0x00400566 in main () at inline.c:31
-@end smallexample
-
-So in the case of this example, a frame decorator is applied to all
-frames, regardless of whether they may be inlined or not.  As
-@value{GDBN} iterates over the iterator produced by the frame filters,
-@value{GDBN} executes each frame decorator which then makes a decision
-on what to print in the @code{function} callback.  Using a strategy
-like this is a way to defer decisions on the frame content to printing
-time.
-
-@subheading Eliding Frames
-
-It might be that the above example is not desirable for representing
-inlined frames, and a hierarchical approach may be preferred.  If we
-want to hierarchically represent frames, the @code{elided} frame
-decorator interface might be preferable.
-
-This example approaches the issue with the @code{elided} method.  This
-example is quite long, but very simplistic.  It is out-of-scope for
-this section to write a complete example that comprehensively covers
-all approaches of finding and printing inlined frames.  However, this
-example illustrates the approach an author might use.
-
-This example comprises of three sections.
-
-@smallexample
-class InlineFrameFilter():
-
-    def __init__(self):
-        self.name = "InlinedFrameFilter"
-        self.priority = 100
-        self.enabled = True
-        gdb.frame_filters[self.name] = self
-
-    def filter(self, frame_iter):
-        return ElidingInlineIterator(frame_iter)
-@end smallexample
-
-This frame filter is very similar to the other examples.  The only
-difference is this frame filter is wrapping the iterator provided to
-it (@code{frame_iter}) with a custom iterator called
-@code{ElidingInlineIterator}.  This again defers actions to when
-@value{GDBN} prints the backtrace, as the iterator is not traversed
-until printing.
-
-The iterator for this example is as follows.  It is in this section of
-the example where decisions are made on the content of the backtrace.
-
-@smallexample
-class ElidingInlineIterator:
-    def __init__(self, ii):
-        self.input_iterator = ii
-
-    def __iter__(self):
-        return self
-
-    def next(self):
-        frame = next(self.input_iterator)
-
-        if frame.inferior_frame().type() != gdb.INLINE_FRAME:
-            return frame
-
-        try:
-            eliding_frame = next(self.input_iterator)
-        except StopIteration:
-            return frame
-        return ElidingFrameDecorator(eliding_frame, [frame])
-@end smallexample
-
-This iterator implements the Python iterator protocol.  When the
-@code{next} function is called (when @value{GDBN} prints each frame),
-the iterator checks if this frame decorator, @code{frame}, is wrapping
-an inlined frame.  If it is not, it returns the existing frame decorator
-untouched.  If it is wrapping an inlined frame, it assumes that the
-inlined frame was contained within the next oldest frame,
-@code{eliding_frame}, which it fetches.  It then creates and returns a
-frame decorator, @code{ElidingFrameDecorator}, which contains both the
-elided frame, and the eliding frame.
-
-@smallexample
-class ElidingInlineDecorator(FrameDecorator):
-
-    def __init__(self, frame, elided_frames):
-        super(ElidingInlineDecorator, self).__init__(frame)
-        self.frame = frame
-        self.elided_frames = elided_frames
-
-    def elided(self):
-        return iter(self.elided_frames)
-@end smallexample
-
-This frame decorator overrides one function and returns the inlined
-frame in the @code{elided} method.  As before it lets
-@code{FrameDecorator} do the rest of the work involved in printing
-this frame.  This produces the following output.
-
-@smallexample
-#0  0x004004e0 in bar () at inline.c:11
-#2  0x00400529 in main () at inline.c:25
-    #1  0x00400529 in max (b=6, a=12) at inline.c:15
-@end smallexample
-
-In that output, @code{max} which has been inlined into @code{main} is
-printed hierarchically.  Another approach would be to combine the
-@code{function} method, and the @code{elided} method to both print a
-marker in the inlined frame, and also show the hierarchical
-relationship.
-
-@node Inferiors In Python
-@subsubsection Inferiors In Python
-@cindex inferiors in Python
-
-@findex gdb.Inferior
-Programs which are being run under @value{GDBN} are called inferiors
-(@pxref{Inferiors and Programs}).  Python scripts can access
-information about and manipulate inferiors controlled by @value{GDBN}
-via objects of the @code{gdb.Inferior} class.
-
-The following inferior-related functions are available in the @code{gdb}
-module:
-
-@defun gdb.inferiors ()
-Return a tuple containing all inferior objects.
-@end defun
-
-@defun gdb.selected_inferior ()
-Return an object representing the current inferior.
-@end defun
-
-A @code{gdb.Inferior} object has the following attributes:
-
-@defvar Inferior.num
-ID of inferior, as assigned by GDB.
-@end defvar
-
-@defvar Inferior.pid
-Process ID of the inferior, as assigned by the underlying operating
-system.
-@end defvar
-
-@defvar Inferior.was_attached
-Boolean signaling whether the inferior was created using `attach', or
-started by @value{GDBN} itself.
-@end defvar
-
-A @code{gdb.Inferior} object has the following methods:
-
-@defun 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 defun
-
-@defun 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
-return an empty tuple.
-@end defun
-
-@findex Inferior.read_memory
-@defun Inferior.read_memory (address, length)
-Read @var{length} bytes of memory from the inferior, starting at
-@var{address}.  Returns a buffer object, which behaves much like an array
-or a string.  It can be modified and given to the
-@code{Inferior.write_memory} function.  In @code{Python} 3, the return
-value is a @code{memoryview} object.
-@end defun
-
-@findex Inferior.write_memory
-@defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
-Write the contents of @var{buffer} to the inferior, starting at
-@var{address}.  The @var{buffer} parameter must be a Python object
-which supports the buffer protocol, i.e., a string, an array or the
-object returned from @code{Inferior.read_memory}.  If given, @var{length}
-determines the number of bytes from @var{buffer} to be written.
-@end defun
-
-@findex gdb.search_memory
-@defun Inferior.search_memory (address, length, pattern)
-Search a region of the inferior memory starting at @var{address} with
-the given @var{length} using the search pattern supplied in
-@var{pattern}.  The @var{pattern} parameter must be a Python object
-which supports the buffer protocol, i.e., a string, an array or the
-object returned from @code{gdb.read_memory}.  Returns a Python @code{Long}
-containing the address where the pattern was found, or @code{None} if
-the pattern could not be found.
-@end defun
-
-@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:
-
-@defun 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 defun
-
-@defun EventRegistry.disconnect (object)
-Remove the given @var{object} from the registry.  Once removed, the object
-will no longer receive notifications of events.
-@end defun
-
-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}.
-
-@defvar 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 defvar
-
-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 two attributes:
-@defvar ExitedEvent.exit_code
-An integer representing the exit code, if available, which the inferior 
-has returned.  (The exit code could be unavailable if, for example,
-@value{GDBN} detaches from the inferior.) If the exit code is unavailable,
-the attribute does not exist.
-@end defvar
-@defvar ExitedEvent inferior
-A reference to the inferior which triggered the @code{exited} event.
-@end defvar
-
-@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:
-
-@defvar 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 defvar
-
-Also emits  @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
-
-@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
-been hit, and has the following attributes:
-
-@defvar BreakpointEvent.breakpoints
-A sequence containing references to all the breakpoints (type 
-@code{gdb.Breakpoint}) that were hit.
-@xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
-@end defvar
-@defvar BreakpointEvent.breakpoint
-A reference to the first breakpoint that was hit.
-This function is maintained for backward compatibility and is now deprecated 
-in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
-@end defvar
-
-@item events.new_objfile
-Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
-been loaded by @value{GDBN}.  @code{gdb.NewObjFileEvent} has one attribute:
-
-@defvar NewObjFileEvent.new_objfile
-A reference to the object file (@code{gdb.Objfile}) which has been loaded.
-@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
-@end defvar
-
-@end table
-
-@node Threads In Python
-@subsubsection Threads In Python
-@cindex threads in python
-
-@findex gdb.InferiorThread
-Python scripts can access information about, and manipulate inferior threads
-controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
-
-The following thread-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.selected_thread
-@defun gdb.selected_thread ()
-This function returns the thread object for the selected thread.  If there
-is no selected thread, this will return @code{None}.
-@end defun
-
-A @code{gdb.InferiorThread} object has the following attributes:
-
-@defvar 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 defvar
-
-@defvar InferiorThread.num
-ID of the thread, as assigned by GDB.
-@end defvar
-
-@defvar InferiorThread.ptid
-ID of the thread, as assigned by the operating system.  This attribute is a
-tuple containing three integers.  The first is the Process ID (PID); the second
-is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
-Either the LWPID or TID may be 0, which indicates that the operating system
-does not  use that identifier.
-@end defvar
-
-A @code{gdb.InferiorThread} object has the following methods:
-
-@defun 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 defun
-
-@defun InferiorThread.switch ()
-This changes @value{GDBN}'s currently selected thread to the one represented
-by this object.
-@end defun
-
-@defun InferiorThread.is_stopped ()
-Return a Boolean indicating whether the thread is stopped.
-@end defun
-
-@defun InferiorThread.is_running ()
-Return a Boolean indicating whether the thread is running.
-@end defun
-
-@defun InferiorThread.is_exited ()
-Return a Boolean indicating whether the thread is exited.
-@end defun
-
-@node Commands In Python
-@subsubsection Commands In Python
-
-@cindex commands in python
-@cindex python commands
-You can implement new @value{GDBN} CLI commands in Python.  A CLI
-command is implemented using an instance of the @code{gdb.Command}
-class, most commonly using a subclass.
-
-@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
-The object initializer for @code{Command} registers the new command
-with @value{GDBN}.  This initializer is normally invoked from the
-subclass' own @code{__init__} method.
-
-@var{name} is the name of the command.  If @var{name} consists of
-multiple words, then the initial words are looked for as prefix
-commands.  In this case, if one of the prefix commands does not exist,
-an exception is raised.
-
-There is no support for multi-line commands.
-
-@var{command_class} should be one of the @samp{COMMAND_} constants
-defined below.  This argument tells @value{GDBN} how to categorize the
-new command in the help system.
-
-@var{completer_class} is an optional argument.  If given, it should be
-one of the @samp{COMPLETE_} constants defined below.  This argument
-tells @value{GDBN} how to perform completion for this command.  If not
-given, @value{GDBN} will attempt to complete using the object's
-@code{complete} method (see below); if no such method is found, an
-error will occur when completion is attempted.
-
-@var{prefix} is an optional argument.  If @code{True}, then the new
-command is a prefix command; sub-commands of this command may be
-registered.
-
-The help text for the new command is taken from the Python
-documentation string for the command's class, if there is one.  If no
-documentation string is provided, the default value ``This command is
-not documented.'' is used.
-@end defun
-
-@cindex don't repeat Python command
-@defun Command.dont_repeat ()
-By default, a @value{GDBN} command is repeated when the user enters a
-blank line at the command prompt.  A command can suppress this
-behavior by invoking the @code{dont_repeat} method.  This is similar
-to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
-@end defun
-
-@defun Command.invoke (argument, from_tty)
-This method is called by @value{GDBN} when this command is invoked.
-
-@var{argument} is a string.  It is the argument to the command, after
-leading and trailing whitespace has been stripped.
-
-@var{from_tty} is a boolean argument.  When true, this means that the
-command was entered by the user at the terminal; when false it means
-that the command came from elsewhere.
-
-If this method throws an exception, it is turned into a @value{GDBN}
-@code{error} call.  Otherwise, the return value is ignored.
-
-@findex gdb.string_to_argv
-To break @var{argument} up into an argv-like string use
-@code{gdb.string_to_argv}.  This function behaves identically to
-@value{GDBN}'s internal argument lexer @code{buildargv}.
-It is recommended to use this for consistency.
-Arguments are separated by spaces and may be quoted.
-Example:
-
-@smallexample
-print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
-['1', '2 "3', '4 "5', "6 '7"]
-@end smallexample
-
-@end defun
-
-@cindex completion of Python commands
-@defun Command.complete (text, word)
-This method is called by @value{GDBN} when the user attempts
-completion on this command.  All forms of completion are handled by
-this method, that is, the @key{TAB} and @key{M-?} key bindings
-(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
-complete}).
-
-The arguments @var{text} and @var{word} are both strings.  @var{text}
-holds the complete command line up to the cursor's location.
-@var{word} holds the last word of the command line; this is computed
-using a word-breaking heuristic.
-
-The @code{complete} method can return several values:
-@itemize @bullet
-@item
-If the return value is a sequence, the contents of the sequence are
-used as the completions.  It is up to @code{complete} to ensure that the
-contents actually do complete the word.  A zero-length sequence is
-allowed, it means that there were no completions available.  Only
-string elements of the sequence are used; other elements in the
-sequence are ignored.
-
-@item
-If the return value is one of the @samp{COMPLETE_} constants defined
-below, then the corresponding @value{GDBN}-internal completion
-function is invoked, and its result is used.
-
-@item
-All other results are treated as though there were no available
-completions.
-@end itemize
-@end defun
-
-When a new command is registered, it must be declared as a member of
-some general class of commands.  This is used to classify top-level
-commands in the on-line help system; note that prefix commands are not
-listed under their own category but rather that of their top-level
-command.  The available classifications are represented by constants
-defined in the @code{gdb} module:
-
-@table @code
-@findex COMMAND_NONE
-@findex gdb.COMMAND_NONE
-@item gdb.COMMAND_NONE
-The command does not belong to any particular class.  A command in
-this category will not be displayed in any of the help categories.
-
-@findex COMMAND_RUNNING
-@findex gdb.COMMAND_RUNNING
-@item gdb.COMMAND_RUNNING
-The command is related to running the inferior.  For example,
-@code{start}, @code{step}, and @code{continue} are in this category.
-Type @kbd{help running} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_DATA
-@findex gdb.COMMAND_DATA
-@item gdb.COMMAND_DATA
-The command is related to data or variables.  For example,
-@code{call}, @code{find}, and @code{print} are in this category.  Type
-@kbd{help data} at the @value{GDBN} prompt to see a list of commands
-in this category.
-
-@findex COMMAND_STACK
-@findex gdb.COMMAND_STACK
-@item gdb.COMMAND_STACK
-The command has to do with manipulation of the stack.  For example,
-@code{backtrace}, @code{frame}, and @code{return} are in this
-category.  Type @kbd{help stack} at the @value{GDBN} prompt to see a
-list of commands in this category.
-
-@findex COMMAND_FILES
-@findex gdb.COMMAND_FILES
-@item gdb.COMMAND_FILES
-This class is used for file-related commands.  For example,
-@code{file}, @code{list} and @code{section} are in this category.
-Type @kbd{help files} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_SUPPORT
-@findex gdb.COMMAND_SUPPORT
-@item gdb.COMMAND_SUPPORT
-This should be used for ``support facilities'', generally meaning
-things that are useful to the user when interacting with @value{GDBN},
-but not related to the state of the inferior.  For example,
-@code{help}, @code{make}, and @code{shell} are in this category.  Type
-@kbd{help support} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_STATUS
-@findex gdb.COMMAND_STATUS
-@item gdb.COMMAND_STATUS
-The command is an @samp{info}-related command, that is, related to the
-state of @value{GDBN} itself.  For example, @code{info}, @code{macro},
-and @code{show} are in this category.  Type @kbd{help status} at the
-@value{GDBN} prompt to see a list of commands in this category.
-
-@findex COMMAND_BREAKPOINTS
-@findex gdb.COMMAND_BREAKPOINTS
-@item gdb.COMMAND_BREAKPOINTS
-The command has to do with breakpoints.  For example, @code{break},
-@code{clear}, and @code{delete} are in this category.  Type @kbd{help
-breakpoints} at the @value{GDBN} prompt to see a list of commands in
-this category.
-
-@findex COMMAND_TRACEPOINTS
-@findex gdb.COMMAND_TRACEPOINTS
-@item gdb.COMMAND_TRACEPOINTS
-The command has to do with tracepoints.  For example, @code{trace},
-@code{actions}, and @code{tfind} are in this category.  Type
-@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_USER
-@findex gdb.COMMAND_USER
-@item gdb.COMMAND_USER
-The command is a general purpose command for the user, and typically
-does not fit in one of the other categories.
-Type @kbd{help user-defined} at the @value{GDBN} prompt to see
-a list of commands in this category, as well as the list of gdb macros
-(@pxref{Sequences}).
-
-@findex COMMAND_OBSCURE
-@findex gdb.COMMAND_OBSCURE
-@item gdb.COMMAND_OBSCURE
-The command is only used in unusual circumstances, or is not of
-general interest to users.  For example, @code{checkpoint},
-@code{fork}, and @code{stop} are in this category.  Type @kbd{help
-obscure} at the @value{GDBN} prompt to see a list of commands in this
-category.
-
-@findex COMMAND_MAINTENANCE
-@findex gdb.COMMAND_MAINTENANCE
-@item gdb.COMMAND_MAINTENANCE
-The command is only useful to @value{GDBN} maintainers.  The
-@code{maintenance} and @code{flushregs} commands are in this category.
-Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
-commands in this category.
-@end table
-
-A new command can use a predefined completion function, either by
-specifying it via an argument at initialization, or by returning it
-from the @code{complete} method.  These predefined completion
-constants are all defined in the @code{gdb} module:
-
-@table @code
-@findex COMPLETE_NONE
-@findex gdb.COMPLETE_NONE
-@item gdb.COMPLETE_NONE
-This constant means that no completion should be done.
-
-@findex COMPLETE_FILENAME
-@findex gdb.COMPLETE_FILENAME
-@item gdb.COMPLETE_FILENAME
-This constant means that filename completion should be performed.
-
-@findex COMPLETE_LOCATION
-@findex gdb.COMPLETE_LOCATION
-@item gdb.COMPLETE_LOCATION
-This constant means that location completion should be done.
-@xref{Specify Location}.
-
-@findex COMPLETE_COMMAND
-@findex gdb.COMPLETE_COMMAND
-@item gdb.COMPLETE_COMMAND
-This constant means that completion should examine @value{GDBN}
-command names.
-
-@findex COMPLETE_SYMBOL
-@findex gdb.COMPLETE_SYMBOL
-@item gdb.COMPLETE_SYMBOL
-This constant means that completion should be done using symbol names
-as the source.
-
-@findex COMPLETE_EXPRESSION
-@findex gdb.COMPLETE_EXPRESSION
-@item gdb.COMPLETE_EXPRESSION
-This constant means that completion should be done on expressions.
-Often this means completing on symbol names, but some language
-parsers also have support for completing on field names.
-@end table
-
-The following code snippet shows how a trivial CLI command can be
-implemented in Python:
-
-@smallexample
-class HelloWorld (gdb.Command):
-  """Greet the whole world."""
-
-  def __init__ (self):
-    super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
-
-  def invoke (self, arg, from_tty):
-    print "Hello, World!"
-
-HelloWorld ()
-@end smallexample
-
-The last line instantiates the class, and is necessary to trigger the
-registration of the command with @value{GDBN}.  Depending on how the
-Python code is read into @value{GDBN}, you may need to import the
-@code{gdb} module explicitly.
-
-@node Parameters In Python
-@subsubsection Parameters In Python
-
-@cindex parameters in python
-@cindex python parameters
-@tindex gdb.Parameter
-@tindex Parameter
-You can implement new @value{GDBN} parameters using Python.  A new
-parameter is implemented as an instance of the @code{gdb.Parameter}
-class.
-
-Parameters are exposed to the user via the @code{set} and
-@code{show} commands.  @xref{Help}.
-
-There are many parameters that already exist and can be set in
-@value{GDBN}.  Two examples are: @code{set follow fork} and
-@code{set charset}.  Setting these parameters influences certain
-behavior in @value{GDBN}.  Similarly, you can define parameters that
-can be used to influence behavior in custom Python scripts and commands.
-
-@defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
-The object initializer for @code{Parameter} registers the new
-parameter with @value{GDBN}.  This initializer is normally invoked
-from the subclass' own @code{__init__} method.
-
-@var{name} is the name of the new parameter.  If @var{name} consists
-of multiple words, then the initial words are looked for as prefix
-parameters.  An example of this can be illustrated with the
-@code{set print} set of parameters.  If @var{name} is
-@code{print foo}, then @code{print} will be searched as the prefix
-parameter.  In this case the parameter can subsequently be accessed in
-@value{GDBN} as @code{set print foo}.
-
-If @var{name} consists of multiple words, and no prefix parameter group
-can be found, an exception is raised.
-
-@var{command-class} should be one of the @samp{COMMAND_} constants
-(@pxref{Commands In Python}).  This argument tells @value{GDBN} how to
-categorize the new parameter in the help system.
-
-@var{parameter-class} should be one of the @samp{PARAM_} constants
-defined below.  This argument tells @value{GDBN} the type of the new
-parameter; this information is used for input validation and
-completion.
-
-If @var{parameter-class} is @code{PARAM_ENUM}, then
-@var{enum-sequence} must be a sequence of strings.  These strings
-represent the possible values for the parameter.
-
-If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
-of a fourth argument will cause an exception to be thrown.
-
-The help text for the new parameter is taken from the Python
-documentation string for the parameter's class, if there is one.  If
-there is no documentation string, a default value is used.
-@end defun
-
-@defvar Parameter.set_doc
-If this attribute exists, and is a string, then its value is used as
-the help text for this parameter's @code{set} command.  The value is
-examined when @code{Parameter.__init__} is invoked; subsequent changes
-have no effect.
-@end defvar
-
-@defvar Parameter.show_doc
-If this attribute exists, and is a string, then its value is used as
-the help text for this parameter's @code{show} command.  The value is
-examined when @code{Parameter.__init__} is invoked; subsequent changes
-have no effect.
-@end defvar
-
-@defvar Parameter.value
-The @code{value} attribute holds the underlying value of the
-parameter.  It can be read and assigned to just as any other
-attribute.  @value{GDBN} does validation when assignments are made.
-@end defvar
-
-There are two methods that should be implemented in any
-@code{Parameter} class.  These are:
-
-@defun 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 defun
-
-@defun 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 defun
-
-When a new parameter is defined, its type must be specified.  The
-available types are represented by constants defined in the @code{gdb}
-module:
-
-@table @code
-@findex PARAM_BOOLEAN
-@findex gdb.PARAM_BOOLEAN
-@item gdb.PARAM_BOOLEAN
-The value is a plain boolean.  The Python boolean values, @code{True}
-and @code{False} are the only valid values.
-
-@findex PARAM_AUTO_BOOLEAN
-@findex gdb.PARAM_AUTO_BOOLEAN
-@item gdb.PARAM_AUTO_BOOLEAN
-The value has three possible states: true, false, and @samp{auto}.  In
-Python, true and false are represented using boolean constants, and
-@samp{auto} is represented using @code{None}.
-
-@findex PARAM_UINTEGER
-@findex gdb.PARAM_UINTEGER
-@item gdb.PARAM_UINTEGER
-The value is an unsigned integer.  The value of 0 should be
-interpreted to mean ``unlimited''.
-
-@findex PARAM_INTEGER
-@findex gdb.PARAM_INTEGER
-@item gdb.PARAM_INTEGER
-The value is a signed integer.  The value of 0 should be interpreted
-to mean ``unlimited''.
-
-@findex PARAM_STRING
-@findex gdb.PARAM_STRING
-@item gdb.PARAM_STRING
-The value is a string.  When the user modifies the string, any escape
-sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
-translated into corresponding characters and encoded into the current
-host charset.
-
-@findex PARAM_STRING_NOESCAPE
-@findex gdb.PARAM_STRING_NOESCAPE
-@item gdb.PARAM_STRING_NOESCAPE
-The value is a string.  When the user modifies the string, escapes are
-passed through untranslated.
-
-@findex PARAM_OPTIONAL_FILENAME
-@findex gdb.PARAM_OPTIONAL_FILENAME
-@item gdb.PARAM_OPTIONAL_FILENAME
-The value is a either a filename (a string), or @code{None}.
-
-@findex PARAM_FILENAME
-@findex gdb.PARAM_FILENAME
-@item gdb.PARAM_FILENAME
-The value is a filename.  This is just like
-@code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
-
-@findex PARAM_ZINTEGER
-@findex gdb.PARAM_ZINTEGER
-@item gdb.PARAM_ZINTEGER
-The value is an integer.  This is like @code{PARAM_INTEGER}, except 0
-is interpreted as itself.
-
-@findex PARAM_ENUM
-@findex gdb.PARAM_ENUM
-@item gdb.PARAM_ENUM
-The value is a string, which must be one of a collection string
-constants provided when the parameter is created.
-@end table
-
-@node Functions In Python
-@subsubsection Writing new convenience functions
-
-@cindex writing convenience functions
-@cindex convenience functions in python
-@cindex python convenience functions
-@tindex gdb.Function
-@tindex Function
-You can implement new convenience functions (@pxref{Convenience Vars})
-in Python.  A convenience function is an instance of a subclass of the
-class @code{gdb.Function}.
-
-@defun Function.__init__ (name)
-The initializer for @code{Function} registers the new function with
-@value{GDBN}.  The argument @var{name} is the name of the function,
-a string.  The function will be visible to the user as a convenience
-variable of type @code{internal function}, whose name is the same as
-the given @var{name}.
-
-The documentation for the new function is taken from the documentation
-string for the new class.
-@end defun
-
-@defun Function.invoke (@var{*args})
-When a convenience function is evaluated, its arguments are converted
-to instances of @code{gdb.Value}, and then the function's
-@code{invoke} method is called.  Note that @value{GDBN} does not
-predetermine the arity of convenience functions.  Instead, all
-available arguments are passed to @code{invoke}, following the
-standard Python calling convention.  In particular, a convenience
-function can have default values for parameters without ill effect.
-
-The return value of this method is used as its value in the enclosing
-expression.  If an ordinary Python value is returned, it is converted
-to a @code{gdb.Value} following the usual rules.
-@end defun
-
-The following code snippet shows how a trivial convenience function can
-be implemented in Python:
-
-@smallexample
-class Greet (gdb.Function):
-  """Return string to greet someone.
-Takes a name as argument."""
-
-  def __init__ (self):
-    super (Greet, self).__init__ ("greet")
-
-  def invoke (self, name):
-    return "Hello, %s!" % name.string ()
-
-Greet ()
-@end smallexample
-
-The last line instantiates the class, and is necessary to trigger the
-registration of the function with @value{GDBN}.  Depending on how the
-Python code is read into @value{GDBN}, you may need to import the
-@code{gdb} module explicitly.
-
-Now you can use the function in an expression:
-
-@smallexample
-(gdb) print $greet("Bob")
-$1 = "Hello, Bob!"
-@end smallexample
-
-@node Progspaces In Python
-@subsubsection Program Spaces In Python
-
-@cindex progspaces in python
-@tindex gdb.Progspace
-@tindex Progspace
-A program space, or @dfn{progspace}, represents a symbolic view
-of an address space.
-It consists of all of the objfiles of the program.
-@xref{Objfiles In Python}.
-@xref{Inferiors and Programs, program spaces}, for more details
-about program spaces.
-
-The following progspace-related functions are available in the
-@code{gdb} module:
-
-@findex gdb.current_progspace
-@defun gdb.current_progspace ()
-This function returns the program space of the currently selected inferior.
-@xref{Inferiors and Programs}.
-@end defun
-
-@findex gdb.progspaces
-@defun gdb.progspaces ()
-Return a sequence of all the progspaces currently known to @value{GDBN}.
-@end defun
-
-Each progspace is represented by an instance of the @code{gdb.Progspace}
-class.
-
-@defvar Progspace.filename
-The file name of the progspace as a string.
-@end defvar
-
-@defvar Progspace.pretty_printers
-The @code{pretty_printers} attribute is a list of functions.  It is
-used to look up pretty-printers.  A @code{Value} is passed to each
-function in order; if the function returns @code{None}, then the
-search continues.  Otherwise, the return value should be an object
-which is used to format the value.  @xref{Pretty Printing API}, for more
-information.
-@end defvar
-
-@defvar Progspace.type_printers
-The @code{type_printers} attribute is a list of type printer objects.
-@xref{Type Printing API}, for more information.
-@end defvar
-
-@defvar Progspace.frame_filters
-The @code{frame_filters} attribute is a dictionary of frame filter
-objects.  @xref{Frame Filter API}, for more information.
-@end defvar
-
-@node Objfiles In Python
-@subsubsection Objfiles In Python
-
-@cindex objfiles in python
-@tindex gdb.Objfile
-@tindex Objfile
-@value{GDBN} loads symbols for an inferior from various
-symbol-containing files (@pxref{Files}).  These include the primary
-executable file, any shared libraries used by the inferior, and any
-separate debug info files (@pxref{Separate Debug Files}).
-@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
-
-The following objfile-related functions are available in the
-@code{gdb} module:
-
-@findex gdb.current_objfile
-@defun gdb.current_objfile ()
-When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
-sets the ``current objfile'' to the corresponding objfile.  This
-function returns the current objfile.  If there is no current objfile,
-this function returns @code{None}.
-@end defun
-
-@findex gdb.objfiles
-@defun gdb.objfiles ()
-Return a sequence of all the objfiles current known to @value{GDBN}.
-@xref{Objfiles In Python}.
-@end defun
-
-Each objfile is represented by an instance of the @code{gdb.Objfile}
-class.
-
-@defvar Objfile.filename
-The file name of the objfile as a string.
-@end defvar
-
-@defvar Objfile.pretty_printers
-The @code{pretty_printers} attribute is a list of functions.  It is
-used to look up pretty-printers.  A @code{Value} is passed to each
-function in order; if the function returns @code{None}, then the
-search continues.  Otherwise, the return value should be an object
-which is used to format the value.  @xref{Pretty Printing API}, for more
-information.
-@end defvar
-
-@defvar Objfile.type_printers
-The @code{type_printers} attribute is a list of type printer objects.
-@xref{Type Printing API}, for more information.
-@end defvar
-
-@defvar Objfile.frame_filters
-The @code{frame_filters} attribute is a dictionary of frame filter
-objects.  @xref{Frame Filter API}, for more information.
-@end defvar
-
-A @code{gdb.Objfile} object has the following methods:
-
-@defun 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 defun
-
-@node Frames In Python
-@subsubsection Accessing inferior stack frames from Python.
-
-@cindex frames in python
-When the debugged program stops, @value{GDBN} is able to analyze its call
-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{gdb.error}
-exception (@pxref{Exception Handling}).
-
-Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
-operator, like:
-
-@smallexample
-(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
-True
-@end smallexample
-
-The following frame-related functions are available in the @code{gdb} module:
-
-@findex gdb.selected_frame
-@defun gdb.selected_frame ()
-Return the selected frame object.  (@pxref{Selection,,Selecting a Frame}).
-@end defun
-
-@findex gdb.newest_frame
-@defun gdb.newest_frame ()
-Return the newest frame object for the selected thread.
-@end defun
-
-@defun gdb.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
-@code{unwind_stop_reason} method further down in this section).
-@end defun
-
-A @code{gdb.Frame} object has the following methods:
-
-@defun Frame.is_valid ()
-Returns true if the @code{gdb.Frame} object is valid, false if not.
-A frame object can become invalid if the frame it refers to doesn't
-exist anymore in the inferior.  All @code{gdb.Frame} methods will throw
-an exception if it is invalid at the time the method is called.
-@end defun
-
-@defun Frame.name ()
-Returns the function name of the frame, or @code{None} if it can't be
-obtained.
-@end defun
-
-@defun Frame.architecture ()
-Returns the @code{gdb.Architecture} object corresponding to the frame's
-architecture.  @xref{Architectures In Python}.
-@end defun
-
-@defun Frame.type ()
-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.TAILCALL_FRAME
-A frame representing a tail call.  @xref{Tail Call Frames}.
-
-@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 defun
-
-@defun Frame.unwind_stop_reason ()
-Return an integer representing the reason why it's not possible to find
-more frames toward the outermost frame.  Use
-@code{gdb.frame_stop_reason_string} to convert the value returned by this
-function to a string. The value can be one of:
-
-@table @code
-@item gdb.FRAME_UNWIND_NO_REASON
-No particular reason (older frames should be available).
-
-@item gdb.FRAME_UNWIND_NULL_ID
-The previous frame's analyzer returns an invalid result.  This is no
-longer used by @value{GDBN}, and is kept only for backward
-compatibility.
-
-@item gdb.FRAME_UNWIND_OUTERMOST
-This frame is the outermost.
-
-@item gdb.FRAME_UNWIND_UNAVAILABLE
-Cannot unwind further, because that would require knowing the 
-values of registers or memory that have not been collected.
-
-@item gdb.FRAME_UNWIND_INNER_ID
-This frame ID looks like it ought to belong to a NEXT frame,
-but we got it for a PREV frame.  Normally, this is a sign of
-unwinder failure.  It could also indicate stack corruption.
-
-@item gdb.FRAME_UNWIND_SAME_ID
-This frame has the same ID as the previous one.  That means
-that unwinding further would almost certainly give us another
-frame with exactly the same ID, so break the chain.  Normally,
-this is a sign of unwinder failure.  It could also indicate
-stack corruption.
-
-@item gdb.FRAME_UNWIND_NO_SAVED_PC
-The frame unwinder did not find any saved PC, but we needed
-one to unwind further.
-
-@item gdb.FRAME_UNWIND_FIRST_ERROR
-Any stop reason greater or equal to this value indicates some kind
-of error.  This special value facilitates writing code that tests
-for errors in unwinding in a way that will work correctly even if
-the list of the other values is modified in future @value{GDBN}
-versions.  Using it, you could write:
-@smallexample
-reason = gdb.selected_frame().unwind_stop_reason ()
-reason_str =  gdb.frame_stop_reason_string (reason)
-if reason >=  gdb.FRAME_UNWIND_FIRST_ERROR:
-    print "An error occured: %s" % reason_str
-@end smallexample
-@end table
-
-@end defun
-
-@defun Frame.pc ()
-Returns the frame's resume address.
-@end defun
-
-@defun Frame.block ()
-Return the frame's code block.  @xref{Blocks In Python}.
-@end defun
-
-@defun Frame.function ()
-Return the symbol for the function corresponding to this frame.
-@xref{Symbols In Python}.
-@end defun
-
-@defun Frame.older ()
-Return the frame that called this frame.
-@end defun
-
-@defun Frame.newer ()
-Return the frame called by this frame.
-@end defun
-
-@defun Frame.find_sal ()
-Return the frame's symtab and line object.
-@xref{Symbol Tables In Python}.
-@end defun
-
-@defun Frame.read_var (variable @r{[}, block@r{]})
-Return the value of @var{variable} in this frame.  If the optional
-argument @var{block} is provided, search for the variable from that
-block; otherwise start at the frame's current block (which is
-determined by the frame's current program counter).  @var{variable}
-must be a string or a @code{gdb.Symbol} object.  @var{block} must be a
-@code{gdb.Block} object.
-@end defun
-
-@defun Frame.select ()
-Set this frame to be the selected frame.  @xref{Stack, ,Examining the
-Stack}.
-@end defun
-
-@node Blocks In Python
-@subsubsection Accessing blocks from Python.
-
-@cindex blocks in python
-@tindex gdb.Block
-
-In @value{GDBN}, symbols are stored in blocks.  A block corresponds
-roughly to a scope in the source code.  Blocks are organized
-hierarchically, and are represented individually in Python as a
-@code{gdb.Block}.  Blocks rely on debugging information being
-available.
-
-A frame has a block.  Please see @ref{Frames In Python}, for a more
-in-depth discussion of frames.
-
-The outermost block is known as the @dfn{global block}.  The global
-block typically holds public global variables and functions.
-
-The block nested just inside the global block is the @dfn{static
-block}.  The static block typically holds file-scoped variables and
-functions.
-
-@value{GDBN} provides a method to get a block's superblock, but there
-is currently no way to examine the sub-blocks of a block, or to
-iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
-Python}).
-
-Here is a short example that should help explain blocks:
-
-@smallexample
-/* This is in the global block.  */
-int global;
-
-/* This is in the static block.  */
-static int file_scope;
-
-/* 'function' is in the global block, and 'argument' is
-   in a block nested inside of 'function'.  */
-int function (int argument)
-@{
-  /* 'local' is in a block inside 'function'.  It may or may
-     not be in the same block as 'argument'.  */
-  int local;
-
-  @{
-     /* 'inner' is in a block whose superblock is the one holding
-        'local'.  */
-     int inner;
-
-     /* If this call is expanded by the compiler, you may see
-        a nested block here whose function is 'inline_function'
-        and whose superblock is the one holding 'inner'.  */
-     inline_function ();
-  @}
-@}
-@end smallexample
-
-A @code{gdb.Block} is iterable.  The iterator returns the symbols
-(@pxref{Symbols In Python}) local to the block.  Python programs
-should not assume that a specific block object will always contain a
-given symbol, since changes in @value{GDBN} features and
-infrastructure may cause symbols move across blocks in a symbol
-table.
-
-The following block-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.block_for_pc
-@defun gdb.block_for_pc (pc)
-Return the innermost @code{gdb.Block} containing the given @var{pc}
-value.  If the block cannot be found for the @var{pc} value specified,
-the function will return @code{None}.
-@end defun
-
-A @code{gdb.Block} object has the following methods:
-
-@defun 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.  The block's validity is also checked
-during iteration over symbols of the block.
-@end defun
-
-A @code{gdb.Block} object has the following attributes:
-
-@defvar Block.start
-The start address of the block.  This attribute is not writable.
-@end defvar
-
-@defvar Block.end
-The end address of the block.  This attribute is not writable.
-@end defvar
-
-@defvar Block.function
-The name of the block represented as a @code{gdb.Symbol}.  If the
-block is not named, then this attribute holds @code{None}.  This
-attribute is not writable.
-
-For ordinary function blocks, the superblock is the static block.
-However, you should note that it is possible for a function block to
-have a superblock that is not the static block -- for instance this
-happens for an inlined function.
-@end defvar
-
-@defvar Block.superblock
-The block containing this block.  If this parent block does not exist,
-this attribute holds @code{None}.  This attribute is not writable.
-@end defvar
-
-@defvar Block.global_block
-The global block associated with this block.  This attribute is not
-writable.
-@end defvar
-
-@defvar Block.static_block
-The static block associated with this block.  This attribute is not
-writable.
-@end defvar
-
-@defvar Block.is_global
-@code{True} if the @code{gdb.Block} object is a global block,
-@code{False} if not.  This attribute is not
-writable.
-@end defvar
-
-@defvar Block.is_static
-@code{True} if the @code{gdb.Block} object is a static block,
-@code{False} if not.  This attribute is not writable.
-@end defvar
-
-@node Symbols In Python
-@subsubsection Python representation of Symbols.
-
-@cindex symbols in python
-@tindex gdb.Symbol
-
-@value{GDBN} represents every variable, function and type as an
-entry in a symbol table.  @xref{Symbols, ,Examining the Symbol Table}.
-Similarly, Python represents these symbols in @value{GDBN} with the
-@code{gdb.Symbol} object.
-
-The following symbol-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.lookup_symbol
-@defun gdb.lookup_symbol (name @r{[}, block @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.  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 gdb.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:
-
-@defvar Symbol.type
-The type of the symbol or @code{None} if no type is recorded.
-This attribute is represented as a @code{gdb.Type} object.
-@xref{Types In Python}.  This attribute is not writable.
-@end defvar
-
-@defvar Symbol.symtab
-The symbol table in which the symbol appears.  This attribute is
-represented as a @code{gdb.Symtab} object.  @xref{Symbol Tables In
-Python}.  This attribute is not writable.
-@end defvar
-
-@defvar Symbol.line
-The line number in the source code at which the symbol was defined.
-This is an integer.
-@end defvar
-
-@defvar Symbol.name
-The name of the symbol as a string.  This attribute is not writable.
-@end defvar
-
-@defvar Symbol.linkage_name
-The name of the symbol, as used by the linker (i.e., may be mangled).
-This attribute is not writable.
-@end defvar
-
-@defvar Symbol.print_name
-The name of the symbol in a form suitable for output.  This is either
-@code{name} or @code{linkage_name}, depending on whether the user
-asked @value{GDBN} to display demangled or mangled names.
-@end defvar
-
-@defvar Symbol.addr_class
-The address class of the symbol.  This classifies how to find the value
-of a symbol.  Each address class is a constant defined in the
-@code{gdb} module and described later in this chapter.
-@end defvar
-
-@defvar Symbol.needs_frame
-This is @code{True} if evaluating this symbol's value requires a frame
-(@pxref{Frames In Python}) and @code{False} otherwise.  Typically,
-local variables will require a frame, but other symbols will not.
-@end defvar
-
-@defvar Symbol.is_argument
-@code{True} if the symbol is an argument of a function.
-@end defvar
-
-@defvar Symbol.is_constant
-@code{True} if the symbol is a constant.
-@end defvar
-
-@defvar Symbol.is_function
-@code{True} if the symbol is a function or a method.
-@end defvar
-
-@defvar Symbol.is_variable
-@code{True} if the symbol is a variable.
-@end defvar
-
-A @code{gdb.Symbol} object has the following methods:
-
-@defun 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 defun
-
-@defun Symbol.value (@r{[}frame@r{]})
-Compute the value of the symbol, as a @code{gdb.Value}.  For
-functions, this computes the address of the function, cast to the
-appropriate type.  If the symbol requires a frame in order to compute
-its value, then @var{frame} must be given.  If @var{frame} is not
-given, or if @var{frame} is invalid, then this method will throw an
-exception.
-@end defun
-
-The available domain categories in @code{gdb.Symbol} are represented
-as constants in the @code{gdb} module:
-
-@table @code
-@findex SYMBOL_UNDEF_DOMAIN
-@findex gdb.SYMBOL_UNDEF_DOMAIN
-@item gdb.SYMBOL_UNDEF_DOMAIN
-This is used when a domain has not been discovered or none of the
-following domains apply.  This usually indicates an error either
-in the symbol information or in @value{GDBN}'s handling of symbols.
-@findex SYMBOL_VAR_DOMAIN
-@findex gdb.SYMBOL_VAR_DOMAIN
-@item gdb.SYMBOL_VAR_DOMAIN
-This domain contains variables, function names, typedef names and enum
-type values.
-@findex SYMBOL_STRUCT_DOMAIN
-@findex gdb.SYMBOL_STRUCT_DOMAIN
-@item gdb.SYMBOL_STRUCT_DOMAIN
-This domain holds struct, union and enum type names.
-@findex SYMBOL_LABEL_DOMAIN
-@findex gdb.SYMBOL_LABEL_DOMAIN
-@item gdb.SYMBOL_LABEL_DOMAIN
-This domain contains names of labels (for gotos).
-@findex SYMBOL_VARIABLES_DOMAIN
-@findex gdb.SYMBOL_VARIABLES_DOMAIN
-@item gdb.SYMBOL_VARIABLES_DOMAIN
-This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
-contains everything minus functions and types.
-@findex SYMBOL_FUNCTIONS_DOMAIN
-@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
-@item gdb.SYMBOL_FUNCTION_DOMAIN
-This domain contains all functions.
-@findex SYMBOL_TYPES_DOMAIN
-@findex gdb.SYMBOL_TYPES_DOMAIN
-@item gdb.SYMBOL_TYPES_DOMAIN
-This domain contains all types.
-@end table
-
-The available address class categories in @code{gdb.Symbol} are represented
-as constants in the @code{gdb} module:
-
-@table @code
-@findex SYMBOL_LOC_UNDEF
-@findex gdb.SYMBOL_LOC_UNDEF
-@item gdb.SYMBOL_LOC_UNDEF
-If this is returned by address class, it indicates an error either in
-the symbol information or in @value{GDBN}'s handling of symbols.
-@findex SYMBOL_LOC_CONST
-@findex gdb.SYMBOL_LOC_CONST
-@item gdb.SYMBOL_LOC_CONST
-Value is constant int.
-@findex SYMBOL_LOC_STATIC
-@findex gdb.SYMBOL_LOC_STATIC
-@item gdb.SYMBOL_LOC_STATIC
-Value is at a fixed address.
-@findex SYMBOL_LOC_REGISTER
-@findex gdb.SYMBOL_LOC_REGISTER
-@item gdb.SYMBOL_LOC_REGISTER
-Value is in a register.
-@findex SYMBOL_LOC_ARG
-@findex gdb.SYMBOL_LOC_ARG
-@item gdb.SYMBOL_LOC_ARG
-Value is an argument.  This value is at the offset stored within the
-symbol inside the frame's argument list.
-@findex SYMBOL_LOC_REF_ARG
-@findex gdb.SYMBOL_LOC_REF_ARG
-@item gdb.SYMBOL_LOC_REF_ARG
-Value address is stored in the frame's argument list.  Just like
-@code{LOC_ARG} except that the value's address is stored at the
-offset, not the value itself.
-@findex SYMBOL_LOC_REGPARM_ADDR
-@findex gdb.SYMBOL_LOC_REGPARM_ADDR
-@item gdb.SYMBOL_LOC_REGPARM_ADDR
-Value is a specified register.  Just like @code{LOC_REGISTER} except
-the register holds the address of the argument instead of the argument
-itself.
-@findex SYMBOL_LOC_LOCAL
-@findex gdb.SYMBOL_LOC_LOCAL
-@item gdb.SYMBOL_LOC_LOCAL
-Value is a local variable.
-@findex SYMBOL_LOC_TYPEDEF
-@findex gdb.SYMBOL_LOC_TYPEDEF
-@item gdb.SYMBOL_LOC_TYPEDEF
-Value not used.  Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
-have this class.
-@findex SYMBOL_LOC_BLOCK
-@findex gdb.SYMBOL_LOC_BLOCK
-@item gdb.SYMBOL_LOC_BLOCK
-Value is a block.
-@findex SYMBOL_LOC_CONST_BYTES
-@findex gdb.SYMBOL_LOC_CONST_BYTES
-@item gdb.SYMBOL_LOC_CONST_BYTES
-Value is a byte-sequence.
-@findex SYMBOL_LOC_UNRESOLVED
-@findex gdb.SYMBOL_LOC_UNRESOLVED
-@item gdb.SYMBOL_LOC_UNRESOLVED
-Value is at a fixed address, but the address of the variable has to be
-determined from the minimal symbol table whenever the variable is
-referenced.
-@findex SYMBOL_LOC_OPTIMIZED_OUT
-@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
-@item gdb.SYMBOL_LOC_OPTIMIZED_OUT
-The value does not actually exist in the program.
-@findex SYMBOL_LOC_COMPUTED
-@findex gdb.SYMBOL_LOC_COMPUTED
-@item gdb.SYMBOL_LOC_COMPUTED
-The value's address is a computed location.
-@end table
-
-@node Symbol Tables In Python
-@subsubsection Symbol table representation in Python.
-
-@cindex symbol tables in python
-@tindex gdb.Symtab
-@tindex gdb.Symtab_and_line
-
-Access to symbol table data maintained by @value{GDBN} on the inferior
-is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
-@code{gdb.Symtab}.  Symbol table and line data for a frame is returned
-from the @code{find_sal} method in @code{gdb.Frame} object.
-@xref{Frames In Python}.
-
-For more information on @value{GDBN}'s symbol table management, see
-@ref{Symbols, ,Examining the Symbol Table}, for more information.
-
-A @code{gdb.Symtab_and_line} object has the following attributes:
-
-@defvar Symtab_and_line.symtab
-The symbol table object (@code{gdb.Symtab}) for this frame.
-This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.pc
-Indicates the start of the address range occupied by code for the
-current source line.  This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.last
-Indicates the end of the address range occupied by code for the current
-source line.  This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.line
-Indicates the current line number for this object.  This
-attribute is not writable.
-@end defvar
-
-A @code{gdb.Symtab_and_line} object has the following methods:
-
-@defun 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 defun
-
-A @code{gdb.Symtab} object has the following attributes:
-
-@defvar Symtab.filename
-The symbol table's source filename.  This attribute is not writable.
-@end defvar
-
-@defvar Symtab.objfile
-The symbol table's backing object file.  @xref{Objfiles In Python}.
-This attribute is not writable.
-@end defvar
-
-A @code{gdb.Symtab} object has the following methods:
-
-@defun 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 defun
-
-@defun Symtab.fullname ()
-Return the symbol table's source absolute file name.
-@end defun
-
-@defun Symtab.global_block ()
-Return the global block of the underlying symbol table.
-@xref{Blocks In Python}.
-@end defun
-
-@defun Symtab.static_block ()
-Return the static block of the underlying symbol table.
-@xref{Blocks In Python}.
-@end defun
-
-@defun Symtab.linetable ()
-Return the line table associated with the symbol table.
-@xref{Line Tables In Python}.
-@end defun
-
-@node Line Tables In Python
-@subsubsection Manipulating line tables using Python
-
-@cindex line tables in python
-@tindex gdb.LineTable
-
-Python code can request and inspect line table information from a
-symbol table that is loaded in @value{GDBN}.  A line table is a
-mapping of source lines to their executable locations in memory.  To
-acquire the line table information for a particular symbol table, use
-the @code{linetable} function (@pxref{Symbol Tables In Python}).
-
-A @code{gdb.LineTable} is iterable.  The iterator returns
-@code{LineTableEntry} objects that correspond to the source line and
-address for each line table entry.  @code{LineTableEntry} objects have
-the following attributes:
-
-@defvar LineTableEntry.line
-The source line number for this line table entry.  This number
-corresponds to the actual line of source.  This attribute is not
-writable.
-@end defvar
-
-@defvar LineTableEntry.pc
-The address that is associated with the line table entry where the
-executable code for that source line resides in memory.  This
-attribute is not writable.
-@end defvar
-
-As there can be multiple addresses for a single source line, you may
-receive multiple @code{LineTableEntry} objects with matching
-@code{line} attributes, but with different @code{pc} attributes.  The
-iterator is sorted in ascending @code{pc} order.  Here is a small
-example illustrating iterating over a line table.
-
-@smallexample
-symtab = gdb.selected_frame().find_sal().symtab
-linetable = symtab.linetable()
-for line in linetable:
-   print "Line: "+str(line.line)+" Address: "+hex(line.pc)
-@end smallexample
-
-This will have the following output:
-
-@smallexample
-Line: 33 Address: 0x4005c8L
-Line: 37 Address: 0x4005caL
-Line: 39 Address: 0x4005d2L
-Line: 40 Address: 0x4005f8L
-Line: 42 Address: 0x4005ffL
-Line: 44 Address: 0x400608L
-Line: 42 Address: 0x40060cL
-Line: 45 Address: 0x400615L
-@end smallexample
-
-In addition to being able to iterate over a @code{LineTable}, it also
-has the following direct access methods:
-
-@defun LineTable.line (line)
-Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
-entries in the line table for the given @var{line}.  @var{line} refers
-to the source code line.  If there are no entries for that source code
-@var{line}, the Python @code{None} is returned.
-@end defun
-
-@defun LineTable.has_line (line)
-Return a Python @code{Boolean} indicating whether there is an entry in
-the line table for this source line.  Return @code{True} if an entry
-is found, or @code{False} if not.
-@end defun
-
-@defun LineTable.source_lines ()
-Return a Python @code{List} of the source line numbers in the symbol
-table.  Only lines with executable code locations are returned.  The
-contents of the @code{List} will just be the source line entries
-represented as Python @code{Long} values.
-@end defun
-
-@node Breakpoints In Python
-@subsubsection Manipulating breakpoints using Python
-
-@cindex breakpoints in python
-@tindex gdb.Breakpoint
-
-Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
-class.
-
-@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@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 @code{break} command,
-or in the case of a watchpoint, by the @code{watch} command.  The
-optional @var{type} denotes the breakpoint to create from the types
-defined later in this chapter.  This argument can be either:
-@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}.  @var{type}
-defaults to @code{gdb.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{temporary} argument makes the breakpoint a temporary breakpoint.
-Temporary breakpoints are deleted after they have been hit.  Any
-further access to the Python breakpoint after it has been hit will
-result in a runtime error (as that breakpoint has now been
-automatically deleted).  The optional @var{wp_class} argument defines
-the class of watchpoint to create, if @var{type} is
-@code{gdb.BP_WATCHPOINT}.  If a watchpoint class is not provided, it
-is assumed to be a @code{gdb.WP_WRITE} class.
-@end defun
-
-@defun 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 in 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.
-
-You should not alter the execution state of the inferior (i.e.@:, step,
-next, etc.), alter the current frame context (i.e.@:, change the current
-active frame), or alter, add or delete any breakpoint.  As a general
-rule, you should not alter any data within @value{GDBN} or the inferior
-at this time.
-
-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 defun
-
-The available watchpoint types represented by constants are defined in the
-@code{gdb} module:
-
-@table @code
-@findex WP_READ
-@findex gdb.WP_READ
-@item gdb.WP_READ
-Read only watchpoint.
-
-@findex WP_WRITE
-@findex gdb.WP_WRITE
-@item gdb.WP_WRITE
-Write only watchpoint.
-
-@findex WP_ACCESS
-@findex gdb.WP_ACCESS
-@item gdb.WP_ACCESS
-Read/Write watchpoint.
-@end table
-
-@defun Breakpoint.is_valid ()
-Return @code{True} if this @code{Breakpoint} object is valid,
-@code{False} otherwise.  A @code{Breakpoint} object can become invalid
-if the user deletes the breakpoint.  In this case, the object still
-exists, but the underlying breakpoint does not.  In the cases of
-watchpoint scope, the watchpoint remains valid even if execution of the
-inferior leaves the scope of that watchpoint.
-@end defun
-
-@defun 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 defun
-
-@defvar Breakpoint.enabled
-This attribute is @code{True} if the breakpoint is enabled, and
-@code{False} otherwise.  This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.silent
-This attribute is @code{True} if the breakpoint is silent, and
-@code{False} otherwise.  This attribute is writable.
-
-Note that a breakpoint can also be silent if it has commands and the
-first command is @code{silent}.  This is not reported by the
-@code{silent} attribute.
-@end defvar
-
-@defvar Breakpoint.thread
-If the breakpoint is thread-specific, this attribute holds the thread
-id.  If the breakpoint is not thread-specific, this attribute is
-@code{None}.  This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.task
-If the breakpoint is Ada task-specific, this attribute holds the Ada task
-id.  If the breakpoint is not task-specific (or the underlying
-language is not Ada), this attribute is @code{None}.  This attribute
-is writable.
-@end defvar
-
-@defvar Breakpoint.ignore_count
-This attribute holds the ignore count for the breakpoint, an integer.
-This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.number
-This attribute holds the breakpoint's number --- the identifier used by
-the user to manipulate the breakpoint.  This attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.type
-This attribute holds the breakpoint's type --- the identifier used to
-determine the actual breakpoint type or use-case.  This attribute is not
-writable.
-@end defvar
-
-@defvar 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 defvar
-
-@defvar Breakpoint.temporary
-This attribute indicates whether the breakpoint was created as a
-temporary breakpoint.  Temporary breakpoints are automatically deleted
-after that breakpoint has been hit.  Access to this attribute, and all
-other attributes and functions other than the @code{is_valid}
-function, will result in an error after the breakpoint has been hit
-(as it has been automatically deleted).  This attribute is not
-writable.
-@end defvar
-
-The available types are represented by constants defined in the @code{gdb}
-module:
-
-@table @code
-@findex BP_BREAKPOINT
-@findex gdb.BP_BREAKPOINT
-@item gdb.BP_BREAKPOINT
-Normal code breakpoint.
-
-@findex BP_WATCHPOINT
-@findex gdb.BP_WATCHPOINT
-@item gdb.BP_WATCHPOINT
-Watchpoint breakpoint.
-
-@findex BP_HARDWARE_WATCHPOINT
-@findex gdb.BP_HARDWARE_WATCHPOINT
-@item gdb.BP_HARDWARE_WATCHPOINT
-Hardware assisted watchpoint.
-
-@findex BP_READ_WATCHPOINT
-@findex gdb.BP_READ_WATCHPOINT
-@item gdb.BP_READ_WATCHPOINT
-Hardware assisted read watchpoint.
-
-@findex BP_ACCESS_WATCHPOINT
-@findex gdb.BP_ACCESS_WATCHPOINT
-@item gdb.BP_ACCESS_WATCHPOINT
-Hardware assisted access watchpoint.
-@end table
-
-@defvar Breakpoint.hit_count
-This attribute holds the hit count for the breakpoint, an integer.
-This attribute is writable, but currently it can only be set to zero.
-@end defvar
-
-@defvar Breakpoint.location
-This attribute holds the location of the breakpoint, as specified by
-the user.  It is a string.  If the breakpoint does not have a location
-(that is, it is a watchpoint) the attribute's value is @code{None}.  This
-attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.expression
-This attribute holds a breakpoint expression, as specified by
-the user.  It is a string.  If the breakpoint does not have an
-expression (the breakpoint is not a watchpoint) the attribute's value
-is @code{None}.  This attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.condition
-This attribute holds the condition of the breakpoint, as specified by
-the user.  It is a string.  If there is no condition, this attribute's
-value is @code{None}.  This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.commands
-This attribute holds the commands attached to the breakpoint.  If
-there are commands, this attribute's value is a string holding all the
-commands, separated by newlines.  If there are no commands, this
-attribute is @code{None}.  This attribute is not writable.
-@end defvar
-
-@node Finish Breakpoints in Python
-@subsubsection Finish Breakpoints
-
-@cindex python finish breakpoints
-@tindex gdb.FinishBreakpoint
-
-A finish breakpoint is a temporary breakpoint set at the return address of
-a frame, based on the @code{finish} command.  @code{gdb.FinishBreakpoint}
-extends @code{gdb.Breakpoint}.  The underlying breakpoint will be disabled 
-and deleted when the execution will run out of the breakpoint scope (i.e.@: 
-@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
-Finish breakpoints are thread specific and must be create with the right 
-thread selected.  
- 
-@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
-Create a finish breakpoint at the return address of the @code{gdb.Frame}
-object @var{frame}.  If @var{frame} is not provided, this defaults to the
-newest frame.  The optional @var{internal} argument allows the breakpoint to
-become invisible to the user.  @xref{Breakpoints In Python}, for further 
-details about this argument.
-@end defun
-
-@defun FinishBreakpoint.out_of_scope (self)
-In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} 
-@code{return} command, @dots{}), a function may not properly terminate, and
-thus never hit the finish breakpoint.  When @value{GDBN} notices such a
-situation, the @code{out_of_scope} callback will be triggered.
-
-You may want to sub-class @code{gdb.FinishBreakpoint} and override this
-method:
-
-@smallexample
-class MyFinishBreakpoint (gdb.FinishBreakpoint)
-    def stop (self):
-        print "normal finish"
-        return True
-    
-    def out_of_scope ():
-        print "abnormal finish"
-@end smallexample 
-@end defun
-
-@defvar FinishBreakpoint.return_value
-When @value{GDBN} is stopped at a finish breakpoint and the frame 
-used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
-attribute will contain a @code{gdb.Value} object corresponding to the return
-value of the function.  The value will be @code{None} if the function return 
-type is @code{void} or if the return value was not computable.  This attribute
-is not writable.
-@end defvar
-
-@node Lazy Strings In Python
-@subsubsection Python representation of lazy strings.
-
-@cindex lazy strings in python
-@tindex gdb.LazyString
-
-A @dfn{lazy string} is a string whose contents is not retrieved or
-encoded until it is needed.
-
-A @code{gdb.LazyString} is represented in @value{GDBN} as an
-@code{address} that points to a region of memory, an @code{encoding}
-that will be used to encode that region of memory, and a @code{length}
-to delimit the region of memory that represents the string.  The
-difference between a @code{gdb.LazyString} and a string wrapped within
-a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
-differently by @value{GDBN} when printing.  A @code{gdb.LazyString} is
-retrieved and encoded during printing, while a @code{gdb.Value}
-wrapping a string is immediately retrieved and encoded on creation.
-
-A @code{gdb.LazyString} object has the following functions:
-
-@defun LazyString.value ()
-Convert the @code{gdb.LazyString} to a @code{gdb.Value}.  This value
-will point to the string in memory, but will lose all the delayed
-retrieval, encoding and handling that @value{GDBN} applies to a
-@code{gdb.LazyString}.
-@end defun
-
-@defvar LazyString.address
-This attribute holds the address of the string.  This attribute is not
-writable.
-@end defvar
-
-@defvar LazyString.length
-This attribute holds the length of the string in characters.  If the
-length is -1, then the string will be fetched and encoded up to the
-first null of appropriate width.  This attribute is not writable.
-@end defvar
-
-@defvar LazyString.encoding
-This attribute holds the encoding that will be applied to the string
-when the string is printed by @value{GDBN}.  If the encoding is not
-set, or contains an empty string,  then @value{GDBN} will select the
-most appropriate encoding when the string is printed.  This attribute
-is not writable.
-@end defvar
-
-@defvar LazyString.type
-This attribute holds the type that is represented by the lazy string's
-type.  For a lazy string this will always be a pointer type.  To
-resolve this to the lazy string's character type, use the type's
-@code{target} method.  @xref{Types In Python}.  This attribute is not
-writable.
-@end defvar
-
-@node Architectures In Python
-@subsubsection Python representation of architectures
-@cindex Python architectures
-
-@value{GDBN} uses architecture specific parameters and artifacts in a
-number of its various computations.  An architecture is represented
-by an instance of the @code{gdb.Architecture} class.
-
-A @code{gdb.Architecture} class has the following methods:
-
-@defun Architecture.name ()
-Return the name (string value) of the architecture.
-@end defun
-
-@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
-Return a list of disassembled instructions starting from the memory
-address @var{start_pc}.  The optional arguments @var{end_pc} and
-@var{count} determine the number of instructions in the returned list.
-If both the optional arguments @var{end_pc} and @var{count} are
-specified, then a list of at most @var{count} disassembled instructions
-whose start address falls in the closed memory address interval from
-@var{start_pc} to @var{end_pc} are returned.  If @var{end_pc} is not
-specified, but @var{count} is specified, then @var{count} number of
-instructions starting from the address @var{start_pc} are returned.  If
-@var{count} is not specified but @var{end_pc} is specified, then all
-instructions whose start address falls in the closed memory address
-interval from @var{start_pc} to @var{end_pc} are returned.  If neither
-@var{end_pc} nor @var{count} are specified, then a single instruction at
-@var{start_pc} is returned.  For all of these cases, each element of the
-returned list is a Python @code{dict} with the following string keys:
-
-@table @code
-
-@item addr
-The value corresponding to this key is a Python long integer capturing
-the memory address of the instruction.
-
-@item asm
-The value corresponding to this key is a string value which represents
-the instruction with assembly language mnemonics.  The assembly
-language flavor used is the same as that specified by the current CLI
-variable @code{disassembly-flavor}.  @xref{Machine Code}.
-
-@item length
-The value corresponding to this key is the length (integer value) of the
-instruction in bytes.
-
-@end table
-@end defun
-
-@node Python Auto-loading
-@subsection Python Auto-loading
-@cindex Python auto-loading
-
-When a new object file is read (for example, due to the @code{file}
-command, or because the inferior has loaded a shared library),
-@value{GDBN} will look for Python support scripts in several ways:
-@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
-@xref{Auto-loading extensions}.
-
-The auto-loading feature is useful for supplying application-specific
-debugging commands and scripts.
-
-Auto-loading can be enabled or disabled,
-and the list of auto-loaded scripts can be printed.
-
-@table @code
-@anchor{set auto-load python-scripts}
-@kindex set auto-load python-scripts
-@item set auto-load python-scripts [on|off]
-Enable or disable the auto-loading of Python scripts.
-
-@anchor{show auto-load python-scripts}
-@kindex show auto-load python-scripts
-@item show auto-load python-scripts
-Show whether auto-loading of Python scripts is enabled or disabled.
-
-@anchor{info auto-load python-scripts}
-@kindex info auto-load python-scripts
-@cindex print list of auto-loaded Python scripts
-@item info auto-load python-scripts [@var{regexp}]
-Print the list of all Python scripts that @value{GDBN} auto-loaded.
-
-Also printed is the list of Python scripts that were mentioned in
-the @code{.debug_gdb_scripts} section and were not found
-(@pxref{dotdebug_gdb_scripts section}).
-This is useful because their names are not printed when @value{GDBN}
-tries to load them and fails.  There may be many of them, and printing
-an error message for each one is problematic.
-
-If @var{regexp} is supplied only Python scripts with matching names are printed.
-
-Example:
-
-@smallexample
-(gdb) info auto-load python-scripts
-Loaded Script
-Yes    py-section-script.py
-       full name: /tmp/py-section-script.py
-No     my-foo-pretty-printers.py
-@end smallexample
-@end table
-
-When reading an auto-loaded file, @value{GDBN} sets the
-@dfn{current objfile}.  This is available via the @code{gdb.current_objfile}
-function (@pxref{Objfiles In Python}).  This can be useful for
-registering objfile-specific pretty-printers and frame-filters.
-
-@node Python modules
-@subsection Python modules
-@cindex python modules
-
-@value{GDBN} comes with several modules to assist writing Python code.
-
-@menu
-* gdb.printing::       Building and registering pretty-printers.
-* gdb.types::          Utilities for working with types.
-* gdb.prompt::         Utilities for prompt value substitution.
-@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 FlagEnumerationPrinter (@var{name})
-A pretty-printer which handles printing of @code{enum} values.  Unlike
-@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
-work properly when there is some overlap between the enumeration
-constants.  @var{name} is the name of the printer and also the name of
-the @code{enum} type to look up.
-
-@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
-Register @var{printer} with the pretty-printer list of @var{obj}.
-If @var{replace} is @code{True} then any existing copy of the printer
-is replaced.  Otherwise a @code{RuntimeError} exception is raised
-if a printer with the same name already exists.
-@end table
-
-@node gdb.types
-@subsubsection gdb.types
-@cindex gdb.types
-
-This module provides a collection of utilities for working with
-@code{gdb.Type} 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}.
-
-@item deep_items (@var{type})
-Returns a Python iterator similar to the standard
-@code{gdb.Type.iteritems} method, except that the iterator returned
-by @code{deep_items} will recursively traverse anonymous struct or
-union fields.  For example:
-
-@smallexample
-struct A
-@{
-    int a;
-    union @{
-        int b0;
-        int b1;
-    @};
-@};
-@end smallexample
-
-@noindent
-Then in @value{GDBN}:
-@smallexample
-(@value{GDBP}) python import gdb.types
-(@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
-(@value{GDBP}) python print struct_a.keys ()
-@{['a', '']@}
-(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
-@{['a', 'b0', 'b1']@}
-@end smallexample
-
-@item get_type_recognizers ()
-Return a list of the enabled type recognizers for the current context.
-This is called by @value{GDBN} during the type-printing process
-(@pxref{Type Printing API}).
-
-@item apply_type_recognizers (recognizers, type_obj)
-Apply the type recognizers, @var{recognizers}, to the type object
-@var{type_obj}.  If any recognizer returns a string, return that
-string.  Otherwise, return @code{None}.  This is called by
-@value{GDBN} during the type-printing process (@pxref{Type Printing
-API}).
-
-@item register_type_printer (locus, printer)
-This is a convenience function to register a type printer.
-@var{printer} is the type printer to register.  It must implement the
-type printer protocol.  @var{locus} is either a @code{gdb.Objfile}, in
-which case the printer is registered with that objfile; a
-@code{gdb.Progspace}, in which case the printer is registered with
-that progspace; or @code{None}, in which case the printer is
-registered globally.
-
-@item TypePrinter
-This is a base class that implements the type printer protocol.  Type
-printers are encouraged, but not required, to derive from this class.
-It defines a constructor:
-
-@defmethod TypePrinter __init__ (self, name)
-Initialize the type printer with the given name.  The new printer
-starts in the enabled state.
-@end defmethod
-
-@end table
-
-@node gdb.prompt
-@subsubsection gdb.prompt
-@cindex gdb.prompt
-
-This module provides a method for prompt value-substitution.
-
-@table @code
-@item substitute_prompt (@var{string})
-Return @var{string} with escape sequences substituted by values.  Some
-escape sequences take arguments.  You can specify arguments inside
-``@{@}'' immediately following the escape sequence.
-
-The escape sequences you can pass to this function are:
-
-@table @code
-@item \\
-Substitute a backslash.
-@item \e
-Substitute an ESC character.
-@item \f
-Substitute the selected frame; an argument names a frame parameter.
-@item \n
-Substitute a newline.
-@item \p
-Substitute a parameter's value; the argument names the parameter.
-@item \r
-Substitute a carriage return.
-@item \t
-Substitute the selected thread; an argument names a thread parameter.
-@item \v
-Substitute the version of GDB.
-@item \w
-Substitute the current working directory.
-@item \[
-Begin a sequence of non-printing characters.  These sequences are
-typically used with the ESC character, and are not counted in the string
-length.  Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
-blue-colored ``(gdb)'' prompt where the length is five.
-@item \]
-End a sequence of non-printing characters.
-@end table
-
-For example:
-
-@smallexample
-substitute_prompt (``frame: \f,
-                   print arguments: \p@{print frame-arguments@}'')
-@end smallexample
-
-@exdent will return the string:
-
-@smallexample
-"frame: main, print arguments: scalars"
-@end smallexample
-@end table
+@c Python docs live in a separate file.
+@include python.texi
 
 @c Guile docs live in a separate file.
 @include guile.texi
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
new file mode 100644
index 0000000..62636a4
--- /dev/null
+++ b/gdb/doc/python.texi
@@ -0,0 +1,4444 @@
+@c Copyright (C) 2008-2014 Free Software Foundation, Inc.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with the
+@c Invariant Sections being ``Free Software'' and ``Free Software Needs
+@c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+@c and with the Back-Cover Texts as in (a) below.
+@c 
+@c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
+@c this GNU Manual.  Buying copies from GNU Press supports the FSF in
+@c developing GNU and promoting software freedom.''
+
+@node Python
+@section Extending @value{GDBN} using Python
+@cindex python scripting
+@cindex scripting with python
+
+You can extend @value{GDBN} using the @uref{http://www.python.org/,
+Python programming language}.  This feature is available only if
+@value{GDBN} was configured using @option{--with-python}.
+
+@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},
+is automatically added to the Python Search Path in order to allow
+the Python interpreter to locate all scripts installed at this location.
+
+Additionally, @value{GDBN} commands and convenience functions which
+are written in Python and are located in the
+@file{@var{data-directory}/python/gdb/command} or
+@file{@var{data-directory}/python/gdb/function} directories are
+automatically imported when @value{GDBN} starts.
+
+@menu
+* Python Commands::             Accessing Python from @value{GDBN}.
+* Python API::                  Accessing @value{GDBN} from Python.
+* Python Auto-loading::         Automatically loading Python code.
+* Python modules::              Python modules provided by @value{GDBN}.
+@end menu
+
+@node Python Commands
+@subsection Python Commands
+@cindex python commands
+@cindex commands to access python
+
+@value{GDBN} provides two commands for accessing the Python interpreter,
+and one related setting:
+
+@table @code
+@kindex python-interactive
+@kindex pi
+@item python-interactive @r{[}@var{command}@r{]}
+@itemx pi @r{[}@var{command}@r{]}
+Without an argument, the @code{python-interactive} command can be used
+to start an interactive Python prompt.  To return to @value{GDBN},
+type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
+
+Alternatively, a single-line Python command can be given as an
+argument and evaluated.  If the command is an expression, the result
+will be printed; otherwise, nothing will be printed.  For example:
+
+@smallexample
+(@value{GDBP}) python-interactive 2 + 3
+5
+@end smallexample
+
+@kindex python
+@kindex py
+@item python @r{[}@var{command}@r{]}
+@itemx py @r{[}@var{command}@r{]}
+The @code{python} command can be used to evaluate Python code.
+
+If given an argument, the @code{python} command will evaluate the
+argument as a Python command.  For example:
+
+@smallexample
+(@value{GDBP}) python print 23
+23
+@end smallexample
+
+If you do not provide an argument to @code{python}, it will act as a
+multi-line command, like @code{define}.  In this case, the Python
+script is made up of subsequent command lines, given after the
+@code{python} command.  This command list is terminated using a line
+containing @code{end}.  For example:
+
+@smallexample
+(@value{GDBP}) python
+Type python script
+End with a line saying just "end".
+>print 23
+>end
+23
+@end smallexample
+
+@kindex set python print-stack
+@item set python print-stack
+By default, @value{GDBN} will print only the message component of a
+Python exception when an error occurs in a Python script.  This can be
+controlled using @code{set python print-stack}: if @code{full}, then
+full Python stack printing is enabled; if @code{none}, then Python stack
+and message printing is disabled; if @code{message}, the default, only
+the message component of the error is printed.
+@end table
+
+It is also possible to execute a Python script from the @value{GDBN}
+interpreter:
+
+@table @code
+@item source @file{script-name}
+The script name must end with @samp{.py} and @value{GDBN} must be configured
+to recognize the script language based on filename extension using
+the @code{script-extension} setting.  @xref{Extending GDB, ,Extending GDB}.
+
+@item python execfile ("script-name")
+This method is based on the @code{execfile} Python built-in function,
+and thus is always available.
+@end table
+
+@node Python API
+@subsection Python API
+@cindex python api
+@cindex programming in python
+
+You can get quick online help for @value{GDBN}'s Python API by issuing
+the command @w{@kbd{python help (gdb)}}.
+
+Functions and methods which have two or more optional arguments allow
+them to be specified using keyword syntax.  This allows passing some
+optional arguments while skipping others.  Example:
+@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
+
+@menu
+* Basic Python::                Basic Python Functions.
+* 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.
+* Writing a Pretty-Printer::    Writing a Pretty-Printer.
+* Type Printing API::		Pretty-printing types.
+* Frame Filter API::            Filtering Frames.
+* Frame Decorator API::         Decorating Frames.
+* Writing a Frame Filter::      Writing a Frame Filter.
+* 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.
+* Functions In Python::         Writing new convenience functions.
+* Progspaces In Python::        Program spaces.
+* Objfiles In Python::          Object files.
+* Frames In Python::            Accessing inferior stack frames from Python.
+* Blocks In Python::            Accessing blocks from Python.
+* Symbols In Python::           Python representation of symbols.
+* Symbol Tables In Python::     Python representation of symbol tables.
+* Line Tables In Python::       Python representation of line tables.
+* Breakpoints In Python::       Manipulating breakpoints using Python.
+* Finish Breakpoints in Python:: Setting Breakpoints on function return
+                                using Python.
+* Lazy Strings In Python::      Python representation of lazy strings.
+* Architectures In Python::     Python representation of architectures.
+@end menu
+
+@node Basic Python
+@subsubsection Basic Python
+
+@cindex python stdout
+@cindex python pagination
+At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
+@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
+A Python program which outputs to one of these streams may have its
+output interrupted by the user (@pxref{Screen Size}).  In this
+situation, a Python @code{KeyboardInterrupt} exception is thrown.
+
+Some care must be taken when writing Python code to run in
+@value{GDBN}.  Two things worth noting in particular:
+
+@itemize @bullet
+@item
+@value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
+Python code must not override these, or even change the options using
+@code{sigaction}.  If your program changes the handling of these
+signals, @value{GDBN} will most likely stop working correctly.  Note
+that it is unfortunately common for GUI toolkits to install a
+@code{SIGCHLD} handler.
+
+@item
+@value{GDBN} takes care to mark its internal file descriptors as
+close-on-exec.  However, this cannot be done in a thread-safe way on
+all platforms.  Your Python programs should be aware of this and
+should both create new file descriptors with the close-on-exec flag
+set and arrange to close unneeded file descriptors before starting a
+child process.
+@end itemize
+
+@cindex python functions
+@cindex python module
+@cindex gdb module
+@value{GDBN} introduces a new Python module, named @code{gdb}.  All
+methods and classes added by @value{GDBN} are placed in this module.
+@value{GDBN} automatically @code{import}s the @code{gdb} module for
+use in all scripts evaluated by the @code{python} command.
+
+@findex gdb.PYTHONDIR
+@defvar gdb.PYTHONDIR
+A string containing the python directory (@pxref{Python}).
+@end defvar
+
+@findex gdb.execute
+@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
+Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
+If a GDB exception happens while @var{command} runs, it is
+translated as described in @ref{Exception Handling,,Exception Handling}.
+
+@var{from_tty} specifies whether @value{GDBN} ought to consider this
+command as having originated from the user invoking it interactively.
+It must be a boolean value.  If omitted, it defaults to @code{False}.
+
+By default, any output produced by @var{command} is sent to
+@value{GDBN}'s standard output.  If the @var{to_string} parameter is
+@code{True}, then output will be collected by @code{gdb.execute} and
+returned as a string.  The default is @code{False}, in which case the
+return value is @code{None}.  If @var{to_string} is @code{True}, the
+@value{GDBN} virtual terminal will be temporarily set to unlimited width
+and height, and its pagination will be disabled; @pxref{Screen Size}.
+@end defun
+
+@findex gdb.breakpoints
+@defun gdb.breakpoints ()
+Return a sequence holding all of @value{GDBN}'s breakpoints.
+@xref{Breakpoints In Python}, for more information.
+@end defun
+
+@findex gdb.parameter
+@defun gdb.parameter (parameter)
+Return the value of a @value{GDBN} parameter.  @var{parameter} is a
+string naming the parameter to look up; @var{parameter} may contain
+spaces if the parameter has a multi-part name.  For example,
+@samp{print object} is a valid parameter name.
+
+If the named parameter does not exist, this function throws a
+@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
+@defun gdb.history (number)
+Return a value from @value{GDBN}'s value history (@pxref{Value
+History}).  @var{number} indicates which history element to return.
+If @var{number} is negative, then @value{GDBN} will take its absolute value
+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{gdb.error} exception will be
+raised.
+
+If no exception is raised, the return value is always an instance of
+@code{gdb.Value} (@pxref{Values From Inferior}).
+@end defun
+
+@findex gdb.parse_and_eval
+@defun gdb.parse_and_eval (expression)
+Parse @var{expression} as an expression in the current language,
+evaluate it, and return the result as a @code{gdb.Value}.
+@var{expression} must be a string.
+
+This function can be useful when implementing a new command
+(@pxref{Commands In Python}), as it provides a way to parse the
+command's argument as an expression.  It is also useful simply to
+compute values, for example, it is the only way to get the value of a
+convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
+@end defun
+
+@findex gdb.find_pc_line
+@defun gdb.find_pc_line (pc)
+Return the @code{gdb.Symtab_and_line} object corresponding to the
+@var{pc} value.  @xref{Symbol Tables In Python}.  If an invalid
+value of @var{pc} is passed as an argument, then the @code{symtab} and
+@code{line} attributes of the returned @code{gdb.Symtab_and_line} object
+will be @code{None} and 0 respectively.
+@end defun
+
+@findex gdb.post_event
+@defun gdb.post_event (event)
+Put @var{event}, a callable object taking no arguments, into
+@value{GDBN}'s internal event queue.  This callable will be invoked at
+some later point, during @value{GDBN}'s event processing.  Events
+posted using @code{post_event} will be run in the order in which they
+were posted; however, there is no way to know when they will be
+processed relative to other events inside @value{GDBN}.
+
+@value{GDBN} is not thread-safe.  If your Python program uses multiple
+threads, you must be careful to only call @value{GDBN}-specific
+functions in the main @value{GDBN} thread.  @code{post_event} ensures
+this.  For example:
+
+@smallexample
+(@value{GDBP}) python
+>import threading
+>
+>class Writer():
+> def __init__(self, message):
+>        self.message = message;
+> def __call__(self):
+>        gdb.write(self.message)
+>
+>class MyThread1 (threading.Thread):
+> def run (self):
+>        gdb.post_event(Writer("Hello "))
+>
+>class MyThread2 (threading.Thread):
+> def run (self):
+>        gdb.post_event(Writer("World\n"))
+>
+>MyThread1().start()
+>MyThread2().start()
+>end
+(@value{GDBP}) Hello World
+@end smallexample
+@end defun
+
+@findex gdb.write 
+@defun gdb.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 gdb.STDOUT
+@value{GDBN}'s standard output stream.
+
+@findex STDERR
+@findex gdb.STDERR
+@item gdb.STDERR
+@value{GDBN}'s standard error stream.
+
+@findex STDLOG
+@findex gdb.STDLOG
+@item gdb.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 and will automatically direct the output to the
+relevant stream.
+@end defun
+
+@findex gdb.flush
+@defun gdb.flush ()
+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 gdb.STDOUT
+@value{GDBN}'s standard output stream.
+
+@findex STDERR
+@findex gdb.STDERR
+@item gdb.STDERR
+@value{GDBN}'s standard error stream.
+
+@findex STDLOG
+@findex gdb.STDLOG
+@item gdb.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
+@defun gdb.target_charset ()
+Return the name of the current target character set (@pxref{Character
+Sets}).  This differs from @code{gdb.parameter('target-charset')} in
+that @samp{auto} is never returned.
+@end defun
+
+@findex gdb.target_wide_charset
+@defun gdb.target_wide_charset ()
+Return the name of the current target wide character set
+(@pxref{Character Sets}).  This differs from
+@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
+never returned.
+@end defun
+
+@findex gdb.solib_name
+@defun gdb.solib_name (address)
+Return the name of the shared library holding the given @var{address}
+as a string, or @code{None}.
+@end defun
+
+@findex gdb.decode_line 
+@defun gdb.decode_line @r{[}expression@r{]}
+Return locations of the line specified by @var{expression}, or of the
+current line if no argument was given.  This function returns a Python
+tuple containing two elements.  The first element contains a string
+holding any unparsed section of @var{expression} (or @code{None} if
+the expression has been fully parsed).  The second element contains
+either @code{None} or another tuple that contains all the locations
+that match the expression represented as @code{gdb.Symtab_and_line}
+objects (@pxref{Symbol Tables In Python}).  If @var{expression} is
+provided, it is decoded the way that @value{GDBN}'s inbuilt
+@code{break} or @code{edit} commands do (@pxref{Specify Location}).
+@end defun
+
+@defun gdb.prompt_hook (current_prompt)
+@anchor{prompt_hook}
+
+If @var{prompt_hook} is callable, @value{GDBN} will call the method
+assigned to this operation before a prompt is displayed by
+@value{GDBN}.
+
+The parameter @code{current_prompt} contains the current @value{GDBN} 
+prompt.  This method must return a Python string, or @code{None}.  If
+a string is returned, the @value{GDBN} prompt will be set to that
+string.  If @code{None} is returned, @value{GDBN} will continue to use
+the current prompt.
+
+Some prompts cannot be substituted in @value{GDBN}.  Secondary prompts
+such as those used by readline for command input, and annotation
+related prompts are prohibited from being changed.
+@end defun
+
+@node Exception Handling
+@subsubsection Exception Handling
+@cindex python exceptions
+@cindex exceptions, python
+
+When executing the @code{python} command, Python exceptions
+uncaught within the Python code are translated to calls to
+@value{GDBN} error-reporting mechanism.  If the command that called
+@code{python} does not handle the error, @value{GDBN} will
+terminate it and print an error message containing the Python
+exception name, the associated value, and the Python call stack
+backtrace at the point where the exception was raised.  Example:
+
+@smallexample
+(@value{GDBP}) python print foo
+Traceback (most recent call last):
+  File "<string>", line 1, in <module>
+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 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
+When implementing @value{GDBN} commands in Python via @code{gdb.Command},
+it is useful to be able to throw an exception that doesn't cause a
+traceback to be printed.  For example, the user may have invoked the
+command incorrectly.  Use the @code{gdb.GdbError} exception
+to handle this case.  Example:
+
+@smallexample
+(gdb) python
+>class HelloWorld (gdb.Command):
+>  """Greet the whole world."""
+>  def __init__ (self):
+>    super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
+>  def invoke (self, args, from_tty):
+>    argv = gdb.string_to_argv (args)
+>    if len (argv) != 0:
+>      raise gdb.GdbError ("hello-world takes no arguments")
+>    print "Hello, World!"
+>HelloWorld ()
+>end
+(gdb) hello-world 42
+hello-world takes no arguments
+@end smallexample
+
+@node Values From Inferior
+@subsubsection Values From Inferior
+@cindex values from inferior, with Python
+@cindex python, working with values from inferior
+
+@cindex @code{gdb.Value}
+@value{GDBN} provides values it obtains from the inferior program in
+an object of type @code{gdb.Value}.  @value{GDBN} uses this object
+for its internal bookkeeping of the inferior's values, and for
+fetching values when necessary.
+
+Inferior values that are simple scalars can be used directly in
+Python expressions that are valid for the value's data type.  Here's
+an example for an integer or floating-point value @code{some_val}:
+
+@smallexample
+bar = some_val + 2
+@end smallexample
+
+@noindent
+As result of this, @code{bar} will also be a @code{gdb.Value} object
+whose values are of the same type as those of @code{some_val}.
+
+Inferior values that are structures or instances of some class can
+be accessed using the Python @dfn{dictionary syntax}.  For example, if
+@code{some_val} is a @code{gdb.Value} instance holding a structure, you
+can access its @code{foo} element with:
+
+@smallexample
+bar = some_val['foo']
+@end smallexample
+
+@cindex getting structure elements using gdb.Field objects as subscripts
+Again, @code{bar} will also be a @code{gdb.Value} object.  Structure
+elements can also be accessed by using @code{gdb.Field} objects as
+subscripts (@pxref{Types In Python}, for more information on
+@code{gdb.Field} objects).  For example, if @code{foo_field} is a
+@code{gdb.Field} object corresponding to element @code{foo} of the above
+structure, then @code{bar} can also be accessed as follows:
+
+@smallexample
+bar = some_val[foo_field]
+@end smallexample
+
+A @code{gdb.Value} that represents a function can be executed via
+inferior function call.  Any arguments provided to the call must match
+the function's prototype, and must be provided in the order specified
+by that prototype.
+
+For example, @code{some_val} is a @code{gdb.Value} instance
+representing a function that takes two integers as arguments.  To
+execute this function, call it like so:
+
+@smallexample
+result = some_val (10,20)
+@end smallexample
+
+Any values returned from a function call will be stored as a
+@code{gdb.Value}.
+
+The following attributes are provided:
+
+@defvar Value.address
+If this object is addressable, this read-only attribute holds a
+@code{gdb.Value} object representing the address.  Otherwise,
+this attribute holds @code{None}.
+@end defvar
+
+@cindex optimized out value in Python
+@defvar Value.is_optimized_out
+This read-only boolean attribute is true if the compiler optimized out
+this value, thus it is not available for fetching from the inferior.
+@end defvar
+
+@defvar Value.type
+The type of this @code{gdb.Value}.  The value of this attribute is a
+@code{gdb.Type} object (@pxref{Types In Python}).
+@end defvar
+
+@defvar Value.dynamic_type
+The dynamic type of this @code{gdb.Value}.  This uses C@t{++} run-time
+type information (@acronym{RTTI}) to determine the dynamic type of the
+value.  If this value is of class type, it will return the class in
+which the value is embedded, if any.  If this value is of pointer or
+reference to a class type, it will compute the dynamic type of the
+referenced object, and return a pointer or reference to that type,
+respectively.  In all other cases, it will return the value's static
+type.
+
+Note that this feature will only work when debugging a C@t{++} program
+that includes @acronym{RTTI} for the object in question.  Otherwise,
+it will just return the static type of the value as in @kbd{ptype foo}
+(@pxref{Symbols, ptype}).
+@end defvar
+
+@defvar Value.is_lazy
+The value of this read-only boolean attribute is @code{True} if this
+@code{gdb.Value} has not yet been fetched from the inferior.  
+@value{GDBN} does not fetch values until necessary, for efficiency.  
+For example:
+
+@smallexample
+myval = gdb.parse_and_eval ('somevar')
+@end smallexample
+
+The value of @code{somevar} is not fetched at this time.  It will be 
+fetched when the value is needed, or when the @code{fetch_lazy}
+method is invoked.  
+@end defvar
+
+The following methods are provided:
+
+@defun Value.__init__ (@var{val})
+Many Python values can be converted directly to a @code{gdb.Value} via
+this object initializer.  Specifically:
+
+@table @asis
+@item Python boolean
+A Python boolean is converted to the boolean type from the current
+language.
+
+@item Python integer
+A Python integer is converted to the C @code{long} type for the
+current architecture.
+
+@item Python long
+A Python long is converted to the C @code{long long} type for the
+current architecture.
+
+@item Python float
+A Python float is converted to the C @code{double} type for the
+current architecture.
+
+@item Python string
+A Python string is converted to a target string, using the current
+target encoding.
+
+@item @code{gdb.Value}
+If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
+
+@item @code{gdb.LazyString}
+If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
+Python}), then the lazy string's @code{value} method is called, and
+its result is used.
+@end table
+@end defun
+
+@defun Value.cast (type)
+Return a new instance of @code{gdb.Value} that is the result of
+casting this instance to the type described by @var{type}, which must
+be a @code{gdb.Type} object.  If the cast cannot be performed for some
+reason, this method throws an exception.
+@end defun
+
+@defun Value.dereference ()
+For pointer data types, this method returns a new @code{gdb.Value} object
+whose contents is the object pointed to by the pointer.  For example, if
+@code{foo} is a C pointer to an @code{int}, declared in your C program as
+
+@smallexample
+int *foo;
+@end smallexample
+
+@noindent
+then you can use the corresponding @code{gdb.Value} to access what
+@code{foo} points to like this:
+
+@smallexample
+bar = foo.dereference ()
+@end smallexample
+
+The result @code{bar} will be a @code{gdb.Value} object holding the
+value pointed to by @code{foo}.
+
+A similar function @code{Value.referenced_value} exists which also
+returns @code{gdb.Value} objects corresonding to the values pointed to
+by pointer values (and additionally, values referenced by reference
+values).  However, the behavior of @code{Value.dereference}
+differs from @code{Value.referenced_value} by the fact that the
+behavior of @code{Value.dereference} is identical to applying the C
+unary operator @code{*} on a given value.  For example, consider a
+reference to a pointer @code{ptrref}, declared in your C@t{++} program
+as
+
+@smallexample
+typedef int *intptr;
+...
+int val = 10;
+intptr ptr = &val;
+intptr &ptrref = ptr;
+@end smallexample
+
+Though @code{ptrref} is a reference value, one can apply the method
+@code{Value.dereference} to the @code{gdb.Value} object corresponding
+to it and obtain a @code{gdb.Value} which is identical to that
+corresponding to @code{val}.  However, if you apply the method
+@code{Value.referenced_value}, the result would be a @code{gdb.Value}
+object identical to that corresponding to @code{ptr}.
+
+@smallexample
+py_ptrref = gdb.parse_and_eval ("ptrref")
+py_val = py_ptrref.dereference ()
+py_ptr = py_ptrref.referenced_value ()
+@end smallexample
+
+The @code{gdb.Value} object @code{py_val} is identical to that
+corresponding to @code{val}, and @code{py_ptr} is identical to that
+corresponding to @code{ptr}.  In general, @code{Value.dereference} can
+be applied whenever the C unary operator @code{*} can be applied
+to the corresponding C value.  For those cases where applying both
+@code{Value.dereference} and @code{Value.referenced_value} is allowed,
+the results obtained need not be identical (as we have seen in the above
+example).  The results are however identical when applied on
+@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
+objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
+@end defun
+
+@defun Value.referenced_value ()
+For pointer or reference data types, this method returns a new
+@code{gdb.Value} object corresponding to the value referenced by the
+pointer/reference value.  For pointer data types,
+@code{Value.dereference} and @code{Value.referenced_value} produce
+identical results.  The difference between these methods is that
+@code{Value.dereference} cannot get the values referenced by reference
+values.  For example, consider a reference to an @code{int}, declared
+in your C@t{++} program as
+
+@smallexample
+int val = 10;
+int &ref = val;
+@end smallexample
+
+@noindent
+then applying @code{Value.dereference} to the @code{gdb.Value} object
+corresponding to @code{ref} will result in an error, while applying
+@code{Value.referenced_value} will result in a @code{gdb.Value} object
+identical to that corresponding to @code{val}.
+
+@smallexample
+py_ref = gdb.parse_and_eval ("ref")
+er_ref = py_ref.dereference ()       # Results in error
+py_val = py_ref.referenced_value ()  # Returns the referenced value
+@end smallexample
+
+The @code{gdb.Value} object @code{py_val} is identical to that
+corresponding to @code{val}.
+@end defun
+
+@defun Value.dynamic_cast (type)
+Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
+operator were used.  Consult a C@t{++} reference for details.
+@end defun
+
+@defun Value.reinterpret_cast (type)
+Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
+operator were used.  Consult a C@t{++} reference for details.
+@end defun
+
+@defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
+If this @code{gdb.Value} represents a string, then this method
+converts the contents to a Python string.  Otherwise, this method will
+throw an exception.
+
+Strings are recognized in a language-specific way; whether a given
+@code{gdb.Value} represents a string is determined by the current
+language.
+
+For C-like languages, a value is a string if it is a pointer to or an
+array of characters or ints.  The string is assumed to be terminated
+by a zero of the appropriate width.  However if the optional length
+argument is given, the string will be converted to that given length,
+ignoring any embedded zeros that the string may contain.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the string in the @code{gdb.Value}, such as
+@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}.  It accepts
+the same encodings as the corresponding argument to Python's
+@code{string.decode} method, and the Python codec machinery will be used
+to convert the string.  If @var{encoding} is not given, or if
+@var{encoding} is the empty string, then either the @code{target-charset}
+(@pxref{Character Sets}) will be used, or a language-specific encoding
+will be used, if the current language is able to supply one.
+
+The optional @var{errors} argument is the same as the corresponding
+argument to Python's @code{string.decode} method.
+
+If the optional @var{length} argument is given, the string will be
+fetched and converted to the given length.
+@end defun
+
+@defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
+If this @code{gdb.Value} represents a string, then this method
+converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
+In Python}).  Otherwise, this method will throw an exception.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the @code{gdb.LazyString}.  Some examples are:
+@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}.  If the
+@var{encoding} argument is an encoding that @value{GDBN} does
+recognize, @value{GDBN} will raise an error.
+
+When a lazy string is printed, the @value{GDBN} encoding machinery is
+used to convert the string during printing.  If the optional
+@var{encoding} argument is not provided, or is an empty string,
+@value{GDBN} will automatically select the encoding most suitable for
+the string type.  For further information on encoding in @value{GDBN}
+please see @ref{Character Sets}.
+
+If the optional @var{length} argument is given, the string will be
+fetched and encoded to the length of characters specified.  If
+the @var{length} argument is not provided, the string will be fetched
+and encoded until a null of appropriate width is found.
+@end defun
+
+@defun Value.fetch_lazy ()
+If the @code{gdb.Value} object is currently a lazy value 
+(@code{gdb.Value.is_lazy} is @code{True}), then the value is
+fetched from the inferior.  Any errors that occur in the process
+will produce a Python exception.
+
+If the @code{gdb.Value} object is not a lazy value, this method
+has no effect.
+
+This method does not return a value.
+@end defun
+
+
+@node Types In Python
+@subsubsection Types In Python
+@cindex types in Python
+@cindex Python, working with types
+
+@tindex gdb.Type
+@value{GDBN} represents types from the inferior using the class
+@code{gdb.Type}.
+
+The following type-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.lookup_type
+@defun gdb.lookup_type (name @r{[}, block@r{]})
+This function looks up a type by name.  @var{name} is the name of the
+type to look up.  It must be a string.
+
+If @var{block} is given, then @var{name} is looked up in that scope.
+Otherwise, it is searched for globally.
+
+Ordinarily, this function will return an instance of @code{gdb.Type}.
+If the named type cannot be found, it will throw an exception.
+@end defun
+
+If the type is a structure or class type, or an enum type, the fields
+of that type can be accessed using the Python @dfn{dictionary syntax}.
+For example, if @code{some_type} is a @code{gdb.Type} instance holding
+a structure type, you can access its @code{foo} field with:
+
+@smallexample
+bar = some_type['foo']
+@end smallexample
+
+@code{bar} will be a @code{gdb.Field} object; see below under the
+description of the @code{Type.fields} method for a description of the
+@code{gdb.Field} class.
+
+An instance of @code{Type} has the following attributes:
+
+@defvar Type.code
+The type code for this type.  The type code will be one of the
+@code{TYPE_CODE_} constants defined below.
+@end defvar
+
+@defvar Type.name
+The name of this type.  If this type has no name, then @code{None}
+is returned.
+@end defvar
+
+@defvar Type.sizeof
+The size of this type, in target @code{char} units.  Usually, a
+target's @code{char} type will be an 8-bit byte.  However, on some
+unusual platforms, this type may have a different size.
+@end defvar
+
+@defvar Type.tag
+The tag name for this type.  The tag name is the name after
+@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
+languages have this concept.  If this type has no tag name, then
+@code{None} is returned.
+@end defvar
+
+The following methods are provided:
+
+@defun Type.fields ()
+For structure and union types, this method returns the fields.  Range
+types have two fields, the minimum and maximum values.  Enum types
+have one field per enum constant.  Function and method types have one
+field per parameter.  The base types of C@t{++} classes are also
+represented as fields.  If the type has no fields, or does not fit
+into one of these categories, an empty sequence will be returned.
+
+Each field is a @code{gdb.Field} object, with some pre-defined attributes:
+@table @code
+@item bitpos
+This attribute is not available for @code{enum} or @code{static}
+(as in C@t{++} or Java) fields.  The value is the position, counting
+in bits, from the start of the containing type.
+
+@item enumval
+This attribute is only available for @code{enum} fields, and its value
+is the enumeration member's integer representation.
+
+@item name
+The name of the field, or @code{None} for anonymous fields.
+
+@item artificial
+This is @code{True} if the field is artificial, usually meaning that
+it was provided by the compiler and not the user.  This attribute is
+always provided, and is @code{False} if the field is not artificial.
+
+@item is_base_class
+This is @code{True} if the field represents a base class of a C@t{++}
+structure.  This attribute is always provided, and is @code{False}
+if the field is not a base class of the type that is the argument of
+@code{fields}, or if that type was not a C@t{++} class.
+
+@item bitsize
+If the field is packed, or is a bitfield, then this will have a
+non-zero value, which is the size of the field in bits.  Otherwise,
+this will be zero; in this case the field's size is given by its type.
+
+@item type
+The type of the field.  This is usually an instance of @code{Type},
+but it can be @code{None} in some situations.
+
+@item parent_type
+The type which contains this field.  This is an instance of
+@code{gdb.Type}.
+@end table
+@end defun
+
+@defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
+Return a new @code{gdb.Type} object which represents an array of this
+type.  If one argument is given, it is the inclusive upper bound of
+the array; in this case the lower bound is zero.  If two arguments are
+given, the first argument is the lower bound of the array, and the
+second argument is the upper bound of the array.  An array's length
+must not be negative, but the bounds can be.
+@end defun
+
+@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
+Return a new @code{gdb.Type} object which represents a vector of this
+type.  If one argument is given, it is the inclusive upper bound of
+the vector; in this case the lower bound is zero.  If two arguments are
+given, the first argument is the lower bound of the vector, and the
+second argument is the upper bound of the vector.  A vector's length
+must not be negative, but the bounds can be.
+
+The difference between an @code{array} and a @code{vector} is that
+arrays behave like in C: when used in expressions they decay to a pointer
+to the first element whereas vectors are treated as first class values.
+@end defun
+
+@defun Type.const ()
+Return a new @code{gdb.Type} object which represents a
+@code{const}-qualified variant of this type.
+@end defun
+
+@defun Type.volatile ()
+Return a new @code{gdb.Type} object which represents a
+@code{volatile}-qualified variant of this type.
+@end defun
+
+@defun Type.unqualified ()
+Return a new @code{gdb.Type} object which represents an unqualified
+variant of this type.  That is, the result is neither @code{const} nor
+@code{volatile}.
+@end defun
+
+@defun Type.range ()
+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{gdb.error} exception (@pxref{Exception Handling}).
+@end defun
+
+@defun Type.reference ()
+Return a new @code{gdb.Type} object which represents a reference to this
+type.
+@end defun
+
+@defun Type.pointer ()
+Return a new @code{gdb.Type} object which represents a pointer to this
+type.
+@end defun
+
+@defun Type.strip_typedefs ()
+Return a new @code{gdb.Type} that represents the real type,
+after removing all layers of typedefs.
+@end defun
+
+@defun Type.target ()
+Return a new @code{gdb.Type} object which represents the target type
+of this type.
+
+For a pointer type, the target type is the type of the pointed-to
+object.  For an array type (meaning C-like arrays), the target type is
+the type of the elements of the array.  For a function or method type,
+the target type is the type of the return value.  For a complex type,
+the target type is the type of the elements.  For a typedef, the
+target type is the aliased type.
+
+If the type does not have a target, this method will throw an
+exception.
+@end defun
+
+@defun Type.template_argument (n @r{[}, block@r{]})
+If this @code{gdb.Type} is an instantiation of a template, this will
+return a new @code{gdb.Type} which represents the type of the
+@var{n}th template argument.
+
+If this @code{gdb.Type} is not a template type, this will throw an
+exception.  Ordinarily, only C@t{++} code will have template types.
+
+If @var{block} is given, then @var{name} is looked up in that scope.
+Otherwise, it is searched for globally.
+@end defun
+
+
+Each type has a code, which indicates what category this type falls
+into.  The available type categories are represented by constants
+defined in the @code{gdb} module:
+
+@table @code
+@findex TYPE_CODE_PTR
+@findex gdb.TYPE_CODE_PTR
+@item gdb.TYPE_CODE_PTR
+The type is a pointer.
+
+@findex TYPE_CODE_ARRAY
+@findex gdb.TYPE_CODE_ARRAY
+@item gdb.TYPE_CODE_ARRAY
+The type is an array.
+
+@findex TYPE_CODE_STRUCT
+@findex gdb.TYPE_CODE_STRUCT
+@item gdb.TYPE_CODE_STRUCT
+The type is a structure.
+
+@findex TYPE_CODE_UNION
+@findex gdb.TYPE_CODE_UNION
+@item gdb.TYPE_CODE_UNION
+The type is a union.
+
+@findex TYPE_CODE_ENUM
+@findex gdb.TYPE_CODE_ENUM
+@item gdb.TYPE_CODE_ENUM
+The type is an enum.
+
+@findex TYPE_CODE_FLAGS
+@findex gdb.TYPE_CODE_FLAGS
+@item gdb.TYPE_CODE_FLAGS
+A bit flags type, used for things such as status registers.
+
+@findex TYPE_CODE_FUNC
+@findex gdb.TYPE_CODE_FUNC
+@item gdb.TYPE_CODE_FUNC
+The type is a function.
+
+@findex TYPE_CODE_INT
+@findex gdb.TYPE_CODE_INT
+@item gdb.TYPE_CODE_INT
+The type is an integer type.
+
+@findex TYPE_CODE_FLT
+@findex gdb.TYPE_CODE_FLT
+@item gdb.TYPE_CODE_FLT
+A floating point type.
+
+@findex TYPE_CODE_VOID
+@findex gdb.TYPE_CODE_VOID
+@item gdb.TYPE_CODE_VOID
+The special type @code{void}.
+
+@findex TYPE_CODE_SET
+@findex gdb.TYPE_CODE_SET
+@item gdb.TYPE_CODE_SET
+A Pascal set type.
+
+@findex TYPE_CODE_RANGE
+@findex gdb.TYPE_CODE_RANGE
+@item gdb.TYPE_CODE_RANGE
+A range type, that is, an integer type with bounds.
+
+@findex TYPE_CODE_STRING
+@findex gdb.TYPE_CODE_STRING
+@item gdb.TYPE_CODE_STRING
+A string type.  Note that this is only used for certain languages with
+language-defined string types; C strings are not represented this way.
+
+@findex TYPE_CODE_BITSTRING
+@findex gdb.TYPE_CODE_BITSTRING
+@item gdb.TYPE_CODE_BITSTRING
+A string of bits.  It is deprecated.
+
+@findex TYPE_CODE_ERROR
+@findex gdb.TYPE_CODE_ERROR
+@item gdb.TYPE_CODE_ERROR
+An unknown or erroneous type.
+
+@findex TYPE_CODE_METHOD
+@findex gdb.TYPE_CODE_METHOD
+@item gdb.TYPE_CODE_METHOD
+A method type, as found in C@t{++} or Java.
+
+@findex TYPE_CODE_METHODPTR
+@findex gdb.TYPE_CODE_METHODPTR
+@item gdb.TYPE_CODE_METHODPTR
+A pointer-to-member-function.
+
+@findex TYPE_CODE_MEMBERPTR
+@findex gdb.TYPE_CODE_MEMBERPTR
+@item gdb.TYPE_CODE_MEMBERPTR
+A pointer-to-member.
+
+@findex TYPE_CODE_REF
+@findex gdb.TYPE_CODE_REF
+@item gdb.TYPE_CODE_REF
+A reference type.
+
+@findex TYPE_CODE_CHAR
+@findex gdb.TYPE_CODE_CHAR
+@item gdb.TYPE_CODE_CHAR
+A character type.
+
+@findex TYPE_CODE_BOOL
+@findex gdb.TYPE_CODE_BOOL
+@item gdb.TYPE_CODE_BOOL
+A boolean type.
+
+@findex TYPE_CODE_COMPLEX
+@findex gdb.TYPE_CODE_COMPLEX
+@item gdb.TYPE_CODE_COMPLEX
+A complex float type.
+
+@findex TYPE_CODE_TYPEDEF
+@findex gdb.TYPE_CODE_TYPEDEF
+@item gdb.TYPE_CODE_TYPEDEF
+A typedef to some other type.
+
+@findex TYPE_CODE_NAMESPACE
+@findex gdb.TYPE_CODE_NAMESPACE
+@item gdb.TYPE_CODE_NAMESPACE
+A C@t{++} namespace.
+
+@findex TYPE_CODE_DECFLOAT
+@findex gdb.TYPE_CODE_DECFLOAT
+@item gdb.TYPE_CODE_DECFLOAT
+A decimal floating point type.
+
+@findex TYPE_CODE_INTERNAL_FUNCTION
+@findex gdb.TYPE_CODE_INTERNAL_FUNCTION
+@item gdb.TYPE_CODE_INTERNAL_FUNCTION
+A function internal to @value{GDBN}.  This is the type used to represent
+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
+
+An example output is provided (@pxref{Pretty Printing}).
+
+A pretty-printer is just an object that holds a value and implements a
+specific interface, defined here.
+
+@defun pretty_printer.children (self)
+@value{GDBN} will call this method on a pretty-printer to compute the
+children of the pretty-printer's value.
+
+This method must return an object conforming to the Python iterator
+protocol.  Each item returned by the iterator must be a tuple holding
+two elements.  The first element is the ``name'' of the child; the
+second element is the child's value.  The value can be any Python
+object which is convertible to a @value{GDBN} value.
+
+This method is optional.  If it does not exist, @value{GDBN} will act
+as though the value has no children.
+@end defun
+
+@defun pretty_printer.display_hint (self)
+The CLI may call this method and use its result to change the
+formatting of a value.  The result will also be supplied to an MI
+consumer as a @samp{displayhint} attribute of the variable being
+printed.
+
+This method is optional.  If it does exist, this method must return a
+string.
+
+Some display hints are predefined by @value{GDBN}:
+
+@table @samp
+@item array
+Indicate that the object being printed is ``array-like''.  The CLI
+uses this to respect parameters such as @code{set print elements} and
+@code{set print array}.
+
+@item map
+Indicate that the object being printed is ``map-like'', and that the
+children of this value can be assumed to alternate between keys and
+values.
+
+@item string
+Indicate that the object being printed is ``string-like''.  If the
+printer's @code{to_string} method returns a Python string of some
+kind, then @value{GDBN} will call its internal language-specific
+string-printing function to format the string.  For the CLI this means
+adding quotation marks, possibly escaping some characters, respecting
+@code{set print elements}, and the like.
+@end table
+@end defun
+
+@defun pretty_printer.to_string (self)
+@value{GDBN} will call this method to display the string
+representation of the value passed to the object's constructor.
+
+When printing from the CLI, if the @code{to_string} method exists,
+then @value{GDBN} will prepend its result to the values returned by
+@code{children}.  Exactly how this formatting is done is dependent on
+the display hint, and may change as more hints are added.  Also,
+depending on the print settings (@pxref{Print Settings}), the CLI may
+print just the result of @code{to_string} in a stack trace, omitting
+the result of @code{children}.
+
+If this method returns a string, it is printed verbatim.
+
+Otherwise, if this method returns an instance of @code{gdb.Value},
+then @value{GDBN} prints this value.  This may result in a call to
+another pretty-printer.
+
+If instead the method returns a Python value which is convertible to a
+@code{gdb.Value}, then @value{GDBN} performs the conversion and prints
+the resulting value.  Again, this may result in a call to another
+pretty-printer.  Python scalars (integers, floats, and booleans) and
+strings are convertible to @code{gdb.Value}; other types are not.
+
+Finally, if this method returns @code{None} then no further operations
+are peformed in this method and nothing is printed.
+
+If the result is not one of these types, an exception is raised.
+@end defun
+
+@value{GDBN} provides a function which can be used to look up the
+default pretty-printer for a @code{gdb.Value}:
+
+@findex gdb.default_visualizer
+@defun gdb.default_visualizer (value)
+This function takes a @code{gdb.Value} object as an argument.  If a
+pretty-printer for this value exists, then it is returned.  If no such
+printer exists, then this returns @code{None}.
+@end defun
+
+@node Selecting Pretty-Printers
+@subsubsection Selecting Pretty-Printers
+
+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.  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.
+
+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
+@code{None}.
+
+@value{GDBN} first checks the @code{pretty_printers} attribute of each
+@code{gdb.Objfile} in the current program space and iteratively calls
+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.
+After these lists have been exhausted, it tries the global
+@code{gdb.pretty_printers} list, again calling each enabled function until an
+object is returned.
+
+The order in which the objfiles are searched is not specified.  For a
+given list, functions are always invoked from the head of the list,
+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.  @xref{Pretty Printing API}, for details on the API this class
+must provide.
+
+@smallexample
+class StdStringPrinter(object):
+    "Print a std::string"
+
+    def __init__(self, val):
+        self.val = val
+
+    def to_string(self):
+        return self.val['_M_dataplus']['_M_p']
+
+    def display_hint(self):
+        return 'string'
+@end smallexample
+
+And here is an example showing how a lookup function for the printer
+example above might be written.
+
+@smallexample
+def str_lookup_function(val):
+    lookup_tag = val.type.tag
+    if lookup_tag == None:
+        return None
+    regex = re.compile("^std::basic_string<char,.*>$")
+    if regex.match(lookup_tag):
+        return StdStringPrinter(val)
+    return None
+@end smallexample
+
+The example lookup function extracts the value's type, and attempts to
+match it to a type that it can pretty-print.  If it is a type the
+printer can pretty-print, it will return a printer object.  If not, it
+returns @code{None}.
+
+We recommend that you put your core pretty-printers into a Python
+package.  If your pretty-printers are for use with a library, we
+further recommend embedding a version number into the package name.
+This practice will enable @value{GDBN} to load multiple versions of
+your pretty-printers at the same time, because they will have
+different names.
+
+You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
+can be evaluated multiple times without changing its meaning.  An
+ideal auto-load file will consist solely of @code{import}s of your
+printer modules, followed by a call to a register pretty-printers with
+the current objfile.
+
+Taken as a whole, this approach will scale nicely to multiple
+inferiors, each potentially using a different library version.
+Embedding a version number in the Python package name will ensure that
+@value{GDBN} is able to load both sets of printers simultaneously.
+Then, because the search for pretty-printers is done by objfile, and
+because your auto-loaded code took care to register your library's
+printers with a specific objfile, @value{GDBN} will find the correct
+printers for the specific version of the library used by each
+inferior.
+
+To continue the @code{std::string} example (@pxref{Pretty Printing API}),
+this code might appear in @code{gdb.libstdcxx.v6}:
+
+@smallexample
+def register_printers(objfile):
+    objfile.pretty_printers.append(str_lookup_function)
+@end smallexample
+
+@noindent
+And then the corresponding contents of the auto-load file would be:
+
+@smallexample
+import gdb.libstdcxx.v6
+gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
+@end smallexample
+
+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.
+
+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 @code{gdb.printing} module provides a formal way of solving these
+problems (@pxref{gdb.printing}).
+Here is another example that handles multiple types.
+
+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 Type Printing API
+@subsubsection Type Printing API
+@cindex type printing API for Python
+
+@value{GDBN} provides a way for Python code to customize type display.
+This is mainly useful for substituting canonical typedef names for
+types.
+
+@cindex type printer
+A @dfn{type printer} is just a Python object conforming to a certain
+protocol.  A simple base class implementing the protocol is provided;
+see @ref{gdb.types}.  A type printer must supply at least:
+
+@defivar type_printer enabled
+A boolean which is True if the printer is enabled, and False
+otherwise.  This is manipulated by the @code{enable type-printer}
+and @code{disable type-printer} commands.
+@end defivar
+
+@defivar type_printer name
+The name of the type printer.  This must be a string.  This is used by
+the @code{enable type-printer} and @code{disable type-printer}
+commands.
+@end defivar
+
+@defmethod type_printer instantiate (self)
+This is called by @value{GDBN} at the start of type-printing.  It is
+only called if the type printer is enabled.  This method must return a
+new object that supplies a @code{recognize} method, as described below.
+@end defmethod
+
+
+When displaying a type, say via the @code{ptype} command, @value{GDBN}
+will compute a list of type recognizers.  This is done by iterating
+first over the per-objfile type printers (@pxref{Objfiles In Python}),
+followed by the per-progspace type printers (@pxref{Progspaces In
+Python}), and finally the global type printers.
+
+@value{GDBN} will call the @code{instantiate} method of each enabled
+type printer.  If this method returns @code{None}, then the result is
+ignored; otherwise, it is appended to the list of recognizers.
+
+Then, when @value{GDBN} is going to display a type name, it iterates
+over the list of recognizers.  For each one, it calls the recognition
+function, stopping if the function returns a non-@code{None} value.
+The recognition function is defined as:
+
+@defmethod type_recognizer recognize (self, type)
+If @var{type} is not recognized, return @code{None}.  Otherwise,
+return a string which is to be printed as the name of @var{type}.
+@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
+Python}).
+@end defmethod
+
+@value{GDBN} uses this two-pass approach so that type printers can
+efficiently cache information without holding on to it too long.  For
+example, it can be convenient to look up type information in a type
+printer and hold it for a recognizer's lifetime; if a single pass were
+done then type printers would have to make use of the event system in
+order to avoid holding information that could become stale as the
+inferior changed.
+
+@node Frame Filter API
+@subsubsection Filtering Frames.
+@cindex frame filters api
+
+Frame filters are Python objects that manipulate the visibility of a
+frame or frames when a backtrace (@pxref{Backtrace}) is printed by
+@value{GDBN}.
+
+Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
+commands (@pxref{GDB/MI}), those that return a collection of frames
+are affected.  The commands that work with frame filters are:
+
+@code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
+@code{-stack-list-frames}
+(@pxref{-stack-list-frames,, The -stack-list-frames command}),
+@code{-stack-list-variables} (@pxref{-stack-list-variables,, The
+-stack-list-variables command}), @code{-stack-list-arguments}
+@pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
+@code{-stack-list-locals} (@pxref{-stack-list-locals,, The
+-stack-list-locals command}).
+
+A frame filter works by taking an iterator as an argument, applying
+actions to the contents of that iterator, and returning another
+iterator (or, possibly, the same iterator it was provided in the case
+where the filter does not perform any operations).  Typically, frame
+filters utilize tools such as the Python's @code{itertools} module to
+work with and create new iterators from the source iterator.
+Regardless of how a filter chooses to apply actions, it must not alter
+the underlying @value{GDBN} frame or frames, or attempt to alter the
+call-stack within @value{GDBN}.  This preserves data integrity within
+@value{GDBN}.  Frame filters are executed on a priority basis and care
+should be taken that some frame filters may have been executed before,
+and that some frame filters will be executed after.
+
+An important consideration when designing frame filters, and well
+worth reflecting upon, is that frame filters should avoid unwinding
+the call stack if possible.  Some stacks can run very deep, into the
+tens of thousands in some cases.  To search every frame when a frame
+filter executes may be too expensive at that step.  The frame filter
+cannot know how many frames it has to iterate over, and it may have to
+iterate through them all.  This ends up duplicating effort as
+@value{GDBN} performs this iteration when it prints the frames.  If
+the filter can defer unwinding frames until frame decorators are
+executed, after the last filter has executed, it should.  @xref{Frame
+Decorator API}, for more information on decorators.  Also, there are
+examples for both frame decorators and filters in later chapters.
+@xref{Writing a Frame Filter}, for more information.
+
+The Python dictionary @code{gdb.frame_filters} contains key/object
+pairings that comprise a frame filter.  Frame filters in this
+dictionary are called @code{global} frame filters, and they are
+available when debugging all inferiors.  These frame filters must
+register with the dictionary directly.  In addition to the
+@code{global} dictionary, there are other dictionaries that are loaded
+with different inferiors via auto-loading (@pxref{Python
+Auto-loading}).  The two other areas where frame filter dictionaries
+can be found are: @code{gdb.Progspace} which contains a
+@code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
+object which also contains a @code{frame_filters} dictionary
+attribute.
+
+When a command is executed from @value{GDBN} that is compatible with
+frame filters, @value{GDBN} combines the @code{global},
+@code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
+loaded.  All of the @code{gdb.Objfile} dictionaries are combined, as
+several frames, and thus several object files, might be in use.
+@value{GDBN} then prunes any frame filter whose @code{enabled}
+attribute is @code{False}.  This pruned list is then sorted according
+to the @code{priority} attribute in each filter.
+
+Once the dictionaries are combined, pruned and sorted, @value{GDBN}
+creates an iterator which wraps each frame in the call stack in a
+@code{FrameDecorator} object, and calls each filter in order.  The
+output from the previous filter will always be the input to the next
+filter, and so on.
+
+Frame filters have a mandatory interface which each frame filter must
+implement, defined here:
+
+@defun FrameFilter.filter (iterator)
+@value{GDBN} will call this method on a frame filter when it has
+reached the order in the priority list for that filter.
+
+For example, if there are four frame filters:
+
+@smallexample
+Name         Priority
+
+Filter1      5
+Filter2      10
+Filter3      100
+Filter4      1
+@end smallexample
+
+The order that the frame filters will be called is:
+
+@smallexample
+Filter3 -> Filter2 -> Filter1 -> Filter4
+@end smallexample
+
+Note that the output from @code{Filter3} is passed to the input of
+@code{Filter2}, and so on.
+
+This @code{filter} method is passed a Python iterator.  This iterator
+contains a sequence of frame decorators that wrap each
+@code{gdb.Frame}, or a frame decorator that wraps another frame
+decorator.  The first filter that is executed in the sequence of frame
+filters will receive an iterator entirely comprised of default
+@code{FrameDecorator} objects.  However, after each frame filter is
+executed, the previous frame filter may have wrapped some or all of
+the frame decorators with their own frame decorator.  As frame
+decorators must also conform to a mandatory interface, these
+decorators can be assumed to act in a uniform manner (@pxref{Frame
+Decorator API}).
+
+This method must return an object conforming to the Python iterator
+protocol.  Each item in the iterator must be an object conforming to
+the frame decorator interface.  If a frame filter does not wish to
+perform any operations on this iterator, it should return that
+iterator untouched.
+
+This method is not optional.  If it does not exist, @value{GDBN} will
+raise and print an error.
+@end defun
+
+@defvar FrameFilter.name
+The @code{name} attribute must be Python string which contains the
+name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
+Management}).  This attribute may contain any combination of letters
+or numbers.  Care should be taken to ensure that it is unique.  This
+attribute is mandatory.
+@end defvar
+
+@defvar FrameFilter.enabled
+The @code{enabled} attribute must be Python boolean.  This attribute
+indicates to @value{GDBN} whether the frame filter is enabled, and
+should be considered when frame filters are executed.  If
+@code{enabled} is @code{True}, then the frame filter will be executed
+when any of the backtrace commands detailed earlier in this chapter
+are executed.  If @code{enabled} is @code{False}, then the frame
+filter will not be executed.  This attribute is mandatory.
+@end defvar
+
+@defvar FrameFilter.priority
+The @code{priority} attribute must be Python integer.  This attribute
+controls the order of execution in relation to other frame filters.
+There are no imposed limits on the range of @code{priority} other than
+it must be a valid integer.  The higher the @code{priority} attribute,
+the sooner the frame filter will be executed in relation to other
+frame filters.  Although @code{priority} can be negative, it is
+recommended practice to assume zero is the lowest priority that a
+frame filter can be assigned.  Frame filters that have the same
+priority are executed in unsorted order in that priority slot.  This
+attribute is mandatory.
+@end defvar
+
+@node Frame Decorator API
+@subsubsection Decorating Frames.
+@cindex frame decorator api
+
+Frame decorators are sister objects to frame filters (@pxref{Frame
+Filter API}).  Frame decorators are applied by a frame filter and can
+only be used in conjunction with frame filters.
+
+The purpose of a frame decorator is to customize the printed content
+of each @code{gdb.Frame} in commands where frame filters are executed.
+This concept is called decorating a frame.  Frame decorators decorate
+a @code{gdb.Frame} with Python code contained within each API call.
+This separates the actual data contained in a @code{gdb.Frame} from
+the decorated data produced by a frame decorator.  This abstraction is
+necessary to maintain integrity of the data contained in each
+@code{gdb.Frame}.
+
+Frame decorators have a mandatory interface, defined below.
+
+@value{GDBN} already contains a frame decorator called
+@code{FrameDecorator}.  This contains substantial amounts of
+boilerplate code to decorate the content of a @code{gdb.Frame}.  It is
+recommended that other frame decorators inherit and extend this
+object, and only to override the methods needed.
+
+@defun FrameDecorator.elided (self)
+
+The @code{elided} method groups frames together in a hierarchical
+system.  An example would be an interpreter, where multiple low-level
+frames make up a single call in the interpreted language.  In this
+example, the frame filter would elide the low-level frames and present
+a single high-level frame, representing the call in the interpreted
+language, to the user.
+
+The @code{elided} function must return an iterable and this iterable
+must contain the frames that are being elided wrapped in a suitable
+frame decorator.  If no frames are being elided this function may
+return an empty iterable, or @code{None}.  Elided frames are indented
+from normal frames in a @code{CLI} backtrace, or in the case of
+@code{GDB/MI}, are placed in the @code{children} field of the eliding
+frame.
+
+It is the frame filter's task to also filter out the elided frames from
+the source iterator.  This will avoid printing the frame twice.
+@end defun
+
+@defun FrameDecorator.function (self)
+
+This method returns the name of the function in the frame that is to
+be printed.
+
+This method must return a Python string describing the function, or
+@code{None}.
+
+If this function returns @code{None}, @value{GDBN} will not print any
+data for this field.
+@end defun
+
+@defun FrameDecorator.address (self)
+
+This method returns the address of the frame that is to be printed.
+
+This method must return a Python numeric integer type of sufficient
+size to describe the address of the frame, or @code{None}.
+
+If this function returns a @code{None}, @value{GDBN} will not print
+any data for this field.
+@end defun
+
+@defun FrameDecorator.filename (self)
+
+This method returns the filename and path associated with this frame.
+
+This method must return a Python string containing the filename and
+the path to the object file backing the frame, or @code{None}.
+
+If this function returns a @code{None}, @value{GDBN} will not print
+any data for this field.
+@end defun
+
+@defun FrameDecorator.line (self):
+
+This method returns the line number associated with the current
+position within the function addressed by this frame.
+
+This method must return a Python integer type, or @code{None}.
+
+If this function returns a @code{None}, @value{GDBN} will not print
+any data for this field.
+@end defun
+
+@defun FrameDecorator.frame_args (self)
+@anchor{frame_args}
+
+This method must return an iterable, or @code{None}.  Returning an
+empty iterable, or @code{None} means frame arguments will not be
+printed for this frame.  This iterable must contain objects that
+implement two methods, described here.
+
+This object must implement a @code{argument} method which takes a
+single @code{self} parameter and must return a @code{gdb.Symbol}
+(@pxref{Symbols In Python}), or a Python string.  The object must also
+implement a @code{value} method which takes a single @code{self}
+parameter and must return a @code{gdb.Value} (@pxref{Values From
+Inferior}), a Python value, or @code{None}.  If the @code{value}
+method returns @code{None}, and the @code{argument} method returns a
+@code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
+the @code{gdb.Symbol} automatically.
+
+A brief example:
+
+@smallexample
+class SymValueWrapper():
+
+    def __init__(self, symbol, value):
+        self.sym = symbol
+        self.val = value
+
+    def value(self):
+        return self.val
+
+    def symbol(self):
+        return self.sym
+
+class SomeFrameDecorator()
+...
+...
+    def frame_args(self):
+        args = []
+        try:
+            block = self.inferior_frame.block()
+        except:
+            return None
+
+        # Iterate over all symbols in a block.  Only add
+        # symbols that are arguments.
+        for sym in block:
+            if not sym.is_argument:
+                continue
+            args.append(SymValueWrapper(sym,None))
+
+        # Add example synthetic argument.
+        args.append(SymValueWrapper(``foo'', 42))
+
+        return args
+@end smallexample
+@end defun
+
+@defun FrameDecorator.frame_locals (self)
+
+This method must return an iterable or @code{None}.  Returning an
+empty iterable, or @code{None} means frame local arguments will not be
+printed for this frame.
+
+The object interface, the description of the various strategies for
+reading frame locals, and the example are largely similar to those
+described in the @code{frame_args} function, (@pxref{frame_args,,The
+frame filter frame_args function}).  Below is a modified example:
+
+@smallexample
+class SomeFrameDecorator()
+...
+...
+    def frame_locals(self):
+        vars = []
+        try:
+            block = self.inferior_frame.block()
+        except:
+            return None
+
+        # Iterate over all symbols in a block.  Add all
+        # symbols, except arguments.
+        for sym in block:
+            if sym.is_argument:
+                continue
+            vars.append(SymValueWrapper(sym,None))
+
+        # Add an example of a synthetic local variable.
+        vars.append(SymValueWrapper(``bar'', 99))
+
+        return vars
+@end smallexample
+@end defun
+
+@defun FrameDecorator.inferior_frame (self):
+
+This method must return the underlying @code{gdb.Frame} that this
+frame decorator is decorating.  @value{GDBN} requires the underlying
+frame for internal frame information to determine how to print certain
+values when printing a frame.
+@end defun
+
+@node Writing a Frame Filter
+@subsubsection Writing a Frame Filter
+@cindex writing a frame filter
+
+There are three basic elements that a frame filter must implement: it
+must correctly implement the documented interface (@pxref{Frame Filter
+API}), it must register itself with @value{GDBN}, and finally, it must
+decide if it is to work on the data provided by @value{GDBN}.  In all
+cases, whether it works on the iterator or not, each frame filter must
+return an iterator.  A bare-bones frame filter follows the pattern in
+the following example.
+
+@smallexample
+import gdb
+
+class FrameFilter():
+
+    def __init__(self):
+        # Frame filter attribute creation.
+        #
+        # 'name' is the name of the filter that GDB will display.
+        #
+        # 'priority' is the priority of the filter relative to other
+        # filters.
+        #
+        # 'enabled' is a boolean that indicates whether this filter is
+        # enabled and should be executed.
+
+        self.name = "Foo"
+        self.priority = 100
+        self.enabled = True
+
+        # Register this frame filter with the global frame_filters
+        # dictionary.
+        gdb.frame_filters[self.name] = self
+
+    def filter(self, frame_iter):
+        # Just return the iterator.
+        return frame_iter
+@end smallexample
+
+The frame filter in the example above implements the three
+requirements for all frame filters.  It implements the API, self
+registers, and makes a decision on the iterator (in this case, it just
+returns the iterator untouched).
+
+The first step is attribute creation and assignment, and as shown in
+the comments the filter assigns the following attributes:  @code{name},
+@code{priority} and whether the filter should be enabled with the
+@code{enabled} attribute.
+
+The second step is registering the frame filter with the dictionary or
+dictionaries that the frame filter has interest in.  As shown in the
+comments, this filter just registers itself with the global dictionary
+@code{gdb.frame_filters}.  As noted earlier, @code{gdb.frame_filters}
+is a dictionary that is initialized in the @code{gdb} module when
+@value{GDBN} starts.  What dictionary a filter registers with is an
+important consideration.  Generally, if a filter is specific to a set
+of code, it should be registered either in the @code{objfile} or
+@code{progspace} dictionaries as they are specific to the program
+currently loaded in @value{GDBN}.  The global dictionary is always
+present in @value{GDBN} and is never unloaded.  Any filters registered
+with the global dictionary will exist until @value{GDBN} exits.  To
+avoid filters that may conflict, it is generally better to register
+frame filters against the dictionaries that more closely align with
+the usage of the filter currently in question.  @xref{Python
+Auto-loading}, for further information on auto-loading Python scripts.
+
+@value{GDBN} takes a hands-off approach to frame filter registration,
+therefore it is the frame filter's responsibility to ensure
+registration has occurred, and that any exceptions are handled
+appropriately.  In particular, you may wish to handle exceptions
+relating to Python dictionary key uniqueness.  It is mandatory that
+the dictionary key is the same as frame filter's @code{name}
+attribute.  When a user manages frame filters (@pxref{Frame Filter
+Management}), the names @value{GDBN} will display are those contained
+in the @code{name} attribute.
+
+The final step of this example is the implementation of the
+@code{filter} method.  As shown in the example comments, we define the
+@code{filter} method and note that the method must take an iterator,
+and also must return an iterator.  In this bare-bones example, the
+frame filter is not very useful as it just returns the iterator
+untouched.  However this is a valid operation for frame filters that
+have the @code{enabled} attribute set, but decide not to operate on
+any frames.
+
+In the next example, the frame filter operates on all frames and
+utilizes a frame decorator to perform some work on the frames.
+@xref{Frame Decorator API}, for further information on the frame
+decorator interface.
+
+This example works on inlined frames.  It highlights frames which are
+inlined by tagging them with an ``[inlined]'' tag.  By applying a
+frame decorator to all frames with the Python @code{itertools imap}
+method, the example defers actions to the frame decorator.  Frame
+decorators are only processed when @value{GDBN} prints the backtrace.
+
+This introduces a new decision making topic: whether to perform
+decision making operations at the filtering step, or at the printing
+step.  In this example's approach, it does not perform any filtering
+decisions at the filtering step beyond mapping a frame decorator to
+each frame.  This allows the actual decision making to be performed
+when each frame is printed.  This is an important consideration, and
+well worth reflecting upon when designing a frame filter.  An issue
+that frame filters should avoid is unwinding the stack if possible.
+Some stacks can run very deep, into the tens of thousands in some
+cases.  To search every frame to determine if it is inlined ahead of
+time may be too expensive at the filtering step.  The frame filter
+cannot know how many frames it has to iterate over, and it would have
+to iterate through them all.  This ends up duplicating effort as
+@value{GDBN} performs this iteration when it prints the frames.
+
+In this example decision making can be deferred to the printing step.
+As each frame is printed, the frame decorator can examine each frame
+in turn when @value{GDBN} iterates.  From a performance viewpoint,
+this is the most appropriate decision to make as it avoids duplicating
+the effort that the printing step would undertake anyway.  Also, if
+there are many frame filters unwinding the stack during filtering, it
+can substantially delay the printing of the backtrace which will
+result in large memory usage, and a poor user experience.
+
+@smallexample
+class InlineFilter():
+
+    def __init__(self):
+        self.name = "InlinedFrameFilter"
+        self.priority = 100
+        self.enabled = True
+        gdb.frame_filters[self.name] = self
+
+    def filter(self, frame_iter):
+        frame_iter = itertools.imap(InlinedFrameDecorator,
+                                    frame_iter)
+        return frame_iter
+@end smallexample
+
+This frame filter is somewhat similar to the earlier example, except
+that the @code{filter} method applies a frame decorator object called
+@code{InlinedFrameDecorator} to each element in the iterator.  The
+@code{imap} Python method is light-weight.  It does not proactively
+iterate over the iterator, but rather creates a new iterator which
+wraps the existing one.
+
+Below is the frame decorator for this example.
+
+@smallexample
+class InlinedFrameDecorator(FrameDecorator):
+
+    def __init__(self, fobj):
+        super(InlinedFrameDecorator, self).__init__(fobj)
+
+    def function(self):
+        frame = fobj.inferior_frame()
+        name = str(frame.name())
+
+        if frame.type() == gdb.INLINE_FRAME:
+            name = name + " [inlined]"
+
+        return name
+@end smallexample
+
+This frame decorator only defines and overrides the @code{function}
+method.  It lets the supplied @code{FrameDecorator}, which is shipped
+with @value{GDBN}, perform the other work associated with printing
+this frame.
+
+The combination of these two objects create this output from a
+backtrace:
+
+@smallexample
+#0  0x004004e0 in bar () at inline.c:11
+#1  0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
+#2  0x00400566 in main () at inline.c:31
+@end smallexample
+
+So in the case of this example, a frame decorator is applied to all
+frames, regardless of whether they may be inlined or not.  As
+@value{GDBN} iterates over the iterator produced by the frame filters,
+@value{GDBN} executes each frame decorator which then makes a decision
+on what to print in the @code{function} callback.  Using a strategy
+like this is a way to defer decisions on the frame content to printing
+time.
+
+@subheading Eliding Frames
+
+It might be that the above example is not desirable for representing
+inlined frames, and a hierarchical approach may be preferred.  If we
+want to hierarchically represent frames, the @code{elided} frame
+decorator interface might be preferable.
+
+This example approaches the issue with the @code{elided} method.  This
+example is quite long, but very simplistic.  It is out-of-scope for
+this section to write a complete example that comprehensively covers
+all approaches of finding and printing inlined frames.  However, this
+example illustrates the approach an author might use.
+
+This example comprises of three sections.
+
+@smallexample
+class InlineFrameFilter():
+
+    def __init__(self):
+        self.name = "InlinedFrameFilter"
+        self.priority = 100
+        self.enabled = True
+        gdb.frame_filters[self.name] = self
+
+    def filter(self, frame_iter):
+        return ElidingInlineIterator(frame_iter)
+@end smallexample
+
+This frame filter is very similar to the other examples.  The only
+difference is this frame filter is wrapping the iterator provided to
+it (@code{frame_iter}) with a custom iterator called
+@code{ElidingInlineIterator}.  This again defers actions to when
+@value{GDBN} prints the backtrace, as the iterator is not traversed
+until printing.
+
+The iterator for this example is as follows.  It is in this section of
+the example where decisions are made on the content of the backtrace.
+
+@smallexample
+class ElidingInlineIterator:
+    def __init__(self, ii):
+        self.input_iterator = ii
+
+    def __iter__(self):
+        return self
+
+    def next(self):
+        frame = next(self.input_iterator)
+
+        if frame.inferior_frame().type() != gdb.INLINE_FRAME:
+            return frame
+
+        try:
+            eliding_frame = next(self.input_iterator)
+        except StopIteration:
+            return frame
+        return ElidingFrameDecorator(eliding_frame, [frame])
+@end smallexample
+
+This iterator implements the Python iterator protocol.  When the
+@code{next} function is called (when @value{GDBN} prints each frame),
+the iterator checks if this frame decorator, @code{frame}, is wrapping
+an inlined frame.  If it is not, it returns the existing frame decorator
+untouched.  If it is wrapping an inlined frame, it assumes that the
+inlined frame was contained within the next oldest frame,
+@code{eliding_frame}, which it fetches.  It then creates and returns a
+frame decorator, @code{ElidingFrameDecorator}, which contains both the
+elided frame, and the eliding frame.
+
+@smallexample
+class ElidingInlineDecorator(FrameDecorator):
+
+    def __init__(self, frame, elided_frames):
+        super(ElidingInlineDecorator, self).__init__(frame)
+        self.frame = frame
+        self.elided_frames = elided_frames
+
+    def elided(self):
+        return iter(self.elided_frames)
+@end smallexample
+
+This frame decorator overrides one function and returns the inlined
+frame in the @code{elided} method.  As before it lets
+@code{FrameDecorator} do the rest of the work involved in printing
+this frame.  This produces the following output.
+
+@smallexample
+#0  0x004004e0 in bar () at inline.c:11
+#2  0x00400529 in main () at inline.c:25
+    #1  0x00400529 in max (b=6, a=12) at inline.c:15
+@end smallexample
+
+In that output, @code{max} which has been inlined into @code{main} is
+printed hierarchically.  Another approach would be to combine the
+@code{function} method, and the @code{elided} method to both print a
+marker in the inlined frame, and also show the hierarchical
+relationship.
+
+@node Inferiors In Python
+@subsubsection Inferiors In Python
+@cindex inferiors in Python
+
+@findex gdb.Inferior
+Programs which are being run under @value{GDBN} are called inferiors
+(@pxref{Inferiors and Programs}).  Python scripts can access
+information about and manipulate inferiors controlled by @value{GDBN}
+via objects of the @code{gdb.Inferior} class.
+
+The following inferior-related functions are available in the @code{gdb}
+module:
+
+@defun gdb.inferiors ()
+Return a tuple containing all inferior objects.
+@end defun
+
+@defun gdb.selected_inferior ()
+Return an object representing the current inferior.
+@end defun
+
+A @code{gdb.Inferior} object has the following attributes:
+
+@defvar Inferior.num
+ID of inferior, as assigned by GDB.
+@end defvar
+
+@defvar Inferior.pid
+Process ID of the inferior, as assigned by the underlying operating
+system.
+@end defvar
+
+@defvar Inferior.was_attached
+Boolean signaling whether the inferior was created using `attach', or
+started by @value{GDBN} itself.
+@end defvar
+
+A @code{gdb.Inferior} object has the following methods:
+
+@defun 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 defun
+
+@defun 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
+return an empty tuple.
+@end defun
+
+@findex Inferior.read_memory
+@defun Inferior.read_memory (address, length)
+Read @var{length} bytes of memory from the inferior, starting at
+@var{address}.  Returns a buffer object, which behaves much like an array
+or a string.  It can be modified and given to the
+@code{Inferior.write_memory} function.  In @code{Python} 3, the return
+value is a @code{memoryview} object.
+@end defun
+
+@findex Inferior.write_memory
+@defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
+Write the contents of @var{buffer} to the inferior, starting at
+@var{address}.  The @var{buffer} parameter must be a Python object
+which supports the buffer protocol, i.e., a string, an array or the
+object returned from @code{Inferior.read_memory}.  If given, @var{length}
+determines the number of bytes from @var{buffer} to be written.
+@end defun
+
+@findex gdb.search_memory
+@defun Inferior.search_memory (address, length, pattern)
+Search a region of the inferior memory starting at @var{address} with
+the given @var{length} using the search pattern supplied in
+@var{pattern}.  The @var{pattern} parameter must be a Python object
+which supports the buffer protocol, i.e., a string, an array or the
+object returned from @code{gdb.read_memory}.  Returns a Python @code{Long}
+containing the address where the pattern was found, or @code{None} if
+the pattern could not be found.
+@end defun
+
+@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:
+
+@defun 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 defun
+
+@defun EventRegistry.disconnect (object)
+Remove the given @var{object} from the registry.  Once removed, the object
+will no longer receive notifications of events.
+@end defun
+
+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}.
+
+@defvar 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 defvar
+
+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 two attributes:
+@defvar ExitedEvent.exit_code
+An integer representing the exit code, if available, which the inferior 
+has returned.  (The exit code could be unavailable if, for example,
+@value{GDBN} detaches from the inferior.) If the exit code is unavailable,
+the attribute does not exist.
+@end defvar
+@defvar ExitedEvent inferior
+A reference to the inferior which triggered the @code{exited} event.
+@end defvar
+
+@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:
+
+@defvar 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 defvar
+
+Also emits  @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
+
+@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
+been hit, and has the following attributes:
+
+@defvar BreakpointEvent.breakpoints
+A sequence containing references to all the breakpoints (type 
+@code{gdb.Breakpoint}) that were hit.
+@xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
+@end defvar
+@defvar BreakpointEvent.breakpoint
+A reference to the first breakpoint that was hit.
+This function is maintained for backward compatibility and is now deprecated 
+in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
+@end defvar
+
+@item events.new_objfile
+Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
+been loaded by @value{GDBN}.  @code{gdb.NewObjFileEvent} has one attribute:
+
+@defvar NewObjFileEvent.new_objfile
+A reference to the object file (@code{gdb.Objfile}) which has been loaded.
+@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
+@end defvar
+
+@end table
+
+@node Threads In Python
+@subsubsection Threads In Python
+@cindex threads in python
+
+@findex gdb.InferiorThread
+Python scripts can access information about, and manipulate inferior threads
+controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
+
+The following thread-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.selected_thread
+@defun gdb.selected_thread ()
+This function returns the thread object for the selected thread.  If there
+is no selected thread, this will return @code{None}.
+@end defun
+
+A @code{gdb.InferiorThread} object has the following attributes:
+
+@defvar 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 defvar
+
+@defvar InferiorThread.num
+ID of the thread, as assigned by GDB.
+@end defvar
+
+@defvar InferiorThread.ptid
+ID of the thread, as assigned by the operating system.  This attribute is a
+tuple containing three integers.  The first is the Process ID (PID); the second
+is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
+Either the LWPID or TID may be 0, which indicates that the operating system
+does not  use that identifier.
+@end defvar
+
+A @code{gdb.InferiorThread} object has the following methods:
+
+@defun 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 defun
+
+@defun InferiorThread.switch ()
+This changes @value{GDBN}'s currently selected thread to the one represented
+by this object.
+@end defun
+
+@defun InferiorThread.is_stopped ()
+Return a Boolean indicating whether the thread is stopped.
+@end defun
+
+@defun InferiorThread.is_running ()
+Return a Boolean indicating whether the thread is running.
+@end defun
+
+@defun InferiorThread.is_exited ()
+Return a Boolean indicating whether the thread is exited.
+@end defun
+
+@node Commands In Python
+@subsubsection Commands In Python
+
+@cindex commands in python
+@cindex python commands
+You can implement new @value{GDBN} CLI commands in Python.  A CLI
+command is implemented using an instance of the @code{gdb.Command}
+class, most commonly using a subclass.
+
+@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
+The object initializer for @code{Command} registers the new command
+with @value{GDBN}.  This initializer is normally invoked from the
+subclass' own @code{__init__} method.
+
+@var{name} is the name of the command.  If @var{name} consists of
+multiple words, then the initial words are looked for as prefix
+commands.  In this case, if one of the prefix commands does not exist,
+an exception is raised.
+
+There is no support for multi-line commands.
+
+@var{command_class} should be one of the @samp{COMMAND_} constants
+defined below.  This argument tells @value{GDBN} how to categorize the
+new command in the help system.
+
+@var{completer_class} is an optional argument.  If given, it should be
+one of the @samp{COMPLETE_} constants defined below.  This argument
+tells @value{GDBN} how to perform completion for this command.  If not
+given, @value{GDBN} will attempt to complete using the object's
+@code{complete} method (see below); if no such method is found, an
+error will occur when completion is attempted.
+
+@var{prefix} is an optional argument.  If @code{True}, then the new
+command is a prefix command; sub-commands of this command may be
+registered.
+
+The help text for the new command is taken from the Python
+documentation string for the command's class, if there is one.  If no
+documentation string is provided, the default value ``This command is
+not documented.'' is used.
+@end defun
+
+@cindex don't repeat Python command
+@defun Command.dont_repeat ()
+By default, a @value{GDBN} command is repeated when the user enters a
+blank line at the command prompt.  A command can suppress this
+behavior by invoking the @code{dont_repeat} method.  This is similar
+to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
+@end defun
+
+@defun Command.invoke (argument, from_tty)
+This method is called by @value{GDBN} when this command is invoked.
+
+@var{argument} is a string.  It is the argument to the command, after
+leading and trailing whitespace has been stripped.
+
+@var{from_tty} is a boolean argument.  When true, this means that the
+command was entered by the user at the terminal; when false it means
+that the command came from elsewhere.
+
+If this method throws an exception, it is turned into a @value{GDBN}
+@code{error} call.  Otherwise, the return value is ignored.
+
+@findex gdb.string_to_argv
+To break @var{argument} up into an argv-like string use
+@code{gdb.string_to_argv}.  This function behaves identically to
+@value{GDBN}'s internal argument lexer @code{buildargv}.
+It is recommended to use this for consistency.
+Arguments are separated by spaces and may be quoted.
+Example:
+
+@smallexample
+print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
+['1', '2 "3', '4 "5', "6 '7"]
+@end smallexample
+
+@end defun
+
+@cindex completion of Python commands
+@defun Command.complete (text, word)
+This method is called by @value{GDBN} when the user attempts
+completion on this command.  All forms of completion are handled by
+this method, that is, the @key{TAB} and @key{M-?} key bindings
+(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
+complete}).
+
+The arguments @var{text} and @var{word} are both strings.  @var{text}
+holds the complete command line up to the cursor's location.
+@var{word} holds the last word of the command line; this is computed
+using a word-breaking heuristic.
+
+The @code{complete} method can return several values:
+@itemize @bullet
+@item
+If the return value is a sequence, the contents of the sequence are
+used as the completions.  It is up to @code{complete} to ensure that the
+contents actually do complete the word.  A zero-length sequence is
+allowed, it means that there were no completions available.  Only
+string elements of the sequence are used; other elements in the
+sequence are ignored.
+
+@item
+If the return value is one of the @samp{COMPLETE_} constants defined
+below, then the corresponding @value{GDBN}-internal completion
+function is invoked, and its result is used.
+
+@item
+All other results are treated as though there were no available
+completions.
+@end itemize
+@end defun
+
+When a new command is registered, it must be declared as a member of
+some general class of commands.  This is used to classify top-level
+commands in the on-line help system; note that prefix commands are not
+listed under their own category but rather that of their top-level
+command.  The available classifications are represented by constants
+defined in the @code{gdb} module:
+
+@table @code
+@findex COMMAND_NONE
+@findex gdb.COMMAND_NONE
+@item gdb.COMMAND_NONE
+The command does not belong to any particular class.  A command in
+this category will not be displayed in any of the help categories.
+
+@findex COMMAND_RUNNING
+@findex gdb.COMMAND_RUNNING
+@item gdb.COMMAND_RUNNING
+The command is related to running the inferior.  For example,
+@code{start}, @code{step}, and @code{continue} are in this category.
+Type @kbd{help running} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@findex COMMAND_DATA
+@findex gdb.COMMAND_DATA
+@item gdb.COMMAND_DATA
+The command is related to data or variables.  For example,
+@code{call}, @code{find}, and @code{print} are in this category.  Type
+@kbd{help data} at the @value{GDBN} prompt to see a list of commands
+in this category.
+
+@findex COMMAND_STACK
+@findex gdb.COMMAND_STACK
+@item gdb.COMMAND_STACK
+The command has to do with manipulation of the stack.  For example,
+@code{backtrace}, @code{frame}, and @code{return} are in this
+category.  Type @kbd{help stack} at the @value{GDBN} prompt to see a
+list of commands in this category.
+
+@findex COMMAND_FILES
+@findex gdb.COMMAND_FILES
+@item gdb.COMMAND_FILES
+This class is used for file-related commands.  For example,
+@code{file}, @code{list} and @code{section} are in this category.
+Type @kbd{help files} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@findex COMMAND_SUPPORT
+@findex gdb.COMMAND_SUPPORT
+@item gdb.COMMAND_SUPPORT
+This should be used for ``support facilities'', generally meaning
+things that are useful to the user when interacting with @value{GDBN},
+but not related to the state of the inferior.  For example,
+@code{help}, @code{make}, and @code{shell} are in this category.  Type
+@kbd{help support} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@findex COMMAND_STATUS
+@findex gdb.COMMAND_STATUS
+@item gdb.COMMAND_STATUS
+The command is an @samp{info}-related command, that is, related to the
+state of @value{GDBN} itself.  For example, @code{info}, @code{macro},
+and @code{show} are in this category.  Type @kbd{help status} at the
+@value{GDBN} prompt to see a list of commands in this category.
+
+@findex COMMAND_BREAKPOINTS
+@findex gdb.COMMAND_BREAKPOINTS
+@item gdb.COMMAND_BREAKPOINTS
+The command has to do with breakpoints.  For example, @code{break},
+@code{clear}, and @code{delete} are in this category.  Type @kbd{help
+breakpoints} at the @value{GDBN} prompt to see a list of commands in
+this category.
+
+@findex COMMAND_TRACEPOINTS
+@findex gdb.COMMAND_TRACEPOINTS
+@item gdb.COMMAND_TRACEPOINTS
+The command has to do with tracepoints.  For example, @code{trace},
+@code{actions}, and @code{tfind} are in this category.  Type
+@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@findex COMMAND_USER
+@findex gdb.COMMAND_USER
+@item gdb.COMMAND_USER
+The command is a general purpose command for the user, and typically
+does not fit in one of the other categories.
+Type @kbd{help user-defined} at the @value{GDBN} prompt to see
+a list of commands in this category, as well as the list of gdb macros
+(@pxref{Sequences}).
+
+@findex COMMAND_OBSCURE
+@findex gdb.COMMAND_OBSCURE
+@item gdb.COMMAND_OBSCURE
+The command is only used in unusual circumstances, or is not of
+general interest to users.  For example, @code{checkpoint},
+@code{fork}, and @code{stop} are in this category.  Type @kbd{help
+obscure} at the @value{GDBN} prompt to see a list of commands in this
+category.
+
+@findex COMMAND_MAINTENANCE
+@findex gdb.COMMAND_MAINTENANCE
+@item gdb.COMMAND_MAINTENANCE
+The command is only useful to @value{GDBN} maintainers.  The
+@code{maintenance} and @code{flushregs} commands are in this category.
+Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
+commands in this category.
+@end table
+
+A new command can use a predefined completion function, either by
+specifying it via an argument at initialization, or by returning it
+from the @code{complete} method.  These predefined completion
+constants are all defined in the @code{gdb} module:
+
+@table @code
+@findex COMPLETE_NONE
+@findex gdb.COMPLETE_NONE
+@item gdb.COMPLETE_NONE
+This constant means that no completion should be done.
+
+@findex COMPLETE_FILENAME
+@findex gdb.COMPLETE_FILENAME
+@item gdb.COMPLETE_FILENAME
+This constant means that filename completion should be performed.
+
+@findex COMPLETE_LOCATION
+@findex gdb.COMPLETE_LOCATION
+@item gdb.COMPLETE_LOCATION
+This constant means that location completion should be done.
+@xref{Specify Location}.
+
+@findex COMPLETE_COMMAND
+@findex gdb.COMPLETE_COMMAND
+@item gdb.COMPLETE_COMMAND
+This constant means that completion should examine @value{GDBN}
+command names.
+
+@findex COMPLETE_SYMBOL
+@findex gdb.COMPLETE_SYMBOL
+@item gdb.COMPLETE_SYMBOL
+This constant means that completion should be done using symbol names
+as the source.
+
+@findex COMPLETE_EXPRESSION
+@findex gdb.COMPLETE_EXPRESSION
+@item gdb.COMPLETE_EXPRESSION
+This constant means that completion should be done on expressions.
+Often this means completing on symbol names, but some language
+parsers also have support for completing on field names.
+@end table
+
+The following code snippet shows how a trivial CLI command can be
+implemented in Python:
+
+@smallexample
+class HelloWorld (gdb.Command):
+  """Greet the whole world."""
+
+  def __init__ (self):
+    super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
+
+  def invoke (self, arg, from_tty):
+    print "Hello, World!"
+
+HelloWorld ()
+@end smallexample
+
+The last line instantiates the class, and is necessary to trigger the
+registration of the command with @value{GDBN}.  Depending on how the
+Python code is read into @value{GDBN}, you may need to import the
+@code{gdb} module explicitly.
+
+@node Parameters In Python
+@subsubsection Parameters In Python
+
+@cindex parameters in python
+@cindex python parameters
+@tindex gdb.Parameter
+@tindex Parameter
+You can implement new @value{GDBN} parameters using Python.  A new
+parameter is implemented as an instance of the @code{gdb.Parameter}
+class.
+
+Parameters are exposed to the user via the @code{set} and
+@code{show} commands.  @xref{Help}.
+
+There are many parameters that already exist and can be set in
+@value{GDBN}.  Two examples are: @code{set follow fork} and
+@code{set charset}.  Setting these parameters influences certain
+behavior in @value{GDBN}.  Similarly, you can define parameters that
+can be used to influence behavior in custom Python scripts and commands.
+
+@defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
+The object initializer for @code{Parameter} registers the new
+parameter with @value{GDBN}.  This initializer is normally invoked
+from the subclass' own @code{__init__} method.
+
+@var{name} is the name of the new parameter.  If @var{name} consists
+of multiple words, then the initial words are looked for as prefix
+parameters.  An example of this can be illustrated with the
+@code{set print} set of parameters.  If @var{name} is
+@code{print foo}, then @code{print} will be searched as the prefix
+parameter.  In this case the parameter can subsequently be accessed in
+@value{GDBN} as @code{set print foo}.
+
+If @var{name} consists of multiple words, and no prefix parameter group
+can be found, an exception is raised.
+
+@var{command-class} should be one of the @samp{COMMAND_} constants
+(@pxref{Commands In Python}).  This argument tells @value{GDBN} how to
+categorize the new parameter in the help system.
+
+@var{parameter-class} should be one of the @samp{PARAM_} constants
+defined below.  This argument tells @value{GDBN} the type of the new
+parameter; this information is used for input validation and
+completion.
+
+If @var{parameter-class} is @code{PARAM_ENUM}, then
+@var{enum-sequence} must be a sequence of strings.  These strings
+represent the possible values for the parameter.
+
+If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
+of a fourth argument will cause an exception to be thrown.
+
+The help text for the new parameter is taken from the Python
+documentation string for the parameter's class, if there is one.  If
+there is no documentation string, a default value is used.
+@end defun
+
+@defvar Parameter.set_doc
+If this attribute exists, and is a string, then its value is used as
+the help text for this parameter's @code{set} command.  The value is
+examined when @code{Parameter.__init__} is invoked; subsequent changes
+have no effect.
+@end defvar
+
+@defvar Parameter.show_doc
+If this attribute exists, and is a string, then its value is used as
+the help text for this parameter's @code{show} command.  The value is
+examined when @code{Parameter.__init__} is invoked; subsequent changes
+have no effect.
+@end defvar
+
+@defvar Parameter.value
+The @code{value} attribute holds the underlying value of the
+parameter.  It can be read and assigned to just as any other
+attribute.  @value{GDBN} does validation when assignments are made.
+@end defvar
+
+There are two methods that should be implemented in any
+@code{Parameter} class.  These are:
+
+@defun 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 defun
+
+@defun 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 defun
+
+When a new parameter is defined, its type must be specified.  The
+available types are represented by constants defined in the @code{gdb}
+module:
+
+@table @code
+@findex PARAM_BOOLEAN
+@findex gdb.PARAM_BOOLEAN
+@item gdb.PARAM_BOOLEAN
+The value is a plain boolean.  The Python boolean values, @code{True}
+and @code{False} are the only valid values.
+
+@findex PARAM_AUTO_BOOLEAN
+@findex gdb.PARAM_AUTO_BOOLEAN
+@item gdb.PARAM_AUTO_BOOLEAN
+The value has three possible states: true, false, and @samp{auto}.  In
+Python, true and false are represented using boolean constants, and
+@samp{auto} is represented using @code{None}.
+
+@findex PARAM_UINTEGER
+@findex gdb.PARAM_UINTEGER
+@item gdb.PARAM_UINTEGER
+The value is an unsigned integer.  The value of 0 should be
+interpreted to mean ``unlimited''.
+
+@findex PARAM_INTEGER
+@findex gdb.PARAM_INTEGER
+@item gdb.PARAM_INTEGER
+The value is a signed integer.  The value of 0 should be interpreted
+to mean ``unlimited''.
+
+@findex PARAM_STRING
+@findex gdb.PARAM_STRING
+@item gdb.PARAM_STRING
+The value is a string.  When the user modifies the string, any escape
+sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
+translated into corresponding characters and encoded into the current
+host charset.
+
+@findex PARAM_STRING_NOESCAPE
+@findex gdb.PARAM_STRING_NOESCAPE
+@item gdb.PARAM_STRING_NOESCAPE
+The value is a string.  When the user modifies the string, escapes are
+passed through untranslated.
+
+@findex PARAM_OPTIONAL_FILENAME
+@findex gdb.PARAM_OPTIONAL_FILENAME
+@item gdb.PARAM_OPTIONAL_FILENAME
+The value is a either a filename (a string), or @code{None}.
+
+@findex PARAM_FILENAME
+@findex gdb.PARAM_FILENAME
+@item gdb.PARAM_FILENAME
+The value is a filename.  This is just like
+@code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
+
+@findex PARAM_ZINTEGER
+@findex gdb.PARAM_ZINTEGER
+@item gdb.PARAM_ZINTEGER
+The value is an integer.  This is like @code{PARAM_INTEGER}, except 0
+is interpreted as itself.
+
+@findex PARAM_ENUM
+@findex gdb.PARAM_ENUM
+@item gdb.PARAM_ENUM
+The value is a string, which must be one of a collection string
+constants provided when the parameter is created.
+@end table
+
+@node Functions In Python
+@subsubsection Writing new convenience functions
+
+@cindex writing convenience functions
+@cindex convenience functions in python
+@cindex python convenience functions
+@tindex gdb.Function
+@tindex Function
+You can implement new convenience functions (@pxref{Convenience Vars})
+in Python.  A convenience function is an instance of a subclass of the
+class @code{gdb.Function}.
+
+@defun Function.__init__ (name)
+The initializer for @code{Function} registers the new function with
+@value{GDBN}.  The argument @var{name} is the name of the function,
+a string.  The function will be visible to the user as a convenience
+variable of type @code{internal function}, whose name is the same as
+the given @var{name}.
+
+The documentation for the new function is taken from the documentation
+string for the new class.
+@end defun
+
+@defun Function.invoke (@var{*args})
+When a convenience function is evaluated, its arguments are converted
+to instances of @code{gdb.Value}, and then the function's
+@code{invoke} method is called.  Note that @value{GDBN} does not
+predetermine the arity of convenience functions.  Instead, all
+available arguments are passed to @code{invoke}, following the
+standard Python calling convention.  In particular, a convenience
+function can have default values for parameters without ill effect.
+
+The return value of this method is used as its value in the enclosing
+expression.  If an ordinary Python value is returned, it is converted
+to a @code{gdb.Value} following the usual rules.
+@end defun
+
+The following code snippet shows how a trivial convenience function can
+be implemented in Python:
+
+@smallexample
+class Greet (gdb.Function):
+  """Return string to greet someone.
+Takes a name as argument."""
+
+  def __init__ (self):
+    super (Greet, self).__init__ ("greet")
+
+  def invoke (self, name):
+    return "Hello, %s!" % name.string ()
+
+Greet ()
+@end smallexample
+
+The last line instantiates the class, and is necessary to trigger the
+registration of the function with @value{GDBN}.  Depending on how the
+Python code is read into @value{GDBN}, you may need to import the
+@code{gdb} module explicitly.
+
+Now you can use the function in an expression:
+
+@smallexample
+(gdb) print $greet("Bob")
+$1 = "Hello, Bob!"
+@end smallexample
+
+@node Progspaces In Python
+@subsubsection Program Spaces In Python
+
+@cindex progspaces in python
+@tindex gdb.Progspace
+@tindex Progspace
+A program space, or @dfn{progspace}, represents a symbolic view
+of an address space.
+It consists of all of the objfiles of the program.
+@xref{Objfiles In Python}.
+@xref{Inferiors and Programs, program spaces}, for more details
+about program spaces.
+
+The following progspace-related functions are available in the
+@code{gdb} module:
+
+@findex gdb.current_progspace
+@defun gdb.current_progspace ()
+This function returns the program space of the currently selected inferior.
+@xref{Inferiors and Programs}.
+@end defun
+
+@findex gdb.progspaces
+@defun gdb.progspaces ()
+Return a sequence of all the progspaces currently known to @value{GDBN}.
+@end defun
+
+Each progspace is represented by an instance of the @code{gdb.Progspace}
+class.
+
+@defvar Progspace.filename
+The file name of the progspace as a string.
+@end defvar
+
+@defvar Progspace.pretty_printers
+The @code{pretty_printers} attribute is a list of functions.  It is
+used to look up pretty-printers.  A @code{Value} is passed to each
+function in order; if the function returns @code{None}, then the
+search continues.  Otherwise, the return value should be an object
+which is used to format the value.  @xref{Pretty Printing API}, for more
+information.
+@end defvar
+
+@defvar Progspace.type_printers
+The @code{type_printers} attribute is a list of type printer objects.
+@xref{Type Printing API}, for more information.
+@end defvar
+
+@defvar Progspace.frame_filters
+The @code{frame_filters} attribute is a dictionary of frame filter
+objects.  @xref{Frame Filter API}, for more information.
+@end defvar
+
+@node Objfiles In Python
+@subsubsection Objfiles In Python
+
+@cindex objfiles in python
+@tindex gdb.Objfile
+@tindex Objfile
+@value{GDBN} loads symbols for an inferior from various
+symbol-containing files (@pxref{Files}).  These include the primary
+executable file, any shared libraries used by the inferior, and any
+separate debug info files (@pxref{Separate Debug Files}).
+@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
+
+The following objfile-related functions are available in the
+@code{gdb} module:
+
+@findex gdb.current_objfile
+@defun gdb.current_objfile ()
+When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
+sets the ``current objfile'' to the corresponding objfile.  This
+function returns the current objfile.  If there is no current objfile,
+this function returns @code{None}.
+@end defun
+
+@findex gdb.objfiles
+@defun gdb.objfiles ()
+Return a sequence of all the objfiles current known to @value{GDBN}.
+@xref{Objfiles In Python}.
+@end defun
+
+Each objfile is represented by an instance of the @code{gdb.Objfile}
+class.
+
+@defvar Objfile.filename
+The file name of the objfile as a string.
+@end defvar
+
+@defvar Objfile.pretty_printers
+The @code{pretty_printers} attribute is a list of functions.  It is
+used to look up pretty-printers.  A @code{Value} is passed to each
+function in order; if the function returns @code{None}, then the
+search continues.  Otherwise, the return value should be an object
+which is used to format the value.  @xref{Pretty Printing API}, for more
+information.
+@end defvar
+
+@defvar Objfile.type_printers
+The @code{type_printers} attribute is a list of type printer objects.
+@xref{Type Printing API}, for more information.
+@end defvar
+
+@defvar Objfile.frame_filters
+The @code{frame_filters} attribute is a dictionary of frame filter
+objects.  @xref{Frame Filter API}, for more information.
+@end defvar
+
+A @code{gdb.Objfile} object has the following methods:
+
+@defun 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 defun
+
+@node Frames In Python
+@subsubsection Accessing inferior stack frames from Python.
+
+@cindex frames in python
+When the debugged program stops, @value{GDBN} is able to analyze its call
+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{gdb.error}
+exception (@pxref{Exception Handling}).
+
+Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
+operator, like:
+
+@smallexample
+(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
+True
+@end smallexample
+
+The following frame-related functions are available in the @code{gdb} module:
+
+@findex gdb.selected_frame
+@defun gdb.selected_frame ()
+Return the selected frame object.  (@pxref{Selection,,Selecting a Frame}).
+@end defun
+
+@findex gdb.newest_frame
+@defun gdb.newest_frame ()
+Return the newest frame object for the selected thread.
+@end defun
+
+@defun gdb.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
+@code{unwind_stop_reason} method further down in this section).
+@end defun
+
+A @code{gdb.Frame} object has the following methods:
+
+@defun Frame.is_valid ()
+Returns true if the @code{gdb.Frame} object is valid, false if not.
+A frame object can become invalid if the frame it refers to doesn't
+exist anymore in the inferior.  All @code{gdb.Frame} methods will throw
+an exception if it is invalid at the time the method is called.
+@end defun
+
+@defun Frame.name ()
+Returns the function name of the frame, or @code{None} if it can't be
+obtained.
+@end defun
+
+@defun Frame.architecture ()
+Returns the @code{gdb.Architecture} object corresponding to the frame's
+architecture.  @xref{Architectures In Python}.
+@end defun
+
+@defun Frame.type ()
+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.TAILCALL_FRAME
+A frame representing a tail call.  @xref{Tail Call Frames}.
+
+@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 defun
+
+@defun Frame.unwind_stop_reason ()
+Return an integer representing the reason why it's not possible to find
+more frames toward the outermost frame.  Use
+@code{gdb.frame_stop_reason_string} to convert the value returned by this
+function to a string. The value can be one of:
+
+@table @code
+@item gdb.FRAME_UNWIND_NO_REASON
+No particular reason (older frames should be available).
+
+@item gdb.FRAME_UNWIND_NULL_ID
+The previous frame's analyzer returns an invalid result.  This is no
+longer used by @value{GDBN}, and is kept only for backward
+compatibility.
+
+@item gdb.FRAME_UNWIND_OUTERMOST
+This frame is the outermost.
+
+@item gdb.FRAME_UNWIND_UNAVAILABLE
+Cannot unwind further, because that would require knowing the 
+values of registers or memory that have not been collected.
+
+@item gdb.FRAME_UNWIND_INNER_ID
+This frame ID looks like it ought to belong to a NEXT frame,
+but we got it for a PREV frame.  Normally, this is a sign of
+unwinder failure.  It could also indicate stack corruption.
+
+@item gdb.FRAME_UNWIND_SAME_ID
+This frame has the same ID as the previous one.  That means
+that unwinding further would almost certainly give us another
+frame with exactly the same ID, so break the chain.  Normally,
+this is a sign of unwinder failure.  It could also indicate
+stack corruption.
+
+@item gdb.FRAME_UNWIND_NO_SAVED_PC
+The frame unwinder did not find any saved PC, but we needed
+one to unwind further.
+
+@item gdb.FRAME_UNWIND_FIRST_ERROR
+Any stop reason greater or equal to this value indicates some kind
+of error.  This special value facilitates writing code that tests
+for errors in unwinding in a way that will work correctly even if
+the list of the other values is modified in future @value{GDBN}
+versions.  Using it, you could write:
+@smallexample
+reason = gdb.selected_frame().unwind_stop_reason ()
+reason_str =  gdb.frame_stop_reason_string (reason)
+if reason >=  gdb.FRAME_UNWIND_FIRST_ERROR:
+    print "An error occured: %s" % reason_str
+@end smallexample
+@end table
+
+@end defun
+
+@defun Frame.pc ()
+Returns the frame's resume address.
+@end defun
+
+@defun Frame.block ()
+Return the frame's code block.  @xref{Blocks In Python}.
+@end defun
+
+@defun Frame.function ()
+Return the symbol for the function corresponding to this frame.
+@xref{Symbols In Python}.
+@end defun
+
+@defun Frame.older ()
+Return the frame that called this frame.
+@end defun
+
+@defun Frame.newer ()
+Return the frame called by this frame.
+@end defun
+
+@defun Frame.find_sal ()
+Return the frame's symtab and line object.
+@xref{Symbol Tables In Python}.
+@end defun
+
+@defun Frame.read_var (variable @r{[}, block@r{]})
+Return the value of @var{variable} in this frame.  If the optional
+argument @var{block} is provided, search for the variable from that
+block; otherwise start at the frame's current block (which is
+determined by the frame's current program counter).  @var{variable}
+must be a string or a @code{gdb.Symbol} object.  @var{block} must be a
+@code{gdb.Block} object.
+@end defun
+
+@defun Frame.select ()
+Set this frame to be the selected frame.  @xref{Stack, ,Examining the
+Stack}.
+@end defun
+
+@node Blocks In Python
+@subsubsection Accessing blocks from Python.
+
+@cindex blocks in python
+@tindex gdb.Block
+
+In @value{GDBN}, symbols are stored in blocks.  A block corresponds
+roughly to a scope in the source code.  Blocks are organized
+hierarchically, and are represented individually in Python as a
+@code{gdb.Block}.  Blocks rely on debugging information being
+available.
+
+A frame has a block.  Please see @ref{Frames In Python}, for a more
+in-depth discussion of frames.
+
+The outermost block is known as the @dfn{global block}.  The global
+block typically holds public global variables and functions.
+
+The block nested just inside the global block is the @dfn{static
+block}.  The static block typically holds file-scoped variables and
+functions.
+
+@value{GDBN} provides a method to get a block's superblock, but there
+is currently no way to examine the sub-blocks of a block, or to
+iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
+Python}).
+
+Here is a short example that should help explain blocks:
+
+@smallexample
+/* This is in the global block.  */
+int global;
+
+/* This is in the static block.  */
+static int file_scope;
+
+/* 'function' is in the global block, and 'argument' is
+   in a block nested inside of 'function'.  */
+int function (int argument)
+@{
+  /* 'local' is in a block inside 'function'.  It may or may
+     not be in the same block as 'argument'.  */
+  int local;
+
+  @{
+     /* 'inner' is in a block whose superblock is the one holding
+        'local'.  */
+     int inner;
+
+     /* If this call is expanded by the compiler, you may see
+        a nested block here whose function is 'inline_function'
+        and whose superblock is the one holding 'inner'.  */
+     inline_function ();
+  @}
+@}
+@end smallexample
+
+A @code{gdb.Block} is iterable.  The iterator returns the symbols
+(@pxref{Symbols In Python}) local to the block.  Python programs
+should not assume that a specific block object will always contain a
+given symbol, since changes in @value{GDBN} features and
+infrastructure may cause symbols move across blocks in a symbol
+table.
+
+The following block-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.block_for_pc
+@defun gdb.block_for_pc (pc)
+Return the innermost @code{gdb.Block} containing the given @var{pc}
+value.  If the block cannot be found for the @var{pc} value specified,
+the function will return @code{None}.
+@end defun
+
+A @code{gdb.Block} object has the following methods:
+
+@defun 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.  The block's validity is also checked
+during iteration over symbols of the block.
+@end defun
+
+A @code{gdb.Block} object has the following attributes:
+
+@defvar Block.start
+The start address of the block.  This attribute is not writable.
+@end defvar
+
+@defvar Block.end
+The end address of the block.  This attribute is not writable.
+@end defvar
+
+@defvar Block.function
+The name of the block represented as a @code{gdb.Symbol}.  If the
+block is not named, then this attribute holds @code{None}.  This
+attribute is not writable.
+
+For ordinary function blocks, the superblock is the static block.
+However, you should note that it is possible for a function block to
+have a superblock that is not the static block -- for instance this
+happens for an inlined function.
+@end defvar
+
+@defvar Block.superblock
+The block containing this block.  If this parent block does not exist,
+this attribute holds @code{None}.  This attribute is not writable.
+@end defvar
+
+@defvar Block.global_block
+The global block associated with this block.  This attribute is not
+writable.
+@end defvar
+
+@defvar Block.static_block
+The static block associated with this block.  This attribute is not
+writable.
+@end defvar
+
+@defvar Block.is_global
+@code{True} if the @code{gdb.Block} object is a global block,
+@code{False} if not.  This attribute is not
+writable.
+@end defvar
+
+@defvar Block.is_static
+@code{True} if the @code{gdb.Block} object is a static block,
+@code{False} if not.  This attribute is not writable.
+@end defvar
+
+@node Symbols In Python
+@subsubsection Python representation of Symbols.
+
+@cindex symbols in python
+@tindex gdb.Symbol
+
+@value{GDBN} represents every variable, function and type as an
+entry in a symbol table.  @xref{Symbols, ,Examining the Symbol Table}.
+Similarly, Python represents these symbols in @value{GDBN} with the
+@code{gdb.Symbol} object.
+
+The following symbol-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.lookup_symbol
+@defun gdb.lookup_symbol (name @r{[}, block @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.  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 gdb.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:
+
+@defvar Symbol.type
+The type of the symbol or @code{None} if no type is recorded.
+This attribute is represented as a @code{gdb.Type} object.
+@xref{Types In Python}.  This attribute is not writable.
+@end defvar
+
+@defvar Symbol.symtab
+The symbol table in which the symbol appears.  This attribute is
+represented as a @code{gdb.Symtab} object.  @xref{Symbol Tables In
+Python}.  This attribute is not writable.
+@end defvar
+
+@defvar Symbol.line
+The line number in the source code at which the symbol was defined.
+This is an integer.
+@end defvar
+
+@defvar Symbol.name
+The name of the symbol as a string.  This attribute is not writable.
+@end defvar
+
+@defvar Symbol.linkage_name
+The name of the symbol, as used by the linker (i.e., may be mangled).
+This attribute is not writable.
+@end defvar
+
+@defvar Symbol.print_name
+The name of the symbol in a form suitable for output.  This is either
+@code{name} or @code{linkage_name}, depending on whether the user
+asked @value{GDBN} to display demangled or mangled names.
+@end defvar
+
+@defvar Symbol.addr_class
+The address class of the symbol.  This classifies how to find the value
+of a symbol.  Each address class is a constant defined in the
+@code{gdb} module and described later in this chapter.
+@end defvar
+
+@defvar Symbol.needs_frame
+This is @code{True} if evaluating this symbol's value requires a frame
+(@pxref{Frames In Python}) and @code{False} otherwise.  Typically,
+local variables will require a frame, but other symbols will not.
+@end defvar
+
+@defvar Symbol.is_argument
+@code{True} if the symbol is an argument of a function.
+@end defvar
+
+@defvar Symbol.is_constant
+@code{True} if the symbol is a constant.
+@end defvar
+
+@defvar Symbol.is_function
+@code{True} if the symbol is a function or a method.
+@end defvar
+
+@defvar Symbol.is_variable
+@code{True} if the symbol is a variable.
+@end defvar
+
+A @code{gdb.Symbol} object has the following methods:
+
+@defun 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 defun
+
+@defun Symbol.value (@r{[}frame@r{]})
+Compute the value of the symbol, as a @code{gdb.Value}.  For
+functions, this computes the address of the function, cast to the
+appropriate type.  If the symbol requires a frame in order to compute
+its value, then @var{frame} must be given.  If @var{frame} is not
+given, or if @var{frame} is invalid, then this method will throw an
+exception.
+@end defun
+
+The available domain categories in @code{gdb.Symbol} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_UNDEF_DOMAIN
+@findex gdb.SYMBOL_UNDEF_DOMAIN
+@item gdb.SYMBOL_UNDEF_DOMAIN
+This is used when a domain has not been discovered or none of the
+following domains apply.  This usually indicates an error either
+in the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_VAR_DOMAIN
+@findex gdb.SYMBOL_VAR_DOMAIN
+@item gdb.SYMBOL_VAR_DOMAIN
+This domain contains variables, function names, typedef names and enum
+type values.
+@findex SYMBOL_STRUCT_DOMAIN
+@findex gdb.SYMBOL_STRUCT_DOMAIN
+@item gdb.SYMBOL_STRUCT_DOMAIN
+This domain holds struct, union and enum type names.
+@findex SYMBOL_LABEL_DOMAIN
+@findex gdb.SYMBOL_LABEL_DOMAIN
+@item gdb.SYMBOL_LABEL_DOMAIN
+This domain contains names of labels (for gotos).
+@findex SYMBOL_VARIABLES_DOMAIN
+@findex gdb.SYMBOL_VARIABLES_DOMAIN
+@item gdb.SYMBOL_VARIABLES_DOMAIN
+This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
+contains everything minus functions and types.
+@findex SYMBOL_FUNCTIONS_DOMAIN
+@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
+@item gdb.SYMBOL_FUNCTION_DOMAIN
+This domain contains all functions.
+@findex SYMBOL_TYPES_DOMAIN
+@findex gdb.SYMBOL_TYPES_DOMAIN
+@item gdb.SYMBOL_TYPES_DOMAIN
+This domain contains all types.
+@end table
+
+The available address class categories in @code{gdb.Symbol} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_LOC_UNDEF
+@findex gdb.SYMBOL_LOC_UNDEF
+@item gdb.SYMBOL_LOC_UNDEF
+If this is returned by address class, it indicates an error either in
+the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_LOC_CONST
+@findex gdb.SYMBOL_LOC_CONST
+@item gdb.SYMBOL_LOC_CONST
+Value is constant int.
+@findex SYMBOL_LOC_STATIC
+@findex gdb.SYMBOL_LOC_STATIC
+@item gdb.SYMBOL_LOC_STATIC
+Value is at a fixed address.
+@findex SYMBOL_LOC_REGISTER
+@findex gdb.SYMBOL_LOC_REGISTER
+@item gdb.SYMBOL_LOC_REGISTER
+Value is in a register.
+@findex SYMBOL_LOC_ARG
+@findex gdb.SYMBOL_LOC_ARG
+@item gdb.SYMBOL_LOC_ARG
+Value is an argument.  This value is at the offset stored within the
+symbol inside the frame's argument list.
+@findex SYMBOL_LOC_REF_ARG
+@findex gdb.SYMBOL_LOC_REF_ARG
+@item gdb.SYMBOL_LOC_REF_ARG
+Value address is stored in the frame's argument list.  Just like
+@code{LOC_ARG} except that the value's address is stored at the
+offset, not the value itself.
+@findex SYMBOL_LOC_REGPARM_ADDR
+@findex gdb.SYMBOL_LOC_REGPARM_ADDR
+@item gdb.SYMBOL_LOC_REGPARM_ADDR
+Value is a specified register.  Just like @code{LOC_REGISTER} except
+the register holds the address of the argument instead of the argument
+itself.
+@findex SYMBOL_LOC_LOCAL
+@findex gdb.SYMBOL_LOC_LOCAL
+@item gdb.SYMBOL_LOC_LOCAL
+Value is a local variable.
+@findex SYMBOL_LOC_TYPEDEF
+@findex gdb.SYMBOL_LOC_TYPEDEF
+@item gdb.SYMBOL_LOC_TYPEDEF
+Value not used.  Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
+have this class.
+@findex SYMBOL_LOC_BLOCK
+@findex gdb.SYMBOL_LOC_BLOCK
+@item gdb.SYMBOL_LOC_BLOCK
+Value is a block.
+@findex SYMBOL_LOC_CONST_BYTES
+@findex gdb.SYMBOL_LOC_CONST_BYTES
+@item gdb.SYMBOL_LOC_CONST_BYTES
+Value is a byte-sequence.
+@findex SYMBOL_LOC_UNRESOLVED
+@findex gdb.SYMBOL_LOC_UNRESOLVED
+@item gdb.SYMBOL_LOC_UNRESOLVED
+Value is at a fixed address, but the address of the variable has to be
+determined from the minimal symbol table whenever the variable is
+referenced.
+@findex SYMBOL_LOC_OPTIMIZED_OUT
+@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
+@item gdb.SYMBOL_LOC_OPTIMIZED_OUT
+The value does not actually exist in the program.
+@findex SYMBOL_LOC_COMPUTED
+@findex gdb.SYMBOL_LOC_COMPUTED
+@item gdb.SYMBOL_LOC_COMPUTED
+The value's address is a computed location.
+@end table
+
+@node Symbol Tables In Python
+@subsubsection Symbol table representation in Python.
+
+@cindex symbol tables in python
+@tindex gdb.Symtab
+@tindex gdb.Symtab_and_line
+
+Access to symbol table data maintained by @value{GDBN} on the inferior
+is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
+@code{gdb.Symtab}.  Symbol table and line data for a frame is returned
+from the @code{find_sal} method in @code{gdb.Frame} object.
+@xref{Frames In Python}.
+
+For more information on @value{GDBN}'s symbol table management, see
+@ref{Symbols, ,Examining the Symbol Table}, for more information.
+
+A @code{gdb.Symtab_and_line} object has the following attributes:
+
+@defvar Symtab_and_line.symtab
+The symbol table object (@code{gdb.Symtab}) for this frame.
+This attribute is not writable.
+@end defvar
+
+@defvar Symtab_and_line.pc
+Indicates the start of the address range occupied by code for the
+current source line.  This attribute is not writable.
+@end defvar
+
+@defvar Symtab_and_line.last
+Indicates the end of the address range occupied by code for the current
+source line.  This attribute is not writable.
+@end defvar
+
+@defvar Symtab_and_line.line
+Indicates the current line number for this object.  This
+attribute is not writable.
+@end defvar
+
+A @code{gdb.Symtab_and_line} object has the following methods:
+
+@defun 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 defun
+
+A @code{gdb.Symtab} object has the following attributes:
+
+@defvar Symtab.filename
+The symbol table's source filename.  This attribute is not writable.
+@end defvar
+
+@defvar Symtab.objfile
+The symbol table's backing object file.  @xref{Objfiles In Python}.
+This attribute is not writable.
+@end defvar
+
+A @code{gdb.Symtab} object has the following methods:
+
+@defun 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 defun
+
+@defun Symtab.fullname ()
+Return the symbol table's source absolute file name.
+@end defun
+
+@defun Symtab.global_block ()
+Return the global block of the underlying symbol table.
+@xref{Blocks In Python}.
+@end defun
+
+@defun Symtab.static_block ()
+Return the static block of the underlying symbol table.
+@xref{Blocks In Python}.
+@end defun
+
+@defun Symtab.linetable ()
+Return the line table associated with the symbol table.
+@xref{Line Tables In Python}.
+@end defun
+
+@node Line Tables In Python
+@subsubsection Manipulating line tables using Python
+
+@cindex line tables in python
+@tindex gdb.LineTable
+
+Python code can request and inspect line table information from a
+symbol table that is loaded in @value{GDBN}.  A line table is a
+mapping of source lines to their executable locations in memory.  To
+acquire the line table information for a particular symbol table, use
+the @code{linetable} function (@pxref{Symbol Tables In Python}).
+
+A @code{gdb.LineTable} is iterable.  The iterator returns
+@code{LineTableEntry} objects that correspond to the source line and
+address for each line table entry.  @code{LineTableEntry} objects have
+the following attributes:
+
+@defvar LineTableEntry.line
+The source line number for this line table entry.  This number
+corresponds to the actual line of source.  This attribute is not
+writable.
+@end defvar
+
+@defvar LineTableEntry.pc
+The address that is associated with the line table entry where the
+executable code for that source line resides in memory.  This
+attribute is not writable.
+@end defvar
+
+As there can be multiple addresses for a single source line, you may
+receive multiple @code{LineTableEntry} objects with matching
+@code{line} attributes, but with different @code{pc} attributes.  The
+iterator is sorted in ascending @code{pc} order.  Here is a small
+example illustrating iterating over a line table.
+
+@smallexample
+symtab = gdb.selected_frame().find_sal().symtab
+linetable = symtab.linetable()
+for line in linetable:
+   print "Line: "+str(line.line)+" Address: "+hex(line.pc)
+@end smallexample
+
+This will have the following output:
+
+@smallexample
+Line: 33 Address: 0x4005c8L
+Line: 37 Address: 0x4005caL
+Line: 39 Address: 0x4005d2L
+Line: 40 Address: 0x4005f8L
+Line: 42 Address: 0x4005ffL
+Line: 44 Address: 0x400608L
+Line: 42 Address: 0x40060cL
+Line: 45 Address: 0x400615L
+@end smallexample
+
+In addition to being able to iterate over a @code{LineTable}, it also
+has the following direct access methods:
+
+@defun LineTable.line (line)
+Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
+entries in the line table for the given @var{line}.  @var{line} refers
+to the source code line.  If there are no entries for that source code
+@var{line}, the Python @code{None} is returned.
+@end defun
+
+@defun LineTable.has_line (line)
+Return a Python @code{Boolean} indicating whether there is an entry in
+the line table for this source line.  Return @code{True} if an entry
+is found, or @code{False} if not.
+@end defun
+
+@defun LineTable.source_lines ()
+Return a Python @code{List} of the source line numbers in the symbol
+table.  Only lines with executable code locations are returned.  The
+contents of the @code{List} will just be the source line entries
+represented as Python @code{Long} values.
+@end defun
+
+@node Breakpoints In Python
+@subsubsection Manipulating breakpoints using Python
+
+@cindex breakpoints in python
+@tindex gdb.Breakpoint
+
+Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
+class.
+
+@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@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 @code{break} command,
+or in the case of a watchpoint, by the @code{watch} command.  The
+optional @var{type} denotes the breakpoint to create from the types
+defined later in this chapter.  This argument can be either:
+@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}.  @var{type}
+defaults to @code{gdb.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{temporary} argument makes the breakpoint a temporary breakpoint.
+Temporary breakpoints are deleted after they have been hit.  Any
+further access to the Python breakpoint after it has been hit will
+result in a runtime error (as that breakpoint has now been
+automatically deleted).  The optional @var{wp_class} argument defines
+the class of watchpoint to create, if @var{type} is
+@code{gdb.BP_WATCHPOINT}.  If a watchpoint class is not provided, it
+is assumed to be a @code{gdb.WP_WRITE} class.
+@end defun
+
+@defun 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 in 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.
+
+You should not alter the execution state of the inferior (i.e.@:, step,
+next, etc.), alter the current frame context (i.e.@:, change the current
+active frame), or alter, add or delete any breakpoint.  As a general
+rule, you should not alter any data within @value{GDBN} or the inferior
+at this time.
+
+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 defun
+
+The available watchpoint types represented by constants are defined in the
+@code{gdb} module:
+
+@table @code
+@findex WP_READ
+@findex gdb.WP_READ
+@item gdb.WP_READ
+Read only watchpoint.
+
+@findex WP_WRITE
+@findex gdb.WP_WRITE
+@item gdb.WP_WRITE
+Write only watchpoint.
+
+@findex WP_ACCESS
+@findex gdb.WP_ACCESS
+@item gdb.WP_ACCESS
+Read/Write watchpoint.
+@end table
+
+@defun Breakpoint.is_valid ()
+Return @code{True} if this @code{Breakpoint} object is valid,
+@code{False} otherwise.  A @code{Breakpoint} object can become invalid
+if the user deletes the breakpoint.  In this case, the object still
+exists, but the underlying breakpoint does not.  In the cases of
+watchpoint scope, the watchpoint remains valid even if execution of the
+inferior leaves the scope of that watchpoint.
+@end defun
+
+@defun 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 defun
+
+@defvar Breakpoint.enabled
+This attribute is @code{True} if the breakpoint is enabled, and
+@code{False} otherwise.  This attribute is writable.
+@end defvar
+
+@defvar Breakpoint.silent
+This attribute is @code{True} if the breakpoint is silent, and
+@code{False} otherwise.  This attribute is writable.
+
+Note that a breakpoint can also be silent if it has commands and the
+first command is @code{silent}.  This is not reported by the
+@code{silent} attribute.
+@end defvar
+
+@defvar Breakpoint.thread
+If the breakpoint is thread-specific, this attribute holds the thread
+id.  If the breakpoint is not thread-specific, this attribute is
+@code{None}.  This attribute is writable.
+@end defvar
+
+@defvar Breakpoint.task
+If the breakpoint is Ada task-specific, this attribute holds the Ada task
+id.  If the breakpoint is not task-specific (or the underlying
+language is not Ada), this attribute is @code{None}.  This attribute
+is writable.
+@end defvar
+
+@defvar Breakpoint.ignore_count
+This attribute holds the ignore count for the breakpoint, an integer.
+This attribute is writable.
+@end defvar
+
+@defvar Breakpoint.number
+This attribute holds the breakpoint's number --- the identifier used by
+the user to manipulate the breakpoint.  This attribute is not writable.
+@end defvar
+
+@defvar Breakpoint.type
+This attribute holds the breakpoint's type --- the identifier used to
+determine the actual breakpoint type or use-case.  This attribute is not
+writable.
+@end defvar
+
+@defvar 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 defvar
+
+@defvar Breakpoint.temporary
+This attribute indicates whether the breakpoint was created as a
+temporary breakpoint.  Temporary breakpoints are automatically deleted
+after that breakpoint has been hit.  Access to this attribute, and all
+other attributes and functions other than the @code{is_valid}
+function, will result in an error after the breakpoint has been hit
+(as it has been automatically deleted).  This attribute is not
+writable.
+@end defvar
+
+The available types are represented by constants defined in the @code{gdb}
+module:
+
+@table @code
+@findex BP_BREAKPOINT
+@findex gdb.BP_BREAKPOINT
+@item gdb.BP_BREAKPOINT
+Normal code breakpoint.
+
+@findex BP_WATCHPOINT
+@findex gdb.BP_WATCHPOINT
+@item gdb.BP_WATCHPOINT
+Watchpoint breakpoint.
+
+@findex BP_HARDWARE_WATCHPOINT
+@findex gdb.BP_HARDWARE_WATCHPOINT
+@item gdb.BP_HARDWARE_WATCHPOINT
+Hardware assisted watchpoint.
+
+@findex BP_READ_WATCHPOINT
+@findex gdb.BP_READ_WATCHPOINT
+@item gdb.BP_READ_WATCHPOINT
+Hardware assisted read watchpoint.
+
+@findex BP_ACCESS_WATCHPOINT
+@findex gdb.BP_ACCESS_WATCHPOINT
+@item gdb.BP_ACCESS_WATCHPOINT
+Hardware assisted access watchpoint.
+@end table
+
+@defvar Breakpoint.hit_count
+This attribute holds the hit count for the breakpoint, an integer.
+This attribute is writable, but currently it can only be set to zero.
+@end defvar
+
+@defvar Breakpoint.location
+This attribute holds the location of the breakpoint, as specified by
+the user.  It is a string.  If the breakpoint does not have a location
+(that is, it is a watchpoint) the attribute's value is @code{None}.  This
+attribute is not writable.
+@end defvar
+
+@defvar Breakpoint.expression
+This attribute holds a breakpoint expression, as specified by
+the user.  It is a string.  If the breakpoint does not have an
+expression (the breakpoint is not a watchpoint) the attribute's value
+is @code{None}.  This attribute is not writable.
+@end defvar
+
+@defvar Breakpoint.condition
+This attribute holds the condition of the breakpoint, as specified by
+the user.  It is a string.  If there is no condition, this attribute's
+value is @code{None}.  This attribute is writable.
+@end defvar
+
+@defvar Breakpoint.commands
+This attribute holds the commands attached to the breakpoint.  If
+there are commands, this attribute's value is a string holding all the
+commands, separated by newlines.  If there are no commands, this
+attribute is @code{None}.  This attribute is not writable.
+@end defvar
+
+@node Finish Breakpoints in Python
+@subsubsection Finish Breakpoints
+
+@cindex python finish breakpoints
+@tindex gdb.FinishBreakpoint
+
+A finish breakpoint is a temporary breakpoint set at the return address of
+a frame, based on the @code{finish} command.  @code{gdb.FinishBreakpoint}
+extends @code{gdb.Breakpoint}.  The underlying breakpoint will be disabled 
+and deleted when the execution will run out of the breakpoint scope (i.e.@: 
+@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
+Finish breakpoints are thread specific and must be create with the right 
+thread selected.  
+ 
+@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
+Create a finish breakpoint at the return address of the @code{gdb.Frame}
+object @var{frame}.  If @var{frame} is not provided, this defaults to the
+newest frame.  The optional @var{internal} argument allows the breakpoint to
+become invisible to the user.  @xref{Breakpoints In Python}, for further 
+details about this argument.
+@end defun
+
+@defun FinishBreakpoint.out_of_scope (self)
+In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} 
+@code{return} command, @dots{}), a function may not properly terminate, and
+thus never hit the finish breakpoint.  When @value{GDBN} notices such a
+situation, the @code{out_of_scope} callback will be triggered.
+
+You may want to sub-class @code{gdb.FinishBreakpoint} and override this
+method:
+
+@smallexample
+class MyFinishBreakpoint (gdb.FinishBreakpoint)
+    def stop (self):
+        print "normal finish"
+        return True
+    
+    def out_of_scope ():
+        print "abnormal finish"
+@end smallexample 
+@end defun
+
+@defvar FinishBreakpoint.return_value
+When @value{GDBN} is stopped at a finish breakpoint and the frame 
+used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
+attribute will contain a @code{gdb.Value} object corresponding to the return
+value of the function.  The value will be @code{None} if the function return 
+type is @code{void} or if the return value was not computable.  This attribute
+is not writable.
+@end defvar
+
+@node Lazy Strings In Python
+@subsubsection Python representation of lazy strings.
+
+@cindex lazy strings in python
+@tindex gdb.LazyString
+
+A @dfn{lazy string} is a string whose contents is not retrieved or
+encoded until it is needed.
+
+A @code{gdb.LazyString} is represented in @value{GDBN} as an
+@code{address} that points to a region of memory, an @code{encoding}
+that will be used to encode that region of memory, and a @code{length}
+to delimit the region of memory that represents the string.  The
+difference between a @code{gdb.LazyString} and a string wrapped within
+a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
+differently by @value{GDBN} when printing.  A @code{gdb.LazyString} is
+retrieved and encoded during printing, while a @code{gdb.Value}
+wrapping a string is immediately retrieved and encoded on creation.
+
+A @code{gdb.LazyString} object has the following functions:
+
+@defun LazyString.value ()
+Convert the @code{gdb.LazyString} to a @code{gdb.Value}.  This value
+will point to the string in memory, but will lose all the delayed
+retrieval, encoding and handling that @value{GDBN} applies to a
+@code{gdb.LazyString}.
+@end defun
+
+@defvar LazyString.address
+This attribute holds the address of the string.  This attribute is not
+writable.
+@end defvar
+
+@defvar LazyString.length
+This attribute holds the length of the string in characters.  If the
+length is -1, then the string will be fetched and encoded up to the
+first null of appropriate width.  This attribute is not writable.
+@end defvar
+
+@defvar LazyString.encoding
+This attribute holds the encoding that will be applied to the string
+when the string is printed by @value{GDBN}.  If the encoding is not
+set, or contains an empty string,  then @value{GDBN} will select the
+most appropriate encoding when the string is printed.  This attribute
+is not writable.
+@end defvar
+
+@defvar LazyString.type
+This attribute holds the type that is represented by the lazy string's
+type.  For a lazy string this will always be a pointer type.  To
+resolve this to the lazy string's character type, use the type's
+@code{target} method.  @xref{Types In Python}.  This attribute is not
+writable.
+@end defvar
+
+@node Architectures In Python
+@subsubsection Python representation of architectures
+@cindex Python architectures
+
+@value{GDBN} uses architecture specific parameters and artifacts in a
+number of its various computations.  An architecture is represented
+by an instance of the @code{gdb.Architecture} class.
+
+A @code{gdb.Architecture} class has the following methods:
+
+@defun Architecture.name ()
+Return the name (string value) of the architecture.
+@end defun
+
+@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
+Return a list of disassembled instructions starting from the memory
+address @var{start_pc}.  The optional arguments @var{end_pc} and
+@var{count} determine the number of instructions in the returned list.
+If both the optional arguments @var{end_pc} and @var{count} are
+specified, then a list of at most @var{count} disassembled instructions
+whose start address falls in the closed memory address interval from
+@var{start_pc} to @var{end_pc} are returned.  If @var{end_pc} is not
+specified, but @var{count} is specified, then @var{count} number of
+instructions starting from the address @var{start_pc} are returned.  If
+@var{count} is not specified but @var{end_pc} is specified, then all
+instructions whose start address falls in the closed memory address
+interval from @var{start_pc} to @var{end_pc} are returned.  If neither
+@var{end_pc} nor @var{count} are specified, then a single instruction at
+@var{start_pc} is returned.  For all of these cases, each element of the
+returned list is a Python @code{dict} with the following string keys:
+
+@table @code
+
+@item addr
+The value corresponding to this key is a Python long integer capturing
+the memory address of the instruction.
+
+@item asm
+The value corresponding to this key is a string value which represents
+the instruction with assembly language mnemonics.  The assembly
+language flavor used is the same as that specified by the current CLI
+variable @code{disassembly-flavor}.  @xref{Machine Code}.
+
+@item length
+The value corresponding to this key is the length (integer value) of the
+instruction in bytes.
+
+@end table
+@end defun
+
+@node Python Auto-loading
+@subsection Python Auto-loading
+@cindex Python auto-loading
+
+When a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library),
+@value{GDBN} will look for Python support scripts in several ways:
+@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
+@xref{Auto-loading extensions}.
+
+The auto-loading feature is useful for supplying application-specific
+debugging commands and scripts.
+
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
+
+@table @code
+@anchor{set auto-load python-scripts}
+@kindex set auto-load python-scripts
+@item set auto-load python-scripts [on|off]
+Enable or disable the auto-loading of Python scripts.
+
+@anchor{show auto-load python-scripts}
+@kindex show auto-load python-scripts
+@item show auto-load python-scripts
+Show whether auto-loading of Python scripts is enabled or disabled.
+
+@anchor{info auto-load python-scripts}
+@kindex info auto-load python-scripts
+@cindex print list of auto-loaded Python scripts
+@item info auto-load python-scripts [@var{regexp}]
+Print the list of all Python scripts that @value{GDBN} auto-loaded.
+
+Also printed is the list of Python scripts that were mentioned in
+the @code{.debug_gdb_scripts} section and were not found
+(@pxref{dotdebug_gdb_scripts section}).
+This is useful because their names are not printed when @value{GDBN}
+tries to load them and fails.  There may be many of them, and printing
+an error message for each one is problematic.
+
+If @var{regexp} is supplied only Python scripts with matching names are printed.
+
+Example:
+
+@smallexample
+(gdb) info auto-load python-scripts
+Loaded Script
+Yes    py-section-script.py
+       full name: /tmp/py-section-script.py
+No     my-foo-pretty-printers.py
+@end smallexample
+@end table
+
+When reading an auto-loaded file, @value{GDBN} sets the
+@dfn{current objfile}.  This is available via the @code{gdb.current_objfile}
+function (@pxref{Objfiles In Python}).  This can be useful for
+registering objfile-specific pretty-printers and frame-filters.
+
+@node Python modules
+@subsection Python modules
+@cindex python modules
+
+@value{GDBN} comes with several modules to assist writing Python code.
+
+@menu
+* gdb.printing::       Building and registering pretty-printers.
+* gdb.types::          Utilities for working with types.
+* gdb.prompt::         Utilities for prompt value substitution.
+@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 FlagEnumerationPrinter (@var{name})
+A pretty-printer which handles printing of @code{enum} values.  Unlike
+@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
+work properly when there is some overlap between the enumeration
+constants.  @var{name} is the name of the printer and also the name of
+the @code{enum} type to look up.
+
+@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
+Register @var{printer} with the pretty-printer list of @var{obj}.
+If @var{replace} is @code{True} then any existing copy of the printer
+is replaced.  Otherwise a @code{RuntimeError} exception is raised
+if a printer with the same name already exists.
+@end table
+
+@node gdb.types
+@subsubsection gdb.types
+@cindex gdb.types
+
+This module provides a collection of utilities for working with
+@code{gdb.Type} 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}.
+
+@item deep_items (@var{type})
+Returns a Python iterator similar to the standard
+@code{gdb.Type.iteritems} method, except that the iterator returned
+by @code{deep_items} will recursively traverse anonymous struct or
+union fields.  For example:
+
+@smallexample
+struct A
+@{
+    int a;
+    union @{
+        int b0;
+        int b1;
+    @};
+@};
+@end smallexample
+
+@noindent
+Then in @value{GDBN}:
+@smallexample
+(@value{GDBP}) python import gdb.types
+(@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
+(@value{GDBP}) python print struct_a.keys ()
+@{['a', '']@}
+(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
+@{['a', 'b0', 'b1']@}
+@end smallexample
+
+@item get_type_recognizers ()
+Return a list of the enabled type recognizers for the current context.
+This is called by @value{GDBN} during the type-printing process
+(@pxref{Type Printing API}).
+
+@item apply_type_recognizers (recognizers, type_obj)
+Apply the type recognizers, @var{recognizers}, to the type object
+@var{type_obj}.  If any recognizer returns a string, return that
+string.  Otherwise, return @code{None}.  This is called by
+@value{GDBN} during the type-printing process (@pxref{Type Printing
+API}).
+
+@item register_type_printer (locus, printer)
+This is a convenience function to register a type printer.
+@var{printer} is the type printer to register.  It must implement the
+type printer protocol.  @var{locus} is either a @code{gdb.Objfile}, in
+which case the printer is registered with that objfile; a
+@code{gdb.Progspace}, in which case the printer is registered with
+that progspace; or @code{None}, in which case the printer is
+registered globally.
+
+@item TypePrinter
+This is a base class that implements the type printer protocol.  Type
+printers are encouraged, but not required, to derive from this class.
+It defines a constructor:
+
+@defmethod TypePrinter __init__ (self, name)
+Initialize the type printer with the given name.  The new printer
+starts in the enabled state.
+@end defmethod
+
+@end table
+
+@node gdb.prompt
+@subsubsection gdb.prompt
+@cindex gdb.prompt
+
+This module provides a method for prompt value-substitution.
+
+@table @code
+@item substitute_prompt (@var{string})
+Return @var{string} with escape sequences substituted by values.  Some
+escape sequences take arguments.  You can specify arguments inside
+``@{@}'' immediately following the escape sequence.
+
+The escape sequences you can pass to this function are:
+
+@table @code
+@item \\
+Substitute a backslash.
+@item \e
+Substitute an ESC character.
+@item \f
+Substitute the selected frame; an argument names a frame parameter.
+@item \n
+Substitute a newline.
+@item \p
+Substitute a parameter's value; the argument names the parameter.
+@item \r
+Substitute a carriage return.
+@item \t
+Substitute the selected thread; an argument names a thread parameter.
+@item \v
+Substitute the version of GDB.
+@item \w
+Substitute the current working directory.
+@item \[
+Begin a sequence of non-printing characters.  These sequences are
+typically used with the ESC character, and are not counted in the string
+length.  Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
+blue-colored ``(gdb)'' prompt where the length is five.
+@item \]
+End a sequence of non-printing characters.
+@end table
+
+For example:
+
+@smallexample
+substitute_prompt (``frame: \f,
+                   print arguments: \p@{print frame-arguments@}'')
+@end smallexample
+
+@exdent will return the string:
+
+@smallexample
+"frame: main, print arguments: scalars"
+@end smallexample
+@end table