— Scheme Procedure: create-breakpoint! location [#:type type] [#:wp-class wp-class] [#:internal 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. This argument can be either: BP_BREAKPOINT or BP_WATCHPOINT. type 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 created, 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: breakpoint-delete! breakpoint

Permanently delete breakpoint. This also invalidates the Guile breakpoint object. Any further attempt to access the object will throw an exception.

— 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. 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. 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 (create-breakpoint! "main.c:42"))
          (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.