Previous: Lazy Strings In Python, Up: Python API


23.2.2.20 Manipulating breakpoints using Python

Python code can manipulate breakpoints via the gdb.Breakpoint class.

— Method on Breakpoint: __init__ spec [type] [wp_class] [internal]

Create a new breakpoint. spec is a string naming the location of the breakpoint, or an expression that defines a watchpoint. The contents can be any location recognized by the 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: BP_BREAKPOINT or BP_WATCHPOINT. type defaults to 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 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.

— Operation on gdb.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 as 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.

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:

WP_READ
Read only watchpoint.


WP_WRITE
Write only watchpoint.


WP_ACCESS
Read/Write watchpoint.
— Method on 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.

— Method on 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.

— Instance Variable of Breakpoint: enabled

This attribute is True if the breakpoint is enabled, and False otherwise. This attribute is writable.

— Instance Variable of 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.

— Instance Variable of 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.

— Instance Variable of 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.

— Instance Variable of Breakpoint: ignore_count

This attribute holds the ignore count for the breakpoint, an integer. This attribute is writable.

— Instance Variable of Breakpoint: number

This attribute holds the breakpoint's number — the identifier used by the user to manipulate the breakpoint. This attribute is not writable.

— Instance Variable of 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.

— Instance Variable of 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.

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.


BP_READ_WATCHPOINT
Hardware assisted read watchpoint.


BP_ACCESS_WATCHPOINT
Hardware assisted access watchpoint.
— Instance Variable of 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.

— Instance Variable of 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.

— Instance Variable of 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.

— Instance Variable of 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.

— Instance Variable of 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.