| This is gdb.info, produced by makeinfo version 5.2 from gdb.texinfo. |
| |
| Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| * gdbserver: (gdb) Server. The GNU debugging server. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Tenth Edition, of 'Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB (GDB) Version 7.10. |
| |
| Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: Selecting Pretty-Printers, Next: Writing a Pretty-Printer, Prev: Pretty Printing API, Up: Python API |
| |
| 23.2.2.6 Selecting Pretty-Printers |
| .................................. |
| |
| The Python list '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 'global' printers, |
| they're available when debugging all inferiors. Each 'gdb.Progspace' |
| contains a 'pretty_printers' attribute. Each 'gdb.Objfile' also |
| contains a 'pretty_printers' attribute. |
| |
| Each function on these lists is passed a single 'gdb.Value' argument |
| and should return a pretty-printer object conforming to the interface |
| definition above (*note Pretty Printing API::). If a function cannot |
| create a pretty-printer for the value, it should return 'None'. |
| |
| GDB first checks the 'pretty_printers' attribute of each |
| 'gdb.Objfile' in the current program space and iteratively calls each |
| enabled lookup routine in the list for that 'gdb.Objfile' until it |
| receives a pretty-printer object. If no pretty-printer is found in the |
| objfile lists, GDB 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 |
| '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 |
| GDB provides support for enabling and disabling individual printers. |
| For example, if '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 'enabled' |
| attribute to the registered function or callable object. If this |
| attribute is present and its value is 'False', the printer is disabled, |
| otherwise the printer is enabled. |
| |
| |
| File: gdb.info, Node: Writing a Pretty-Printer, Next: Type Printing API, Prev: Selecting Pretty-Printers, Up: Python API |
| |
| 23.2.2.7 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 'std::string' printer might be |
| written. *Note Pretty Printing API::, for details on the API this class |
| must provide. |
| |
| 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' |
| |
| And here is an example showing how a lookup function for the printer |
| example above might be written. |
| |
| def str_lookup_function(val): |
| lookup_tag = val.type.tag |
| if lookup_tag == None: |
| return None |
| regex = re.compile("^std::basic_string<char,.*>$") |
| if regex.match(lookup_tag): |
| return StdStringPrinter(val) |
| return None |
| |
| 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 '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 GDB to load multiple versions of your |
| pretty-printers at the same time, because they will have different |
| names. |
| |
| You should write auto-loaded code (*note Python Auto-loading::) such |
| that it can be evaluated multiple times without changing its meaning. |
| An ideal auto-load file will consist solely of '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 |
| GDB 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, GDB will find the correct printers for the specific |
| version of the library used by each inferior. |
| |
| To continue the 'std::string' example (*note Pretty Printing API::), |
| this code might appear in 'gdb.libstdcxx.v6': |
| |
| def register_printers(objfile): |
| objfile.pretty_printers.append(str_lookup_function) |
| |
| And then the corresponding contents of the auto-load file would be: |
| |
| import gdb.libstdcxx.v6 |
| gdb.libstdcxx.v6.register_printers(gdb.current_objfile()) |
| |
| 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 "subprinters" are the printers for the individual data |
| types. |
| |
| The 'gdb.printing' module provides a formal way of solving these |
| problems (*note gdb.printing::). Here is another example that handles |
| multiple types. |
| |
| These are the types we are going to pretty-print: |
| |
| struct foo { int a, b; }; |
| struct bar { struct foo x, y; }; |
| |
| Here are the printers: |
| |
| 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"]) + ">") |
| |
| This example doesn't need a lookup function, that is handled by the |
| 'gdb.printing' module. Instead a function is provided to build up the |
| object that handles the lookup. |
| |
| 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 |
| |
| And here is the autoload support: |
| |
| import gdb.printing |
| import my_library |
| gdb.printing.register_pretty_printer( |
| gdb.current_objfile(), |
| my_library.build_pretty_printer()) |
| |
| Finally, when this printer is loaded into GDB, here is the |
| corresponding output of 'info pretty-printer': |
| |
| (gdb) info pretty-printer |
| my_library.so: |
| my_library |
| foo |
| bar |
| |
| |
| File: gdb.info, Node: Type Printing API, Next: Frame Filter API, Prev: Writing a Pretty-Printer, Up: Python API |
| |
| 23.2.2.8 Type Printing API |
| .......................... |
| |
| GDB provides a way for Python code to customize type display. This is |
| mainly useful for substituting canonical typedef names for types. |
| |
| A "type printer" is just a Python object conforming to a certain |
| protocol. A simple base class implementing the protocol is provided; |
| see *note gdb.types::. A type printer must supply at least: |
| |
| -- Instance Variable of type_printer: enabled |
| A boolean which is True if the printer is enabled, and False |
| otherwise. This is manipulated by the 'enable type-printer' and |
| 'disable type-printer' commands. |
| |
| -- Instance Variable of type_printer: name |
| The name of the type printer. This must be a string. This is used |
| by the 'enable type-printer' and 'disable type-printer' commands. |
| |
| -- Method on type_printer: instantiate (self) |
| This is called by GDB 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 'recognize' method, as described below. |
| |
| When displaying a type, say via the 'ptype' command, GDB will compute |
| a list of type recognizers. This is done by iterating first over the |
| per-objfile type printers (*note Objfiles In Python::), followed by the |
| per-progspace type printers (*note Progspaces In Python::), and finally |
| the global type printers. |
| |
| GDB will call the 'instantiate' method of each enabled type printer. |
| If this method returns 'None', then the result is ignored; otherwise, it |
| is appended to the list of recognizers. |
| |
| Then, when GDB 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-'None' value. The recognition |
| function is defined as: |
| |
| -- Method on type_recognizer: recognize (self, type) |
| If TYPE is not recognized, return 'None'. Otherwise, return a |
| string which is to be printed as the name of TYPE. The TYPE |
| argument will be an instance of 'gdb.Type' (*note Types In |
| Python::). |
| |
| GDB 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. |
| |
| |
| File: gdb.info, Node: Frame Filter API, Next: Frame Decorator API, Prev: Type Printing API, Up: Python API |
| |
| 23.2.2.9 Filtering Frames. |
| .......................... |
| |
| Frame filters are Python objects that manipulate the visibility of a |
| frame or frames when a backtrace (*note Backtrace::) is printed by GDB. |
| |
| Only commands that print a backtrace, or, in the case of GDB/MI |
| commands (*note GDB/MI::), those that return a collection of frames are |
| affected. The commands that work with frame filters are: |
| |
| 'backtrace' (*note The backtrace command: backtrace-command.), |
| '-stack-list-frames' (*note The -stack-list-frames command: |
| -stack-list-frames.), '-stack-list-variables' (*note The |
| -stack-list-variables command: -stack-list-variables.), |
| '-stack-list-arguments' *note The -stack-list-arguments command: |
| -stack-list-arguments.) and '-stack-list-locals' (*note The |
| -stack-list-locals command: -stack-list-locals.). |
| |
| 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 '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 GDB |
| frame or frames, or attempt to alter the call-stack within GDB. This |
| preserves data integrity within GDB. 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 GDB 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. *Note Frame Decorator API::, for more information |
| on decorators. Also, there are examples for both frame decorators and |
| filters in later chapters. *Note Writing a Frame Filter::, for more |
| information. |
| |
| The Python dictionary 'gdb.frame_filters' contains key/object |
| pairings that comprise a frame filter. Frame filters in this dictionary |
| are called 'global' frame filters, and they are available when debugging |
| all inferiors. These frame filters must register with the dictionary |
| directly. In addition to the 'global' dictionary, there are other |
| dictionaries that are loaded with different inferiors via auto-loading |
| (*note Python Auto-loading::). The two other areas where frame filter |
| dictionaries can be found are: 'gdb.Progspace' which contains a |
| 'frame_filters' dictionary attribute, and each 'gdb.Objfile' object |
| which also contains a 'frame_filters' dictionary attribute. |
| |
| When a command is executed from GDB that is compatible with frame |
| filters, GDB combines the 'global', 'gdb.Progspace' and all |
| 'gdb.Objfile' dictionaries currently loaded. All of the 'gdb.Objfile' |
| dictionaries are combined, as several frames, and thus several object |
| files, might be in use. GDB then prunes any frame filter whose |
| 'enabled' attribute is 'False'. This pruned list is then sorted |
| according to the 'priority' attribute in each filter. |
| |
| Once the dictionaries are combined, pruned and sorted, GDB creates an |
| iterator which wraps each frame in the call stack in a '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: |
| |
| -- Function: FrameFilter.filter (iterator) |
| GDB 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: |
| |
| Name Priority |
| |
| Filter1 5 |
| Filter2 10 |
| Filter3 100 |
| Filter4 1 |
| |
| The order that the frame filters will be called is: |
| |
| Filter3 -> Filter2 -> Filter1 -> Filter4 |
| |
| Note that the output from 'Filter3' is passed to the input of |
| 'Filter2', and so on. |
| |
| This 'filter' method is passed a Python iterator. This iterator |
| contains a sequence of frame decorators that wrap each '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 '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 (*note 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, GDB will raise |
| and print an error. |
| |
| -- Variable: FrameFilter.name |
| The 'name' attribute must be Python string which contains the name |
| of the filter displayed by GDB (*note 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. |
| |
| -- Variable: FrameFilter.enabled |
| The 'enabled' attribute must be Python boolean. This attribute |
| indicates to GDB whether the frame filter is enabled, and should be |
| considered when frame filters are executed. If 'enabled' is |
| 'True', then the frame filter will be executed when any of the |
| backtrace commands detailed earlier in this chapter are executed. |
| If 'enabled' is 'False', then the frame filter will not be |
| executed. This attribute is mandatory. |
| |
| -- Variable: FrameFilter.priority |
| The '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 'priority' other than |
| it must be a valid integer. The higher the 'priority' attribute, |
| the sooner the frame filter will be executed in relation to other |
| frame filters. Although '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. |
| |
| |
| File: gdb.info, Node: Frame Decorator API, Next: Writing a Frame Filter, Prev: Frame Filter API, Up: Python API |
| |
| 23.2.2.10 Decorating Frames. |
| ............................ |
| |
| Frame decorators are sister objects to frame filters (*note 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 'gdb.Frame' in commands where frame filters are executed. This |
| concept is called decorating a frame. Frame decorators decorate a |
| 'gdb.Frame' with Python code contained within each API call. This |
| separates the actual data contained in a 'gdb.Frame' from the decorated |
| data produced by a frame decorator. This abstraction is necessary to |
| maintain integrity of the data contained in each 'gdb.Frame'. |
| |
| Frame decorators have a mandatory interface, defined below. |
| |
| GDB already contains a frame decorator called 'FrameDecorator'. This |
| contains substantial amounts of boilerplate code to decorate the content |
| of a 'gdb.Frame'. It is recommended that other frame decorators inherit |
| and extend this object, and only to override the methods needed. |
| |
| -- Function: FrameDecorator.elided (self) |
| |
| The '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 '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 'None'. Elided frames are indented |
| from normal frames in a 'CLI' backtrace, or in the case of |
| 'GDB/MI', are placed in the '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. |
| |
| -- Function: 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 |
| 'None'. |
| |
| If this function returns 'None', GDB will not print any data for |
| this field. |
| |
| -- Function: 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 'None'. |
| |
| If this function returns a 'None', GDB will not print any data for |
| this field. |
| |
| -- Function: 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 'None'. |
| |
| If this function returns a 'None', GDB will not print any data for |
| this field. |
| |
| -- Function: 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 'None'. |
| |
| If this function returns a 'None', GDB will not print any data for |
| this field. |
| |
| -- Function: FrameDecorator.frame_args (self) |
| |
| This method must return an iterable, or 'None'. Returning an empty |
| iterable, or '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 'argument' method which takes a single |
| 'self' parameter and must return a 'gdb.Symbol' (*note Symbols In |
| Python::), or a Python string. The object must also implement a |
| 'value' method which takes a single 'self' parameter and must |
| return a 'gdb.Value' (*note Values From Inferior::), a Python |
| value, or 'None'. If the 'value' method returns 'None', and the |
| 'argument' method returns a 'gdb.Symbol', GDB will look-up and |
| print the value of the 'gdb.Symbol' automatically. |
| |
| A brief example: |
| |
| 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 |
| |
| -- Function: FrameDecorator.frame_locals (self) |
| |
| This method must return an iterable or 'None'. Returning an empty |
| iterable, or '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 'frame_args' function, (*note The frame filter |
| frame_args function: frame_args.). Below is a modified example: |
| |
| 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 |
| |
| -- Function: FrameDecorator.inferior_frame (self): |
| |
| This method must return the underlying 'gdb.Frame' that this frame |
| decorator is decorating. GDB requires the underlying frame for |
| internal frame information to determine how to print certain values |
| when printing a frame. |
| |
| |
| File: gdb.info, Node: Writing a Frame Filter, Next: Unwinding Frames in Python, Prev: Frame Decorator API, Up: Python API |
| |
| 23.2.2.11 Writing a Frame Filter |
| ................................ |
| |
| There are three basic elements that a frame filter must implement: it |
| must correctly implement the documented interface (*note Frame Filter |
| API::), it must register itself with GDB, and finally, it must decide if |
| it is to work on the data provided by GDB. 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. |
| |
| 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 |
| |
| 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: 'name', |
| 'priority' and whether the filter should be enabled with the '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 |
| 'gdb.frame_filters'. As noted earlier, 'gdb.frame_filters' is a |
| dictionary that is initialized in the 'gdb' module when GDB 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 'objfile' or 'progspace' dictionaries as they |
| are specific to the program currently loaded in GDB. The global |
| dictionary is always present in GDB and is never unloaded. Any filters |
| registered with the global dictionary will exist until GDB 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. *Note Python Auto-loading::, |
| for further information on auto-loading Python scripts. |
| |
| GDB 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 'name' attribute. When a user manages frame |
| filters (*note Frame Filter Management::), the names GDB will display |
| are those contained in the 'name' attribute. |
| |
| The final step of this example is the implementation of the 'filter' |
| method. As shown in the example comments, we define the '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 '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. *Note |
| 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 'itertools imap' method, the |
| example defers actions to the frame decorator. Frame decorators are |
| only processed when GDB 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 GDB 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 GDB 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. |
| |
| 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 |
| |
| This frame filter is somewhat similar to the earlier example, except |
| that the 'filter' method applies a frame decorator object called |
| 'InlinedFrameDecorator' to each element in the iterator. The '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. |
| |
| 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 |
| |
| This frame decorator only defines and overrides the 'function' |
| method. It lets the supplied 'FrameDecorator', which is shipped with |
| GDB, perform the other work associated with printing this frame. |
| |
| The combination of these two objects create this output from a |
| backtrace: |
| |
| #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 |
| |
| 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 GDB |
| iterates over the iterator produced by the frame filters, GDB executes |
| each frame decorator which then makes a decision on what to print in the |
| 'function' callback. Using a strategy like this is a way to defer |
| decisions on the frame content to printing time. |
| |
| 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 'elided' frame decorator |
| interface might be preferable. |
| |
| This example approaches the issue with the '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. |
| |
| 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) |
| |
| This frame filter is very similar to the other examples. The only |
| difference is this frame filter is wrapping the iterator provided to it |
| ('frame_iter') with a custom iterator called 'ElidingInlineIterator'. |
| This again defers actions to when GDB 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. |
| |
| 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]) |
| |
| This iterator implements the Python iterator protocol. When the |
| 'next' function is called (when GDB prints each frame), the iterator |
| checks if this frame decorator, '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, 'eliding_frame', which it |
| fetches. It then creates and returns a frame decorator, |
| 'ElidingFrameDecorator', which contains both the elided frame, and the |
| eliding frame. |
| |
| 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) |
| |
| This frame decorator overrides one function and returns the inlined |
| frame in the 'elided' method. As before it lets 'FrameDecorator' do the |
| rest of the work involved in printing this frame. This produces the |
| following output. |
| |
| #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 |
| |
| In that output, 'max' which has been inlined into 'main' is printed |
| hierarchically. Another approach would be to combine the 'function' |
| method, and the 'elided' method to both print a marker in the inlined |
| frame, and also show the hierarchical relationship. |
| |
| |
| File: gdb.info, Node: Unwinding Frames in Python, Next: Xmethods In Python, Prev: Writing a Frame Filter, Up: Python API |
| |
| 23.2.2.12 Unwinding Frames in Python |
| .................................... |
| |
| In GDB terminology "unwinding" is the process of finding the previous |
| frame (that is, caller's) from the current one. An unwinder has three |
| methods. The first one checks if it can handle given frame ("sniff" |
| it). For the frames it can sniff an unwinder provides two additional |
| methods: it can return frame's ID, and it can fetch registers from the |
| previous frame. A running GDB mantains a list of the unwinders and |
| calls each unwinder's sniffer in turn until it finds the one that |
| recognizes the current frame. There is an API to register an unwinder. |
| |
| The unwinders that come with GDB handle standard frames. However, |
| mixed language applications (for example, an application running Java |
| Virtual Machine) sometimes use frame layouts that cannot be handled by |
| the GDB unwinders. You can write Python code that can handle such |
| custom frames. |
| |
| You implement a frame unwinder in Python as a class with which has |
| two attributes, 'name' and 'enabled', with obvious meanings, and a |
| single method '__call__', which examines a given frame and returns an |
| object (an instance of 'gdb.UnwindInfo class)' describing it. If an |
| unwinder does not recognize a frame, it should return 'None'. The code |
| in GDB that enables writing unwinders in Python uses this object to |
| return frame's ID and previous frame registers when GDB core asks for |
| them. |
| |
| Unwinder Input |
| -------------- |
| |
| An object passed to an unwinder (a 'gdb.PendingFrame' instance) provides |
| a method to read frame's registers: |
| |
| -- Function: PendingFrame.read_register (reg) |
| This method returns the contents of the register REGN in the frame |
| as a 'gdb.Value' object. REG can be either a register number or a |
| register name; the values are platform-specific. They are usually |
| found in the corresponding 'PLATFORM-tdep.h' file in the GDB source |
| tree. |
| |
| It also provides a factory method to create a 'gdb.UnwindInfo' |
| instance to be returned to GDB: |
| |
| -- Function: PendingFrame.create_unwind_info (frame_id) |
| Returns a new 'gdb.UnwindInfo' instance identified by given |
| FRAME_ID. The argument is used to build GDB's frame ID using one |
| of functions provided by GDB. FRAME_ID's attributes determine |
| which function will be used, as follows: |
| |
| 'sp, pc, special' |
| 'frame_id_build_special (FRAME_ID.sp, FRAME_ID.pc, |
| FRAME_ID.special)' |
| |
| 'sp, pc' |
| 'frame_id_build (FRAME_ID.sp, FRAME_ID.pc)' |
| |
| This is the most common case. |
| |
| 'sp' |
| 'frame_id_build_wild (FRAME_ID.sp)' |
| The attribute values should be 'gdb.Value' |
| |
| Unwinder Output: UnwindInfo |
| --------------------------- |
| |
| Use 'PendingFrame.create_unwind_info' method described above to create a |
| 'gdb.UnwindInfo' instance. Use the following method to specify caller |
| registers that have been saved in this frame: |
| |
| -- Function: gdb.UnwindInfo.add_saved_register (reg, value) |
| REG identifies the register. It can be a number or a name, just as |
| for the 'PendingFrame.read_register' method above. VALUE is a |
| register value (a 'gdb.Value' object). |
| |
| Unwinder Skeleton Code |
| ---------------------- |
| |
| GDB comes with the module containing the base 'Unwinder' class. Derive |
| your unwinder class from it and structure the code as follows: |
| |
| from gdb.unwinders import Unwinder |
| |
| class FrameId(object): |
| def __init__(self, sp, pc): |
| self.sp = sp |
| self.pc = pc |
| |
| |
| class MyUnwinder(Unwinder): |
| def __init__(....): |
| supe(MyUnwinder, self).__init___(<expects unwinder name argument>) |
| |
| def __call__(pending_frame): |
| if not <we recognize frame>: |
| return None |
| # Create UnwindInfo. Usually the frame is identified by the stack |
| # pointer and the program counter. |
| sp = pending_frame.read_register(<SP number>) |
| pc = pending_frame.read_register(<PC number>) |
| unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc)) |
| |
| # Find the values of the registers in the caller's frame and |
| # save them in the result: |
| unwind_info.add_saved_register(<register>, <value>) |
| .... |
| |
| # Return the result: |
| return unwind_info |
| |
| |
| Registering a Unwinder |
| ---------------------- |
| |
| An object file, a program space, and the GDB proper can have unwinders |
| registered with it. |
| |
| The 'gdb.unwinders' module provides the function to register a |
| unwinder: |
| |
| -- Function: gdb.unwinder.register_unwinder (locus, unwinder, |
| replace=False) |
| LOCUS is specifies an object file or a program space to which |
| UNWINDER is added. Passing 'None' or 'gdb' adds UNWINDER to the |
| GDB's global unwinder list. The newly added UNWINDER will be |
| called before any other unwinder from the same locus. Two |
| unwinders in the same locus cannot have the same name. An attempt |
| to add a unwinder with already existing name raises an exception |
| unless REPLACE is 'True', in which case the old unwinder is |
| deleted. |
| |
| Unwinder Precedence |
| ------------------- |
| |
| GDB first calls the unwinders from all the object files in no particular |
| order, then the unwinders from the current program space, and finally |
| the unwinders from GDB. |
| |
| |
| File: gdb.info, Node: Xmethods In Python, Next: Xmethod API, Prev: Unwinding Frames in Python, Up: Python API |
| |
| 23.2.2.13 Xmethods In Python |
| ............................ |
| |
| "Xmethods" are additional methods or replacements for existing methods |
| of a C++ class. This feature is useful for those cases where a method |
| defined in C++ source code could be inlined or optimized out by the |
| compiler, making it unavailable to GDB. For such cases, one can define |
| an xmethod to serve as a replacement for the method defined in the C++ |
| source code. GDB will then invoke the xmethod, instead of the C++ |
| method, to evaluate expressions. One can also use xmethods when |
| debugging with core files. Moreover, when debugging live programs, |
| invoking an xmethod need not involve running the inferior (which can |
| potentially perturb its state). Hence, even if the C++ method is |
| available, it is better to use its replacement xmethod if one is |
| defined. |
| |
| The xmethods feature in Python is available via the concepts of an |
| "xmethod matcher" and an "xmethod worker". To implement an xmethod, one |
| has to implement a matcher and a corresponding worker for it (more than |
| one worker can be implemented, each catering to a different overloaded |
| instance of the method). Internally, GDB invokes the 'match' method of |
| a matcher to match the class type and method name. On a match, the |
| 'match' method returns a list of matching _worker_ objects. Each worker |
| object typically corresponds to an overloaded instance of the xmethod. |
| They implement a 'get_arg_types' method which returns a sequence of |
| types corresponding to the arguments the xmethod requires. GDB uses |
| this sequence of types to perform overload resolution and picks a |
| winning xmethod worker. A winner is also selected from among the |
| methods GDB finds in the C++ source code. Next, the winning xmethod |
| worker and the winning C++ method are compared to select an overall |
| winner. In case of a tie between a xmethod worker and a C++ method, the |
| xmethod worker is selected as the winner. That is, if a winning xmethod |
| worker is found to be equivalent to the winning C++ method, then the |
| xmethod worker is treated as a replacement for the C++ method. GDB uses |
| the overall winner to invoke the method. If the winning xmethod worker |
| is the overall winner, then the corresponding xmethod is invoked via the |
| '__call__' method of the worker object. |
| |
| If one wants to implement an xmethod as a replacement for an existing |
| C++ method, then they have to implement an equivalent xmethod which has |
| exactly the same name and takes arguments of exactly the same type as |
| the C++ method. If the user wants to invoke the C++ method even though |
| a replacement xmethod is available for that method, then they can |
| disable the xmethod. |
| |
| *Note Xmethod API::, for API to implement xmethods in Python. *Note |
| Writing an Xmethod::, for implementing xmethods in Python. |
| |
| |
| File: gdb.info, Node: Xmethod API, Next: Writing an Xmethod, Prev: Xmethods In Python, Up: Python API |
| |
| 23.2.2.14 Xmethod API |
| ..................... |
| |
| The GDB Python API provides classes, interfaces and functions to |
| implement, register and manipulate xmethods. *Note Xmethods In |
| Python::. |
| |
| An xmethod matcher should be an instance of a class derived from |
| 'XMethodMatcher' defined in the module 'gdb.xmethod', or an object with |
| similar interface and attributes. An instance of 'XMethodMatcher' has |
| the following attributes: |
| |
| -- Variable: name |
| The name of the matcher. |
| |
| -- Variable: enabled |
| A boolean value indicating whether the matcher is enabled or |
| disabled. |
| |
| -- Variable: methods |
| A list of named methods managed by the matcher. Each object in the |
| list is an instance of the class 'XMethod' defined in the module |
| 'gdb.xmethod', or any object with the following attributes: |
| |
| 'name' |
| Name of the xmethod which should be unique for each xmethod |
| managed by the matcher. |
| |
| 'enabled' |
| A boolean value indicating whether the xmethod is enabled or |
| disabled. |
| |
| The class 'XMethod' is a convenience class with same attributes as |
| above along with the following constructor: |
| |
| -- Function: XMethod.__init__ (self, name) |
| Constructs an enabled xmethod with name NAME. |
| |
| The 'XMethodMatcher' class has the following methods: |
| |
| -- Function: XMethodMatcher.__init__ (self, name) |
| Constructs an enabled xmethod matcher with name NAME. The |
| 'methods' attribute is initialized to 'None'. |
| |
| -- Function: XMethodMatcher.match (self, class_type, method_name) |
| Derived classes should override this method. It should return a |
| xmethod worker object (or a sequence of xmethod worker objects) |
| matching the CLASS_TYPE and METHOD_NAME. CLASS_TYPE is a |
| 'gdb.Type' object, and METHOD_NAME is a string value. If the |
| matcher manages named methods as listed in its 'methods' attribute, |
| then only those worker objects whose corresponding entries in the |
| 'methods' list are enabled should be returned. |
| |
| An xmethod worker should be an instance of a class derived from |
| 'XMethodWorker' defined in the module 'gdb.xmethod', or support the |
| following interface: |
| |
| -- Function: XMethodWorker.get_arg_types (self) |
| This method returns a sequence of 'gdb.Type' objects corresponding |
| to the arguments that the xmethod takes. It can return an empty |
| sequence or 'None' if the xmethod does not take any arguments. If |
| the xmethod takes a single argument, then a single 'gdb.Type' |
| object corresponding to it can be returned. |
| |
| -- Function: XMethodWorker.get_result_type (self, *args) |
| This method returns a 'gdb.Type' object representing the type of |
| the result of invoking this xmethod. The ARGS argument is the same |
| tuple of arguments that would be passed to the '__call__' method of |
| this worker. |
| |
| -- Function: XMethodWorker.__call__ (self, *args) |
| This is the method which does the _work_ of the xmethod. The ARGS |
| arguments is the tuple of arguments to the xmethod. Each element |
| in this tuple is a gdb.Value object. The first element is always |
| the 'this' pointer value. |
| |
| For GDB to lookup xmethods, the xmethod matchers should be registered |
| using the following function defined in the module 'gdb.xmethod': |
| |
| -- Function: register_xmethod_matcher (locus, matcher, replace=False) |
| The 'matcher' is registered with 'locus', replacing an existing |
| matcher with the same name as 'matcher' if 'replace' is 'True'. |
| 'locus' can be a 'gdb.Objfile' object (*note Objfiles In Python::), |
| or a 'gdb.Progspace' object (*note Progspaces In Python::), or |
| 'None'. If it is 'None', then 'matcher' is registered globally. |
| |
| |
| File: gdb.info, Node: Writing an Xmethod, Next: Inferiors In Python, Prev: Xmethod API, Up: Python API |
| |
| 23.2.2.15 Writing an Xmethod |
| ............................ |
| |
| Implementing xmethods in Python will require implementing xmethod |
| matchers and xmethod workers (*note Xmethods In Python::). Consider the |
| following C++ class: |
| |
| class MyClass |
| { |
| public: |
| MyClass (int a) : a_(a) { } |
| |
| int geta (void) { return a_; } |
| int operator+ (int b); |
| |
| private: |
| int a_; |
| }; |
| |
| int |
| MyClass::operator+ (int b) |
| { |
| return a_ + b; |
| } |
| |
| Let us define two xmethods for the class 'MyClass', one replacing the |
| method 'geta', and another adding an overloaded flavor of 'operator+' |
| which takes a 'MyClass' argument (the C++ code above already has an |
| overloaded 'operator+' which takes an 'int' argument). The xmethod |
| matcher can be defined as follows: |
| |
| class MyClass_geta(gdb.xmethod.XMethod): |
| def __init__(self): |
| gdb.xmethod.XMethod.__init__(self, 'geta') |
| |
| def get_worker(self, method_name): |
| if method_name == 'geta': |
| return MyClassWorker_geta() |
| |
| |
| class MyClass_sum(gdb.xmethod.XMethod): |
| def __init__(self): |
| gdb.xmethod.XMethod.__init__(self, 'sum') |
| |
| def get_worker(self, method_name): |
| if method_name == 'operator+': |
| return MyClassWorker_plus() |
| |
| |
| class MyClassMatcher(gdb.xmethod.XMethodMatcher): |
| def __init__(self): |
| gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher') |
| # List of methods 'managed' by this matcher |
| self.methods = [MyClass_geta(), MyClass_sum()] |
| |
| def match(self, class_type, method_name): |
| if class_type.tag != 'MyClass': |
| return None |
| workers = [] |
| for method in self.methods: |
| if method.enabled: |
| worker = method.get_worker(method_name) |
| if worker: |
| workers.append(worker) |
| |
| return workers |
| |
| Notice that the 'match' method of 'MyClassMatcher' returns a worker |
| object of type 'MyClassWorker_geta' for the 'geta' method, and a worker |
| object of type 'MyClassWorker_plus' for the 'operator+' method. This is |
| done indirectly via helper classes derived from 'gdb.xmethod.XMethod'. |
| One does not need to use the 'methods' attribute in a matcher as it is |
| optional. However, if a matcher manages more than one xmethod, it is a |
| good practice to list the xmethods in the 'methods' attribute of the |
| matcher. This will then facilitate enabling and disabling individual |
| xmethods via the 'enable/disable' commands. Notice also that a worker |
| object is returned only if the corresponding entry in the 'methods' |
| attribute of the matcher is enabled. |
| |
| The implementation of the worker classes returned by the matcher |
| setup above is as follows: |
| |
| class MyClassWorker_geta(gdb.xmethod.XMethodWorker): |
| def get_arg_types(self): |
| return None |
| |
| def get_result_type(self, obj): |
| return gdb.lookup_type('int') |
| |
| def __call__(self, obj): |
| return obj['a_'] |
| |
| |
| class MyClassWorker_plus(gdb.xmethod.XMethodWorker): |
| def get_arg_types(self): |
| return gdb.lookup_type('MyClass') |
| |
| def get_result_type(self, obj): |
| return gdb.lookup_type('int') |
| |
| def __call__(self, obj, other): |
| return obj['a_'] + other['a_'] |
| |
| For GDB to actually lookup a xmethod, it has to be registered with |
| it. The matcher defined above is registered with GDB globally as |
| follows: |
| |
| gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher()) |
| |
| If an object 'obj' of type 'MyClass' is initialized in C++ code as |
| follows: |
| |
| MyClass obj(5); |
| |
| then, after loading the Python script defining the xmethod matchers and |
| workers into 'GDBN', invoking the method 'geta' or using the operator |
| '+' on 'obj' will invoke the xmethods defined above: |
| |
| (gdb) p obj.geta() |
| $1 = 5 |
| |
| (gdb) p obj + obj |
| $2 = 10 |
| |
| Consider another example with a C++ template class: |
| |
| template <class T> |
| class MyTemplate |
| { |
| public: |
| MyTemplate () : dsize_(10), data_ (new T [10]) { } |
| ~MyTemplate () { delete [] data_; } |
| |
| int footprint (void) |
| { |
| return sizeof (T) * dsize_ + sizeof (MyTemplate<T>); |
| } |
| |
| private: |
| int dsize_; |
| T *data_; |
| }; |
| |
| Let us implement an xmethod for the above class which serves as a |
| replacement for the 'footprint' method. The full code listing of the |
| xmethod workers and xmethod matchers is as follows: |
| |
| class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker): |
| def __init__(self, class_type): |
| self.class_type = class_type |
| |
| def get_arg_types(self): |
| return None |
| |
| def get_result_type(self): |
| return gdb.lookup_type('int') |
| |
| def __call__(self, obj): |
| return (self.class_type.sizeof + |
| obj['dsize_'] * |
| self.class_type.template_argument(0).sizeof) |
| |
| |
| class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher): |
| def __init__(self): |
| gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher') |
| |
| def match(self, class_type, method_name): |
| if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>', |
| class_type.tag) and |
| method_name == 'footprint'): |
| return MyTemplateWorker_footprint(class_type) |
| |
| Notice that, in this example, we have not used the 'methods' |
| attribute of the matcher as the matcher manages only one xmethod. The |
| user can enable/disable this xmethod by enabling/disabling the matcher |
| itself. |
| |
| |
| File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing an Xmethod, Up: Python API |
| |
| 23.2.2.16 Inferiors In Python |
| ............................. |
| |
| Programs which are being run under GDB are called inferiors (*note |
| Inferiors and Programs::). Python scripts can access information about |
| and manipulate inferiors controlled by GDB via objects of the |
| 'gdb.Inferior' class. |
| |
| The following inferior-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.inferiors () |
| Return a tuple containing all inferior objects. |
| |
| -- Function: gdb.selected_inferior () |
| Return an object representing the current inferior. |
| |
| A 'gdb.Inferior' object has the following attributes: |
| |
| -- Variable: Inferior.num |
| ID of inferior, as assigned by GDB. |
| |
| -- Variable: Inferior.pid |
| Process ID of the inferior, as assigned by the underlying operating |
| system. |
| |
| -- Variable: Inferior.was_attached |
| Boolean signaling whether the inferior was created using 'attach', |
| or started by GDB itself. |
| |
| A 'gdb.Inferior' object has the following methods: |
| |
| -- Function: Inferior.is_valid () |
| Returns 'True' if the 'gdb.Inferior' object is valid, 'False' if |
| not. A 'gdb.Inferior' object will become invalid if the inferior |
| no longer exists within GDB. All other 'gdb.Inferior' methods will |
| throw an exception if it is invalid at the time the method is |
| called. |
| |
| -- Function: 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. |
| |
| -- Function: Inferior.read_memory (address, length) |
| Read LENGTH addressable memory units from the inferior, starting at |
| ADDRESS. Returns a buffer object, which behaves much like an array |
| or a string. It can be modified and given to the |
| 'Inferior.write_memory' function. In 'Python' 3, the return value |
| is a 'memoryview' object. |
| |
| -- Function: Inferior.write_memory (address, buffer [, length]) |
| Write the contents of BUFFER to the inferior, starting at ADDRESS. |
| The BUFFER parameter must be a Python object which supports the |
| buffer protocol, i.e., a string, an array or the object returned |
| from 'Inferior.read_memory'. If given, LENGTH determines the |
| number of addressable memory units from BUFFER to be written. |
| |
| -- Function: Inferior.search_memory (address, length, pattern) |
| Search a region of the inferior memory starting at ADDRESS with the |
| given LENGTH using the search pattern supplied in PATTERN. The |
| PATTERN parameter must be a Python object which supports the buffer |
| protocol, i.e., a string, an array or the object returned from |
| 'gdb.read_memory'. Returns a Python 'Long' containing the address |
| where the pattern was found, or 'None' if the pattern could not be |
| found. |
| |
| |
| File: gdb.info, Node: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API |
| |
| 23.2.2.17 Events In Python |
| .......................... |
| |
| GDB provides a general event facility so that Python code can be |
| notified of various state changes, particularly changes that occur in |
| the inferior. |
| |
| An "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 "event registry". An event registry is an object in the |
| 'gdb.events' module which dispatches particular events. A registry |
| provides methods to register and unregister event handlers: |
| |
| -- Function: EventRegistry.connect (object) |
| Add the given callable OBJECT to the registry. This object will be |
| called when an event corresponding to this registry occurs. |
| |
| -- Function: EventRegistry.disconnect (object) |
| Remove the given OBJECT from the registry. Once removed, the |
| object will no longer receive notifications of events. |
| |
| Here is an example: |
| |
| def exit_handler (event): |
| print "event type: exit" |
| print "exit code: %d" % (event.exit_code) |
| |
| gdb.events.exited.connect (exit_handler) |
| |
| In the above example we connect our handler 'exit_handler' to the |
| registry 'events.exited'. Once connected, 'exit_handler' gets called |
| when the inferior exits. The argument "event" in this example is of |
| type 'gdb.ExitedEvent'. As you can see in the example the '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: |
| |
| 'events.cont' |
| Emits 'gdb.ThreadEvent'. |
| |
| Some events can be thread specific when GDB is running in non-stop |
| mode. When represented in Python, these events all extend |
| '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 |
| 'gdb.BreakpointEvent' and 'gdb.ContinueEvent'. |
| |
| -- Variable: 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 'None'. |
| |
| Emits 'gdb.ContinueEvent' which extends 'gdb.ThreadEvent'. |
| |
| This event indicates that the inferior has been continued after a |
| stop. For inherited attribute refer to 'gdb.ThreadEvent' above. |
| |
| 'events.exited' |
| Emits 'events.ExitedEvent' which indicates that the inferior has |
| exited. 'events.ExitedEvent' has two attributes: |
| -- Variable: 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, GDB detaches from the inferior.) If the exit |
| code is unavailable, the attribute does not exist. |
| -- Variable: ExitedEvent inferior |
| A reference to the inferior which triggered the 'exited' |
| event. |
| |
| 'events.stop' |
| Emits 'gdb.StopEvent' which extends 'gdb.ThreadEvent'. |
| |
| Indicates that the inferior has stopped. All events emitted by |
| this registry extend StopEvent. As a child of 'gdb.ThreadEvent', |
| 'gdb.StopEvent' will indicate the stopped thread when GDB is |
| running in non-stop mode. Refer to 'gdb.ThreadEvent' above for |
| more details. |
| |
| Emits 'gdb.SignalEvent' which extends 'gdb.StopEvent'. |
| |
| This event indicates that the inferior or one of its threads has |
| received as signal. 'gdb.SignalEvent' has the following |
| attributes: |
| |
| -- Variable: 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 'info signals' in the GDB command prompt. |
| |
| Also emits 'gdb.BreakpointEvent' which extends 'gdb.StopEvent'. |
| |
| 'gdb.BreakpointEvent' event indicates that one or more breakpoints |
| have been hit, and has the following attributes: |
| |
| -- Variable: BreakpointEvent.breakpoints |
| A sequence containing references to all the breakpoints (type |
| 'gdb.Breakpoint') that were hit. *Note Breakpoints In |
| Python::, for details of the 'gdb.Breakpoint' object. |
| -- Variable: 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 'gdb.BreakpointEvent.breakpoints' |
| attribute. |
| |
| 'events.new_objfile' |
| Emits 'gdb.NewObjFileEvent' which indicates that a new object file |
| has been loaded by GDB. 'gdb.NewObjFileEvent' has one attribute: |
| |
| -- Variable: NewObjFileEvent.new_objfile |
| A reference to the object file ('gdb.Objfile') which has been |
| loaded. *Note Objfiles In Python::, for details of the |
| 'gdb.Objfile' object. |
| |
| 'events.clear_objfiles' |
| Emits 'gdb.ClearObjFilesEvent' which indicates that the list of |
| object files for a program space has been reset. |
| 'gdb.ClearObjFilesEvent' has one attribute: |
| |
| -- Variable: ClearObjFilesEvent.progspace |
| A reference to the program space ('gdb.Progspace') whose |
| objfile list has been cleared. *Note Progspaces In Python::. |
| |
| 'events.inferior_call_pre' |
| Emits 'gdb.InferiorCallPreEvent' which indicates that a function in |
| the inferior is about to be called. |
| |
| -- Variable: InferiorCallPreEvent.ptid |
| The thread in which the call will be run. |
| |
| -- Variable: InferiorCallPreEvent.address |
| The location of the function to be called. |
| |
| 'events.inferior_call_post' |
| Emits 'gdb.InferiorCallPostEvent' which indicates that a function |
| in the inferior has returned. |
| |
| -- Variable: InferiorCallPostEvent.ptid |
| The thread in which the call was run. |
| |
| -- Variable: InferiorCallPostEvent.address |
| The location of the function that was called. |
| |
| 'events.memory_changed' |
| Emits 'gdb.MemoryChangedEvent' which indicates that the memory of |
| the inferior has been modified by the GDB user, for instance via a |
| command like 'set *addr = value'. The event has the following |
| attributes: |
| |
| -- Variable: MemoryChangedEvent.address |
| The start address of the changed region. |
| |
| -- Variable: MemoryChangedEvent.length |
| Length in bytes of the changed region. |
| |
| 'events.register_changed' |
| Emits 'gdb.RegisterChangedEvent' which indicates that a register in |
| the inferior has been modified by the GDB user. |
| |
| -- Variable: RegisterChangedEvent.frame |
| A gdb.Frame object representing the frame in which the |
| register was modified. |
| -- Variable: RegisterChangedEvent.regnum |
| Denotes which register was modified. |
| |
| |
| File: gdb.info, Node: Threads In Python, Next: Commands In Python, Prev: Events In Python, Up: Python API |
| |
| 23.2.2.18 Threads In Python |
| ........................... |
| |
| Python scripts can access information about, and manipulate inferior |
| threads controlled by GDB, via objects of the 'gdb.InferiorThread' |
| class. |
| |
| The following thread-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.selected_thread () |
| This function returns the thread object for the selected thread. |
| If there is no selected thread, this will return 'None'. |
| |
| A 'gdb.InferiorThread' object has the following attributes: |
| |
| -- Variable: InferiorThread.name |
| The name of the thread. If the user specified a name using 'thread |
| name', then this returns that name. Otherwise, if an OS-supplied |
| name is available, then it is returned. Otherwise, this returns |
| 'None'. |
| |
| This attribute can be assigned to. The new value must be a string |
| object, which sets the new name, or 'None', which removes any |
| user-specified thread name. |
| |
| -- Variable: InferiorThread.num |
| ID of the thread, as assigned by GDB. |
| |
| -- Variable: 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. |
| |
| A 'gdb.InferiorThread' object has the following methods: |
| |
| -- Function: InferiorThread.is_valid () |
| Returns 'True' if the 'gdb.InferiorThread' object is valid, 'False' |
| if not. A 'gdb.InferiorThread' object will become invalid if the |
| thread exits, or the inferior that the thread belongs is deleted. |
| All other 'gdb.InferiorThread' methods will throw an exception if |
| it is invalid at the time the method is called. |
| |
| -- Function: InferiorThread.switch () |
| This changes GDB's currently selected thread to the one represented |
| by this object. |
| |
| -- Function: InferiorThread.is_stopped () |
| Return a Boolean indicating whether the thread is stopped. |
| |
| -- Function: InferiorThread.is_running () |
| Return a Boolean indicating whether the thread is running. |
| |
| -- Function: InferiorThread.is_exited () |
| Return a Boolean indicating whether the thread is exited. |
| |
| |
| File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Threads In Python, Up: Python API |
| |
| 23.2.2.19 Commands In Python |
| ............................ |
| |
| You can implement new GDB CLI commands in Python. A CLI command is |
| implemented using an instance of the 'gdb.Command' class, most commonly |
| using a subclass. |
| |
| -- Function: Command.__init__ (name, COMMAND_CLASS [, COMPLETER_CLASS |
| [, PREFIX]]) |
| The object initializer for 'Command' registers the new command with |
| GDB. This initializer is normally invoked from the subclass' own |
| '__init__' method. |
| |
| NAME is the name of the command. If 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. |
| |
| COMMAND_CLASS should be one of the 'COMMAND_' constants defined |
| below. This argument tells GDB how to categorize the new command |
| in the help system. |
| |
| COMPLETER_CLASS is an optional argument. If given, it should be |
| one of the 'COMPLETE_' constants defined below. This argument |
| tells GDB how to perform completion for this command. If not |
| given, GDB will attempt to complete using the object's 'complete' |
| method (see below); if no such method is found, an error will occur |
| when completion is attempted. |
| |
| PREFIX is an optional argument. If '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. |
| |
| -- Function: Command.dont_repeat () |
| By default, a GDB command is repeated when the user enters a blank |
| line at the command prompt. A command can suppress this behavior |
| by invoking the 'dont_repeat' method. This is similar to the user |
| command 'dont-repeat', see *note dont-repeat: Define. |
| |
| -- Function: Command.invoke (argument, from_tty) |
| This method is called by GDB when this command is invoked. |
| |
| ARGUMENT is a string. It is the argument to the command, after |
| leading and trailing whitespace has been stripped. |
| |
| 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 GDB 'error' |
| call. Otherwise, the return value is ignored. |
| |
| To break ARGUMENT up into an argv-like string use |
| 'gdb.string_to_argv'. This function behaves identically to GDB's |
| internal argument lexer 'buildargv'. It is recommended to use this |
| for consistency. Arguments are separated by spaces and may be |
| quoted. Example: |
| |
| print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") |
| ['1', '2 "3', '4 "5', "6 '7"] |
| |
| -- Function: Command.complete (text, word) |
| This method is called by GDB when the user attempts completion on |
| this command. All forms of completion are handled by this method, |
| that is, the <TAB> and <M-?> key bindings (*note Completion::), and |
| the 'complete' command (*note complete: Help.). |
| |
| The arguments TEXT and WORD are both strings; TEXT holds the |
| complete command line up to the cursor's location, while WORD holds |
| the last word of the command line; this is computed using a |
| word-breaking heuristic. |
| |
| The 'complete' method can return several values: |
| * If the return value is a sequence, the contents of the |
| sequence are used as the completions. It is up to '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. |
| |
| * If the return value is one of the 'COMPLETE_' constants |
| defined below, then the corresponding GDB-internal completion |
| function is invoked, and its result is used. |
| |
| * All other results are treated as though there were no |
| available completions. |
| |
| 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 'gdb' module: |
| |
| '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. |
| |
| 'gdb.COMMAND_RUNNING' |
| The command is related to running the inferior. For example, |
| 'start', 'step', and 'continue' are in this category. Type 'help |
| running' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'gdb.COMMAND_DATA' |
| The command is related to data or variables. For example, 'call', |
| 'find', and 'print' are in this category. Type 'help data' at the |
| GDB prompt to see a list of commands in this category. |
| |
| 'gdb.COMMAND_STACK' |
| The command has to do with manipulation of the stack. For example, |
| 'backtrace', 'frame', and 'return' are in this category. Type |
| 'help stack' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'gdb.COMMAND_FILES' |
| This class is used for file-related commands. For example, 'file', |
| 'list' and 'section' are in this category. Type 'help files' at |
| the GDB prompt to see a list of commands in this category. |
| |
| 'gdb.COMMAND_SUPPORT' |
| This should be used for "support facilities", generally meaning |
| things that are useful to the user when interacting with GDB, but |
| not related to the state of the inferior. For example, 'help', |
| 'make', and 'shell' are in this category. Type 'help support' at |
| the GDB prompt to see a list of commands in this category. |
| |
| 'gdb.COMMAND_STATUS' |
| The command is an 'info'-related command, that is, related to the |
| state of GDB itself. For example, 'info', 'macro', and 'show' are |
| in this category. Type 'help status' at the GDB prompt to see a |
| list of commands in this category. |
| |
| 'gdb.COMMAND_BREAKPOINTS' |
| The command has to do with breakpoints. For example, 'break', |
| 'clear', and 'delete' are in this category. Type 'help |
| breakpoints' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'gdb.COMMAND_TRACEPOINTS' |
| The command has to do with tracepoints. For example, 'trace', |
| 'actions', and 'tfind' are in this category. Type 'help |
| tracepoints' at the GDB prompt to see a list of commands in this |
| category. |
| |
| '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 'help |
| user-defined' at the GDB prompt to see a list of commands in this |
| category, as well as the list of gdb macros (*note Sequences::). |
| |
| 'gdb.COMMAND_OBSCURE' |
| The command is only used in unusual circumstances, or is not of |
| general interest to users. For example, 'checkpoint', 'fork', and |
| 'stop' are in this category. Type 'help obscure' at the GDB prompt |
| to see a list of commands in this category. |
| |
| 'gdb.COMMAND_MAINTENANCE' |
| The command is only useful to GDB maintainers. The 'maintenance' |
| and 'flushregs' commands are in this category. Type 'help |
| internals' at the GDB prompt to see a list of commands in this |
| category. |
| |
| A new command can use a predefined completion function, either by |
| specifying it via an argument at initialization, or by returning it from |
| the 'complete' method. These predefined completion constants are all |
| defined in the 'gdb' module: |
| |
| 'gdb.COMPLETE_NONE' |
| This constant means that no completion should be done. |
| |
| 'gdb.COMPLETE_FILENAME' |
| This constant means that filename completion should be performed. |
| |
| 'gdb.COMPLETE_LOCATION' |
| This constant means that location completion should be done. *Note |
| Specify Location::. |
| |
| 'gdb.COMPLETE_COMMAND' |
| This constant means that completion should examine GDB command |
| names. |
| |
| 'gdb.COMPLETE_SYMBOL' |
| This constant means that completion should be done using symbol |
| names as the source. |
| |
| '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. |
| |
| The following code snippet shows how a trivial CLI command can be |
| implemented in Python: |
| |
| 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 () |
| |
| The last line instantiates the class, and is necessary to trigger the |
| registration of the command with GDB. Depending on how the Python code |
| is read into GDB, you may need to import the 'gdb' module explicitly. |
| |
| |
| File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: Commands In Python, Up: Python API |
| |
| 23.2.2.20 Parameters In Python |
| .............................. |
| |
| You can implement new GDB parameters using Python. A new parameter is |
| implemented as an instance of the 'gdb.Parameter' class. |
| |
| Parameters are exposed to the user via the 'set' and 'show' commands. |
| *Note Help::. |
| |
| There are many parameters that already exist and can be set in GDB. |
| Two examples are: 'set follow fork' and 'set charset'. Setting these |
| parameters influences certain behavior in GDB. Similarly, you can |
| define parameters that can be used to influence behavior in custom |
| Python scripts and commands. |
| |
| -- Function: Parameter.__init__ (name, COMMAND-CLASS, PARAMETER-CLASS |
| [, ENUM-SEQUENCE]) |
| The object initializer for 'Parameter' registers the new parameter |
| with GDB. This initializer is normally invoked from the subclass' |
| own '__init__' method. |
| |
| NAME is the name of the new parameter. If NAME consists of |
| multiple words, then the initial words are looked for as prefix |
| parameters. An example of this can be illustrated with the 'set |
| print' set of parameters. If NAME is 'print foo', then 'print' |
| will be searched as the prefix parameter. In this case the |
| parameter can subsequently be accessed in GDB as 'set print foo'. |
| |
| If NAME consists of multiple words, and no prefix parameter group |
| can be found, an exception is raised. |
| |
| COMMAND-CLASS should be one of the 'COMMAND_' constants (*note |
| Commands In Python::). This argument tells GDB how to categorize |
| the new parameter in the help system. |
| |
| PARAMETER-CLASS should be one of the 'PARAM_' constants defined |
| below. This argument tells GDB the type of the new parameter; this |
| information is used for input validation and completion. |
| |
| If PARAMETER-CLASS is 'PARAM_ENUM', then ENUM-SEQUENCE must be a |
| sequence of strings. These strings represent the possible values |
| for the parameter. |
| |
| If PARAMETER-CLASS is not '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. |
| |
| -- Variable: Parameter.set_doc |
| If this attribute exists, and is a string, then its value is used |
| as the help text for this parameter's 'set' command. The value is |
| examined when 'Parameter.__init__' is invoked; subsequent changes |
| have no effect. |
| |
| -- Variable: Parameter.show_doc |
| If this attribute exists, and is a string, then its value is used |
| as the help text for this parameter's 'show' command. The value is |
| examined when 'Parameter.__init__' is invoked; subsequent changes |
| have no effect. |
| |
| -- Variable: Parameter.value |
| The 'value' attribute holds the underlying value of the parameter. |
| It can be read and assigned to just as any other attribute. GDB |
| does validation when assignments are made. |
| |
| There are two methods that should be implemented in any 'Parameter' |
| class. These are: |
| |
| -- Function: Parameter.get_set_string (self) |
| GDB will call this method when a PARAMETER's value has been changed |
| via the 'set' API (for example, 'set foo off'). The 'value' |
| attribute has already been populated with the new value and may be |
| used in output. This method must return a string. |
| |
| -- Function: Parameter.get_show_string (self, svalue) |
| GDB will call this method when a PARAMETER's 'show' API has been |
| invoked (for example, 'show foo'). The argument 'svalue' receives |
| the string representation of the current value. This method must |
| return a string. |
| |
| When a new parameter is defined, its type must be specified. The |
| available types are represented by constants defined in the 'gdb' |
| module: |
| |
| 'gdb.PARAM_BOOLEAN' |
| The value is a plain boolean. The Python boolean values, 'True' |
| and 'False' are the only valid values. |
| |
| 'gdb.PARAM_AUTO_BOOLEAN' |
| The value has three possible states: true, false, and 'auto'. In |
| Python, true and false are represented using boolean constants, and |
| 'auto' is represented using 'None'. |
| |
| 'gdb.PARAM_UINTEGER' |
| The value is an unsigned integer. The value of 0 should be |
| interpreted to mean "unlimited". |
| |
| 'gdb.PARAM_INTEGER' |
| The value is a signed integer. The value of 0 should be |
| interpreted to mean "unlimited". |
| |
| 'gdb.PARAM_STRING' |
| The value is a string. When the user modifies the string, any |
| escape sequences, such as '\t', '\f', and octal escapes, are |
| translated into corresponding characters and encoded into the |
| current host charset. |
| |
| 'gdb.PARAM_STRING_NOESCAPE' |
| The value is a string. When the user modifies the string, escapes |
| are passed through untranslated. |
| |
| 'gdb.PARAM_OPTIONAL_FILENAME' |
| The value is a either a filename (a string), or 'None'. |
| |
| 'gdb.PARAM_FILENAME' |
| The value is a filename. This is just like |
| 'PARAM_STRING_NOESCAPE', but uses file names for completion. |
| |
| 'gdb.PARAM_ZINTEGER' |
| The value is an integer. This is like 'PARAM_INTEGER', except 0 is |
| interpreted as itself. |
| |
| 'gdb.PARAM_ENUM' |
| The value is a string, which must be one of a collection string |
| constants provided when the parameter is created. |
| |
| |
| File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API |
| |
| 23.2.2.21 Writing new convenience functions |
| ........................................... |
| |
| You can implement new convenience functions (*note Convenience Vars::) |
| in Python. A convenience function is an instance of a subclass of the |
| class 'gdb.Function'. |
| |
| -- Function: Function.__init__ (name) |
| The initializer for 'Function' registers the new function with GDB. |
| The argument NAME is the name of the function, a string. The |
| function will be visible to the user as a convenience variable of |
| type 'internal function', whose name is the same as the given NAME. |
| |
| The documentation for the new function is taken from the |
| documentation string for the new class. |
| |
| -- Function: Function.invoke (*ARGS) |
| When a convenience function is evaluated, its arguments are |
| converted to instances of 'gdb.Value', and then the function's |
| 'invoke' method is called. Note that GDB does not predetermine the |
| arity of convenience functions. Instead, all available arguments |
| are passed to '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 'gdb.Value' following the usual rules. |
| |
| The following code snippet shows how a trivial convenience function |
| can be implemented in Python: |
| |
| 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 () |
| |
| The last line instantiates the class, and is necessary to trigger the |
| registration of the function with GDB. Depending on how the Python code |
| is read into GDB, you may need to import the 'gdb' module explicitly. |
| |
| Now you can use the function in an expression: |
| |
| (gdb) print $greet("Bob") |
| $1 = "Hello, Bob!" |
| |
| |
| File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API |
| |
| 23.2.2.22 Program Spaces In Python |
| .................................. |
| |
| A program space, or "progspace", represents a symbolic view of an |
| address space. It consists of all of the objfiles of the program. |
| *Note Objfiles In Python::. *Note program spaces: Inferiors and |
| Programs, for more details about program spaces. |
| |
| The following progspace-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.current_progspace () |
| This function returns the program space of the currently selected |
| inferior. *Note Inferiors and Programs::. |
| |
| -- Function: gdb.progspaces () |
| Return a sequence of all the progspaces currently known to GDB. |
| |
| Each progspace is represented by an instance of the 'gdb.Progspace' |
| class. |
| |
| -- Variable: Progspace.filename |
| The file name of the progspace as a string. |
| |
| -- Variable: Progspace.pretty_printers |
| The 'pretty_printers' attribute is a list of functions. It is used |
| to look up pretty-printers. A 'Value' is passed to each function |
| in order; if the function returns 'None', then the search |
| continues. Otherwise, the return value should be an object which |
| is used to format the value. *Note Pretty Printing API::, for more |
| information. |
| |
| -- Variable: Progspace.type_printers |
| The 'type_printers' attribute is a list of type printer objects. |
| *Note Type Printing API::, for more information. |
| |
| -- Variable: Progspace.frame_filters |
| The 'frame_filters' attribute is a dictionary of frame filter |
| objects. *Note Frame Filter API::, for more information. |
| |
| One may add arbitrary attributes to 'gdb.Progspace' objects in the |
| usual Python way. This is useful if, for example, one needs to do some |
| extra record keeping associated with the program space. |
| |
| In this contrived example, we want to perform some processing when an |
| objfile with a certain symbol is loaded, but we only want to do this |
| once because it is expensive. To achieve this we record the results |
| with the program space because we can't predict when the desired objfile |
| will be loaded. |
| |
| (gdb) python |
| def clear_objfiles_handler(event): |
| event.progspace.expensive_computation = None |
| def expensive(symbol): |
| """A mock routine to perform an "expensive" computation on symbol.""" |
| print "Computing the answer to the ultimate question ..." |
| return 42 |
| def new_objfile_handler(event): |
| objfile = event.new_objfile |
| progspace = objfile.progspace |
| if not hasattr(progspace, 'expensive_computation') or \ |
| progspace.expensive_computation is None: |
| # We use 'main' for the symbol to keep the example simple. |
| # Note: There's no current way to constrain the lookup |
| # to one objfile. |
| symbol = gdb.lookup_global_symbol('main') |
| if symbol is not None: |
| progspace.expensive_computation = expensive(symbol) |
| gdb.events.clear_objfiles.connect(clear_objfiles_handler) |
| gdb.events.new_objfile.connect(new_objfile_handler) |
| end |
| (gdb) file /tmp/hello |
| Reading symbols from /tmp/hello...done. |
| Computing the answer to the ultimate question ... |
| (gdb) python print gdb.current_progspace().expensive_computation |
| 42 |
| (gdb) run |
| Starting program: /tmp/hello |
| Hello. |
| [Inferior 1 (process 4242) exited normally] |
| |
| |
| File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API |
| |
| 23.2.2.23 Objfiles In Python |
| ............................ |
| |
| GDB loads symbols for an inferior from various symbol-containing files |
| (*note Files::). These include the primary executable file, any shared |
| libraries used by the inferior, and any separate debug info files (*note |
| Separate Debug Files::). GDB calls these symbol-containing files |
| "objfiles". |
| |
| The following objfile-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.current_objfile () |
| When auto-loading a Python script (*note Python Auto-loading::), |
| GDB sets the "current objfile" to the corresponding objfile. This |
| function returns the current objfile. If there is no current |
| objfile, this function returns 'None'. |
| |
| -- Function: gdb.objfiles () |
| Return a sequence of all the objfiles current known to GDB. *Note |
| Objfiles In Python::. |
| |
| -- Function: gdb.lookup_objfile (name [, by_build_id]) |
| Look up NAME, a file name or build ID, in the list of objfiles for |
| the current program space (*note Progspaces In Python::). If the |
| objfile is not found throw the Python 'ValueError' exception. |
| |
| If NAME is a relative file name, then it will match any source file |
| name with the same trailing components. For example, if NAME is |
| 'gcc/expr.c', then it will match source file name of |
| '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or |
| '/build/trunk/gcc/x-expr.c'. |
| |
| If BY_BUILD_ID is provided and is 'True' then NAME is the build ID |
| of the objfile. Otherwise, NAME is a file name. This is supported |
| only on some operating systems, notably those which use the ELF |
| format for binary files and the GNU Binutils. For more details |
| about this feature, see the description of the '--build-id' |
| command-line option in *note Command Line Options: |
| (ld.info)Options. |
| |
| Each objfile is represented by an instance of the 'gdb.Objfile' |
| class. |
| |
| -- Variable: Objfile.filename |
| The file name of the objfile as a string, with symbolic links |
| resolved. |
| |
| The value is 'None' if the objfile is no longer valid. See the |
| 'gdb.Objfile.is_valid' method, described below. |
| |
| -- Variable: Objfile.username |
| The file name of the objfile as specified by the user as a string. |
| |
| The value is 'None' if the objfile is no longer valid. See the |
| 'gdb.Objfile.is_valid' method, described below. |
| |
| -- Variable: Objfile.owner |
| For separate debug info objfiles this is the corresponding |
| 'gdb.Objfile' object that debug info is being provided for. |
| Otherwise this is 'None'. Separate debug info objfiles are added |
| with the 'gdb.Objfile.add_separate_debug_file' method, described |
| below. |
| |
| -- Variable: Objfile.build_id |
| The build ID of the objfile as a string. If the objfile does not |
| have a build ID then the value is 'None'. |
| |
| This is supported only on some operating systems, notably those |
| which use the ELF format for binary files and the GNU Binutils. |
| For more details about this feature, see the description of the |
| '--build-id' command-line option in *note Command Line Options: |
| (ld.info)Options. |
| |
| -- Variable: Objfile.progspace |
| The containing program space of the objfile as a 'gdb.Progspace' |
| object. *Note Progspaces In Python::. |
| |
| -- Variable: Objfile.pretty_printers |
| The 'pretty_printers' attribute is a list of functions. It is used |
| to look up pretty-printers. A 'Value' is passed to each function |
| in order; if the function returns 'None', then the search |
| continues. Otherwise, the return value should be an object which |
| is used to format the value. *Note Pretty Printing API::, for more |
| information. |
| |
| -- Variable: Objfile.type_printers |
| The 'type_printers' attribute is a list of type printer objects. |
| *Note Type Printing API::, for more information. |
| |
| -- Variable: Objfile.frame_filters |
| The 'frame_filters' attribute is a dictionary of frame filter |
| objects. *Note Frame Filter API::, for more information. |
| |
| One may add arbitrary attributes to 'gdb.Objfile' objects in the |
| usual Python way. This is useful if, for example, one needs to do some |
| extra record keeping associated with the objfile. |
| |
| In this contrived example we record the time when GDB loaded the |
| objfile. |
| |
| (gdb) python |
| import datetime |
| def new_objfile_handler(event): |
| # Set the time_loaded attribute of the new objfile. |
| event.new_objfile.time_loaded = datetime.datetime.today() |
| gdb.events.new_objfile.connect(new_objfile_handler) |
| end |
| (gdb) file ./hello |
| Reading symbols from ./hello...done. |
| (gdb) python print gdb.objfiles()[0].time_loaded |
| 2014-10-09 11:41:36.770345 |
| |
| A 'gdb.Objfile' object has the following methods: |
| |
| -- Function: Objfile.is_valid () |
| Returns 'True' if the 'gdb.Objfile' object is valid, 'False' if |
| not. A 'gdb.Objfile' object can become invalid if the object file |
| it refers to is not loaded in GDB any longer. All other |
| 'gdb.Objfile' methods will throw an exception if it is invalid at |
| the time the method is called. |
| |
| -- Function: Objfile.add_separate_debug_file (file) |
| Add FILE to the list of files that GDB will search for debug |
| information for the objfile. This is useful when the debug info |
| has been removed from the program and stored in a separate file. |
| GDB has built-in support for finding separate debug info files |
| (*note Separate Debug Files::), but if the file doesn't live in one |
| of the standard places that GDB searches then this function can be |
| used to add a debug info file from a different place. |
| |
| |
| File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API |
| |
| 23.2.2.24 Accessing inferior stack frames from Python. |
| ...................................................... |
| |
| When the debugged program stops, GDB is able to analyze its call stack |
| (*note Stack frames: Frames.). The 'gdb.Frame' class represents a frame |
| in the stack. A '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, GDB will throw a 'gdb.error' exception (*note |
| Exception Handling::). |
| |
| Two 'gdb.Frame' objects can be compared for equality with the '==' |
| operator, like: |
| |
| (gdb) python print gdb.newest_frame() == gdb.selected_frame () |
| True |
| |
| The following frame-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.selected_frame () |
| Return the selected frame object. (*note Selecting a Frame: |
| Selection.). |
| |
| -- Function: gdb.newest_frame () |
| Return the newest frame object for the selected thread. |
| |
| -- Function: gdb.frame_stop_reason_string (reason) |
| Return a string explaining the reason why GDB stopped unwinding |
| frames, as expressed by the given REASON code (an integer, see the |
| 'unwind_stop_reason' method further down in this section). |
| |
| A 'gdb.Frame' object has the following methods: |
| |
| -- Function: Frame.is_valid () |
| Returns true if the '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 'gdb.Frame' methods will throw |
| an exception if it is invalid at the time the method is called. |
| |
| -- Function: Frame.name () |
| Returns the function name of the frame, or 'None' if it can't be |
| obtained. |
| |
| -- Function: Frame.architecture () |
| Returns the 'gdb.Architecture' object corresponding to the frame's |
| architecture. *Note Architectures In Python::. |
| |
| -- Function: Frame.type () |
| Returns the type of the frame. The value can be one of: |
| 'gdb.NORMAL_FRAME' |
| An ordinary stack frame. |
| |
| 'gdb.DUMMY_FRAME' |
| A fake stack frame that was created by GDB when performing an |
| inferior function call. |
| |
| 'gdb.INLINE_FRAME' |
| A frame representing an inlined function. The function was |
| inlined into a 'gdb.NORMAL_FRAME' that is older than this one. |
| |
| 'gdb.TAILCALL_FRAME' |
| A frame representing a tail call. *Note Tail Call Frames::. |
| |
| 'gdb.SIGTRAMP_FRAME' |
| A signal trampoline frame. This is the frame created by the |
| OS when it calls into a signal handler. |
| |
| 'gdb.ARCH_FRAME' |
| A fake stack frame representing a cross-architecture call. |
| |
| 'gdb.SENTINEL_FRAME' |
| This is like 'gdb.NORMAL_FRAME', but it is only used for the |
| newest frame. |
| |
| -- Function: Frame.unwind_stop_reason () |
| Return an integer representing the reason why it's not possible to |
| find more frames toward the outermost frame. Use |
| 'gdb.frame_stop_reason_string' to convert the value returned by |
| this function to a string. The value can be one of: |
| |
| 'gdb.FRAME_UNWIND_NO_REASON' |
| No particular reason (older frames should be available). |
| |
| 'gdb.FRAME_UNWIND_NULL_ID' |
| The previous frame's analyzer returns an invalid result. This |
| is no longer used by GDB, and is kept only for backward |
| compatibility. |
| |
| 'gdb.FRAME_UNWIND_OUTERMOST' |
| This frame is the outermost. |
| |
| 'gdb.FRAME_UNWIND_UNAVAILABLE' |
| Cannot unwind further, because that would require knowing the |
| values of registers or memory that have not been collected. |
| |
| '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. |
| |
| '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. |
| |
| 'gdb.FRAME_UNWIND_NO_SAVED_PC' |
| The frame unwinder did not find any saved PC, but we needed |
| one to unwind further. |
| |
| 'gdb.FRAME_UNWIND_MEMORY_ERROR' |
| The frame unwinder caused an error while trying to access |
| memory. |
| |
| '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 GDB versions. Using it, you could write: |
| 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 |
| |
| -- Function: Frame.pc () |
| Returns the frame's resume address. |
| |
| -- Function: Frame.block () |
| Return the frame's code block. *Note Blocks In Python::. |
| |
| -- Function: Frame.function () |
| Return the symbol for the function corresponding to this frame. |
| *Note Symbols In Python::. |
| |
| -- Function: Frame.older () |
| Return the frame that called this frame. |
| |
| -- Function: Frame.newer () |
| Return the frame called by this frame. |
| |
| -- Function: Frame.find_sal () |
| Return the frame's symtab and line object. *Note Symbol Tables In |
| Python::. |
| |
| -- Function: Frame.read_register (register) |
| Return the value of REGISTER in this frame. The REGISTER argument |
| must be a string (e.g., ''sp'' or ''rax''). Returns a 'Gdb.Value' |
| object. Throws an exception if REGISTER does not exist. |
| |
| -- Function: Frame.read_var (variable [, block]) |
| Return the value of VARIABLE in this frame. If the optional |
| argument 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). The VARIABLE |
| argument must be a string or a 'gdb.Symbol' object; BLOCK must be a |
| 'gdb.Block' object. |
| |
| -- Function: Frame.select () |
| Set this frame to be the selected frame. *Note Examining the |
| Stack: Stack. |
| |
| |
| File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API |
| |
| 23.2.2.25 Accessing blocks from Python. |
| ....................................... |
| |
| In GDB, 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 'gdb.Block'. Blocks rely on |
| debugging information being available. |
| |
| A frame has a block. Please see *note Frames In Python::, for a more |
| in-depth discussion of frames. |
| |
| The outermost block is known as the "global block". The global block |
| typically holds public global variables and functions. |
| |
| The block nested just inside the global block is the "static block". |
| The static block typically holds file-scoped variables and functions. |
| |
| GDB 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 (*note Symbol Tables In Python::). |
| |
| Here is a short example that should help explain blocks: |
| |
| /* 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 (); |
| } |
| } |
| |
| A 'gdb.Block' is iterable. The iterator returns the symbols (*note |
| 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 GDB features and infrastructure may cause symbols move |
| across blocks in a symbol table. |
| |
| The following block-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.block_for_pc (pc) |
| Return the innermost 'gdb.Block' containing the given PC value. If |
| the block cannot be found for the PC value specified, the function |
| will return 'None'. |
| |
| A 'gdb.Block' object has the following methods: |
| |
| -- Function: Block.is_valid () |
| Returns 'True' if the 'gdb.Block' object is valid, 'False' if not. |
| A block object can become invalid if the block it refers to doesn't |
| exist anymore in the inferior. All other '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. |
| |
| A 'gdb.Block' object has the following attributes: |
| |
| -- Variable: Block.start |
| The start address of the block. This attribute is not writable. |
| |
| -- Variable: Block.end |
| The end address of the block. This attribute is not writable. |
| |
| -- Variable: Block.function |
| The name of the block represented as a 'gdb.Symbol'. If the block |
| is not named, then this attribute holds '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. |
| |
| -- Variable: Block.superblock |
| The block containing this block. If this parent block does not |
| exist, this attribute holds 'None'. This attribute is not |
| writable. |
| |
| -- Variable: Block.global_block |
| The global block associated with this block. This attribute is not |
| writable. |
| |
| -- Variable: Block.static_block |
| The static block associated with this block. This attribute is not |
| writable. |
| |
| -- Variable: Block.is_global |
| 'True' if the 'gdb.Block' object is a global block, 'False' if not. |
| This attribute is not writable. |
| |
| -- Variable: Block.is_static |
| 'True' if the 'gdb.Block' object is a static block, 'False' if not. |
| This attribute is not writable. |
| |
| |
| File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API |
| |
| 23.2.2.26 Python representation of Symbols. |
| ........................................... |
| |
| GDB represents every variable, function and type as an entry in a symbol |
| table. *Note Examining the Symbol Table: Symbols. Similarly, Python |
| represents these symbols in GDB with the 'gdb.Symbol' object. |
| |
| The following symbol-related functions are available in the 'gdb' |
| module: |
| |
| -- Function: gdb.lookup_symbol (name [, block [, domain]]) |
| 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. |
| |
| NAME is the name of the symbol. It must be a string. The optional |
| BLOCK argument restricts the search to symbols visible in that |
| BLOCK. The BLOCK argument must be a 'gdb.Block' object. If |
| omitted, the block for the current frame is used. The optional |
| DOMAIN argument restricts the search to the domain type. The |
| DOMAIN argument must be a domain constant defined in the 'gdb' |
| module and described later in this chapter. |
| |
| The result is a tuple of two elements. The first element is a |
| 'gdb.Symbol' object or 'None' if the symbol is not found. If the |
| symbol is found, the second element is 'True' if the symbol is a |
| field of a method's object (e.g., 'this' in C++), otherwise it is |
| 'False'. If the symbol is not found, the second element is |
| 'False'. |
| |
| -- Function: gdb.lookup_global_symbol (name [, domain]) |
| This function searches for a global symbol by name. The search |
| scope can be restricted to by the domain argument. |
| |
| NAME is the name of the symbol. It must be a string. The optional |
| DOMAIN argument restricts the search to the domain type. The |
| DOMAIN argument must be a domain constant defined in the 'gdb' |
| module and described later in this chapter. |
| |
| The result is a 'gdb.Symbol' object or 'None' if the symbol is not |
| found. |
| |
| A 'gdb.Symbol' object has the following attributes: |
| |
| -- Variable: Symbol.type |
| The type of the symbol or 'None' if no type is recorded. This |
| attribute is represented as a 'gdb.Type' object. *Note Types In |
| Python::. This attribute is not writable. |
| |
| -- Variable: Symbol.symtab |
| The symbol table in which the symbol appears. This attribute is |
| represented as a 'gdb.Symtab' object. *Note Symbol Tables In |
| Python::. This attribute is not writable. |
| |
| -- Variable: Symbol.line |
| The line number in the source code at which the symbol was defined. |
| This is an integer. |
| |
| -- Variable: Symbol.name |
| The name of the symbol as a string. This attribute is not |
| writable. |
| |
| -- Variable: Symbol.linkage_name |
| The name of the symbol, as used by the linker (i.e., may be |
| mangled). This attribute is not writable. |
| |
| -- Variable: Symbol.print_name |
| The name of the symbol in a form suitable for output. This is |
| either 'name' or 'linkage_name', depending on whether the user |
| asked GDB to display demangled or mangled names. |
| |
| -- Variable: 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 |
| 'gdb' module and described later in this chapter. |
| |
| -- Variable: Symbol.needs_frame |
| This is 'True' if evaluating this symbol's value requires a frame |
| (*note Frames In Python::) and 'False' otherwise. Typically, local |
| variables will require a frame, but other symbols will not. |
| |
| -- Variable: Symbol.is_argument |
| 'True' if the symbol is an argument of a function. |
| |
| -- Variable: Symbol.is_constant |
| 'True' if the symbol is a constant. |
| |
| -- Variable: Symbol.is_function |
| 'True' if the symbol is a function or a method. |
| |
| -- Variable: Symbol.is_variable |
| 'True' if the symbol is a variable. |
| |
| A 'gdb.Symbol' object has the following methods: |
| |
| -- Function: Symbol.is_valid () |
| Returns 'True' if the 'gdb.Symbol' object is valid, 'False' if not. |
| A 'gdb.Symbol' object can become invalid if the symbol it refers to |
| does not exist in GDB any longer. All other 'gdb.Symbol' methods |
| will throw an exception if it is invalid at the time the method is |
| called. |
| |
| -- Function: Symbol.value ([frame]) |
| Compute the value of the symbol, as a '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 FRAME must be given. If FRAME is not given, or if |
| FRAME is invalid, then this method will throw an exception. |
| |
| The available domain categories in 'gdb.Symbol' are represented as |
| constants in the 'gdb' module: |
| |
| '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 GDB's handling of symbols. |
| |
| 'gdb.SYMBOL_VAR_DOMAIN' |
| This domain contains variables, function names, typedef names and |
| enum type values. |
| |
| 'gdb.SYMBOL_STRUCT_DOMAIN' |
| This domain holds struct, union and enum type names. |
| |
| 'gdb.SYMBOL_LABEL_DOMAIN' |
| This domain contains names of labels (for gotos). |
| |
| 'gdb.SYMBOL_VARIABLES_DOMAIN' |
| This domain holds a subset of the 'SYMBOLS_VAR_DOMAIN'; it contains |
| everything minus functions and types. |
| |
| 'gdb.SYMBOL_FUNCTION_DOMAIN' |
| This domain contains all functions. |
| |
| 'gdb.SYMBOL_TYPES_DOMAIN' |
| This domain contains all types. |
| |
| The available address class categories in 'gdb.Symbol' are |
| represented as constants in the 'gdb' module: |
| |
| 'gdb.SYMBOL_LOC_UNDEF' |
| If this is returned by address class, it indicates an error either |
| in the symbol information or in GDB's handling of symbols. |
| |
| 'gdb.SYMBOL_LOC_CONST' |
| Value is constant int. |
| |
| 'gdb.SYMBOL_LOC_STATIC' |
| Value is at a fixed address. |
| |
| 'gdb.SYMBOL_LOC_REGISTER' |
| Value is in a register. |
| |
| 'gdb.SYMBOL_LOC_ARG' |
| Value is an argument. This value is at the offset stored within |
| the symbol inside the frame's argument list. |
| |
| 'gdb.SYMBOL_LOC_REF_ARG' |
| Value address is stored in the frame's argument list. Just like |
| 'LOC_ARG' except that the value's address is stored at the offset, |
| not the value itself. |
| |
| 'gdb.SYMBOL_LOC_REGPARM_ADDR' |
| Value is a specified register. Just like 'LOC_REGISTER' except the |
| register holds the address of the argument instead of the argument |
| itself. |
| |
| 'gdb.SYMBOL_LOC_LOCAL' |
| Value is a local variable. |
| |
| 'gdb.SYMBOL_LOC_TYPEDEF' |
| Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all |
| have this class. |
| |
| 'gdb.SYMBOL_LOC_BLOCK' |
| Value is a block. |
| |
| 'gdb.SYMBOL_LOC_CONST_BYTES' |
| Value is a byte-sequence. |
| |
| '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. |
| |
| 'gdb.SYMBOL_LOC_OPTIMIZED_OUT' |
| The value does not actually exist in the program. |
| |
| 'gdb.SYMBOL_LOC_COMPUTED' |
| The value's address is a computed location. |
| |
| |
| File: gdb.info, Node: Symbol Tables In Python, Next: Line Tables In Python, Prev: Symbols In Python, Up: Python API |
| |
| 23.2.2.27 Symbol table representation in Python. |
| ................................................ |
| |
| Access to symbol table data maintained by GDB on the inferior is exposed |
| to Python via two objects: 'gdb.Symtab_and_line' and 'gdb.Symtab'. |
| Symbol table and line data for a frame is returned from the 'find_sal' |
| method in 'gdb.Frame' object. *Note Frames In Python::. |
| |
| For more information on GDB's symbol table management, see *note |
| Examining the Symbol Table: Symbols, for more information. |
| |
| A 'gdb.Symtab_and_line' object has the following attributes: |
| |
| -- Variable: Symtab_and_line.symtab |
| The symbol table object ('gdb.Symtab') for this frame. This |
| attribute is not writable. |
| |
| -- Variable: Symtab_and_line.pc |
| Indicates the start of the address range occupied by code for the |
| current source line. This attribute is not writable. |
| |
| -- Variable: Symtab_and_line.last |
| Indicates the end of the address range occupied by code for the |
| current source line. This attribute is not writable. |
| |
| -- Variable: Symtab_and_line.line |
| Indicates the current line number for this object. This attribute |
| is not writable. |
| |
| A 'gdb.Symtab_and_line' object has the following methods: |
| |
| -- Function: Symtab_and_line.is_valid () |
| Returns 'True' if the 'gdb.Symtab_and_line' object is valid, |
| 'False' if not. A 'gdb.Symtab_and_line' object can become invalid |
| if the Symbol table and line object it refers to does not exist in |
| GDB any longer. All other 'gdb.Symtab_and_line' methods will throw |
| an exception if it is invalid at the time the method is called. |
| |
| A 'gdb.Symtab' object has the following attributes: |
| |
| -- Variable: Symtab.filename |
| The symbol table's source filename. This attribute is not |
| writable. |
| |
| -- Variable: Symtab.objfile |
| The symbol table's backing object file. *Note Objfiles In |
| Python::. This attribute is not writable. |
| |
| -- Variable: Symtab.producer |
| The name and possibly version number of the program that compiled |
| the code in the symbol table. The contents of this string is up to |
| the compiler. If no producer information is available then 'None' |
| is returned. This attribute is not writable. |
| |
| A 'gdb.Symtab' object has the following methods: |
| |
| -- Function: Symtab.is_valid () |
| Returns 'True' if the 'gdb.Symtab' object is valid, 'False' if not. |
| A 'gdb.Symtab' object can become invalid if the symbol table it |
| refers to does not exist in GDB any longer. All other 'gdb.Symtab' |
| methods will throw an exception if it is invalid at the time the |
| method is called. |
| |
| -- Function: Symtab.fullname () |
| Return the symbol table's source absolute file name. |
| |
| -- Function: Symtab.global_block () |
| Return the global block of the underlying symbol table. *Note |
| Blocks In Python::. |
| |
| -- Function: Symtab.static_block () |
| Return the static block of the underlying symbol table. *Note |
| Blocks In Python::. |
| |
| -- Function: Symtab.linetable () |
| Return the line table associated with the symbol table. *Note Line |
| Tables In Python::. |
| |
| |
| File: gdb.info, Node: Line Tables In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API |
| |
| 23.2.2.28 Manipulating line tables using Python |
| ............................................... |
| |
| Python code can request and inspect line table information from a symbol |
| table that is loaded in GDB. 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 'linetable' function |
| (*note Symbol Tables In Python::). |
| |
| A 'gdb.LineTable' is iterable. The iterator returns 'LineTableEntry' |
| objects that correspond to the source line and address for each line |
| table entry. 'LineTableEntry' objects have the following attributes: |
| |
| -- Variable: 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. |
| |
| -- Variable: 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. |
| |
| As there can be multiple addresses for a single source line, you may |
| receive multiple 'LineTableEntry' objects with matching 'line' |
| attributes, but with different 'pc' attributes. The iterator is sorted |
| in ascending 'pc' order. Here is a small example illustrating iterating |
| over a line table. |
| |
| symtab = gdb.selected_frame().find_sal().symtab |
| linetable = symtab.linetable() |
| for line in linetable: |
| print "Line: "+str(line.line)+" Address: "+hex(line.pc) |
| |
| This will have the following output: |
| |
| 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 |
| |
| In addition to being able to iterate over a 'LineTable', it also has |
| the following direct access methods: |
| |
| -- Function: LineTable.line (line) |
| Return a Python 'Tuple' of 'LineTableEntry' objects for any entries |
| in the line table for the given LINE, which specifies the source |
| code line. If there are no entries for that source code LINE, the |
| Python 'None' is returned. |
| |
| -- Function: LineTable.has_line (line) |
| Return a Python 'Boolean' indicating whether there is an entry in |
| the line table for this source line. Return 'True' if an entry is |
| found, or 'False' if not. |
| |
| -- Function: LineTable.source_lines () |
| Return a Python 'List' of the source line numbers in the symbol |
| table. Only lines with executable code locations are returned. |
| The contents of the 'List' will just be the source line entries |
| represented as Python 'Long' values. |
| |
| |
| File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Line Tables In Python, Up: Python API |
| |
| 23.2.2.29 Manipulating breakpoints using Python |
| ............................................... |
| |
| Python code can manipulate breakpoints via the 'gdb.Breakpoint' class. |
| |
| -- Function: Breakpoint.__init__ (spec [, type [, wp_class [,internal |
| [,temporary]]]]) |
| Create a new breakpoint according to SPEC, which 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 |
| 'break' command, or in the case of a watchpoint, by the 'watch' |
| command. The optional TYPE denotes the breakpoint to create from |
| the types defined later in this chapter. This argument can be |
| either 'gdb.BP_BREAKPOINT' or 'gdb.BP_WATCHPOINT'; it defaults to |
| 'gdb.BP_BREAKPOINT'. The optional 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 'info breakpoints' (but will be listed with the 'maint |
| info breakpoints' command). The optional 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 |
| WP_CLASS argument defines the class of watchpoint to create, if |
| TYPE is 'gdb.BP_WATCHPOINT'. If a watchpoint class is not |
| provided, it is assumed to be a 'gdb.WP_WRITE' class. |
| |
| -- Function: Breakpoint.stop (self) |
| The 'gdb.Breakpoint' class can be sub-classed and, in particular, |
| you may choose to implement the 'stop' method. If this method is |
| defined in a sub-class of 'gdb.Breakpoint', it will be called when |
| the inferior reaches any location of a breakpoint which |
| instantiates that sub-class. If the method returns '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 |
| 'stop' method, each one will be called regardless of the return |
| status of the previous. This ensures that all 'stop' methods have |
| a chance to execute at that location. In this scenario if one of |
| the methods returns 'True' but the others return '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 GDB or the |
| inferior at this time. |
| |
| Example 'stop' implementation: |
| |
| class MyBreakpoint (gdb.Breakpoint): |
| def stop (self): |
| inf_val = gdb.parse_and_eval("foo") |
| if inf_val == 3: |
| return True |
| return False |
| |
| The available watchpoint types represented by constants are defined |
| in the 'gdb' module: |
| |
| 'gdb.WP_READ' |
| Read only watchpoint. |
| |
| 'gdb.WP_WRITE' |
| Write only watchpoint. |
| |
| 'gdb.WP_ACCESS' |
| Read/Write watchpoint. |
| |
| -- Function: Breakpoint.is_valid () |
| Return 'True' if this 'Breakpoint' object is valid, 'False' |
| otherwise. A '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. |
| |
| -- Function: Breakpoint.delete () |
| Permanently deletes the GDB breakpoint. This also invalidates the |
| Python 'Breakpoint' object. Any further access to this object's |
| attributes or methods will raise an error. |
| |
| -- Variable: Breakpoint.enabled |
| This attribute is 'True' if the breakpoint is enabled, and 'False' |
| otherwise. This attribute is writable. You can use it to enable |
| or disable the breakpoint. |
| |
| -- Variable: Breakpoint.silent |
| This attribute is 'True' if the breakpoint is silent, and 'False' |
| otherwise. This attribute is writable. |
| |
| Note that a breakpoint can also be silent if it has commands and |
| the first command is 'silent'. This is not reported by the |
| 'silent' attribute. |
| |
| -- Variable: Breakpoint.thread |
| If the breakpoint is thread-specific, this attribute holds the |
| thread id. If the breakpoint is not thread-specific, this |
| attribute is 'None'. This attribute is writable. |
| |
| -- Variable: 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 'None'. This |
| attribute is writable. |
| |
| -- Variable: Breakpoint.ignore_count |
| This attribute holds the ignore count for the breakpoint, an |
| integer. This attribute is writable. |
| |
| -- Variable: Breakpoint.number |
| This attribute holds the breakpoint's number -- the identifier used |
| by the user to manipulate the breakpoint. This attribute is not |
| writable. |
| |
| -- Variable: 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. |
| |
| -- Variable: Breakpoint.visible |
| This attribute tells whether the breakpoint is visible to the user |
| when set, or when the 'info breakpoints' command is run. This |
| attribute is not writable. |
| |
| -- Variable: 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 |
| '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. |
| |
| The available types are represented by constants defined in the 'gdb' |
| module: |
| |
| 'gdb.BP_BREAKPOINT' |
| Normal code breakpoint. |
| |
| 'gdb.BP_WATCHPOINT' |
| Watchpoint breakpoint. |
| |
| 'gdb.BP_HARDWARE_WATCHPOINT' |
| Hardware assisted watchpoint. |
| |
| 'gdb.BP_READ_WATCHPOINT' |
| Hardware assisted read watchpoint. |
| |
| 'gdb.BP_ACCESS_WATCHPOINT' |
| Hardware assisted access watchpoint. |
| |
| -- Variable: 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. |
| |
| -- Variable: 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 |
| 'None'. This attribute is not writable. |
| |
| -- Variable: 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 'None'. This attribute is not writable. |
| |
| -- Variable: 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 'None'. This attribute is writable. |
| |
| -- Variable: 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 'None'. This attribute is not writable. |
| |
| |
| File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API |
| |
| 23.2.2.30 Finish Breakpoints |
| ............................ |
| |
| A finish breakpoint is a temporary breakpoint set at the return address |
| of a frame, based on the 'finish' command. 'gdb.FinishBreakpoint' |
| extends 'gdb.Breakpoint'. The underlying breakpoint will be disabled |
| and deleted when the execution will run out of the breakpoint scope |
| (i.e. 'Breakpoint.stop' or 'FinishBreakpoint.out_of_scope' triggered). |
| Finish breakpoints are thread specific and must be create with the right |
| thread selected. |
| |
| -- Function: FinishBreakpoint.__init__ ([frame] [, internal]) |
| Create a finish breakpoint at the return address of the 'gdb.Frame' |
| object FRAME. If FRAME is not provided, this defaults to the |
| newest frame. The optional INTERNAL argument allows the breakpoint |
| to become invisible to the user. *Note Breakpoints In Python::, |
| for further details about this argument. |
| |
| -- Function: FinishBreakpoint.out_of_scope (self) |
| In some circumstances (e.g. 'longjmp', C++ exceptions, GDB 'return' |
| command, ...), a function may not properly terminate, and thus |
| never hit the finish breakpoint. When GDB notices such a |
| situation, the 'out_of_scope' callback will be triggered. |
| |
| You may want to sub-class 'gdb.FinishBreakpoint' and override this |
| method: |
| |
| class MyFinishBreakpoint (gdb.FinishBreakpoint) |
| def stop (self): |
| print "normal finish" |
| return True |
| |
| def out_of_scope (): |
| print "abnormal finish" |
| |
| -- Variable: FinishBreakpoint.return_value |
| When GDB is stopped at a finish breakpoint and the frame used to |
| build the 'gdb.FinishBreakpoint' object had debug symbols, this |
| attribute will contain a 'gdb.Value' object corresponding to the |
| return value of the function. The value will be 'None' if the |
| function return type is 'void' or if the return value was not |
| computable. This attribute is not writable. |
| |
| |
| File: gdb.info, Node: Lazy Strings In Python, Next: Architectures In Python, Prev: Finish Breakpoints in Python, Up: Python API |
| |
| 23.2.2.31 Python representation of lazy strings. |
| ................................................ |
| |
| A "lazy string" is a string whose contents is not retrieved or encoded |
| until it is needed. |
| |
| A 'gdb.LazyString' is represented in GDB as an 'address' that points |
| to a region of memory, an 'encoding' that will be used to encode that |
| region of memory, and a 'length' to delimit the region of memory that |
| represents the string. The difference between a 'gdb.LazyString' and a |
| string wrapped within a 'gdb.Value' is that a 'gdb.LazyString' will be |
| treated differently by GDB when printing. A 'gdb.LazyString' is |
| retrieved and encoded during printing, while a 'gdb.Value' wrapping a |
| string is immediately retrieved and encoded on creation. |
| |
| A 'gdb.LazyString' object has the following functions: |
| |
| -- Function: LazyString.value () |
| Convert the 'gdb.LazyString' to a 'gdb.Value'. This value will |
| point to the string in memory, but will lose all the delayed |
| retrieval, encoding and handling that GDB applies to a |
| 'gdb.LazyString'. |
| |
| -- Variable: LazyString.address |
| This attribute holds the address of the string. This attribute is |
| not writable. |
| |
| -- Variable: 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. |
| |
| -- Variable: LazyString.encoding |
| This attribute holds the encoding that will be applied to the |
| string when the string is printed by GDB. If the encoding is not |
| set, or contains an empty string, then GDB will select the most |
| appropriate encoding when the string is printed. This attribute is |
| not writable. |
| |
| -- Variable: 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 'target' method. *Note Types In Python::. This attribute |
| is not writable. |
| |
| |
| File: gdb.info, Node: Architectures In Python, Prev: Lazy Strings In Python, Up: Python API |
| |
| 23.2.2.32 Python representation of architectures |
| ................................................ |
| |
| GDB uses architecture specific parameters and artifacts in a number of |
| its various computations. An architecture is represented by an instance |
| of the 'gdb.Architecture' class. |
| |
| A 'gdb.Architecture' class has the following methods: |
| |
| -- Function: Architecture.name () |
| Return the name (string value) of the architecture. |
| |
| -- Function: Architecture.disassemble (START_PC [, END_PC [, COUNT]]) |
| Return a list of disassembled instructions starting from the memory |
| address START_PC. The optional arguments END_PC and COUNT |
| determine the number of instructions in the returned list. If both |
| the optional arguments END_PC and COUNT are specified, then a list |
| of at most COUNT disassembled instructions whose start address |
| falls in the closed memory address interval from START_PC to END_PC |
| are returned. If END_PC is not specified, but COUNT is specified, |
| then COUNT number of instructions starting from the address |
| START_PC are returned. If COUNT is not specified but END_PC is |
| specified, then all instructions whose start address falls in the |
| closed memory address interval from START_PC to END_PC are |
| returned. If neither END_PC nor COUNT are specified, then a single |
| instruction at START_PC is returned. For all of these cases, each |
| element of the returned list is a Python 'dict' with the following |
| string keys: |
| |
| 'addr' |
| The value corresponding to this key is a Python long integer |
| capturing the memory address of the instruction. |
| |
| '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 'disassembly-flavor'. |
| *Note Machine Code::. |
| |
| 'length' |
| The value corresponding to this key is the length (integer |
| value) of the instruction in bytes. |
| |
| |
| File: gdb.info, Node: Python Auto-loading, Next: Python modules, Prev: Python API, Up: Python |
| |
| 23.2.3 Python Auto-loading |
| -------------------------- |
| |
| When a new object file is read (for example, due to the 'file' command, |
| or because the inferior has loaded a shared library), GDB will look for |
| Python support scripts in several ways: 'OBJFILE-gdb.py' and |
| '.debug_gdb_scripts' section. *Note 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. |
| |
| 'set auto-load python-scripts [on|off]' |
| Enable or disable the auto-loading of Python scripts. |
| |
| 'show auto-load python-scripts' |
| Show whether auto-loading of Python scripts is enabled or disabled. |
| |
| 'info auto-load python-scripts [REGEXP]' |
| Print the list of all Python scripts that GDB auto-loaded. |
| |
| Also printed is the list of Python scripts that were mentioned in |
| the '.debug_gdb_scripts' section and were either not found (*note |
| dotdebug_gdb_scripts section::) or were not auto-loaded due to |
| 'auto-load safe-path' rejection (*note Auto-loading::). This is |
| useful because their names are not printed when GDB tries to load |
| them and fails. There may be many of them, and printing an error |
| message for each one is problematic. |
| |
| If REGEXP is supplied only Python scripts with matching names are |
| printed. |
| |
| Example: |
| |
| (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 |
| |
| When reading an auto-loaded file or script, GDB sets the "current |
| objfile". This is available via the 'gdb.current_objfile' function |
| (*note Objfiles In Python::). This can be useful for registering |
| objfile-specific pretty-printers and frame-filters. |
| |
| |
| File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python |
| |
| 23.2.4 Python modules |
| --------------------- |
| |
| GDB 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. |
| |
| |
| File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules |
| |
| 23.2.4.1 gdb.printing |
| ..................... |
| |
| This module provides a collection of utilities for working with |
| pretty-printers. |
| |
| 'PrettyPrinter (NAME, SUBPRINTERS=None)' |
| This class specifies the API that makes 'info pretty-printer', |
| 'enable pretty-printer' and 'disable pretty-printer' work. |
| Pretty-printers should generally inherit from this class. |
| |
| 'SubPrettyPrinter (NAME)' |
| For printers that handle multiple types, this class specifies the |
| corresponding API for the subprinters. |
| |
| 'RegexpCollectionPrettyPrinter (NAME)' |
| Utility class for handling multiple printers, all recognized via |
| regular expressions. *Note Writing a Pretty-Printer::, for an |
| example. |
| |
| 'FlagEnumerationPrinter (NAME)' |
| A pretty-printer which handles printing of 'enum' values. Unlike |
| GDB's built-in 'enum' printing, this printer attempts to work |
| properly when there is some overlap between the enumeration |
| constants. The argument NAME is the name of the printer and also |
| the name of the 'enum' type to look up. |
| |
| 'register_pretty_printer (OBJ, PRINTER, REPLACE=False)' |
| Register PRINTER with the pretty-printer list of OBJ. If REPLACE |
| is 'True' then any existing copy of the printer is replaced. |
| Otherwise a 'RuntimeError' exception is raised if a printer with |
| the same name already exists. |
| |
| |
| File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules |
| |
| 23.2.4.2 gdb.types |
| .................. |
| |
| This module provides a collection of utilities for working with |
| 'gdb.Type' objects. |
| |
| 'get_basic_type (TYPE)' |
| Return TYPE with const and volatile qualifiers stripped, and with |
| typedefs and C++ references converted to the underlying type. |
| |
| C++ example: |
| |
| typedef const int const_int; |
| const_int foo (3); |
| const_int& foo_ref (foo); |
| int main () { return 0; } |
| |
| Then in gdb: |
| |
| (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 |
| |
| 'has_field (TYPE, FIELD)' |
| Return 'True' if TYPE, assumed to be a type with fields (e.g., a |
| structure or union), has field FIELD. |
| |
| 'make_enum_dict (ENUM_TYPE)' |
| Return a Python 'dictionary' type produced from ENUM_TYPE. |
| |
| 'deep_items (TYPE)' |
| Returns a Python iterator similar to the standard |
| 'gdb.Type.iteritems' method, except that the iterator returned by |
| 'deep_items' will recursively traverse anonymous struct or union |
| fields. For example: |
| |
| struct A |
| { |
| int a; |
| union { |
| int b0; |
| int b1; |
| }; |
| }; |
| |
| Then in GDB: |
| (gdb) python import gdb.types |
| (gdb) python struct_a = gdb.lookup_type("struct A") |
| (gdb) python print struct_a.keys () |
| {['a', '']} |
| (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)] |
| {['a', 'b0', 'b1']} |
| |
| 'get_type_recognizers ()' |
| Return a list of the enabled type recognizers for the current |
| context. This is called by GDB during the type-printing process |
| (*note Type Printing API::). |
| |
| 'apply_type_recognizers (recognizers, type_obj)' |
| Apply the type recognizers, RECOGNIZERS, to the type object |
| TYPE_OBJ. If any recognizer returns a string, return that string. |
| Otherwise, return 'None'. This is called by GDB during the |
| type-printing process (*note Type Printing API::). |
| |
| 'register_type_printer (locus, printer)' |
| This is a convenience function to register a type printer PRINTER. |
| The printer must implement the type printer protocol. The LOCUS |
| argument is either a 'gdb.Objfile', in which case the printer is |
| registered with that objfile; a 'gdb.Progspace', in which case the |
| printer is registered with that progspace; or 'None', in which case |
| the printer is registered globally. |
| |
| '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: |
| |
| -- Method on TypePrinter: __init__ (self, name) |
| Initialize the type printer with the given name. The new |
| printer starts in the enabled state. |
| |
| |
| File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules |
| |
| 23.2.4.3 gdb.prompt |
| ................... |
| |
| This module provides a method for prompt value-substitution. |
| |
| 'substitute_prompt (STRING)' |
| Return 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: |
| |
| '\\' |
| Substitute a backslash. |
| '\e' |
| Substitute an ESC character. |
| '\f' |
| Substitute the selected frame; an argument names a frame |
| parameter. |
| '\n' |
| Substitute a newline. |
| '\p' |
| Substitute a parameter's value; the argument names the |
| parameter. |
| '\r' |
| Substitute a carriage return. |
| '\t' |
| Substitute the selected thread; an argument names a thread |
| parameter. |
| '\v' |
| Substitute the version of GDB. |
| '\w' |
| Substitute the current working directory. |
| '\[' |
| 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. |
| '\]' |
| End a sequence of non-printing characters. |
| |
| For example: |
| |
| substitute_prompt (``frame: \f, |
| print arguments: \p{print frame-arguments}'') |
| |
| will return the string: |
| |
| "frame: main, print arguments: scalars" |
| |
| |
| File: gdb.info, Node: Guile, Next: Auto-loading extensions, Prev: Python, Up: Extending GDB |
| |
| 23.3 Extending GDB using Guile |
| ============================== |
| |
| You can extend GDB using the Guile implementation of the Scheme |
| programming language (http://www.gnu.org/software/guile/). This feature |
| is available only if GDB was configured using '--with-guile'. |
| |
| * Menu: |
| |
| * Guile Introduction:: Introduction to Guile scripting in GDB |
| * Guile Commands:: Accessing Guile from GDB |
| * Guile API:: Accessing GDB from Guile |
| * Guile Auto-loading:: Automatically loading Guile code |
| * Guile Modules:: Guile modules provided by GDB |
| |
| |
| File: gdb.info, Node: Guile Introduction, Next: Guile Commands, Up: Guile |
| |
| 23.3.1 Guile Introduction |
| ------------------------- |
| |
| Guile is an implementation of the Scheme programming language and is the |
| GNU project's official extension language. |
| |
| Guile support in GDB follows the Python support in GDB reasonably |
| closely, so concepts there should carry over. However, some things are |
| done differently where it makes sense. |
| |
| GDB requires Guile version 2.0 or greater. Older versions are not |
| supported. |
| |
| Guile scripts used by GDB should be installed in |
| 'DATA-DIRECTORY/guile', where DATA-DIRECTORY is the data directory as |
| determined at GDB startup (*note Data Files::). This directory, known |
| as the "guile directory", is automatically added to the Guile Search |
| Path in order to allow the Guile interpreter to locate all scripts |
| installed at this location. |
| |
| |
| File: gdb.info, Node: Guile Commands, Next: Guile API, Prev: Guile Introduction, Up: Guile |
| |
| 23.3.2 Guile Commands |
| --------------------- |
| |
| GDB provides two commands for accessing the Guile interpreter: |
| |
| 'guile-repl' |
| 'gr' |
| The 'guile-repl' command can be used to start an interactive Guile |
| prompt or "repl". To return to GDB, type ',q' or the 'EOF' |
| character (e.g., 'Ctrl-D' on an empty prompt). These commands do |
| not take any arguments. |
| |
| 'guile [SCHEME-EXPRESSION]' |
| 'gu [SCHEME-EXPRESSION]' |
| The 'guile' command can be used to evaluate a Scheme expression. |
| |
| If given an argument, GDB will pass the argument to the Guile |
| interpreter for evaluation. |
| |
| (gdb) guile (display (+ 20 3)) (newline) |
| 23 |
| |
| The result of the Scheme expression is displayed using normal Guile |
| rules. |
| |
| (gdb) guile (+ 20 3) |
| 23 |
| |
| If you do not provide an argument to 'guile', it will act as a |
| multi-line command, like 'define'. In this case, the Guile script |
| is made up of subsequent command lines, given after the 'guile' |
| command. This command list is terminated using a line containing |
| 'end'. For example: |
| |
| (gdb) guile |
| >(display 23) |
| >(newline) |
| >end |
| 23 |
| |
| It is also possible to execute a Guile script from the GDB |
| interpreter: |
| |
| 'source script-name' |
| The script name must end with '.scm' and GDB must be configured to |
| recognize the script language based on filename extension using the |
| 'script-extension' setting. *Note Extending GDB: Extending GDB. |
| |
| 'guile (load "script-name")' |
| This method uses the 'load' Guile function. It takes a string |
| argument that is the name of the script to load. See the Guile |
| documentation for a description of this function. (*note |
| (guile)Loading::). |
| |
| |
| File: gdb.info, Node: Guile API, Next: Guile Auto-loading, Prev: Guile Commands, Up: Guile |
| |
| 23.3.3 Guile API |
| ---------------- |
| |
| You can get quick online help for GDB's Guile API by issuing the command |
| 'help guile', or by issuing the command ',help' from an interactive |
| Guile session. Furthermore, most Guile procedures provided by GDB have |
| doc strings which can be obtained with ',describe PROCEDURE-NAME' or ',d |
| PROCEDURE-NAME' from the Guile interactive prompt. |
| |
| * Menu: |
| |
| * Basic Guile:: Basic Guile Functions |
| * Guile Configuration:: Guile configuration variables |
| * GDB Scheme Data Types:: Scheme representations of GDB objects |
| * Guile Exception Handling:: How Guile exceptions are translated |
| * Values From Inferior In Guile:: Guile representation of values |
| * Arithmetic In Guile:: Arithmetic in Guile |
| * Types In Guile:: Guile representation of types |
| * Guile Pretty Printing API:: Pretty-printing values with Guile |
| * Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer |
| * Writing a Guile Pretty-Printer:: Writing a pretty-printer |
| * Commands In Guile:: Implementing new commands in Guile |
| * Parameters In Guile:: Adding new GDB parameters |
| * Progspaces In Guile:: Program spaces |
| * Objfiles In Guile:: Object files in Guile |
| * Frames In Guile:: Accessing inferior stack frames from Guile |
| * Blocks In Guile:: Accessing blocks from Guile |
| * Symbols In Guile:: Guile representation of symbols |
| * Symbol Tables In Guile:: Guile representation of symbol tables |
| * Breakpoints In Guile:: Manipulating breakpoints using Guile |
| * Lazy Strings In Guile:: Guile representation of lazy strings |
| * Architectures In Guile:: Guile representation of architectures |
| * Disassembly In Guile:: Disassembling instructions from Guile |
| * I/O Ports in Guile:: GDB I/O ports |
| * Memory Ports in Guile:: Accessing memory through ports and bytevectors |
| * Iterators In Guile:: Basic iterator support |
| |
| |
| File: gdb.info, Node: Basic Guile, Next: Guile Configuration, Up: Guile API |
| |
| 23.3.3.1 Basic Guile |
| .................... |
| |
| At startup, GDB overrides Guile's 'current-output-port' and |
| 'current-error-port' to print using GDB's output-paging streams. A |
| Guile program which outputs to one of these streams may have its output |
| interrupted by the user (*note Screen Size::). In this situation, a |
| Guile 'signal' exception is thrown with value 'SIGINT'. |
| |
| Guile's history mechanism uses the same naming as GDB's, namely the |
| user of dollar-variables (e.g., $1, $2, etc.). The results of |
| evaluations in Guile and in GDB are counted separately, '$1' in Guile is |
| not the same value as '$1' in GDB. |
| |
| GDB is not thread-safe. If your Guile program uses multiple threads, |
| you must be careful to only call GDB-specific functions in the GDB |
| thread. |
| |
| Some care must be taken when writing Guile code to run in GDB. Two |
| things are worth noting in particular: |
| |
| * GDB installs handlers for 'SIGCHLD' and 'SIGINT'. Guile code must |
| not override these, or even change the options using 'sigaction'. |
| If your program changes the handling of these signals, GDB will |
| most likely stop working correctly. Note that it is unfortunately |
| common for GUI toolkits to install a 'SIGCHLD' handler. |
| |
| * GDB 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 Guile 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. |
| |
| GDB introduces a new Guile module, named 'gdb'. All methods and |
| classes added by GDB are placed in this module. GDB does not |
| automatically 'import' the 'gdb' module, scripts must do this |
| themselves. There are various options for how to import a module, so |
| GDB leaves the choice of how the 'gdb' module is imported to the user. |
| To simplify interactive use, it is recommended to add one of the |
| following to your ~/.gdbinit. |
| |
| guile (use-modules (gdb)) |
| |
| guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:))) |
| |
| Which one to choose depends on your preference. The second one adds |
| 'gdb:' as a prefix to all module functions and variables. |
| |
| The rest of this manual assumes the 'gdb' module has been imported |
| without any prefix. See the Guile documentation for 'use-modules' for |
| more information (*note (guile)Using Guile Modules::). |
| |
| Example: |
| |
| (gdb) guile (value-type (make-value 1)) |
| ERROR: Unbound variable: value-type |
| Error while executing Scheme code. |
| (gdb) guile (use-modules (gdb)) |
| (gdb) guile (value-type (make-value 1)) |
| int |
| (gdb) |
| |
| The '(gdb)' module provides these basic Guile functions. |
| |
| -- Scheme Procedure: execute command [#:from-tty boolean] [#:to-string |
| boolean] |
| Evaluate COMMAND, a string, as a GDB CLI command. If a GDB |
| exception happens while COMMAND runs, it is translated as described |
| in *note Guile Exception Handling: Guile Exception Handling. |
| |
| FROM-TTY specifies whether GDB 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 '#f'. |
| |
| By default, any output produced by COMMAND is sent to GDB's |
| standard output (and to the log output if logging is turned on). |
| If the TO-STRING parameter is '#t', then output will be collected |
| by 'execute' and returned as a string. The default is '#f', in |
| which case the return value is unspecified. If TO-STRING is '#t', |
| the GDB virtual terminal will be temporarily set to unlimited width |
| and height, and its pagination will be disabled; *note Screen |
| Size::. |
| |
| -- Scheme Procedure: history-ref number |
| Return a value from GDB's value history (*note Value History::). |
| The NUMBER argument indicates which history element to return. If |
| NUMBER is negative, then GDB 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 NUMBER is zero, then GDB will return |
| the most recent element. If the element specified by NUMBER |
| doesn't exist in the value history, a 'gdb:error' exception will be |
| raised. |
| |
| If no exception is raised, the return value is always an instance |
| of '<gdb:value>' (*note Values From Inferior In Guile::). |
| |
| _Note:_ GDB's value history is independent of Guile's. '$1' in |
| GDB's value history contains the result of evaluating an expression |
| from GDB's command line and '$1' from Guile's history contains the |
| result of evaluating an expression from Guile's command line. |
| |
| -- Scheme Procedure: history-append! value |
| Append VALUE, an instance of '<gdb:value>', to GDB's value history. |
| Return its index in the history. |
| |
| Putting into history values returned by Guile extensions will allow |
| the user convenient access to those values via CLI history |
| facilities. |
| |
| -- Scheme Procedure: parse-and-eval expression |
| Parse EXPRESSION as an expression in the current language, evaluate |
| it, and return the result as a '<gdb:value>'. The EXPRESSION must |
| be a string. |
| |
| This function can be useful when implementing a new command (*note |
| Commands In Guile::), as it provides a way to parse the command's |
| arguments as an expression. It is also is useful when computing |
| values. For example, it is the only way to get the value of a |
| convenience variable (*note Convenience Vars::) as a '<gdb:value>'. |
| |
| |
| File: gdb.info, Node: Guile Configuration, Next: GDB Scheme Data Types, Prev: Basic Guile, Up: Guile API |
| |
| 23.3.3.2 Guile Configuration |
| ............................ |
| |
| GDB provides these Scheme functions to access various configuration |
| parameters. |
| |
| -- Scheme Procedure: data-directory |
| Return a string containing GDB's data directory. This directory |
| contains GDB's ancillary files. |
| |
| -- Scheme Procedure: guile-data-directory |
| Return a string containing GDB's Guile data directory. This |
| directory contains the Guile modules provided by GDB. |
| |
| -- Scheme Procedure: gdb-version |
| Return a string containing the GDB version. |
| |
| -- Scheme Procedure: host-config |
| Return a string containing the host configuration. This is the |
| string passed to '--host' when GDB was configured. |
| |
| -- Scheme Procedure: target-config |
| Return a string containing the target configuration. This is the |
| string passed to '--target' when GDB was configured. |
| |
| |
| File: gdb.info, Node: GDB Scheme Data Types, Next: Guile Exception Handling, Prev: Guile Configuration, Up: Guile API |
| |
| 23.3.3.3 GDB Scheme Data Types |
| .............................. |
| |
| The values exposed by GDB to Guile are known as "GDB objects". There |
| are several kinds of GDB object, and each is disjoint from all other |
| types known to Guile. |
| |
| -- Scheme Procedure: gdb-object-kind object |
| Return the kind of the GDB object, e.g., '<gdb:breakpoint>', as a |
| symbol. |
| |
| GDB defines the following object types: |
| |
| '<gdb:arch>' |
| *Note Architectures In Guile::. |
| |
| '<gdb:block>' |
| *Note Blocks In Guile::. |
| |
| '<gdb:block-symbols-iterator>' |
| *Note Blocks In Guile::. |
| |
| '<gdb:breakpoint>' |
| *Note Breakpoints In Guile::. |
| |
| '<gdb:command>' |
| *Note Commands In Guile::. |
| |
| '<gdb:exception>' |
| *Note Guile Exception Handling::. |
| |
| '<gdb:frame>' |
| *Note Frames In Guile::. |
| |
| '<gdb:iterator>' |
| *Note Iterators In Guile::. |
| |
| '<gdb:lazy-string>' |
| *Note Lazy Strings In Guile::. |
| |
| '<gdb:objfile>' |
| *Note Objfiles In Guile::. |
| |
| '<gdb:parameter>' |
| *Note Parameters In Guile::. |
| |
| '<gdb:pretty-printer>' |
| *Note Guile Pretty Printing API::. |
| |
| '<gdb:pretty-printer-worker>' |
| *Note Guile Pretty Printing API::. |
| |
| '<gdb:progspace>' |
| *Note Progspaces In Guile::. |
| |
| '<gdb:symbol>' |
| *Note Symbols In Guile::. |
| |
| '<gdb:symtab>' |
| *Note Symbol Tables In Guile::. |
| |
| '<gdb:sal>' |
| *Note Symbol Tables In Guile::. |
| |
| '<gdb:type>' |
| *Note Types In Guile::. |
| |
| '<gdb:field>' |
| *Note Types In Guile::. |
| |
| '<gdb:value>' |
| *Note Values From Inferior In Guile::. |
| |
| The following GDB objects are managed internally so that the Scheme |
| function 'eq?' may be applied to them. |
| |
| '<gdb:arch>' |
| '<gdb:block>' |
| '<gdb:breakpoint>' |
| '<gdb:frame>' |
| '<gdb:objfile>' |
| '<gdb:progspace>' |
| '<gdb:symbol>' |
| '<gdb:symtab>' |
| '<gdb:type>' |
| |
| |
| File: gdb.info, Node: Guile Exception Handling, Next: Values From Inferior In Guile, Prev: GDB Scheme Data Types, Up: Guile API |
| |
| 23.3.3.4 Guile Exception Handling |
| ................................. |
| |
| When executing the 'guile' command, Guile exceptions uncaught within the |
| Guile code are translated to calls to the GDB error-reporting mechanism. |
| If the command that called 'guile' does not handle the error, GDB will |
| terminate it and report the error according to the setting of the 'guile |
| print-stack' parameter. |
| |
| The 'guile print-stack' parameter has three settings: |
| |
| 'none' |
| Nothing is printed. |
| |
| 'message' |
| An error message is printed containing the Guile exception name, |
| the associated value, and the Guile call stack backtrace at the |
| point where the exception was raised. Example: |
| |
| (gdb) guile (display foo) |
| ERROR: In procedure memoize-variable-access!: |
| ERROR: Unbound variable: foo |
| Error while executing Scheme code. |
| |
| 'full' |
| In addition to an error message a full backtrace is printed. |
| |
| (gdb) set guile print-stack full |
| (gdb) guile (display foo) |
| Guile Backtrace: |
| In ice-9/boot-9.scm: |
| 157: 10 [catch #t #<catch-closure 2c76e20> ...] |
| In unknown file: |
| ?: 9 [apply-smob/1 #<catch-closure 2c76e20>] |
| In ice-9/boot-9.scm: |
| 157: 8 [catch #t #<catch-closure 2c76d20> ...] |
| In unknown file: |
| ?: 7 [apply-smob/1 #<catch-closure 2c76d20>] |
| ?: 6 [call-with-input-string "(display foo)" ...] |
| In ice-9/boot-9.scm: |
| 2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>] |
| In ice-9/eval-string.scm: |
| 44: 4 [read-and-eval #<input: string 27cb410> #:lang ...] |
| 37: 3 [lp (display foo)] |
| In ice-9/eval.scm: |
| 387: 2 [eval # ()] |
| 393: 1 [eval #<memoized foo> ()] |
| In unknown file: |
| ?: 0 [memoize-variable-access! #<memoized foo> ...] |
| |
| ERROR: In procedure memoize-variable-access!: |
| ERROR: Unbound variable: foo |
| Error while executing Scheme code. |
| |
| GDB errors that happen in GDB commands invoked by Guile code are |
| converted to Guile exceptions. The type of the Guile exception depends |
| on the error. |
| |
| Guile procedures provided by GDB can throw the standard Guile |
| exceptions like 'wrong-type-arg' and 'out-of-range'. |
| |
| User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) is |
| translated to a Guile 'signal' exception with value 'SIGINT'. |
| |
| GDB Guile procedures can also throw these exceptions: |
| |
| 'gdb:error' |
| This exception is a catch-all for errors generated from within GDB. |
| |
| 'gdb:invalid-object' |
| This exception is thrown when accessing Guile objects that wrap |
| underlying GDB objects have become invalid. For example, a |
| '<gdb:breakpoint>' object becomes invalid if the user deletes it |
| from the command line. The object still exists in Guile, but the |
| object it represents is gone. Further operations on this |
| breakpoint will throw this exception. |
| |
| 'gdb:memory-error' |
| This exception is thrown when an operation tried to access invalid |
| memory in the inferior. |
| |
| 'gdb:pp-type-error' |
| This exception is thrown when a Guile pretty-printer passes a bad |
| object to GDB. |
| |
| The following exception-related procedures are provided by the |
| '(gdb)' module. |
| |
| -- Scheme Procedure: make-exception key args |
| Return a '<gdb:exception>' object given by its KEY and ARGS, which |
| are the standard Guile parameters of an exception. See the Guile |
| documentation for more information (*note (guile)Exceptions::). |
| |
| -- Scheme Procedure: exception? object |
| Return '#t' if OBJECT is a '<gdb:exception>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: exception-key exception |
| Return the ARGS field of a '<gdb:exception>' object. |
| |
| -- Scheme Procedure: exception-args exception |
| Return the ARGS field of a '<gdb:exception>' object. |
| |
| |
| File: gdb.info, Node: Values From Inferior In Guile, Next: Arithmetic In Guile, Prev: Guile Exception Handling, Up: Guile API |
| |
| 23.3.3.5 Values From Inferior In Guile |
| ...................................... |
| |
| GDB provides values it obtains from the inferior program in an object of |
| type '<gdb:value>'. GDB uses this object for its internal bookkeeping |
| of the inferior's values, and for fetching values when necessary. |
| |
| GDB does not memoize '<gdb:value>' objects. 'make-value' always |
| returns a fresh object. |
| |
| (gdb) guile (eq? (make-value 1) (make-value 1)) |
| $1 = #f |
| (gdb) guile (equal? (make-value 1) (make-value 1)) |
| $1 = #t |
| |
| A '<gdb:value>' that represents a function can be executed via |
| inferior function call with 'value-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, 'some-val' is a '<gdb:value>' instance representing a |
| function that takes two integers as arguments. To execute this |
| function, call it like so: |
| |
| (define result (value-call some-val 10 20)) |
| |
| Any values returned from a function call are '<gdb:value>' objects. |
| |
| Note: Unlike Python scripting in GDB, inferior values that are simple |
| scalars cannot be used directly in Scheme expressions that are valid for |
| the value's data type. For example, '(+ (parse-and-eval "int_variable") |
| 2)' does not work. And inferior values that are structures or instances |
| of some class cannot be accessed using any special syntax, instead |
| 'value-field' must be used. |
| |
| The following value-related procedures are provided by the '(gdb)' |
| module. |
| |
| -- Scheme Procedure: value? object |
| Return '#t' if OBJECT is a '<gdb:value>' object. Otherwise return |
| '#f'. |
| |
| -- Scheme Procedure: make-value value [#:type type] |
| Many Scheme values can be converted directly to a '<gdb:value>' |
| with this procedure. If TYPE is specified, the result is a value |
| of this type, and if VALUE can't be represented with this type an |
| exception is thrown. Otherwise the type of the result is |
| determined from VALUE as described below. |
| |
| *Note Architectures In Guile::, for a list of the builtin types for |
| an architecture. |
| |
| Here's how Scheme values are converted when TYPE argument to |
| 'make-value' is not specified: |
| |
| Scheme boolean |
| A Scheme boolean is converted the boolean type for the current |
| language. |
| |
| Scheme integer |
| A Scheme integer is converted to the first of a C 'int', |
| 'unsigned int', 'long', 'unsigned long', 'long long' or |
| 'unsigned long long' type for the current architecture that |
| can represent the value. |
| |
| If the Scheme integer cannot be represented as a target |
| integer an 'out-of-range' exception is thrown. |
| |
| Scheme real |
| A Scheme real is converted to the C 'double' type for the |
| current architecture. |
| |
| Scheme string |
| A Scheme string is converted to a string in the current target |
| language using the current target encoding. Characters that |
| cannot be represented in the current target encoding are |
| replaced with the corresponding escape sequence. This is |
| Guile's 'SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE' conversion |
| strategy (*note (guile)Strings::). |
| |
| Passing TYPE is not supported in this case, if it is provided |
| a 'wrong-type-arg' exception is thrown. |
| |
| '<gdb:lazy-string>' |
| If VALUE is a '<gdb:lazy-string>' object (*note Lazy Strings |
| In Guile::), then the 'lazy-string->value' procedure is |
| called, and its result is used. |
| |
| Passing TYPE is not supported in this case, if it is provided |
| a 'wrong-type-arg' exception is thrown. |
| |
| Scheme bytevector |
| If VALUE is a Scheme bytevector and TYPE is provided, VALUE |
| must be the same size, in bytes, of values of type TYPE, and |
| the result is essentially created by using 'memcpy'. |
| |
| If VALUE is a Scheme bytevector and TYPE is not provided, the |
| result is an array of type 'uint8' of the same length. |
| |
| -- Scheme Procedure: value-optimized-out? value |
| Return '#t' if the compiler optimized out VALUE, thus it is not |
| available for fetching from the inferior. Otherwise return '#f'. |
| |
| -- Scheme Procedure: value-address value |
| If VALUE is addressable, returns a '<gdb:value>' object |
| representing the address. Otherwise, '#f' is returned. |
| |
| -- Scheme Procedure: value-type value |
| Return the type of VALUE as a '<gdb:type>' object (*note Types In |
| Guile::). |
| |
| -- Scheme Procedure: value-dynamic-type value |
| Return the dynamic type of VALUE. This uses C++ run-time type |
| information (RTTI) to determine the dynamic type of the value. If |
| the value is of class type, it will return the class in which the |
| value is embedded, if any. If the 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++ program |
| that includes RTTI for the object in question. Otherwise, it will |
| just return the static type of the value as in 'ptype foo'. *Note |
| ptype: Symbols. |
| |
| -- Scheme Procedure: value-cast value type |
| Return a new instance of '<gdb:value>' that is the result of |
| casting VALUE to the type described by TYPE, which must be a |
| '<gdb:type>' object. If the cast cannot be performed for some |
| reason, this method throws an exception. |
| |
| -- Scheme Procedure: value-dynamic-cast value type |
| Like 'value-cast', but works as if the C++ 'dynamic_cast' operator |
| were used. Consult a C++ reference for details. |
| |
| -- Scheme Procedure: value-reinterpret-cast value type |
| Like 'value-cast', but works as if the C++ 'reinterpret_cast' |
| operator were used. Consult a C++ reference for details. |
| |
| -- Scheme Procedure: value-dereference value |
| For pointer data types, this method returns a new '<gdb:value>' |
| object whose contents is the object pointed to by VALUE. For |
| example, if 'foo' is a C pointer to an 'int', declared in your C |
| program as |
| |
| int *foo; |
| |
| then you can use the corresponding '<gdb:value>' to access what |
| 'foo' points to like this: |
| |
| (define bar (value-dereference foo)) |
| |
| The result 'bar' will be a '<gdb:value>' object holding the value |
| pointed to by 'foo'. |
| |
| A similar function 'value-referenced-value' exists which also |
| returns '<gdb:value>' objects corresonding to the values pointed to |
| by pointer values (and additionally, values referenced by reference |
| values). However, the behavior of 'value-dereference' differs from |
| 'value-referenced-value' by the fact that the behavior of |
| 'value-dereference' is identical to applying the C unary operator |
| '*' on a given value. For example, consider a reference to a |
| pointer 'ptrref', declared in your C++ program as |
| |
| typedef int *intptr; |
| ... |
| int val = 10; |
| intptr ptr = &val; |
| intptr &ptrref = ptr; |
| |
| Though 'ptrref' is a reference value, one can apply the method |
| 'value-dereference' to the '<gdb:value>' object corresponding to it |
| and obtain a '<gdb:value>' which is identical to that corresponding |
| to 'val'. However, if you apply the method |
| 'value-referenced-value', the result would be a '<gdb:value>' |
| object identical to that corresponding to 'ptr'. |
| |
| (define scm-ptrref (parse-and-eval "ptrref")) |
| (define scm-val (value-dereference scm-ptrref)) |
| (define scm-ptr (value-referenced-value scm-ptrref)) |
| |
| The '<gdb:value>' object 'scm-val' is identical to that |
| corresponding to 'val', and 'scm-ptr' is identical to that |
| corresponding to 'ptr'. In general, 'value-dereference' can be |
| applied whenever the C unary operator '*' can be applied to the |
| corresponding C value. For those cases where applying both |
| 'value-dereference' and '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 |
| '<gdb:value>' objects corresponding to pointers ('<gdb:value>' |
| objects with type code 'TYPE_CODE_PTR') in a C/C++ program. |
| |
| -- Scheme Procedure: value-referenced-value value |
| For pointer or reference data types, this method returns a new |
| '<gdb:value>' object corresponding to the value referenced by the |
| pointer/reference value. For pointer data types, |
| 'value-dereference' and 'value-referenced-value' produce identical |
| results. The difference between these methods is that |
| 'value-dereference' cannot get the values referenced by reference |
| values. For example, consider a reference to an 'int', declared in |
| your C++ program as |
| |
| int val = 10; |
| int &ref = val; |
| |
| then applying 'value-dereference' to the '<gdb:value>' object |
| corresponding to 'ref' will result in an error, while applying |
| 'value-referenced-value' will result in a '<gdb:value>' object |
| identical to that corresponding to 'val'. |
| |
| (define scm-ref (parse-and-eval "ref")) |
| (define err-ref (value-dereference scm-ref)) ;; error |
| (define scm-val (value-referenced-value scm-ref)) ;; ok |
| |
| The '<gdb:value>' object 'scm-val' is identical to that |
| corresponding to 'val'. |
| |
| -- Scheme Procedure: value-field value field-name |
| Return field FIELD-NAME from '<gdb:value>' object VALUE. |
| |
| -- Scheme Procedure: value-subscript value index |
| Return the value of array VALUE at index INDEX. The VALUE argument |
| must be a subscriptable '<gdb:value>' object. |
| |
| -- Scheme Procedure: value-call value arg-list |
| Perform an inferior function call, taking VALUE as a pointer to the |
| function to call. Each element of list ARG-LIST must be a |
| <gdb:value> object or an object that can be converted to a value. |
| The result is the value returned by the function. |
| |
| -- Scheme Procedure: value->bool value |
| Return the Scheme boolean representing '<gdb:value>' VALUE. The |
| value must be "integer like". Pointers are ok. |
| |
| -- Scheme Procedure: value->integer |
| Return the Scheme integer representing '<gdb:value>' VALUE. The |
| value must be "integer like". Pointers are ok. |
| |
| -- Scheme Procedure: value->real |
| Return the Scheme real number representing '<gdb:value>' VALUE. |
| The value must be a number. |
| |
| -- Scheme Procedure: value->bytevector |
| Return a Scheme bytevector with the raw contents of '<gdb:value>' |
| VALUE. No transformation, endian or otherwise, is performed. |
| |
| -- Scheme Procedure: value->string value [#:encoding encoding] |
| [#:errors errors] [#:length length] |
| If VALUE> represents a string, then this method converts the |
| contents to a Guile string. Otherwise, this method will throw an |
| exception. |
| |
| Values are interpreted as strings according to the rules of the |
| current language. If the optional length argument is given, the |
| string will be converted to that length, and will include any |
| embedded zeroes that the string may contain. Otherwise, for |
| languages where the string is zero-terminated, the entire string |
| will be converted. |
| |
| For example, in C-like languages, a value is a string if it is a |
| pointer to or an array of characters or ints of type 'wchar_t', |
| 'char16_t', or 'char32_t'. |
| |
| If the optional ENCODING argument is given, it must be a string |
| naming the encoding of the string in the '<gdb:value>', such as |
| '"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same |
| encodings as the corresponding argument to Guile's |
| 'scm_from_stringn' function, and the Guile codec machinery will be |
| used to convert the string. If ENCODING is not given, or if |
| ENCODING is the empty string, then either the 'target-charset' |
| (*note Character Sets::) will be used, or a language-specific |
| encoding will be used, if the current language is able to supply |
| one. |
| |
| The optional ERRORS argument is one of '#f', 'error' or |
| 'substitute'. 'error' and 'substitute' must be symbols. If ERRORS |
| is not specified, or if its value is '#f', then the default |
| conversion strategy is used, which is set with the Scheme function |
| 'set-port-conversion-strategy!'. If the value is ''error' then an |
| exception is thrown if there is any conversion error. If the value |
| is ''substitute' then any conversion error is replaced with |
| question marks. *Note (guile)Strings::. |
| |
| If the optional LENGTH argument is given, the string will be |
| fetched and converted to the given length. The length must be a |
| Scheme integer and not a '<gdb:value>' integer. |
| |
| -- Scheme Procedure: value->lazy-string value [#:encoding encoding] |
| [#:length length] |
| If this '<gdb:value>' represents a string, then this method |
| converts VALUE to a '<gdb:lazy-string' (*note Lazy Strings In |
| Guile::). Otherwise, this method will throw an exception. |
| |
| If the optional ENCODING argument is given, it must be a string |
| naming the encoding of the '<gdb:lazy-string'. Some examples are: |
| '"ascii"', '"iso-8859-6"' or '"utf-8"'. If the ENCODING argument |
| is an encoding that GDB does not recognize, GDB will raise an |
| error. |
| |
| When a lazy string is printed, the GDB encoding machinery is used |
| to convert the string during printing. If the optional ENCODING |
| argument is not provided, or is an empty string, GDB will |
| automatically select the encoding most suitable for the string |
| type. For further information on encoding in GDB please see *note |
| Character Sets::. |
| |
| If the optional LENGTH argument is given, the string will be |
| fetched and encoded to the length of characters specified. If the |
| LENGTH argument is not provided, the string will be fetched and |
| encoded until a null of appropriate width is found. The length |
| must be a Scheme integer and not a '<gdb:value>' integer. |
| |
| -- Scheme Procedure: value-lazy? value |
| Return '#t' if VALUE has not yet been fetched from the inferior. |
| Otherwise return '#f'. GDB does not fetch values until necessary, |
| for efficiency. For example: |
| |
| (define myval (parse-and-eval "somevar")) |
| |
| The value of 'somevar' is not fetched at this time. It will be |
| fetched when the value is needed, or when the 'fetch-lazy' |
| procedure is invoked. |
| |
| -- Scheme Procedure: make-lazy-value type address |
| Return a '<gdb:value>' that will be lazily fetched from the target. |
| The object of type '<gdb:type>' whose value to fetch is specified |
| by its TYPE and its target memory ADDRESS, which is a Scheme |
| integer. |
| |
| -- Scheme Procedure: value-fetch-lazy! value |
| If VALUE is a lazy value ('(value-lazy? value)' is '#t'), then the |
| value is fetched from the inferior. Any errors that occur in the |
| process will produce a Guile exception. |
| |
| If VALUE is not a lazy value, this method has no effect. |
| |
| The result of this function is unspecified. |
| |
| -- Scheme Procedure: value-print value |
| Return the string representation (print form) of '<gdb:value>' |
| VALUE. |
| |
| |
| File: gdb.info, Node: Arithmetic In Guile, Next: Types In Guile, Prev: Values From Inferior In Guile, Up: Guile API |
| |
| 23.3.3.6 Arithmetic In Guile |
| ............................ |
| |
| The '(gdb)' module provides several functions for performing arithmetic |
| on '<gdb:value>' objects. The arithmetic is performed as if it were |
| done by the target, and therefore has target semantics which are not |
| necessarily those of Scheme. For example operations work with a fixed |
| precision, not the arbitrary precision of Scheme. |
| |
| Wherever a function takes an integer or pointer as an operand, GDB |
| will convert appropriate Scheme values to perform the operation. |
| |
| -- Scheme Procedure: value-add a b |
| |
| -- Scheme Procedure: value-sub a b |
| |
| -- Scheme Procedure: value-mul a b |
| |
| -- Scheme Procedure: value-div a b |
| |
| -- Scheme Procedure: value-rem a b |
| |
| -- Scheme Procedure: value-mod a b |
| |
| -- Scheme Procedure: value-pow a b |
| |
| -- Scheme Procedure: value-not a |
| |
| -- Scheme Procedure: value-neg a |
| |
| -- Scheme Procedure: value-pos a |
| |
| -- Scheme Procedure: value-abs a |
| |
| -- Scheme Procedure: value-lsh a b |
| |
| -- Scheme Procedure: value-rsh a b |
| |
| -- Scheme Procedure: value-min a b |
| |
| -- Scheme Procedure: value-max a b |
| |
| -- Scheme Procedure: value-lognot a |
| |
| -- Scheme Procedure: value-logand a b |
| |
| -- Scheme Procedure: value-logior a b |
| |
| -- Scheme Procedure: value-logxor a b |
| |
| -- Scheme Procedure: value=? a b |
| |
| -- Scheme Procedure: value<? a b |
| |
| -- Scheme Procedure: value<=? a b |
| |
| -- Scheme Procedure: value>? a b |
| |
| -- Scheme Procedure: value>=? a b |
| |
| Scheme does not provide a 'not-equal' function, and thus Guile |
| support in GDB does not either. |
| |
| |
| File: gdb.info, Node: Types In Guile, Next: Guile Pretty Printing API, Prev: Arithmetic In Guile, Up: Guile API |
| |
| 23.3.3.7 Types In Guile |
| ....................... |
| |
| GDB represents types from the inferior in objects of type '<gdb:type>'. |
| |
| The following type-related procedures are provided by the '(gdb)' |
| module. |
| |
| -- Scheme Procedure: type? object |
| Return '#t' if OBJECT is an object of type '<gdb:type>'. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: lookup-type name [#:block block] |
| This function looks up a type by its NAME, which must be a string. |
| |
| If BLOCK is given, it is an object of type '<gdb:block>', and NAME |
| is looked up in that scope. Otherwise, it is searched for |
| globally. |
| |
| Ordinarily, this function will return an instance of '<gdb:type>'. |
| If the named type cannot be found, it will throw an exception. |
| |
| -- Scheme Procedure: type-code type |
| Return the type code of TYPE. The type code will be one of the |
| 'TYPE_CODE_' constants defined below. |
| |
| -- Scheme Procedure: type-tag type |
| Return the tag name of TYPE. The tag name is the name after |
| 'struct', 'union', or 'enum' in C and C++; not all languages have |
| this concept. If this type has no tag name, then '#f' is returned. |
| |
| -- Scheme Procedure: type-name type |
| Return the name of TYPE. If this type has no name, then '#f' is |
| returned. |
| |
| -- Scheme Procedure: type-print-name type |
| Return the print name of TYPE. This returns something even for |
| anonymous types. For example, for an anonymous C struct '"struct |
| {...}"' is returned. |
| |
| -- Scheme Procedure: type-sizeof type |
| Return the size of this type, in target 'char' units. Usually, a |
| target's 'char' type will be an 8-bit byte. However, on some |
| unusual platforms, this type may have a different size. |
| |
| -- Scheme Procedure: type-strip-typedefs type |
| Return a new '<gdb:type>' that represents the real type of TYPE, |
| after removing all layers of typedefs. |
| |
| -- Scheme Procedure: type-array type n1 [n2] |
| Return a new '<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. |
| |
| -- Scheme Procedure: type-vector type n1 [n2] |
| Return a new '<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 'array' and a '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. |
| |
| -- Scheme Procedure: type-pointer type |
| Return a new '<gdb:type>' object which represents a pointer to |
| TYPE. |
| |
| -- Scheme Procedure: type-range type |
| Return a list of two elements: the low bound and high bound of |
| TYPE. If TYPE does not have a range, an exception is thrown. |
| |
| -- Scheme Procedure: type-reference type |
| Return a new '<gdb:type>' object which represents a reference to |
| TYPE. |
| |
| -- Scheme Procedure: type-target type |
| Return a new '<gdb:type>' object which represents the target type |
| of 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. |
| |
| -- Scheme Procedure: type-const type |
| Return a new '<gdb:type>' object which represents a |
| 'const'-qualified variant of TYPE. |
| |
| -- Scheme Procedure: type-volatile type |
| Return a new '<gdb:type>' object which represents a |
| 'volatile'-qualified variant of TYPE. |
| |
| -- Scheme Procedure: type-unqualified type |
| Return a new '<gdb:type>' object which represents an unqualified |
| variant of TYPE. That is, the result is neither 'const' nor |
| 'volatile'. |
| |
| -- Scheme Procedure: type-num-fields |
| Return the number of fields of '<gdb:type>' TYPE. |
| |
| -- Scheme Procedure: type-fields type |
| Return the fields of TYPE as a list. For structure and union |
| types, 'fields' has the usual meaning. 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++ classes are also represented as |
| fields. If the type has no fields, or does not fit into one of |
| these categories, an empty list will be returned. *Note Fields of |
| a type in Guile::. |
| |
| -- Scheme Procedure: make-field-iterator type |
| Return the fields of TYPE as a <gdb:iterator> object. *Note |
| Iterators In Guile::. |
| |
| -- Scheme Procedure: type-field type field-name |
| Return field named FIELD-NAME in TYPE. The result is an object of |
| type '<gdb:field>'. *Note Fields of a type in Guile::. If the |
| type does not have fields, or FIELD-NAME is not a field of TYPE, an |
| exception is thrown. |
| |
| For example, if 'some-type' is a '<gdb:type>' instance holding a |
| structure type, you can access its 'foo' field with: |
| |
| (define bar (type-field some-type "foo")) |
| |
| 'bar' will be a '<gdb:field>' object. |
| |
| -- Scheme Procedure: type-has-field? type name |
| Return '#t' if '<gdb:type>' TYPE has field named NAME. Otherwise |
| return '#f'. |
| |
| Each type has a code, which indicates what category this type falls |
| into. The available type categories are represented by constants |
| defined in the '(gdb)' module: |
| |
| 'TYPE_CODE_PTR' |
| The type is a pointer. |
| |
| 'TYPE_CODE_ARRAY' |
| The type is an array. |
| |
| 'TYPE_CODE_STRUCT' |
| The type is a structure. |
| |
| 'TYPE_CODE_UNION' |
| The type is a union. |
| |
| 'TYPE_CODE_ENUM' |
| The type is an enum. |
| |
| 'TYPE_CODE_FLAGS' |
| A bit flags type, used for things such as status registers. |
| |
| 'TYPE_CODE_FUNC' |
| The type is a function. |
| |
| 'TYPE_CODE_INT' |
| The type is an integer type. |
| |
| 'TYPE_CODE_FLT' |
| A floating point type. |
| |
| 'TYPE_CODE_VOID' |
| The special type 'void'. |
| |
| 'TYPE_CODE_SET' |
| A Pascal set type. |
| |
| 'TYPE_CODE_RANGE' |
| A range type, that is, an integer type with bounds. |
| |
| '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. |
| |
| 'TYPE_CODE_BITSTRING' |
| A string of bits. It is deprecated. |
| |
| 'TYPE_CODE_ERROR' |
| An unknown or erroneous type. |
| |
| 'TYPE_CODE_METHOD' |
| A method type, as found in C++ or Java. |
| |
| 'TYPE_CODE_METHODPTR' |
| A pointer-to-member-function. |
| |
| 'TYPE_CODE_MEMBERPTR' |
| A pointer-to-member. |
| |
| 'TYPE_CODE_REF' |
| A reference type. |
| |
| 'TYPE_CODE_CHAR' |
| A character type. |
| |
| 'TYPE_CODE_BOOL' |
| A boolean type. |
| |
| 'TYPE_CODE_COMPLEX' |
| A complex float type. |
| |
| 'TYPE_CODE_TYPEDEF' |
| A typedef to some other type. |
| |
| 'TYPE_CODE_NAMESPACE' |
| A C++ namespace. |
| |
| 'TYPE_CODE_DECFLOAT' |
| A decimal floating point type. |
| |
| 'TYPE_CODE_INTERNAL_FUNCTION' |
| A function internal to GDB. This is the type used to represent |
| convenience functions (*note Convenience Funs::). |
| |
| Further support for types is provided in the '(gdb types)' Guile |
| module (*note Guile Types Module::). |
| |
| Each field is represented as an object of type '<gdb:field>'. |
| |
| The following field-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: field? object |
| Return '#t' if OBJECT is an object of type '<gdb:field>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: field-name field |
| Return the name of the field, or '#f' for anonymous fields. |
| |
| -- Scheme Procedure: field-type field |
| Return the type of the field. This is usually an instance of |
| '<gdb:type>', but it can be '#f' in some situations. |
| |
| -- Scheme Procedure: field-enumval field |
| Return the enum value represented by '<gdb:field>' FIELD. |
| |
| -- Scheme Procedure: field-bitpos field |
| Return the bit position of '<gdb:field>' FIELD. This attribute is |
| not available for 'static' fields (as in C++ or Java). |
| |
| -- Scheme Procedure: field-bitsize field |
| If the field is packed, or is a bitfield, return the size of |
| '<gdb:field>' FIELD in bits. Otherwise, zero is returned; in which |
| case the field's size is given by its type. |
| |
| -- Scheme Procedure: field-artificial? field |
| Return '#t' if the field is artificial, usually meaning that it was |
| provided by the compiler and not the user. Otherwise return '#f'. |
| |
| -- Scheme Procedure: field-base-class? field |
| Return '#t' if the field represents a base class of a C++ |
| structure. Otherwise return '#f'. |
| |
| |
| File: gdb.info, Node: Guile Pretty Printing API, Next: Selecting Guile Pretty-Printers, Prev: Types In Guile, Up: Guile API |
| |
| 23.3.3.8 Guile Pretty Printing API |
| .................................. |
| |
| An example output is provided (*note Pretty Printing::). |
| |
| A pretty-printer is represented by an object of type |
| <gdb:pretty-printer>. Pretty-printer objects are created with |
| 'make-pretty-printer'. |
| |
| The following pretty-printer-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: make-pretty-printer name lookup-function |
| Return a '<gdb:pretty-printer>' object named NAME. |
| |
| LOOKUP-FUNCTION is a function of one parameter: the value to be |
| printed. If the value is handled by this pretty-printer, then |
| LOOKUP-FUNCTION returns an object of type |
| <gdb:pretty-printer-worker> to perform the actual pretty-printing. |
| Otherwise LOOKUP-FUNCTION returns '#f'. |
| |
| -- Scheme Procedure: pretty-printer? object |
| Return '#t' if OBJECT is a '<gdb:pretty-printer>' object. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: pretty-printer-enabled? pretty-printer |
| Return '#t' if PRETTY-PRINTER is enabled. Otherwise return '#f'. |
| |
| -- Scheme Procedure: set-pretty-printer-enabled! pretty-printer flag |
| Set the enabled flag of PRETTY-PRINTER to FLAG. The value returned |
| is unspecified. |
| |
| -- Scheme Procedure: pretty-printers |
| Return the list of global pretty-printers. |
| |
| -- Scheme Procedure: set-pretty-printers! pretty-printers |
| Set the list of global pretty-printers to PRETTY-PRINTERS. The |
| value returned is unspecified. |
| |
| -- Scheme Procedure: make-pretty-printer-worker display-hint to-string |
| children |
| Return an object of type '<gdb:pretty-printer-worker>'. |
| |
| This function takes three parameters: |
| |
| 'display-hint' |
| DISPLAY-HINT provides a hint to GDB or GDB front end via MI to |
| change the formatting of the value being printed. The value |
| must be a string or '#f' (meaning there is no hint). Several |
| values for DISPLAY-HINT are predefined by GDB: |
| |
| 'array' |
| Indicate that the object being printed is "array-like". |
| The CLI uses this to respect parameters such as 'set |
| print elements' and 'set print array'. |
| |
| '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. |
| |
| 'string' |
| Indicate that the object being printed is "string-like". |
| If the printer's 'to-string' function returns a Guile |
| string of some kind, then GDB 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 'set print |
| elements', and the like. |
| |
| 'to-string' |
| TO-STRING is either a function of one parameter, the |
| '<gdb:pretty-printer-worker>' object, or '#f'. |
| |
| When printing from the CLI, if the 'to-string' method exists, |
| then GDB will prepend its result to the values returned by |
| '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 (*note Print |
| Settings::), the CLI may print just the result of 'to-string' |
| in a stack trace, omitting the result of 'children'. |
| |
| If this method returns a string, it is printed verbatim. |
| |
| Otherwise, if this method returns an instance of |
| '<gdb:value>', then GDB prints this value. This may result in |
| a call to another pretty-printer. |
| |
| If instead the method returns a Guile value which is |
| convertible to a '<gdb:value>', then GDB performs the |
| conversion and prints the resulting value. Again, this may |
| result in a call to another pretty-printer. Guile scalars |
| (integers, floats, and booleans) and strings are convertible |
| to '<gdb:value>'; other types are not. |
| |
| Finally, if this method returns '#f' 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. |
| |
| TO-STRING may also be '#f' in which case it is left to |
| CHILDREN to print the value. |
| |
| 'children' |
| CHILDREN is either a function of one parameter, the |
| '<gdb:pretty-printer-worker>' object, or '#f'. |
| |
| GDB will call this function on a pretty-printer to compute the |
| children of the pretty-printer's value. |
| |
| This function must return a <gdb:iterator> object. 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 Guile |
| object which is convertible to a GDB value. |
| |
| If CHILDREN is '#f', GDB will act as though the value has no |
| children. |
| |
| GDB provides a function which can be used to look up the default |
| pretty-printer for a '<gdb:value>': |
| |
| -- Scheme Procedure: default-visualizer value |
| This function takes a '<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 '#f'. |
| |
| |
| File: gdb.info, Node: Selecting Guile Pretty-Printers, Next: Writing a Guile Pretty-Printer, Prev: Guile Pretty Printing API, Up: Guile API |
| |
| 23.3.3.9 Selecting Guile Pretty-Printers |
| ........................................ |
| |
| There are three sets of pretty-printers that GDB searches: |
| |
| * Per-objfile list of pretty-printers (*note Objfiles In Guile::). |
| * Per-progspace list of pretty-printers (*note Progspaces In |
| Guile::). |
| * The global list of pretty-printers (*note Guile Pretty Printing |
| API::). These printers are available when debugging any inferior. |
| |
| Pretty-printer lookup is done by passing the value to be printed to |
| the lookup function of each enabled object in turn. Lookup stops when a |
| lookup function returns a non-'#f' value or when the list is exhausted. |
| Lookup functions must return either a '<gdb:pretty-printer-worker>' |
| object or '#f'. Otherwise an exception is thrown. |
| |
| GDB first checks the result of 'objfile-pretty-printers' of each |
| '<gdb:objfile>' in the current program space and iteratively calls each |
| enabled lookup function in the list for that '<gdb:objfile>' until a |
| non-'#f' object is returned. If no pretty-printer is found in the |
| objfile lists, GDB then searches the result of |
| 'progspace-pretty-printers' of the current program space, calling each |
| enabled function until a non-'#f' object is returned. After these lists |
| have been exhausted, it tries the global pretty-printers list, obtained |
| with 'pretty-printers', again calling each enabled function until a |
| non-'#f' 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 |
| '<gdb:pretty-printer-worker>' 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 |
| GDB provides support for enabling and disabling individual printers. |
| For example, if '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 from Scheme by calling |
| 'set-pretty-printer-enabled!'. *Note Guile Pretty Printing API::. |
| |
| |
| File: gdb.info, Node: Writing a Guile Pretty-Printer, Next: Commands In Guile, Prev: Selecting Guile Pretty-Printers, Up: Guile API |
| |
| 23.3.3.10 Writing a Guile Pretty-Printer |
| ........................................ |
| |
| A pretty-printer consists of two basic parts: a lookup function to |
| determine if the type is supported, and the printer itself. |
| |
| Here is an example showing how a 'std::string' printer might be |
| written. *Note Guile Pretty Printing API::, for details. |
| |
| (define (make-my-string-printer value) |
| "Print a my::string string" |
| (make-pretty-printer-worker |
| "string" |
| (lambda (printer) |
| (value-field value "_data")) |
| #f)) |
| |
| And here is an example showing how a lookup function for the printer |
| example above might be written. |
| |
| (define (str-lookup-function pretty-printer value) |
| (let ((tag (type-tag (value-type value)))) |
| (and tag |
| (string-prefix? "std::string<" tag) |
| (make-my-string-printer value)))) |
| |
| Then to register this printer in the global printer list: |
| |
| (append-pretty-printer! |
| (make-pretty-printer "my-string" str-lookup-function)) |
| |
| 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 <gdb:pretty-printer-worker> |
| object. If not, it returns '#f'. |
| |
| We recommend that you put your core pretty-printers into a Guile |
| 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 GDB to load multiple versions of your |
| pretty-printers at the same time, because they will have different |
| names. |
| |
| You should write auto-loaded code (*note Guile Auto-loading::) such |
| that it can be evaluated multiple times without changing its meaning. |
| An ideal auto-load file will consist solely of '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 Guile package name will ensure that |
| GDB 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, GDB will find the correct printers for the specific |
| version of the library used by each inferior. |
| |
| To continue the 'my::string' example, this code might appear in |
| '(my-project my-library v1)': |
| |
| (use-modules (gdb)) |
| (define (register-printers objfile) |
| (append-objfile-pretty-printer! |
| (make-pretty-printer "my-string" str-lookup-function))) |
| |
| And then the corresponding contents of the auto-load file would be: |
| |
| (use-modules (gdb) (my-project my-library v1)) |
| (register-printers (current-objfile)) |
| |
| The previous example illustrates a basic pretty-printer. There are a |
| few things that can be improved on. 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 "subprinters" are the printers for the |
| individual data types. |
| |
| The '(gdb printing)' module provides a formal way of solving this |
| problem (*note Guile Printing Module::). Here is another example that |
| handles multiple types. |
| |
| These are the types we are going to pretty-print: |
| |
| struct foo { int a, b; }; |
| struct bar { struct foo x, y; }; |
| |
| Here are the printers: |
| |
| (define (make-foo-printer value) |
| "Print a foo object" |
| (make-pretty-printer-worker |
| "foo" |
| (lambda (printer) |
| (format #f "a=<~a> b=<~a>" |
| (value-field value "a") (value-field value "a"))) |
| #f)) |
| |
| (define (make-bar-printer value) |
| "Print a bar object" |
| (make-pretty-printer-worker |
| "foo" |
| (lambda (printer) |
| (format #f "x=<~a> y=<~a>" |
| (value-field value "x") (value-field value "y"))) |
| #f)) |
| |
| This example doesn't need a lookup function, that is handled by the |
| '(gdb printing)' module. Instead a function is provided to build up the |
| object that handles the lookup. |
| |
| (use-modules (gdb printing)) |
| |
| (define (build-pretty-printer) |
| (let ((pp (make-pretty-printer-collection "my-library"))) |
| (pp-collection-add-tag-printer "foo" make-foo-printer) |
| (pp-collection-add-tag-printer "bar" make-bar-printer) |
| pp)) |
| |
| And here is the autoload support: |
| |
| (use-modules (gdb) (my-library)) |
| (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer)) |
| |
| Finally, when this printer is loaded into GDB, here is the |
| corresponding output of 'info pretty-printer': |
| |
| (gdb) info pretty-printer |
| my_library.so: |
| my-library |
| foo |
| bar |
| |
| |
| File: gdb.info, Node: Commands In Guile, Next: Parameters In Guile, Prev: Writing a Guile Pretty-Printer, Up: Guile API |
| |
| 23.3.3.11 Commands In Guile |
| ........................... |
| |
| You can implement new GDB CLI commands in Guile. A CLI command object |
| is created with the 'make-command' Guile function, and added to GDB with |
| the 'register-command!' Guile function. This two-step approach is taken |
| to separate out the side-effect of adding the command to GDB from |
| 'make-command'. |
| |
| There is no support for multi-line commands, that is commands that |
| consist of multiple lines and are terminated with 'end'. |
| |
| -- Scheme Procedure: (make-command name [#:invoke invoke] |
| [#:command-class command-class] [#:completer-class completer] |
| [#:prefix? prefix] [#:doc doc-string]) |
| |
| The argument NAME is the name of the command. If 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. |
| |
| The result is the '<gdb:command>' object representing the command. |
| The command is not usable until it has been registered with GDB |
| with 'register-command!'. |
| |
| The rest of the arguments are optional. |
| |
| The argument INVOKE is a procedure of three arguments: SELF, ARGS |
| and FROM-TTY. The argument SELF is the '<gdb:command>' object |
| representing the command. The argument ARGS is a string |
| representing the arguments passed to the command, after leading and |
| trailing whitespace has been stripped. The argument FROM-TTY is a |
| boolean flag and specifies whether the command should consider |
| itself to have been originated from the user invoking it |
| interactively. If this function throws an exception, it is turned |
| into a GDB 'error' call. Otherwise, the return value is ignored. |
| |
| The argument COMMAND-CLASS is one of the 'COMMAND_' constants |
| defined below. This argument tells GDB how to categorize the new |
| command in the help system. The default is 'COMMAND_NONE'. |
| |
| The argument COMPLETER is either '#f', one of the 'COMPLETE_' |
| constants defined below, or a procedure, also defined below. This |
| argument tells GDB how to perform completion for this command. If |
| not provided or if the value is '#f', then no completion is |
| performed on the command. |
| |
| The argument PREFIX is a boolean flag indicating whether the new |
| command is a prefix command; sub-commands of this command may be |
| registered. |
| |
| The argument DOC-STRING is help text for the new command. If no |
| documentation string is provided, the default value "This command |
| is not documented." is used. |
| |
| -- Scheme Procedure: register-command! command |
| Add COMMAND, a '<gdb:command>' object, to GDB's list of commands. |
| It is an error to register a command more than once. The result is |
| unspecified. |
| |
| -- Scheme Procedure: command? object |
| Return '#t' if OBJECT is a '<gdb:command>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: dont-repeat |
| By default, a GDB command is repeated when the user enters a blank |
| line at the command prompt. A command can suppress this behavior |
| by invoking the 'dont-repeat' function. This is similar to the |
| user command 'dont-repeat', see *note dont-repeat: Define. |
| |
| -- Scheme Procedure: string->argv string |
| Convert a string to a list of strings split up according to GDB's |
| argv parsing rules. It is recommended to use this for consistency. |
| Arguments are separated by spaces and may be quoted. Example: |
| |
| scheme@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"") |
| $1 = ("1" "2 \"3" "4 \"5" "6 '7") |
| |
| -- Scheme Procedure: throw-user-error message . args |
| Throw a 'gdb:user-error' exception. The argument MESSAGE is the |
| error message as a format string, like the FMT argument to the |
| 'format' Scheme function. *Note (guile)Formatted Output::. The |
| argument ARGS is a list of the optional arguments of MESSAGE. |
| |
| This is used when the command detects a user error of some kind, |
| say a bad command argument. |
| |
| (gdb) guile (use-modules (gdb)) |
| (gdb) guile |
| (register-command! (make-command "test-user-error" |
| #:command-class COMMAND_OBSCURE |
| #:invoke (lambda (self arg from-tty) |
| (throw-user-error "Bad argument ~a" arg)))) |
| end |
| (gdb) test-user-error ugh |
| ERROR: Bad argument ugh |
| |
| -- completer: self text word |
| If the COMPLETER option to 'make-command' is a procedure, it takes |
| three arguments: SELF which is the '<gdb:command>' object, and TEXT |
| and WORD which are both strings. The argument TEXT holds the |
| complete command line up to the cursor's location. The argument |
| WORD holds the last word of the command line; this is computed |
| using a word-breaking heuristic. |
| |
| All forms of completion are handled by this function, that is, the |
| <TAB> and <M-?> key bindings (*note Completion::), and the |
| 'complete' command (*note complete: Help.). |
| |
| This procedure can return several kinds of values: |
| |
| * If the return value is a list, the contents of the list are |
| used as the completions. It is up to COMPLETER to ensure that |
| the contents actually do complete the word. An empty list is |
| allowed, it means that there were no completions available. |
| Only string elements of the list are used; other elements in |
| the list are ignored. |
| |
| * If the return value is a '<gdb:iterator>' object, it is |
| iterated over to obtain the completions. It is up to |
| 'completer-procedure' to ensure that the results actually do |
| complete the word. Only string elements of the result are |
| used; other elements in the sequence are ignored. |
| |
| * All other results are treated as though there were no |
| available completions. |
| |
| When a new command is registered, it will have been 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 'gdb' module: |
| |
| '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. |
| This is the default. |
| |
| 'COMMAND_RUNNING' |
| The command is related to running the inferior. For example, |
| 'start', 'step', and 'continue' are in this category. Type 'help |
| running' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'COMMAND_DATA' |
| The command is related to data or variables. For example, 'call', |
| 'find', and 'print' are in this category. Type 'help data' at the |
| GDB prompt to see a list of commands in this category. |
| |
| 'COMMAND_STACK' |
| The command has to do with manipulation of the stack. For example, |
| 'backtrace', 'frame', and 'return' are in this category. Type |
| 'help stack' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'COMMAND_FILES' |
| This class is used for file-related commands. For example, 'file', |
| 'list' and 'section' are in this category. Type 'help files' at |
| the GDB prompt to see a list of commands in this category. |
| |
| 'COMMAND_SUPPORT' |
| This should be used for "support facilities", generally meaning |
| things that are useful to the user when interacting with GDB, but |
| not related to the state of the inferior. For example, 'help', |
| 'make', and 'shell' are in this category. Type 'help support' at |
| the GDB prompt to see a list of commands in this category. |
| |
| 'COMMAND_STATUS' |
| The command is an 'info'-related command, that is, related to the |
| state of GDB itself. For example, 'info', 'macro', and 'show' are |
| in this category. Type 'help status' at the GDB prompt to see a |
| list of commands in this category. |
| |
| 'COMMAND_BREAKPOINTS' |
| The command has to do with breakpoints. For example, 'break', |
| 'clear', and 'delete' are in this category. Type 'help |
| breakpoints' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'COMMAND_TRACEPOINTS' |
| The command has to do with tracepoints. For example, 'trace', |
| 'actions', and 'tfind' are in this category. Type 'help |
| tracepoints' at the GDB prompt to see a list of commands in this |
| category. |
| |
| 'COMMAND_USER' |
| The command is a general purpose command for the user, and |
| typically does not fit in one of the other categories. Type 'help |
| user-defined' at the GDB prompt to see a list of commands in this |
| category, as well as the list of gdb macros (*note Sequences::). |
| |
| 'COMMAND_OBSCURE' |
| The command is only used in unusual circumstances, or is not of |
| general interest to users. For example, 'checkpoint', 'fork', and |
| 'stop' are in this category. Type 'help obscure' at the GDB prompt |
| to see a list of commands in this category. |
| |
| 'COMMAND_MAINTENANCE' |
| The command is only useful to GDB maintainers. The 'maintenance' |
| and 'flushregs' commands are in this category. Type 'help |
| internals' at the GDB prompt to see a list of commands in this |
| category. |
| |
| A new command can use a predefined completion function, either by |
| specifying it via an argument at initialization, or by returning it from |
| the 'completer' procedure. These predefined completion constants are |
| all defined in the 'gdb' module: |
| |
| 'COMPLETE_NONE' |
| This constant means that no completion should be done. |
| |
| 'COMPLETE_FILENAME' |
| This constant means that filename completion should be performed. |
| |
| 'COMPLETE_LOCATION' |
| This constant means that location completion should be done. *Note |
| Specify Location::. |
| |
| 'COMPLETE_COMMAND' |
| This constant means that completion should examine GDB command |
| names. |
| |
| 'COMPLETE_SYMBOL' |
| This constant means that completion should be done using symbol |
| names as the source. |
| |
| '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. |
| |
| The following code snippet shows how a trivial CLI command can be |
| implemented in Guile: |
| |
| (gdb) guile |
| (register-command! (make-command "hello-world" |
| #:command-class COMMAND_USER |
| #:doc "Greet the whole world." |
| #:invoke (lambda (self args from-tty) (display "Hello, World!\n")))) |
| end |
| (gdb) hello-world |
| Hello, World! |
| |
| |
| File: gdb.info, Node: Parameters In Guile, Next: Progspaces In Guile, Prev: Commands In Guile, Up: Guile API |
| |
| 23.3.3.12 Parameters In Guile |
| ............................. |
| |
| You can implement new GDB "parameters" using Guile (1). |
| |
| There are many parameters that already exist and can be set in GDB. |
| Two examples are: 'set follow-fork' and 'set charset'. Setting these |
| parameters influences certain behavior in GDB. Similarly, you can |
| define parameters that can be used to influence behavior in custom Guile |
| scripts and commands. |
| |
| A new parameter is defined with the 'make-parameter' Guile function, |
| and added to GDB with the 'register-parameter!' Guile function. This |
| two-step approach is taken to separate out the side-effect of adding the |
| parameter to GDB from 'make-parameter'. |
| |
| Parameters are exposed to the user via the 'set' and 'show' commands. |
| *Note Help::. |
| |
| -- Scheme Procedure: (make-parameter name [#:command-class |
| command-class] [#:parameter-type parameter-type] [#:enum-list |
| enum-list] [#:set-func set-func] [#:show-func show-func] |
| [#:doc doc] [#:set-doc set-doc] [#:show-doc show-doc] |
| [#:initial-value initial-value]) |
| |
| The argument NAME is the name of the new parameter. If NAME |
| consists of multiple words, then the initial words are looked for |
| as prefix parameters. An example of this can be illustrated with |
| the 'set print' set of parameters. If NAME is 'print foo', then |
| 'print' will be searched as the prefix parameter. In this case the |
| parameter can subsequently be accessed in GDB as 'set print foo'. |
| If NAME consists of multiple words, and no prefix parameter group |
| can be found, an exception is raised. |
| |
| The result is the '<gdb:parameter>' object representing the |
| parameter. The parameter is not usable until it has been |
| registered with GDB with 'register-parameter!'. |
| |
| The rest of the arguments are optional. |
| |
| The argument COMMAND-CLASS should be one of the 'COMMAND_' |
| constants (*note Commands In Guile::). This argument tells GDB how |
| to categorize the new parameter in the help system. The default is |
| 'COMMAND_NONE'. |
| |
| The argument PARAMETER-TYPE should be one of the 'PARAM_' constants |
| defined below. This argument tells GDB the type of the new |
| parameter; this information is used for input validation and |
| completion. The default is 'PARAM_BOOLEAN'. |
| |
| If PARAMETER-TYPE is 'PARAM_ENUM', then ENUM-LIST must be a list of |
| strings. These strings represent the possible values for the |
| parameter. |
| |
| If PARAMETER-TYPE is not 'PARAM_ENUM', then the presence of |
| ENUM-LIST will cause an exception to be thrown. |
| |
| The argument SET-FUNC is a function of one argument: SELF which is |
| the '<gdb:parameter>' object representing the parameter. GDB will |
| call this function when a PARAMETER's value has been changed via |
| the 'set' API (for example, 'set foo off'). The value of the |
| parameter has already been set to the new value. This function |
| must return a string to be displayed to the user. GDB will add a |
| trailing newline if the string is non-empty. GDB generally doesn't |
| print anything when a parameter is set, thus typically this |
| function should return '""'. A non-empty string result should |
| typically be used for displaying warnings and errors. |
| |
| The argument SHOW-FUNC is a function of two arguments: SELF which |
| is the '<gdb:parameter>' object representing the parameter, and |
| SVALUE which is the string representation of the current value. |
| GDB will call this function when a PARAMETER's 'show' API has been |
| invoked (for example, 'show foo'). This function must return a |
| string, and will be displayed to the user. GDB will add a trailing |
| newline. |
| |
| The argument DOC is the help text for the new parameter. If there |
| is no documentation string, a default value is used. |
| |
| The argument SET-DOC is the help text for this parameter's 'set' |
| command. |
| |
| The argument SHOW-DOC is the help text for this parameter's 'show' |
| command. |
| |
| The argument INITIAL-VALUE specifies the initial value of the |
| parameter. If it is a function, it takes one parameter, the |
| '<gdb:parameter>' object and its result is used as the initial |
| value of the parameter. The initial value must be valid for the |
| parameter type, otherwise an exception is thrown. |
| |
| -- Scheme Procedure: register-parameter! parameter |
| Add PARAMETER, a '<gdb:parameter>' object, to GDB's list of |
| parameters. It is an error to register a parameter more than once. |
| The result is unspecified. |
| |
| -- Scheme Procedure: parameter? object |
| Return '#t' if OBJECT is a '<gdb:parameter>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: parameter-value parameter |
| Return the value of PARAMETER which may either be a |
| '<gdb:parameter>' object or a string naming the parameter. |
| |
| -- Scheme Procedure: set-parameter-value! parameter new-value |
| Assign PARAMETER the value of NEW-VALUE. The argument PARAMETER |
| must be an object of type '<gdb:parameter>'. GDB does validation |
| when assignments are made. |
| |
| When a new parameter is defined, its type must be specified. The |
| available types are represented by constants defined in the 'gdb' |
| module: |
| |
| 'PARAM_BOOLEAN' |
| The value is a plain boolean. The Guile boolean values, '#t' and |
| '#f' are the only valid values. |
| |
| 'PARAM_AUTO_BOOLEAN' |
| The value has three possible states: true, false, and 'auto'. In |
| Guile, true and false are represented using boolean constants, and |
| 'auto' is represented using '#:auto'. |
| |
| 'PARAM_UINTEGER' |
| The value is an unsigned integer. The value of 0 should be |
| interpreted to mean "unlimited". |
| |
| 'PARAM_ZINTEGER' |
| The value is an integer. |
| |
| 'PARAM_ZUINTEGER' |
| The value is an unsigned integer. |
| |
| 'PARAM_ZUINTEGER_UNLIMITED' |
| The value is an integer in the range '[0, INT_MAX]'. A value of |
| '-1' means "unlimited", and other negative numbers are not allowed. |
| |
| 'PARAM_STRING' |
| The value is a string. When the user modifies the string, any |
| escape sequences, such as '\t', '\f', and octal escapes, are |
| translated into corresponding characters and encoded into the |
| current host charset. |
| |
| 'PARAM_STRING_NOESCAPE' |
| The value is a string. When the user modifies the string, escapes |
| are passed through untranslated. |
| |
| 'PARAM_OPTIONAL_FILENAME' |
| The value is a either a filename (a string), or '#f'. |
| |
| 'PARAM_FILENAME' |
| The value is a filename. This is just like |
| 'PARAM_STRING_NOESCAPE', but uses file names for completion. |
| |
| 'PARAM_ENUM' |
| The value is a string, which must be one of a collection of string |
| constants provided when the parameter is created. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Note that GDB parameters must not be confused with Guile’s |
| parameter objects (*note (guile)Parameters::). |
| |
| |
| File: gdb.info, Node: Progspaces In Guile, Next: Objfiles In Guile, Prev: Parameters In Guile, Up: Guile API |
| |
| 23.3.3.13 Program Spaces In Guile |
| ................................. |
| |
| A program space, or "progspace", represents a symbolic view of an |
| address space. It consists of all of the objfiles of the program. |
| *Note Objfiles In Guile::. *Note program spaces: Inferiors and |
| Programs, for more details about program spaces. |
| |
| Each progspace is represented by an instance of the '<gdb:progspace>' |
| smob. *Note GDB Scheme Data Types::. |
| |
| The following progspace-related functions are available in the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: progspace? object |
| Return '#t' if OBJECT is a '<gdb:progspace>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: progspace-valid? progspace |
| Return '#t' if PROGSPACE is valid, '#f' if not. A |
| '<gdb:progspace>' object can become invalid if the program it |
| refers to is not loaded in GDB any longer. |
| |
| -- Scheme Procedure: current-progspace |
| This function returns the program space of the currently selected |
| inferior. There is always a current progspace, this never returns |
| '#f'. *Note Inferiors and Programs::. |
| |
| -- Scheme Procedure: progspaces |
| Return a list of all the progspaces currently known to GDB. |
| |
| -- Scheme Procedure: progspace-filename progspace |
| Return the absolute file name of PROGSPACE as a string. This is |
| the name of the file passed as the argument to the 'file' or |
| 'symbol-file' commands. If the program space does not have an |
| associated file name, then '#f' is returned. This occurs, for |
| example, when GDB is started without a program to debug. |
| |
| A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is |
| invalid. |
| |
| -- Scheme Procedure: progspace-objfiles progspace |
| Return the list of objfiles of PROGSPACE. The order of objfiles in |
| the result is arbitrary. Each element is an object of type |
| '<gdb:objfile>'. *Note Objfiles In Guile::. |
| |
| A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is |
| invalid. |
| |
| -- Scheme Procedure: progspace-pretty-printers progspace |
| Return the list of pretty-printers of PROGSPACE. Each element is |
| an object of type '<gdb:pretty-printer>'. *Note Guile Pretty |
| Printing API::, for more information. |
| |
| -- Scheme Procedure: set-progspace-pretty-printers! progspace |
| printer-list |
| Set the list of registered '<gdb:pretty-printer>' objects for |
| PROGSPACE to PRINTER-LIST. *Note Guile Pretty Printing API::, for |
| more information. |
| |
| |
| File: gdb.info, Node: Objfiles In Guile, Next: Frames In Guile, Prev: Progspaces In Guile, Up: Guile API |
| |
| 23.3.3.14 Objfiles In Guile |
| ........................... |
| |
| GDB loads symbols for an inferior from various symbol-containing files |
| (*note Files::). These include the primary executable file, any shared |
| libraries used by the inferior, and any separate debug info files (*note |
| Separate Debug Files::). GDB calls these symbol-containing files |
| "objfiles". |
| |
| Each objfile is represented as an object of type '<gdb:objfile>'. |
| |
| The following objfile-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: objfile? object |
| Return '#t' if OBJECT is a '<gdb:objfile>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: objfile-valid? objfile |
| Return '#t' if OBJFILE is valid, '#f' if not. A '<gdb:objfile>' |
| object can become invalid if the object file it refers to is not |
| loaded in GDB any longer. All other '<gdb:objfile>' procedures |
| will throw an exception if it is invalid at the time the procedure |
| is called. |
| |
| -- Scheme Procedure: objfile-filename objfile |
| Return the file name of OBJFILE as a string, with symbolic links |
| resolved. |
| |
| -- Scheme Procedure: objfile-progspace objfile |
| Return the '<gdb:progspace>' that this object file lives in. *Note |
| Progspaces In Guile::, for more on progspaces. |
| |
| -- Scheme Procedure: objfile-pretty-printers objfile |
| Return the list of registered '<gdb:pretty-printer>' objects for |
| OBJFILE. *Note Guile Pretty Printing API::, for more information. |
| |
| -- Scheme Procedure: set-objfile-pretty-printers! objfile printer-list |
| Set the list of registered '<gdb:pretty-printer>' objects for |
| OBJFILE to PRINTER-LIST. The PRINTER-LIST must be a list of |
| '<gdb:pretty-printer>' objects. *Note Guile Pretty Printing API::, |
| for more information. |
| |
| -- Scheme Procedure: current-objfile |
| When auto-loading a Guile script (*note Guile Auto-loading::), GDB |
| sets the "current objfile" to the corresponding objfile. This |
| function returns the current objfile. If there is no current |
| objfile, this function returns '#f'. |
| |
| -- Scheme Procedure: objfiles |
| Return a list of all the objfiles in the current program space. |
| |
| |
| File: gdb.info, Node: Frames In Guile, Next: Blocks In Guile, Prev: Objfiles In Guile, Up: Guile API |
| |
| 23.3.3.15 Accessing inferior stack frames from Guile. |
| ..................................................... |
| |
| When the debugged program stops, GDB is able to analyze its call stack |
| (*note Stack frames: Frames.). The '<gdb:frame>' class represents a |
| frame in the stack. A '<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, GDB will throw a 'gdb:invalid-object' exception |
| (*note Guile Exception Handling::). |
| |
| Two '<gdb:frame>' objects can be compared for equality with the |
| 'equal?' function, like: |
| |
| (gdb) guile (equal? (newest-frame) (selected-frame)) |
| #t |
| |
| The following frame-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: frame? object |
| Return '#t' if OBJECT is a '<gdb:frame>' object. Otherwise return |
| '#f'. |
| |
| -- Scheme Procedure: frame-valid? frame |
| Returns '#t' if FRAME is valid, '#f' if not. A frame object can |
| become invalid if the frame it refers to doesn't exist anymore in |
| the inferior. All '<gdb:frame>' procedures will throw an exception |
| if the frame is invalid at the time the procedure is called. |
| |
| -- Scheme Procedure: frame-name frame |
| Return the function name of FRAME, or '#f' if it can't be obtained. |
| |
| -- Scheme Procedure: frame-arch frame |
| Return the '<gdb:architecture>' object corresponding to FRAME's |
| architecture. *Note Architectures In Guile::. |
| |
| -- Scheme Procedure: frame-type frame |
| Return the type of FRAME. The value can be one of: |
| |
| 'NORMAL_FRAME' |
| An ordinary stack frame. |
| |
| 'DUMMY_FRAME' |
| A fake stack frame that was created by GDB when performing an |
| inferior function call. |
| |
| 'INLINE_FRAME' |
| A frame representing an inlined function. The function was |
| inlined into a 'NORMAL_FRAME' that is older than this one. |
| |
| 'TAILCALL_FRAME' |
| A frame representing a tail call. *Note Tail Call Frames::. |
| |
| 'SIGTRAMP_FRAME' |
| A signal trampoline frame. This is the frame created by the |
| OS when it calls into a signal handler. |
| |
| 'ARCH_FRAME' |
| A fake stack frame representing a cross-architecture call. |
| |
| 'SENTINEL_FRAME' |
| This is like 'NORMAL_FRAME', but it is only used for the |
| newest frame. |
| |
| -- Scheme Procedure: frame-unwind-stop-reason frame |
| Return an integer representing the reason why it's not possible to |
| find more frames toward the outermost frame. Use |
| 'unwind-stop-reason-string' to convert the value returned by this |
| function to a string. The value can be one of: |
| |
| 'FRAME_UNWIND_NO_REASON' |
| No particular reason (older frames should be available). |
| |
| 'FRAME_UNWIND_NULL_ID' |
| The previous frame's analyzer returns an invalid result. |
| |
| 'FRAME_UNWIND_OUTERMOST' |
| This frame is the outermost. |
| |
| 'FRAME_UNWIND_UNAVAILABLE' |
| Cannot unwind further, because that would require knowing the |
| values of registers or memory that have not been collected. |
| |
| '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. |
| |
| '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. |
| |
| 'FRAME_UNWIND_NO_SAVED_PC' |
| The frame unwinder did not find any saved PC, but we needed |
| one to unwind further. |
| |
| 'FRAME_UNWIND_MEMORY_ERROR' |
| The frame unwinder caused an error while trying to access |
| memory. |
| |
| '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 GDB versions. Using it, you could write: |
| |
| (define reason (frame-unwind-stop-readon (selected-frame))) |
| (define reason-str (unwind-stop-reason-string reason)) |
| (if (>= reason FRAME_UNWIND_FIRST_ERROR) |
| (format #t "An error occured: ~s\n" reason-str)) |
| |
| -- Scheme Procedure: frame-pc frame |
| Return the frame's resume address. |
| |
| -- Scheme Procedure: frame-block frame |
| Return the frame's code block as a '<gdb:block>' object. *Note |
| Blocks In Guile::. |
| |
| -- Scheme Procedure: frame-function frame |
| Return the symbol for the function corresponding to this frame as a |
| '<gdb:symbol>' object, or '#f' if there isn't one. *Note Symbols |
| In Guile::. |
| |
| -- Scheme Procedure: frame-older frame |
| Return the frame that called FRAME. |
| |
| -- Scheme Procedure: frame-newer frame |
| Return the frame called by FRAME. |
| |
| -- Scheme Procedure: frame-sal frame |
| Return the frame's '<gdb:sal>' (symtab and line) object. *Note |
| Symbol Tables In Guile::. |
| |
| -- Scheme Procedure: frame-read-register frame register |
| Return the value of REGISTER in FRAME. REGISTER should be a |
| string, like 'pc'. |
| |
| -- Scheme Procedure: frame-read-var frame variable [#:block block] |
| Return the value of VARIABLE in FRAME. If the optional argument |
| 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). The VARIABLE must be |
| given as a string or a '<gdb:symbol>' object, and BLOCK must be a |
| '<gdb:block>' object. |
| |
| -- Scheme Procedure: frame-select frame |
| Set FRAME to be the selected frame. *Note Examining the Stack: |
| Stack. |
| |
| -- Scheme Procedure: selected-frame |
| Return the selected frame object. *Note Selecting a Frame: |
| Selection. |
| |
| -- Scheme Procedure: newest-frame |
| Return the newest frame object for the selected thread. |
| |
| -- Scheme Procedure: unwind-stop-reason-string reason |
| Return a string explaining the reason why GDB stopped unwinding |
| frames, as expressed by the given REASON code (an integer, see the |
| 'frame-unwind-stop-reason' procedure above in this section). |
| |
| |
| File: gdb.info, Node: Blocks In Guile, Next: Symbols In Guile, Prev: Frames In Guile, Up: Guile API |
| |
| 23.3.3.16 Accessing blocks from Guile. |
| ...................................... |
| |
| In GDB, 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 Guile as an object of type '<gdb:block>'. |
| Blocks rely on debugging information being available. |
| |
| A frame has a block. Please see *note Frames In Guile::, for a more |
| in-depth discussion of frames. |
| |
| The outermost block is known as the "global block". The global block |
| typically holds public global variables and functions. |
| |
| The block nested just inside the global block is the "static block". |
| The static block typically holds file-scoped variables and functions. |
| |
| GDB 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 (*note Symbol Tables In Guile::). |
| |
| Here is a short example that should help explain blocks: |
| |
| /* 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 (); |
| } |
| } |
| |
| The following block-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: block? object |
| Return '#t' if OBJECT is a '<gdb:block>' object. Otherwise return |
| '#f'. |
| |
| -- Scheme Procedure: block-valid? block |
| Returns '#t' if '<gdb:block>' BLOCK is valid, '#f' if not. A block |
| object can become invalid if the block it refers to doesn't exist |
| anymore in the inferior. All other '<gdb:block>' methods will |
| throw an exception if it is invalid at the time the procedure is |
| called. The block's validity is also checked during iteration over |
| symbols of the block. |
| |
| -- Scheme Procedure: block-start block |
| Return the start address of '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: block-end block |
| Return the end address of '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: block-function block |
| Return the name of '<gdb:block>' BLOCK represented as a |
| '<gdb:symbol>' object. If the block is not named, then '#f' is |
| returned. |
| |
| 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. |
| |
| -- Scheme Procedure: block-superblock block |
| Return the block containing '<gdb:block>' BLOCK. If the parent |
| block does not exist, then '#f' is returned. |
| |
| -- Scheme Procedure: block-global-block block |
| Return the global block associated with '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: block-static-block block |
| Return the static block associated with '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: block-global? block |
| Return '#t' if '<gdb:block>' BLOCK is a global block. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: block-static? block |
| Return '#t' if '<gdb:block>' BLOCK is a static block. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: block-symbols |
| Return a list of all symbols (as <gdb:symbol> objects) in |
| '<gdb:block>' BLOCK. |
| |
| -- Scheme Procedure: make-block-symbols-iterator block |
| Return an object of type '<gdb:iterator>' that will iterate over |
| all symbols of the block. Guile programs should not assume that a |
| specific block object will always contain a given symbol, since |
| changes in GDB features and infrastructure may cause symbols move |
| across blocks in a symbol table. *Note Iterators In Guile::. |
| |
| -- Scheme Procedure: block-symbols-progress? |
| Return #t if the object is a <gdb:block-symbols-progress> object. |
| This object would be obtained from the 'progress' element of the |
| '<gdb:iterator>' object returned by 'make-block-symbols-iterator'. |
| |
| -- Scheme Procedure: lookup-block pc |
| Return the innermost '<gdb:block>' containing the given PC value. |
| If the block cannot be found for the PC value specified, the |
| function will return '#f'. |
| |
| |
| File: gdb.info, Node: Symbols In Guile, Next: Symbol Tables In Guile, Prev: Blocks In Guile, Up: Guile API |
| |
| 23.3.3.17 Guile representation of Symbols. |
| .......................................... |
| |
| GDB represents every variable, function and type as an entry in a symbol |
| table. *Note Examining the Symbol Table: Symbols. Guile represents |
| these symbols in GDB with the '<gdb:symbol>' object. |
| |
| The following symbol-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: symbol? object |
| Return '#t' if OBJECT is an object of type '<gdb:symbol>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: symbol-valid? symbol |
| Return '#t' if the '<gdb:symbol>' object is valid, '#f' if not. A |
| '<gdb:symbol>' object can become invalid if the symbol it refers to |
| does not exist in GDB any longer. All other '<gdb:symbol>' |
| procedures will throw an exception if it is invalid at the time the |
| procedure is called. |
| |
| -- Scheme Procedure: symbol-type symbol |
| Return the type of SYMBOL or '#f' if no type is recorded. The |
| result is an object of type '<gdb:type>'. *Note Types In Guile::. |
| |
| -- Scheme Procedure: symbol-symtab symbol |
| Return the symbol table in which SYMBOL appears. The result is an |
| object of type '<gdb:symtab>'. *Note Symbol Tables In Guile::. |
| |
| -- Scheme Procedure: symbol-line symbol |
| Return the line number in the source code at which SYMBOL was |
| defined. This is an integer. |
| |
| -- Scheme Procedure: symbol-name symbol |
| Return the name of SYMBOL as a string. |
| |
| -- Scheme Procedure: symbol-linkage-name symbol |
| Return the name of SYMBOL, as used by the linker (i.e., may be |
| mangled). |
| |
| -- Scheme Procedure: symbol-print-name symbol |
| Return the name of SYMBOL in a form suitable for output. This is |
| either 'name' or 'linkage_name', depending on whether the user |
| asked GDB to display demangled or mangled names. |
| |
| -- Scheme Procedure: symbol-addr-class symbol |
| Return 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 '(gdb)' module and described later in this chapter. |
| |
| -- Scheme Procedure: symbol-needs-frame? symbol |
| Return '#t' if evaluating SYMBOL's value requires a frame (*note |
| Frames In Guile::) and '#f' otherwise. Typically, local variables |
| will require a frame, but other symbols will not. |
| |
| -- Scheme Procedure: symbol-argument? symbol |
| Return '#t' if SYMBOL is an argument of a function. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: symbol-constant? symbol |
| Return '#t' if SYMBOL is a constant. Otherwise return '#f'. |
| |
| -- Scheme Procedure: symbol-function? symbol |
| Return '#t' if SYMBOL is a function or a method. Otherwise return |
| '#f'. |
| |
| -- Scheme Procedure: symbol-variable? symbol |
| Return '#t' if SYMBOL is a variable. Otherwise return '#f'. |
| |
| -- Scheme Procedure: symbol-value symbol [#:frame frame] |
| Compute the value of SYMBOL, as a '<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 FRAME must be given. If FRAME is not given, or if |
| FRAME is invalid, then an exception is thrown. |
| |
| -- Scheme Procedure: lookup-symbol name [#:block block] [#:domain |
| domain] |
| 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. |
| |
| NAME is the name of the symbol. It must be a string. The optional |
| BLOCK argument restricts the search to symbols visible in that |
| BLOCK. The BLOCK argument must be a '<gdb:block>' object. If |
| omitted, the block for the current frame is used. The optional |
| DOMAIN argument restricts the search to the domain type. The |
| DOMAIN argument must be a domain constant defined in the '(gdb)' |
| module and described later in this chapter. |
| |
| The result is a list of two elements. The first element is a |
| '<gdb:symbol>' object or '#f' if the symbol is not found. If the |
| symbol is found, the second element is '#t' if the symbol is a |
| field of a method's object (e.g., 'this' in C++), otherwise it is |
| '#f'. If the symbol is not found, the second element is '#f'. |
| |
| -- Scheme Procedure: lookup-global-symbol name [#:domain domain] |
| This function searches for a global symbol by name. The search |
| scope can be restricted by the domain argument. |
| |
| NAME is the name of the symbol. It must be a string. The optional |
| DOMAIN argument restricts the search to the domain type. The |
| DOMAIN argument must be a domain constant defined in the '(gdb)' |
| module and described later in this chapter. |
| |
| The result is a '<gdb:symbol>' object or '#f' if the symbol is not |
| found. |
| |
| The available domain categories in '<gdb:symbol>' are represented as |
| constants in the '(gdb)' module: |
| |
| '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 GDB's handling of symbols. |
| |
| 'SYMBOL_VAR_DOMAIN' |
| This domain contains variables, function names, typedef names and |
| enum type values. |
| |
| 'SYMBOL_STRUCT_DOMAIN' |
| This domain holds struct, union and enum type names. |
| |
| 'SYMBOL_LABEL_DOMAIN' |
| This domain contains names of labels (for gotos). |
| |
| 'SYMBOL_VARIABLES_DOMAIN' |
| This domain holds a subset of the 'SYMBOLS_VAR_DOMAIN'; it contains |
| everything minus functions and types. |
| |
| 'SYMBOL_FUNCTION_DOMAIN' |
| This domain contains all functions. |
| |
| 'SYMBOL_TYPES_DOMAIN' |
| This domain contains all types. |
| |
| The available address class categories in '<gdb:symbol>' are |
| represented as constants in the 'gdb' module: |
| |
| 'SYMBOL_LOC_UNDEF' |
| If this is returned by address class, it indicates an error either |
| in the symbol information or in GDB's handling of symbols. |
| |
| 'SYMBOL_LOC_CONST' |
| Value is constant int. |
| |
| 'SYMBOL_LOC_STATIC' |
| Value is at a fixed address. |
| |
| 'SYMBOL_LOC_REGISTER' |
| Value is in a register. |
| |
| 'SYMBOL_LOC_ARG' |
| Value is an argument. This value is at the offset stored within |
| the symbol inside the frame's argument list. |
| |
| 'SYMBOL_LOC_REF_ARG' |
| Value address is stored in the frame's argument list. Just like |
| 'LOC_ARG' except that the value's address is stored at the offset, |
| not the value itself. |
| |
| 'SYMBOL_LOC_REGPARM_ADDR' |
| Value is a specified register. Just like 'LOC_REGISTER' except the |
| register holds the address of the argument instead of the argument |
| itself. |
| |
| 'SYMBOL_LOC_LOCAL' |
| Value is a local variable. |
| |
| 'SYMBOL_LOC_TYPEDEF' |
| Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all |
| have this class. |
| |
| 'SYMBOL_LOC_BLOCK' |
| Value is a block. |
| |
| 'SYMBOL_LOC_CONST_BYTES' |
| Value is a byte-sequence. |
| |
| '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. |
| |
| 'SYMBOL_LOC_OPTIMIZED_OUT' |
| The value does not actually exist in the program. |
| |
| 'SYMBOL_LOC_COMPUTED' |
| The value's address is a computed location. |
| |
| |
| File: gdb.info, Node: Symbol Tables In Guile, Next: Breakpoints In Guile, Prev: Symbols In Guile, Up: Guile API |
| |
| 23.3.3.18 Symbol table representation in Guile. |
| ............................................... |
| |
| Access to symbol table data maintained by GDB on the inferior is exposed |
| to Guile via two objects: '<gdb:sal>' (symtab-and-line) and |
| '<gdb:symtab>'. Symbol table and line data for a frame is returned from |
| the 'frame-find-sal' '<gdb:frame>' procedure. *Note Frames In Guile::. |
| |
| For more information on GDB's symbol table management, see *note |
| Examining the Symbol Table: Symbols. |
| |
| The following symtab-related procedures are provided by the '(gdb)' |
| module: |
| |
| -- Scheme Procedure: symtab? object |
| Return '#t' if OBJECT is an object of type '<gdb:symtab>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: symtab-valid? symtab |
| Return '#t' if the '<gdb:symtab>' object is valid, '#f' if not. A |
| '<gdb:symtab>' object becomes invalid when the symbol table it |
| refers to no longer exists in GDB. All other '<gdb:symtab>' |
| procedures will throw an exception if it is invalid at the time the |
| procedure is called. |
| |
| -- Scheme Procedure: symtab-filename symtab |
| Return the symbol table's source filename. |
| |
| -- Scheme Procedure: symtab-fullname symtab |
| Return the symbol table's source absolute file name. |
| |
| -- Scheme Procedure: symtab-objfile symtab |
| Return the symbol table's backing object file. *Note Objfiles In |
| Guile::. |
| |
| -- Scheme Procedure: symtab-global-block symtab |
| Return the global block of the underlying symbol table. *Note |
| Blocks In Guile::. |
| |
| -- Scheme Procedure: symtab-static-block symtab |
| Return the static block of the underlying symbol table. *Note |
| Blocks In Guile::. |
| |
| The following symtab-and-line-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: sal? object |
| Return '#t' if OBJECT is an object of type '<gdb:sal>'. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: sal-valid? sal |
| Return '#t' if SAL is valid, '#f' if not. A '<gdb:sal>' object |
| becomes invalid when the Symbol table object it refers to no longer |
| exists in GDB. All other '<gdb:sal>' procedures will throw an |
| exception if it is invalid at the time the procedure is called. |
| |
| -- Scheme Procedure: sal-symtab sal |
| Return the symbol table object ('<gdb:symtab>') for SAL. |
| |
| -- Scheme Procedure: sal-line sal |
| Return the line number for SAL. |
| |
| -- Scheme Procedure: sal-pc sal |
| Return the start of the address range occupied by code for SAL. |
| |
| -- Scheme Procedure: sal-last sal |
| Return the end of the address range occupied by code for SAL. |
| |
| -- Scheme Procedure: find-pc-line pc |
| Return the '<gdb:sal>' object corresponding to the PC value. If an |
| invalid value of PC is passed as an argument, then the 'symtab' and |
| 'line' attributes of the returned '<gdb:sal>' object will be '#f' |
| and 0 respectively. |
| |
| |
| File: gdb.info, Node: Breakpoints In Guile, Next: Lazy Strings In Guile, Prev: Symbol Tables In Guile, Up: Guile API |
| |
| 23.3.3.19 Manipulating breakpoints using Guile |
| .............................................. |
| |
| Breakpoints in Guile are represented by objects of type |
| '<gdb:breakpoint>'. New breakpoints can be created with the |
| 'make-breakpoint' Guile function, and then added to GDB with the |
| 'register-breakpoint!' Guile function. This two-step approach is taken |
| to separate out the side-effect of adding the breakpoint to GDB from |
| 'make-breakpoint'. |
| |
| Support is also provided to view and manipulate breakpoints created |
| outside of Guile. |
| |
| The following breakpoint-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: make-breakpoint location [#:type type] [#:wp-class |
| wp-class] [#:internal internal] |
| Create a new breakpoint at LOCATION, a string naming the location |
| of the breakpoint, or an expression that defines a watchpoint. The |
| contents can be any location recognized by the 'break' command, or |
| in the case of a watchpoint, by the 'watch' command. |
| |
| The breakpoint is initially marked as 'invalid'. The breakpoint is |
| not usable until it has been registered with GDB with |
| 'register-breakpoint!', at which point it becomes 'valid'. The |
| result is the '<gdb:breakpoint>' object representing the |
| breakpoint. |
| |
| The optional TYPE denotes the breakpoint to create. This argument |
| can be either 'BP_BREAKPOINT' or 'BP_WATCHPOINT', and defaults to |
| 'BP_BREAKPOINT'. |
| |
| The optional WP-CLASS argument defines the class of watchpoint to |
| create, if TYPE is 'BP_WATCHPOINT'. If a watchpoint class is not |
| provided, it is assumed to be a 'WP_WRITE' class. |
| |
| The optional INTERNAL argument allows the breakpoint to become |
| invisible to the user. The breakpoint will neither be reported |
| when registered, nor will it be listed in the output from 'info |
| breakpoints' (but will be listed with the 'maint info breakpoints' |
| command). If an internal flag is not provided, the breakpoint is |
| visible (non-internal). |
| |
| When a watchpoint is created, GDB will try to create a hardware |
| assisted watchpoint. If successful, the type of the watchpoint is |
| changed from 'BP_WATCHPOINT' to 'BP_HARDWARE_WATCHPOINT' for |
| 'WP_WRITE', 'BP_READ_WATCHPOINT' for 'WP_READ', and |
| 'BP_ACCESS_WATCHPOINT' for 'WP_ACCESS'. If not successful, the |
| type of the watchpoint is left as 'WP_WATCHPOINT'. |
| |
| The available types are represented by constants defined in the |
| 'gdb' module: |
| |
| 'BP_BREAKPOINT' |
| Normal code breakpoint. |
| |
| 'BP_WATCHPOINT' |
| Watchpoint breakpoint. |
| |
| 'BP_HARDWARE_WATCHPOINT' |
| Hardware assisted watchpoint. This value cannot be specified |
| when creating the breakpoint. |
| |
| 'BP_READ_WATCHPOINT' |
| Hardware assisted read watchpoint. This value cannot be |
| specified when creating the breakpoint. |
| |
| 'BP_ACCESS_WATCHPOINT' |
| Hardware assisted access watchpoint. This value cannot be |
| specified when creating the breakpoint. |
| |
| The available watchpoint types represented by constants are defined |
| in the '(gdb)' module: |
| |
| 'WP_READ' |
| Read only watchpoint. |
| |
| 'WP_WRITE' |
| Write only watchpoint. |
| |
| 'WP_ACCESS' |
| Read/Write watchpoint. |
| |
| -- Scheme Procedure: register-breakpoint! breakpoint |
| Add BREAKPOINT, a '<gdb:breakpoint>' object, to GDB's list of |
| breakpoints. The breakpoint must have been created with |
| 'make-breakpoint'. One cannot register breakpoints that have been |
| created outside of Guile. Once a breakpoint is registered it |
| becomes 'valid'. It is an error to register an already registered |
| breakpoint. The result is unspecified. |
| |
| -- Scheme Procedure: delete-breakpoint! breakpoint |
| Remove BREAKPOINT from GDB's list of breakpoints. This also |
| invalidates the Guile BREAKPOINT object. Any further attempt to |
| access the object will throw an exception. |
| |
| If BREAKPOINT was created from Guile with 'make-breakpoint' it may |
| be re-registered with GDB, in which case the breakpoint becomes |
| valid again. |
| |
| -- Scheme Procedure: breakpoints |
| Return a list of all breakpoints. Each element of the list is a |
| '<gdb:breakpoint>' object. |
| |
| -- Scheme Procedure: breakpoint? object |
| Return '#t' if OBJECT is a '<gdb:breakpoint>' object, and '#f' |
| otherwise. |
| |
| -- Scheme Procedure: breakpoint-valid? breakpoint |
| Return '#t' if BREAKPOINT is valid, '#f' otherwise. Breakpoints |
| created with 'make-breakpoint' are marked as invalid until they are |
| registered with GDB with 'register-breakpoint!'. A |
| '<gdb: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. |
| |
| -- Scheme Procedure: breakpoint-number breakpoint |
| Return the breakpoint's number -- the identifier used by the user |
| to manipulate the breakpoint. |
| |
| -- Scheme Procedure: breakpoint-type breakpoint |
| Return the breakpoint's type -- the identifier used to determine |
| the actual breakpoint type or use-case. |
| |
| -- Scheme Procedure: breakpoint-visible? breakpoint |
| Return '#t' if the breakpoint is visible to the user when hit, or |
| when the 'info breakpoints' command is run. Otherwise return '#f'. |
| |
| -- Scheme Procedure: breakpoint-location breakpoint |
| Return 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) return '#f'. |
| |
| -- Scheme Procedure: breakpoint-expression breakpoint |
| Return the 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) return '#f'. |
| |
| -- Scheme Procedure: breakpoint-enabled? breakpoint |
| Return '#t' if the breakpoint is enabled, and '#f' otherwise. |
| |
| -- Scheme Procedure: set-breakpoint-enabled! breakpoint flag |
| Set the enabled state of BREAKPOINT to FLAG. If flag is '#f' it is |
| disabled, otherwise it is enabled. |
| |
| -- Scheme Procedure: breakpoint-silent? breakpoint |
| Return '#t' if the breakpoint is silent, and '#f' otherwise. |
| |
| Note that a breakpoint can also be silent if it has commands and |
| the first command is 'silent'. This is not reported by the |
| 'silent' attribute. |
| |
| -- Scheme Procedure: set-breakpoint-silent! breakpoint flag |
| Set the silent state of BREAKPOINT to FLAG. If flag is '#f' the |
| breakpoint is made silent, otherwise it is made non-silent (or |
| noisy). |
| |
| -- Scheme Procedure: breakpoint-ignore-count breakpoint |
| Return the ignore count for BREAKPOINT. |
| |
| -- Scheme Procedure: set-breakpoint-ignore-count! breakpoint count |
| Set the ignore count for BREAKPOINT to COUNT. |
| |
| -- Scheme Procedure: breakpoint-hit-count breakpoint |
| Return hit count of BREAKPOINT. |
| |
| -- Scheme Procedure: set-breakpoint-hit-count! breakpoint count |
| Set the hit count of BREAKPOINT to COUNT. At present, COUNT must |
| be zero. |
| |
| -- Scheme Procedure: breakpoint-thread breakpoint |
| Return the thread-id for thread-specific breakpoint BREAKPOINT. |
| Return #f if BREAKPOINT is not thread-specific. |
| |
| -- Scheme Procedure: set-breakpoint-thread! breakpoint thread-id|#f |
| Set the thread-id for BREAKPOINT to THREAD-ID. If set to '#f', the |
| breakpoint is no longer thread-specific. |
| |
| -- Scheme Procedure: breakpoint-task breakpoint |
| If the breakpoint is Ada task-specific, return the Ada task id. If |
| the breakpoint is not task-specific (or the underlying language is |
| not Ada), return '#f'. |
| |
| -- Scheme Procedure: set-breakpoint-task! breakpoint task |
| Set the Ada task of BREAKPOINT to TASK. If set to '#f', the |
| breakpoint is no longer task-specific. |
| |
| -- Scheme Procedure: breakpoint-condition breakpoint |
| Return the condition of BREAKPOINT, as specified by the user. It |
| is a string. If there is no condition, return '#f'. |
| |
| -- Scheme Procedure: set-breakpoint-condition! breakpoint condition |
| Set the condition of BREAKPOINT to CONDITION, which must be a |
| string. If set to '#f' then the breakpoint becomes unconditional. |
| |
| -- Scheme Procedure: breakpoint-stop breakpoint |
| Return the stop predicate of BREAKPOINT. See |
| 'set-breakpoint-stop!' below in this section. |
| |
| -- Scheme Procedure: set-breakpoint-stop! breakpoint procedure|#f |
| Set the stop predicate of BREAKPOINT. The predicate PROCEDURE |
| takes one argument: the <gdb:breakpoint> object. If this predicate |
| is set to a procedure then it is invoked whenever the inferior |
| reaches this breakpoint. If it returns '#t', or any non-'#f' |
| value, then the inferior is stopped, otherwise the inferior will |
| continue. |
| |
| If there are multiple breakpoints at the same location with a |
| 'stop' predicate, each one will be called regardless of the return |
| status of the previous. This ensures that all 'stop' predicates |
| have a chance to execute at that location. In this scenario if one |
| of the methods returns '#t' but the others return '#f', 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 GDB or the |
| inferior at this time. |
| |
| Example 'stop' implementation: |
| |
| (define (my-stop? bkpt) |
| (let ((int-val (parse-and-eval "foo"))) |
| (value=? int-val 3))) |
| (define bkpt (make-breakpoint "main.c:42")) |
| (register-breakpoint! bkpt) |
| (set-breakpoint-stop! bkpt my-stop?) |
| |
| -- Scheme Procedure: breakpoint-commands breakpoint |
| Return the commands attached to BREAKPOINT as a string, or '#f' if |
| there are none. |
| |
| |
| File: gdb.info, Node: Lazy Strings In Guile, Next: Architectures In Guile, Prev: Breakpoints In Guile, Up: Guile API |
| |
| 23.3.3.20 Guile representation of lazy strings. |
| ............................................... |
| |
| A "lazy string" is a string whose contents is not retrieved or encoded |
| until it is needed. |
| |
| A '<gdb:lazy-string>' is represented in GDB as an 'address' that |
| points to a region of memory, an 'encoding' that will be used to encode |
| that region of memory, and a 'length' to delimit the region of memory |
| that represents the string. The difference between a |
| '<gdb:lazy-string>' and a string wrapped within a '<gdb:value>' is that |
| a '<gdb:lazy-string>' will be treated differently by GDB when printing. |
| A '<gdb:lazy-string>' is retrieved and encoded during printing, while a |
| '<gdb:value>' wrapping a string is immediately retrieved and encoded on |
| creation. |
| |
| The following lazy-string-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: lazy-string? object |
| Return '#t' if OBJECT is an object of type '<gdb:lazy-string>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: lazy-string-address lazy-sring |
| Return the address of LAZY-STRING. |
| |
| -- Scheme Procedure: lazy-string-length lazy-string |
| Return the length of LAZY-STRING in characters. If the length is |
| -1, then the string will be fetched and encoded up to the first |
| null of appropriate width. |
| |
| -- Scheme Procedure: lazy-string-encoding lazy-string |
| Return the encoding that will be applied to LAZY-STRING when the |
| string is printed by GDB. If the encoding is not set, or contains |
| an empty string, then GDB will select the most appropriate encoding |
| when the string is printed. |
| |
| -- Scheme Procedure: lazy-string-type lazy-string |
| Return the type that is represented by 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 'type-target-type'. *Note |
| Types In Guile::. |
| |
| -- Scheme Procedure: lazy-string->value lazy-string |
| Convert the '<gdb:lazy-string>' to a '<gdb:value>'. This value |
| will point to the string in memory, but will lose all the delayed |
| retrieval, encoding and handling that GDB applies to a |
| '<gdb:lazy-string>'. |
| |
| |
| File: gdb.info, Node: Architectures In Guile, Next: Disassembly In Guile, Prev: Lazy Strings In Guile, Up: Guile API |
| |
| 23.3.3.21 Guile representation of architectures |
| ............................................... |
| |
| GDB uses architecture specific parameters and artifacts in a number of |
| its various computations. An architecture is represented by an instance |
| of the '<gdb:arch>' class. |
| |
| The following architecture-related procedures are provided by the |
| '(gdb)' module: |
| |
| -- Scheme Procedure: arch? object |
| Return '#t' if OBJECT is an object of type '<gdb:arch>'. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: current-arch |
| Return the current architecture as a '<gdb:arch>' object. |
| |
| -- Scheme Procedure: arch-name arch |
| Return the name (string value) of '<gdb:arch>' ARCH. |
| |
| -- Scheme Procedure: arch-charset arch |
| Return name of target character set of '<gdb:arch>' ARCH. |
| |
| -- Scheme Procedure: arch-wide-charset |
| Return name of target wide character set of '<gdb:arch>' ARCH. |
| |
| Each architecture provides a set of predefined types, obtained by the |
| following functions. |
| |
| -- Scheme Procedure: arch-void-type arch |
| Return the '<gdb:type>' object for a 'void' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-char-type arch |
| Return the '<gdb:type>' object for a 'char' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-short-type arch |
| Return the '<gdb:type>' object for a 'short' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-int-type arch |
| Return the '<gdb:type>' object for an 'int' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-long-type arch |
| Return the '<gdb:type>' object for a 'long' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-schar-type arch |
| Return the '<gdb:type>' object for a 'signed char' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-uchar-type arch |
| Return the '<gdb:type>' object for an 'unsigned char' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-ushort-type arch |
| Return the '<gdb:type>' object for an 'unsigned short' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-uint-type arch |
| Return the '<gdb:type>' object for an 'unsigned int' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-ulong-type arch |
| Return the '<gdb:type>' object for an 'unsigned long' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-float-type arch |
| Return the '<gdb:type>' object for a 'float' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-double-type arch |
| Return the '<gdb:type>' object for a 'double' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-longdouble-type arch |
| Return the '<gdb:type>' object for a 'long double' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-bool-type arch |
| Return the '<gdb:type>' object for a 'bool' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-longlong-type arch |
| Return the '<gdb:type>' object for a 'long long' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-ulonglong-type arch |
| Return the '<gdb:type>' object for an 'unsigned long long' type of |
| architecture ARCH. |
| |
| -- Scheme Procedure: arch-int8-type arch |
| Return the '<gdb:type>' object for an 'int8' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-uint8-type arch |
| Return the '<gdb:type>' object for a 'uint8' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-int16-type arch |
| Return the '<gdb:type>' object for an 'int16' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-uint16-type arch |
| Return the '<gdb:type>' object for a 'uint16' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-int32-type arch |
| Return the '<gdb:type>' object for an 'int32' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-uint32-type arch |
| Return the '<gdb:type>' object for a 'uint32' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-int64-type arch |
| Return the '<gdb:type>' object for an 'int64' type of architecture |
| ARCH. |
| |
| -- Scheme Procedure: arch-uint64-type arch |
| Return the '<gdb:type>' object for a 'uint64' type of architecture |
| ARCH. |
| |
| Example: |
| |
| (gdb) guile (type-name (arch-uchar-type (current-arch))) |
| "unsigned char" |
| |
| |
| File: gdb.info, Node: Disassembly In Guile, Next: I/O Ports in Guile, Prev: Architectures In Guile, Up: Guile API |
| |
| 23.3.3.22 Disassembly In Guile |
| .............................. |
| |
| The disassembler can be invoked from Scheme code. Furthermore, the |
| disassembler can take a Guile port as input, allowing one to disassemble |
| from any source, and not just target memory. |
| |
| -- Scheme Procedure: arch-disassemble arch start-pc [#:port port] |
| [#:offset offset] [#:size size] [#:count count] |
| Return a list of disassembled instructions starting from the memory |
| address START-PC. |
| |
| The optional argument PORT specifies the input port to read bytes |
| from. If PORT is '#f' then bytes are read from target memory. |
| |
| The optional argument OFFSET specifies the address offset of the |
| first byte in PORT. This is useful, for example, when PORT |
| specifies a 'bytevector' and you want the bytevector to be |
| disassembled as if it came from that address. The START-PC passed |
| to the reader for PORT is offset by the same amount. |
| |
| Example: |
| (gdb) guile (use-modules (rnrs io ports)) |
| (gdb) guile (define pc (value->integer (parse-and-eval "$pc"))) |
| (gdb) guile (define mem (open-memory #:start pc)) |
| (gdb) guile (define bv (get-bytevector-n mem 10)) |
| (gdb) guile (define bv-port (open-bytevector-input-port bv)) |
| (gdb) guile (define arch (current-arch)) |
| (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc) |
| (((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5))) |
| |
| The optional arguments SIZE and COUNT determine the number of |
| instructions in the returned list. If either SIZE or COUNT is |
| specified as zero, then no instructions are disassembled and an |
| empty list is returned. If both the optional arguments SIZE and |
| COUNT are specified, then a list of at most COUNT disassembled |
| instructions whose start address falls in the closed memory address |
| interval from START-PC to (START-PC + SIZE - 1) are returned. If |
| SIZE is not specified, but COUNT is specified, then COUNT number of |
| instructions starting from the address START-PC are returned. If |
| COUNT is not specified but SIZE is specified, then all instructions |
| whose start address falls in the closed memory address interval |
| from START-PC to (START-PC + SIZE - 1) are returned. If neither |
| SIZE nor COUNT are specified, then a single instruction at START-PC |
| is returned. |
| |
| Each element of the returned list is an alist (associative list) |
| with the following keys: |
| |
| 'address' |
| The value corresponding to this key is a Guile integer of the |
| memory address of the instruction. |
| |
| '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 'disassembly-flavor'. |
| *Note Machine Code::. |
| |
| 'length' |
| The value corresponding to this key is the length of the |
| instruction in bytes. |
| |
| |
| File: gdb.info, Node: I/O Ports in Guile, Next: Memory Ports in Guile, Prev: Disassembly In Guile, Up: Guile API |
| |
| 23.3.3.23 I/O Ports in Guile |
| ............................ |
| |
| -- Scheme Procedure: input-port |
| Return GDB's input port as a Guile port object. |
| |
| -- Scheme Procedure: output-port |
| Return GDB's output port as a Guile port object. |
| |
| -- Scheme Procedure: error-port |
| Return GDB's error port as a Guile port object. |
| |
| -- Scheme Procedure: stdio-port? object |
| Return '#t' if OBJECT is a GDB stdio port. Otherwise return '#f'. |
| |
| |
| File: gdb.info, Node: Memory Ports in Guile, Next: Iterators In Guile, Prev: I/O Ports in Guile, Up: Guile API |
| |
| 23.3.3.24 Memory Ports in Guile |
| ............................... |
| |
| GDB provides a 'port' interface to target memory. This allows Guile |
| code to read/write target memory using Guile's port and bytevector |
| functionality. The main routine is 'open-memory' which returns a port |
| object. One can then read/write memory using that object. |
| |
| -- Scheme Procedure: open-memory [#:mode mode] [#:start address] |
| [#:size size] |
| Return a port object that can be used for reading and writing |
| memory. The port will be open according to MODE, which is the |
| standard mode argument to Guile port open routines, except that the |
| '"a"' and '"l"' modes are not supported. *Note (guile)File |
| Ports::. The '"b"' (binary) character may be present, but is |
| ignored: memory ports are binary only. If '"0"' is appended then |
| the port is marked as unbuffered. The default is '"r"', read-only |
| and buffered. |
| |
| The chunk of memory that can be accessed can be bounded. If both |
| START and SIZE are unspecified, all of memory can be accessed. If |
| only START is specified, all of memory from that point on can be |
| accessed. If only SIZE if specified, all memory in the range |
| [0,SIZE) can be accessed. If both are specified, all memory in the |
| rane [START,START+SIZE) can be accessed. |
| |
| -- Scheme Procedure: memory-port? |
| Return '#t' if OBJECT is an object of type '<gdb:memory-port>'. |
| Otherwise return '#f'. |
| |
| -- Scheme Procedure: memory-port-range memory-port |
| Return the range of '<gdb:memory-port>' MEMORY-PORT as a list of |
| two elements: '(start end)'. The range is START to END inclusive. |
| |
| -- Scheme Procedure: memory-port-read-buffer-size memory-port |
| Return the size of the read buffer of '<gdb:memory-port>' |
| MEMORY-PORT. |
| |
| -- Scheme Procedure: set-memory-port-read-buffer-size! memory-port size |
| Set the size of the read buffer of '<gdb:memory-port>' MEMORY-PORT |
| to SIZE. The result is unspecified. |
| |
| -- Scheme Procedure: memory-port-write-buffer-size memory-port |
| Return the size of the write buffer of '<gdb:memory-port>' |
| MEMORY-PORT. |
| |
| -- Scheme Procedure: set-memory-port-write-buffer-size! memory-port |
| size |
| Set the size of the write buffer of '<gdb:memory-port>' MEMORY-PORT |
| to SIZE. The result is unspecified. |
| |
| A memory port is closed like any other port, with 'close-port'. |
| |
| Combined with Guile's 'bytevectors', memory ports provide a lot of |
| utility. For example, to fill a buffer of 10 integers in memory, one |
| can do something like the following. |
| |
| ;; In the program: int buffer[10]; |
| (use-modules (rnrs bytevectors)) |
| (use-modules (rnrs io ports)) |
| (define addr (parse-and-eval "buffer")) |
| (define n 10) |
| (define byte-size (* n 4)) |
| (define mem-port (open-memory #:mode "r+" #:start |
| (value->integer addr) #:size byte-size)) |
| (define byte-vec (make-bytevector byte-size)) |
| (do ((i 0 (+ i 1))) |
| ((>= i n)) |
| (bytevector-s32-native-set! byte-vec (* i 4) (* i 42))) |
| (put-bytevector mem-port byte-vec) |
| (close-port mem-port) |
| |
| |
| File: gdb.info, Node: Iterators In Guile, Prev: Memory Ports in Guile, Up: Guile API |
| |
| 23.3.3.25 Iterators In Guile |
| ............................ |
| |
| A simple iterator facility is provided to allow, for example, iterating |
| over the set of program symbols without having to first construct a list |
| of all of them. A useful contribution would be to add support for SRFI |
| 41 and SRFI 45. |
| |
| -- Scheme Procedure: make-iterator object progress next! |
| A '<gdb:iterator>' object is constructed with the 'make-iterator' |
| procedure. It takes three arguments: the object to be iterated |
| over, an object to record the progress of the iteration, and a |
| procedure to return the next element in the iteration, or an |
| implementation chosen value to denote the end of iteration. |
| |
| By convention, end of iteration is marked with |
| '(end-of-iteration)', and may be tested with the |
| 'end-of-iteration?' predicate. The result of '(end-of-iteration)' |
| is chosen so that it is not otherwise used by the '(gdb)' module. |
| If you are using '<gdb:iterator>' in your own code it is your |
| responsibility to maintain this invariant. |
| |
| A trivial example for illustration's sake: |
| |
| (use-modules (gdb iterator)) |
| (define my-list (list 1 2 3)) |
| (define iter |
| (make-iterator my-list my-list |
| (lambda (iter) |
| (let ((l (iterator-progress iter))) |
| (if (eq? l '()) |
| (end-of-iteration) |
| (begin |
| (set-iterator-progress! iter (cdr l)) |
| (car l))))))) |
| |
| Here is a slightly more realistic example, which computes a list of |
| all the functions in 'my-global-block'. |
| |
| (use-modules (gdb iterator)) |
| (define this-sal (find-pc-line (frame-pc (selected-frame)))) |
| (define this-symtab (sal-symtab this-sal)) |
| (define this-global-block (symtab-global-block this-symtab)) |
| (define syms-iter (make-block-symbols-iterator this-global-block)) |
| (define functions (iterator-filter symbol-function? syms-iter)) |
| |
| -- Scheme Procedure: iterator? object |
| Return '#t' if OBJECT is a '<gdb:iterator>' object. Otherwise |
| return '#f'. |
| |
| -- Scheme Procedure: iterator-object iterator |
| Return the first argument that was passed to 'make-iterator'. This |
| is the object being iterated over. |
| |
| -- Scheme Procedure: iterator-progress iterator |
| Return the object tracking iteration progress. |
| |
| -- Scheme Procedure: set-iterator-progress! iterator new-value |
| Set the object tracking iteration progress. |
| |
| -- Scheme Procedure: iterator-next! iterator |
| Invoke the procedure that was the third argument to |
| 'make-iterator', passing it one argument, the '<gdb:iterator>' |
| object. The result is either the next element in the iteration, or |
| an end marker as implemented by the 'next!' procedure. By |
| convention the end marker is the result of '(end-of-iteration)'. |
| |
| -- Scheme Procedure: end-of-iteration |
| Return the Scheme object that denotes end of iteration. |
| |
| -- Scheme Procedure: end-of-iteration? object |
| Return '#t' if OBJECT is the end of iteration marker. Otherwise |
| return '#f'. |
| |
| These functions are provided by the '(gdb iterator)' module to assist |
| in using iterators. |
| |
| -- Scheme Procedure: make-list-iterator list |
| Return a '<gdb:iterator>' object that will iterate over LIST. |
| |
| -- Scheme Procedure: iterator->list iterator |
| Return the elements pointed to by ITERATOR as a list. |
| |
| -- Scheme Procedure: iterator-map proc iterator |
| Return the list of objects obtained by applying PROC to the object |
| pointed to by ITERATOR and to each subsequent object. |
| |
| -- Scheme Procedure: iterator-for-each proc iterator |
| Apply PROC to each element pointed to by ITERATOR. The result is |
| unspecified. |
| |
| -- Scheme Procedure: iterator-filter pred iterator |
| Return the list of elements pointed to by ITERATOR that satisfy |
| PRED. |
| |
| -- Scheme Procedure: iterator-until pred iterator |
| Run ITERATOR until the result of '(pred element)' is true and |
| return that as the result. Otherwise return '#f'. |
| |
| |
| File: gdb.info, Node: Guile Auto-loading, Next: Guile Modules, Prev: Guile API, Up: Guile |
| |
| 23.3.4 Guile Auto-loading |
| ------------------------- |
| |
| When a new object file is read (for example, due to the 'file' command, |
| or because the inferior has loaded a shared library), GDB will look for |
| Guile support scripts in two ways: 'OBJFILE-gdb.scm' and the |
| '.debug_gdb_scripts' section. *Note 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. |
| |
| 'set auto-load guile-scripts [on|off]' |
| Enable or disable the auto-loading of Guile scripts. |
| |
| 'show auto-load guile-scripts' |
| Show whether auto-loading of Guile scripts is enabled or disabled. |
| |
| 'info auto-load guile-scripts [REGEXP]' |
| Print the list of all Guile scripts that GDB auto-loaded. |
| |
| Also printed is the list of Guile scripts that were mentioned in |
| the '.debug_gdb_scripts' section and were not found. This is |
| useful because their names are not printed when GDB tries to load |
| them and fails. There may be many of them, and printing an error |
| message for each one is problematic. |
| |
| If REGEXP is supplied only Guile scripts with matching names are |
| printed. |
| |
| Example: |
| |
| (gdb) info auto-load guile-scripts |
| Loaded Script |
| Yes scm-section-script.scm |
| full name: /tmp/scm-section-script.scm |
| No my-foo-pretty-printers.scm |
| |
| When reading an auto-loaded file, GDB sets the "current objfile". |
| This is available via the 'current-objfile' procedure (*note Objfiles In |
| Guile::). This can be useful for registering objfile-specific |
| pretty-printers. |
| |
| |
| File: gdb.info, Node: Guile Modules, Prev: Guile Auto-loading, Up: Guile |
| |
| 23.3.5 Guile Modules |
| -------------------- |
| |
| GDB comes with several modules to assist writing Guile code. |
| |
| * Menu: |
| |
| * Guile Printing Module:: Building and registering pretty-printers |
| * Guile Types Module:: Utilities for working with types |
| |
| |
| File: gdb.info, Node: Guile Printing Module, Next: Guile Types Module, Up: Guile Modules |
| |
| 23.3.5.1 Guile Printing Module |
| .............................. |
| |
| This module provides a collection of utilities for working with |
| pretty-printers. |
| |
| Usage: |
| |
| (use-modules (gdb printing)) |
| |
| -- Scheme Procedure: prepend-pretty-printer! object printer |
| Add PRINTER to the front of the list of pretty-printers for OBJECT. |
| The OBJECT must either be a '<gdb:objfile>' object, or '#f' in |
| which case PRINTER is added to the global list of printers. |
| |
| -- Scheme Procecure: append-pretty-printer! object printer |
| Add PRINTER to the end of the list of pretty-printers for OBJECT. |
| The OBJECT must either be a '<gdb:objfile>' object, or '#f' in |
| which case PRINTER is added to the global list of printers. |
| |
| |
| File: gdb.info, Node: Guile Types Module, Prev: Guile Printing Module, Up: Guile Modules |
| |
| 23.3.5.2 Guile Types Module |
| ........................... |
| |
| This module provides a collection of utilities for working with |
| '<gdb:type>' objects. |
| |
| Usage: |
| |
| (use-modules (gdb types)) |
| |
| -- Scheme Procedure: get-basic-type type |
| Return TYPE with const and volatile qualifiers stripped, and with |
| typedefs and C++ references converted to the underlying type. |
| |
| C++ example: |
| |
| typedef const int const_int; |
| const_int foo (3); |
| const_int& foo_ref (foo); |
| int main () { return 0; } |
| |
| Then in gdb: |
| |
| (gdb) start |
| (gdb) guile (use-modules (gdb) (gdb types)) |
| (gdb) guile (define foo-ref (parse-and-eval "foo_ref")) |
| (gdb) guile (get-basic-type (value-type foo-ref)) |
| int |
| |
| -- Scheme Procedure: type-has-field-deep? type field |
| Return '#t' if TYPE, assumed to be a type with fields (e.g., a |
| structure or union), has field FIELD. Otherwise return '#f'. This |
| searches baseclasses, whereas 'type-has-field?' does not. |
| |
| -- Scheme Procedure: make-enum-hashtable enum-type |
| Return a Guile hash table produced from ENUM-TYPE. Elements in the |
| hash table are referenced with 'hashq-ref'. |
| |
| |
| File: gdb.info, Node: Auto-loading extensions, Next: Multiple Extension Languages, Prev: Guile, Up: Extending GDB |
| |
| 23.4 Auto-loading extensions |
| ============================ |
| |
| GDB provides two mechanisms for automatically loading extensions when a |
| new object file is read (for example, due to the 'file' command, or |
| because the inferior has loaded a shared library): 'OBJFILE-gdb.EXT' and |
| the '.debug_gdb_scripts' section of modern file formats like ELF. |
| |
| * Menu: |
| |
| * objfile-gdb.ext file: objfile-gdbdotext file. The 'OBJFILE-gdb.EXT' file |
| * .debug_gdb_scripts section: dotdebug_gdb_scripts section. The '.debug_gdb_scripts' section |
| * Which flavor to choose?:: |
| |
| The auto-loading feature is useful for supplying application-specific |
| debugging commands and features. |
| |
| Auto-loading can be enabled or disabled, and the list of auto-loaded |
| scripts can be printed. See the 'auto-loading' section of each |
| extension language for more information. For GDB command files see |
| *note Auto-loading sequences::. For Python files see *note Python |
| Auto-loading::. |
| |
| Note that loading of this script file also requires accordingly |
| configured 'auto-load safe-path' (*note Auto-loading safe path::). |
| |
| |
| File: gdb.info, Node: objfile-gdbdotext file, Next: dotdebug_gdb_scripts section, Up: Auto-loading extensions |
| |
| 23.4.1 The 'OBJFILE-gdb.EXT' file |
| --------------------------------- |
| |
| When a new object file is read, GDB looks for a file named |
| 'OBJFILE-gdb.EXT' (we call it SCRIPT-NAME below), where OBJFILE is the |
| object file's name and where EXT is the file extension for the extension |
| language: |
| |
| 'OBJFILE-gdb.gdb' |
| GDB's own command language |
| 'OBJFILE-gdb.py' |
| Python |
| 'OBJFILE-gdb.scm' |
| Guile |
| |
| SCRIPT-NAME is formed by ensuring that the file name of OBJFILE is |
| absolute, following all symlinks, and resolving '.' and '..' components, |
| and appending the '-gdb.EXT' suffix. If this file exists and is |
| readable, GDB will evaluate it as a script in the specified extension |
| language. |
| |
| If this file does not exist, then GDB will look for SCRIPT-NAME file |
| in all of the directories as specified below. |
| |
| Note that loading of these files requires an accordingly configured |
| 'auto-load safe-path' (*note Auto-loading safe path::). |
| |
| For object files using '.exe' suffix GDB tries to load first the |
| scripts normally according to its '.exe' filename. But if no scripts |
| are found GDB also tries script filenames matching the object file |
| without its '.exe' suffix. This '.exe' stripping is case insensitive |
| and it is attempted on any platform. This makes the script filenames |
| compatible between Unix and MS-Windows hosts. |
| |
| 'set auto-load scripts-directory [DIRECTORIES]' |
| Control GDB auto-loaded scripts location. Multiple directory |
| entries may be delimited by the host platform path separator in use |
| (':' on Unix, ';' on MS-Windows and MS-DOS). |
| |
| Each entry here needs to be covered also by the security setting |
| 'set auto-load safe-path' (*note set auto-load safe-path::). |
| |
| This variable defaults to '$debugdir:$datadir/auto-load'. The |
| default 'set auto-load safe-path' value can be also overriden by |
| GDB configuration option '--with-auto-load-dir'. |
| |
| Any reference to '$debugdir' will get replaced by |
| DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any |
| reference to '$datadir' will get replaced by DATA-DIRECTORY which |
| is determined at GDB startup (*note Data Files::). '$debugdir' and |
| '$datadir' must be placed as a directory component -- either alone |
| or delimited by '/' or '\' directory separators, depending on the |
| host platform. |
| |
| The list of directories uses path separator (':' on GNU and Unix |
| systems, ';' on MS-Windows and MS-DOS) to separate directories, |
| similarly to the 'PATH' environment variable. |
| |
| 'show auto-load scripts-directory' |
| Show GDB auto-loaded scripts location. |
| |
| 'add-auto-load-scripts-directory [DIRECTORIES...]' |
| Add an entry (or list of entries) to the list of auto-loaded |
| scripts locations. Multiple entries may be delimited by the host |
| platform path separator in use. |
| |
| GDB does not track which files it has already auto-loaded this way. |
| GDB will load the associated script every time the corresponding OBJFILE |
| is opened. So your '-gdb.EXT' file should be careful to avoid errors if |
| it is evaluated more than once. |
| |
| |
| File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdbdotext file, Up: Auto-loading extensions |
| |
| 23.4.2 The '.debug_gdb_scripts' section |
| --------------------------------------- |
| |
| For systems using file formats like ELF and COFF, when GDB loads a new |
| object file it will look for a special section named |
| '.debug_gdb_scripts'. If this section exists, its contents is a list of |
| null-terminated entries specifying scripts to load. Each entry begins |
| with a non-null prefix byte that specifies the kind of entry, typically |
| the extension language and whether the script is in a file or inlined in |
| '.debug_gdb_scripts'. |
| |
| The following entries are supported: |
| |
| 'SECTION_SCRIPT_ID_PYTHON_FILE = 1' |
| 'SECTION_SCRIPT_ID_SCHEME_FILE = 3' |
| 'SECTION_SCRIPT_ID_PYTHON_TEXT = 4' |
| 'SECTION_SCRIPT_ID_SCHEME_TEXT = 6' |
| |
| 23.4.2.1 Script File Entries |
| ............................ |
| |
| If the entry specifies a file, GDB will look for the file first in the |
| current directory and then along the source search path (*note |
| Specifying Source Directories: Source Path.), except that '$cdir' is not |
| searched, since the compilation directory is not relevant to scripts. |
| |
| File entries can be placed in section '.debug_gdb_scripts' with, for |
| example, this GCC macro for Python scripts. |
| |
| /* Note: The "MS" section flags are to remove duplicates. */ |
| #define DEFINE_GDB_PY_SCRIPT(script_name) \ |
| asm("\ |
| .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ |
| .byte 1 /* Python */\n\ |
| .asciz \"" script_name "\"\n\ |
| .popsection \n\ |
| "); |
| |
| For Guile scripts, replace '.byte 1' with '.byte 3'. Then one can |
| reference the macro in a header or source file like this: |
| |
| DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") |
| |
| The script name may include directories if desired. |
| |
| Note that loading of this script file also requires accordingly |
| configured 'auto-load safe-path' (*note Auto-loading safe path::). |
| |
| If the macro invocation is put in a header, any application or |
| library using this header will get a reference to the specified script, |
| and with the use of '"MS"' attributes on the section, the linker will |
| remove duplicates. |
| |
| 23.4.2.2 Script Text Entries |
| ............................ |
| |
| Script text entries allow to put the executable script in the entry |
| itself instead of loading it from a file. The first line of the entry, |
| everything after the prefix byte and up to the first newline ('0xa') |
| character, is the script name, and must not contain any kind of space |
| character, e.g., spaces or tabs. The rest of the entry, up to the |
| trailing null byte, is the script to execute in the specified language. |
| The name needs to be unique among all script names, as GDB executes each |
| script only once based on its name. |
| |
| Here is an example from file 'py-section-script.c' in the GDB |
| testsuite. |
| |
| #include "symcat.h" |
| #include "gdb/section-scripts.h" |
| asm( |
| ".pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n" |
| ".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n" |
| ".ascii \"gdb.inlined-script\\n\"\n" |
| ".ascii \"class test_cmd (gdb.Command):\\n\"\n" |
| ".ascii \" def __init__ (self):\\n\"\n" |
| ".ascii \" super (test_cmd, self).__init__ (" |
| "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n" |
| ".ascii \" def invoke (self, arg, from_tty):\\n\"\n" |
| ".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n" |
| ".ascii \"test_cmd ()\\n\"\n" |
| ".byte 0\n" |
| ".popsection\n" |
| ); |
| |
| Loading of inlined scripts requires a properly configured 'auto-load |
| safe-path' (*note Auto-loading safe path::). The path to specify in |
| 'auto-load safe-path' is the path of the file containing the |
| '.debug_gdb_scripts' section. |
| |
| |
| File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts section, Up: Auto-loading extensions |
| |
| 23.4.3 Which flavor to choose? |
| ------------------------------ |
| |
| Given the multiple ways of auto-loading extensions, it might not always |
| be clear which one to choose. This section provides some guidance. |
| |
| Benefits of the '-gdb.EXT' way: |
| |
| * Can be used with file formats that don't support multiple sections. |
| |
| * Ease of finding scripts for public libraries. |
| |
| Scripts specified in the '.debug_gdb_scripts' section are searched |
| for in the source search path. For publicly installed libraries, |
| e.g., 'libstdc++', there typically isn't a source directory in |
| which to find the script. |
| |
| * Doesn't require source code additions. |
| |
| Benefits of the '.debug_gdb_scripts' way: |
| |
| * Works with static linking. |
| |
| Scripts for libraries done the '-gdb.EXT' way require an objfile to |
| trigger their loading. When an application is statically linked |
| the only objfile available is the executable, and it is cumbersome |
| to attach all the scripts from all the input libraries to the |
| executable's '-gdb.EXT' script. |
| |
| * Works with classes that are entirely inlined. |
| |
| Some classes can be entirely inlined, and thus there may not be an |
| associated shared library to attach a '-gdb.EXT' script to. |
| |
| * Scripts needn't be copied out of the source tree. |
| |
| In some circumstances, apps can be built out of large collections |
| of internal libraries, and the build infrastructure necessary to |
| install the '-gdb.EXT' scripts in a place where GDB can find them |
| is cumbersome. It may be easier to specify the scripts in the |
| '.debug_gdb_scripts' section as relative paths, and add a path to |
| the top of the source tree to the source search path. |
| |
| |
| File: gdb.info, Node: Multiple Extension Languages, Next: Aliases, Prev: Auto-loading extensions, Up: Extending GDB |
| |
| 23.5 Multiple Extension Languages |
| ================================= |
| |
| The Guile and Python extension languages do not share any state, and |
| generally do not interfere with each other. There are some things to be |
| aware of, however. |
| |
| 23.5.1 Python comes first |
| ------------------------- |
| |
| Python was GDB's first extension language, and to avoid breaking |
| existing behaviour Python comes first. This is generally solved by the |
| "first one wins" principle. GDB maintains a list of enabled extension |
| languages, and when it makes a call to an extension language, (say to |
| pretty-print a value), it tries each in turn until an extension language |
| indicates it has performed the request (e.g., has returned the |
| pretty-printed form of a value). This extends to errors while |
| performing such requests: If an error happens while, for example, trying |
| to pretty-print an object then the error is reported and any following |
| extension languages are not tried. |
| |
| |
| File: gdb.info, Node: Aliases, Prev: Multiple Extension Languages, Up: Extending GDB |
| |
| 23.6 Creating new spellings of existing commands |
| ================================================ |
| |
| It is often useful to define alternate spellings of existing commands. |
| For example, if a new GDB command defined in Python has a long name to |
| type, it is handy to have an abbreviated version of it that involves |
| less typing. |
| |
| GDB itself uses aliases. For example 's' is an alias of the 'step' |
| command even though it is otherwise an ambiguous abbreviation of other |
| commands like 'set' and 'show'. |
| |
| Aliases are also used to provide shortened or more common versions of |
| multi-word commands. For example, GDB provides the 'tty' alias of the |
| 'set inferior-tty' command. |
| |
| You can define a new alias with the 'alias' command. |
| |
| 'alias [-a] [--] ALIAS = COMMAND' |
| |
| ALIAS specifies the name of the new alias. Each word of ALIAS must |
| consist of letters, numbers, dashes and underscores. |
| |
| COMMAND specifies the name of an existing command that is being |
| aliased. |
| |
| The '-a' option specifies that the new alias is an abbreviation of |
| the command. Abbreviations are not shown in command lists displayed by |
| the 'help' command. |
| |
| The '--' option specifies the end of options, and is useful when |
| ALIAS begins with a dash. |
| |
| Here is a simple example showing how to make an abbreviation of a |
| command so that there is less to type. Suppose you were tired of typing |
| 'disas', the current shortest unambiguous abbreviation of the |
| 'disassemble' command and you wanted an even shorter version named 'di'. |
| The following will accomplish this. |
| |
| (gdb) alias -a di = disas |
| |
| Note that aliases are different from user-defined commands. With a |
| user-defined command, you also need to write documentation for it with |
| the 'document' command. An alias automatically picks up the |
| documentation of the existing command. |
| |
| Here is an example where we make 'elms' an abbreviation of 'elements' |
| in the 'set print elements' command. This is to show that you can make |
| an abbreviation of any part of a command. |
| |
| (gdb) alias -a set print elms = set print elements |
| (gdb) alias -a show print elms = show print elements |
| (gdb) set p elms 20 |
| (gdb) show p elms |
| Limit on string chars or array elements to print is 200. |
| |
| Note that if you are defining an alias of a 'set' command, and you |
| want to have an alias for the corresponding 'show' command, then you |
| need to define the latter separately. |
| |
| Unambiguously abbreviated commands are allowed in COMMAND and ALIAS, |
| just as they are normally. |
| |
| (gdb) alias -a set pr elms = set p ele |
| |
| Finally, here is an example showing the creation of a one word alias |
| for a more complex command. This creates alias 'spe' of the command |
| 'set print elements'. |
| |
| (gdb) alias spe = set print elements |
| (gdb) spe 20 |
| |
| |
| File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top |
| |
| 24 Command Interpreters |
| *********************** |
| |
| GDB supports multiple command interpreters, and some command |
| infrastructure to allow users or user interface writers to switch |
| between interpreters or run commands in other interpreters. |
| |
| GDB currently supports two command interpreters, the console |
| interpreter (sometimes called the command-line interpreter or CLI) and |
| the machine interface interpreter (or GDB/MI). This manual describes |
| both of these interfaces in great detail. |
| |
| By default, GDB will start with the console interpreter. However, |
| the user may choose to start GDB with another interpreter by specifying |
| the '-i' or '--interpreter' startup options. Defined interpreters |
| include: |
| |
| 'console' |
| The traditional console or command-line interpreter. This is the |
| most often used interpreter with GDB. With no interpreter |
| specified at runtime, GDB will use this interpreter. |
| |
| 'mi' |
| The newest GDB/MI interface (currently 'mi2'). Used primarily by |
| programs wishing to use GDB as a backend for a debugger GUI or an |
| IDE. For more information, see *note The GDB/MI Interface: GDB/MI. |
| |
| 'mi2' |
| The current GDB/MI interface. |
| |
| 'mi1' |
| The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. |
| |
| The interpreter being used by GDB may not be dynamically switched at |
| runtime. Although possible, this could lead to a very precarious |
| situation. Consider an IDE using GDB/MI. If a user enters the command |
| "interpreter-set console" in a console view, GDB would switch to using |
| the console interpreter, rendering the IDE inoperable! |
| |
| Although you may only choose a single interpreter at startup, you may |
| execute commands in any interpreter from the current interpreter using |
| the appropriate command. If you are running the console interpreter, |
| simply use the 'interpreter-exec' command: |
| |
| interpreter-exec mi "-data-list-register-names" |
| |
| GDB/MI has a similar command, although it is only available in |
| versions of GDB which support GDB/MI version 2 (or greater). |
| |
| |
| File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top |
| |
| 25 GDB Text User Interface |
| ************************** |
| |
| * Menu: |
| |
| * TUI Overview:: TUI overview |
| * TUI Keys:: TUI key bindings |
| * TUI Single Key Mode:: TUI single key mode |
| * TUI Commands:: TUI-specific commands |
| * TUI Configuration:: TUI configuration variables |
| |
| The GDB Text User Interface (TUI) is a terminal interface which uses the |
| 'curses' library to show the source file, the assembly output, the |
| program registers and GDB commands in separate text windows. The TUI |
| mode is supported only on platforms where a suitable version of the |
| 'curses' library is available. |
| |
| The TUI mode is enabled by default when you invoke GDB as 'gdb -tui'. |
| You can also switch in and out of TUI mode while GDB runs by using |
| various TUI commands and key bindings, such as 'tui enable' or 'C-x |
| C-a'. *Note TUI Commands: TUI Commands, and *note TUI Key Bindings: TUI |
| Keys. |
| |
| |
| File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI |
| |
| 25.1 TUI Overview |
| ================= |
| |
| In TUI mode, GDB can display several text windows: |
| |
| _command_ |
| This window is the GDB command window with the GDB prompt and the |
| GDB output. The GDB input is still managed using readline. |
| |
| _source_ |
| The source window shows the source file of the program. The |
| current line and active breakpoints are displayed in this window. |
| |
| _assembly_ |
| The assembly window shows the disassembly output of the program. |
| |
| _register_ |
| This window shows the processor registers. Registers are |
| highlighted when their values change. |
| |
| The source and assembly windows show the current program position by |
| highlighting the current line and marking it with a '>' marker. |
| Breakpoints are indicated with two markers. The first marker indicates |
| the breakpoint type: |
| |
| 'B' |
| Breakpoint which was hit at least once. |
| |
| 'b' |
| Breakpoint which was never hit. |
| |
| 'H' |
| Hardware breakpoint which was hit at least once. |
| |
| 'h' |
| Hardware breakpoint which was never hit. |
| |
| The second marker indicates whether the breakpoint is enabled or not: |
| |
| '+' |
| Breakpoint is enabled. |
| |
| '-' |
| Breakpoint is disabled. |
| |
| The source, assembly and register windows are updated when the |
| current thread changes, when the frame changes, or when the program |
| counter changes. |
| |
| These windows are not all visible at the same time. The command |
| window is always visible. The others can be arranged in several |
| layouts: |
| |
| * source only, |
| |
| * assembly only, |
| |
| * source and assembly, |
| |
| * source and registers, or |
| |
| * assembly and registers. |
| |
| A status line above the command window shows the following |
| information: |
| |
| _target_ |
| Indicates the current GDB target. (*note Specifying a Debugging |
| Target: Targets.). |
| |
| _process_ |
| Gives the current process or thread number. When no process is |
| being debugged, this field is set to 'No process'. |
| |
| _function_ |
| Gives the current function name for the selected frame. The name |
| is demangled if demangling is turned on (*note Print Settings::). |
| When there is no symbol corresponding to the current program |
| counter, the string '??' is displayed. |
| |
| _line_ |
| Indicates the current line number for the selected frame. When the |
| current line number is not known, the string '??' is displayed. |
| |
| _pc_ |
| Indicates the current program counter address. |
| |
| |
| File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI |
| |
| 25.2 TUI Key Bindings |
| ===================== |
| |
| The TUI installs several key bindings in the readline keymaps (*note |
| Command Line Editing::). The following key bindings are installed for |
| both TUI mode and the GDB standard mode. |
| |
| 'C-x C-a' |
| 'C-x a' |
| 'C-x A' |
| Enter or leave the TUI mode. When leaving the TUI mode, the curses |
| window management stops and GDB operates using its standard mode, |
| writing on the terminal directly. When reentering the TUI mode, |
| control is given back to the curses windows. The screen is then |
| refreshed. |
| |
| 'C-x 1' |
| Use a TUI layout with only one window. The layout will either be |
| 'source' or 'assembly'. When the TUI mode is not active, it will |
| switch to the TUI mode. |
| |
| Think of this key binding as the Emacs 'C-x 1' binding. |
| |
| 'C-x 2' |
| Use a TUI layout with at least two windows. When the current |
| layout already has two windows, the next layout with two windows is |
| used. When a new layout is chosen, one window will always be |
| common to the previous layout and the new one. |
| |
| Think of it as the Emacs 'C-x 2' binding. |
| |
| 'C-x o' |
| Change the active window. The TUI associates several key bindings |
| (like scrolling and arrow keys) with the active window. This |
| command gives the focus to the next TUI window. |
| |
| Think of it as the Emacs 'C-x o' binding. |
| |
| 'C-x s' |
| Switch in and out of the TUI SingleKey mode that binds single keys |
| to GDB commands (*note TUI Single Key Mode::). |
| |
| The following key bindings only work in the TUI mode: |
| |
| <PgUp> |
| Scroll the active window one page up. |
| |
| <PgDn> |
| Scroll the active window one page down. |
| |
| <Up> |
| Scroll the active window one line up. |
| |
| <Down> |
| Scroll the active window one line down. |
| |
| <Left> |
| Scroll the active window one column left. |
| |
| <Right> |
| Scroll the active window one column right. |
| |
| 'C-L' |
| Refresh the screen. |
| |
| Because the arrow keys scroll the active window in the TUI mode, they |
| are not available for their normal use by readline unless the command |
| window has the focus. When another window is active, you must use other |
| readline key bindings such as 'C-p', 'C-n', 'C-b' and 'C-f' to control |
| the command window. |
| |
| |
| File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI |
| |
| 25.3 TUI Single Key Mode |
| ======================== |
| |
| The TUI also provides a "SingleKey" mode, which binds several frequently |
| used GDB commands to single keys. Type 'C-x s' to switch into this |
| mode, where the following key bindings are used: |
| |
| 'c' |
| continue |
| |
| 'd' |
| down |
| |
| 'f' |
| finish |
| |
| 'n' |
| next |
| |
| 'q' |
| exit the SingleKey mode. |
| |
| 'r' |
| run |
| |
| 's' |
| step |
| |
| 'u' |
| up |
| |
| 'v' |
| info locals |
| |
| 'w' |
| where |
| |
| Other keys temporarily switch to the GDB command prompt. The key |
| that was pressed is inserted in the editing buffer so that it is |
| possible to type most GDB commands without interaction with the TUI |
| SingleKey mode. Once the command is entered the TUI SingleKey mode is |
| restored. The only way to permanently leave this mode is by typing 'q' |
| or 'C-x s'. |
| |