From 329baa9572b85f84d2914d6d63818a142c46189d Mon Sep 17 00:00:00 2001 From: Doug Evans Date: Mon, 17 Feb 2014 10:35:03 -0800 Subject: [PATCH] Split python docs into separate file. * Makefile.in (GDB_DOC_FILES): Add python.texi. * gdb.texinfo (Python): Moved to ... * python.texi: ... here. New file. --- gdb/doc/ChangeLog | 6 + gdb/doc/Makefile.in | 1 + gdb/doc/gdb.texinfo | 4434 +----------------------------------------- gdb/doc/python.texi | 4444 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 4453 insertions(+), 4432 deletions(-) create mode 100644 gdb/doc/python.texi diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index f7a5eabd036..23823eecccf 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,9 @@ +2014-02-17 Doug Evans + + * Makefile.in (GDB_DOC_FILES): Add python.texi. + * gdb.texinfo (Python): Moved to ... + * python.texi: ... here. New file. + 2014-02-17 Ludovic Courtès * guile.texi (Writing a Guile Pretty-Printer) : diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index 4375b20ff1f..c2360dd2157 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 035573ee540..7dc1564fc69 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 "", line 1, in -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$") - 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 00000000000..62636a4aed5 --- /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 "", line 1, in +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$") + 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 -- 2.30.2