This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[doc RFA] Move python section to python.texi
- From: Doug Evans <xdje42 at gmail dot com>
- To: eliz at gnu dot org, gdb-patches at sourceware dot org
- Date: Thu, 13 Feb 2014 19:47:17 -0800
- Subject: [doc RFA] Move python section to python.texi
- Authentication-results: sourceware.org; auth=none
Hi.
This patch moves the Python section of the manual to its own file:
python.texi.
This patch is purely a mechanical move, no editing has been done
(beyond adding a copyright header to the top of python.texi).
2014-02-13 Doug Evans <xdje42@gmail.com>
doc/
* Makefile.in (GDB_DOC_FILES): Add python.texi.
* gdb.texinfo (Python): Moved to ...
* python.texi: ... here. New file.
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