13.3 Breakpoints

Breakpoints can be set in any m-file function by using the dbstop function.

: dbstop func

: dbstop func line

: dbstop func line1 line2 …

: dbstop line1 …

: dbstop in func

: dbstop in func at line

: dbstop in func at line if "condition"

: dbstop in class at method

: dbstop if event

: dbstop if event ID

: dbstop (bp_struct)

: rline = dbstop …

Set breakpoints for the built-in debugger.

func is the name of a function on the current path. When already in debug mode the func argument can be omitted and the current function will be used. Breakpoints at subfunctions are set with the scope operator ‘>’. For example, If file.m has a subfunction func2, then a breakpoint in func2 can be specified by file>func2.

line is the line number at which to break. If line is not specified, it defaults to the first executable line in the file func.m. Multiple lines can be specified in a single command; when function syntax is used, the lines may also be passed as a single vector argument ([line1, line2, …]).

condition is any Octave expression that can be evaluated in the code context that exists at the breakpoint. When the breakpoint is encountered, condition will be evaluated, and execution will stop if condition is true. If condition cannot be evaluated, for example because it refers to an undefined variable, an error will be thrown. Expressions with side effects (such as y++ > 1) will alter variables, and should generally be avoided. Conditions containing quotes (‘"’, ‘'’) or comment characters (‘#’, ‘%’) must be enclosed in quotes. (This does not apply to conditions entered from the editor’s context menu.) For example:

dbstop in axis at 246 if 'any (opt == "x")'

The form specifying event does not cause a specific breakpoint at a given function and line number. Instead it causes debug mode to be entered when certain unexpected events are encountered. Possible values are

error

Stop when an error is reported. This is equivalent to specifying both debug_on_error (true) and debug_on_interrupt (true).

caught error

Stop when an error is caught by a try-catch block (not yet implemented).

interrupt

Stop when an interrupt (Ctrl-C) occurs.

naninf

Stop when code returns a non-finite value (not yet implemented).

warning

Stop when a warning is reported. This is equivalent to specifying debug_on_warning (true).

The events error, caught error, and warning can all be followed by a string specifying an error ID or warning ID. If that is done, only errors with the specified ID will cause execution to stop. To stop on one of a set of IDs, multiple dbstop commands must be issued.

Breakpoints and events can be removed using the dbclear command with the same syntax.

It is possible to save all breakpoints and restore them at once by issuing the commands bp_state = dbstatus; …; dbstop (bp_state).

The optional output rline is the real line number where the breakpoint was set. This can differ from the specified line if the line is not executable. For example, if a breakpoint attempted on a blank line then Octave will set the real breakpoint at the next executable line.

When a file is re-parsed, such as when it is modified outside the GUI, all breakpoints within the file are cleared.

See also: dbclear, dbstatus, dbstep, debug_on_error, debug_on_warning, debug_on_interrupt.

Breakpoints in class methods are also supported (e.g., dbstop ("@class/method")). However, breakpoints cannot be set in built-in functions (e.g., sin, etc.) or dynamically loaded functions (i.e., oct-files).

To set a breakpoint immediately upon entering a function use line number 1, or omit the line number entirely and just give the function name. When setting the breakpoint Octave will ignore the leading comment block, and the breakpoint will be set on the first executable statement in the function. For example:

dbstop ("asind", 1)
⇒ 29

Note that the return value of 29 means that the breakpoint was effectively set to line 29. The status of breakpoints in a function can be queried with dbstatus.

: dbstatus

: dbstatus func

: bp_list = dbstatus …

Report the location of active breakpoints.

When called with no input or output arguments, print the list of all functions with breakpoints and the line numbers where those breakpoints are set.

If a function name func is specified then only report breakpoints for the named function and its subfunctions.

The optional return argument bp_list is a struct array with the following fields.

name

The name of the function with a breakpoint. A subfunction, say func2 within an m-file, say file.m, is specified as file>func2.

file

The name of the m-file where the function code is located.

line

The line number with the breakpoint.

cond

The condition that must be satisfied for the breakpoint to be active, or the empty string for unconditional breakpoints.

If dbstop if error is true but no explicit IDs are specified, the return value will have an empty field called "errs". If IDs are specified, the errs field will have one row per ID. If dbstop if error is false, there is no "errs" field. The "warn" field is set similarly by dbstop if warning.

See also: dbstop, dbclear, dbwhere, dblist, dbstack.

Reusing the previous example, dbstatus ("asind") will return 29. The breakpoints listed can then be cleared with the dbclear function.

: dbclear func

: dbclear func line

: dbclear func line1 line2 …

: dbclear line …

: dbclear all

: dbclear in func

: dbclear in func at line

: dbclear if event

: dbclear ("func")

: dbclear ("func", line)

: dbclear ("func", line1, line2, …)

: dbclear ("func", line1, …)

: dbclear (line, …)

: dbclear ("all")

Delete a breakpoint at line number line in the function func.

Arguments are

func

Function name as a string variable. When already in debug mode this argument can be omitted and the current function will be used.

line

Line number from which to remove a breakpoint. Multiple lines may be given as separate arguments or as a vector.

event

An event such as error, interrupt, or warning (see dbstop for details).

When called without a line number specification all breakpoints in the named function are cleared.

If the requested line is not a breakpoint no action is performed.

The special keyword "all" will clear all breakpoints from all files.

See also: dbstop, dbstatus, dbwhere.

A breakpoint may also be set in a subfunction. For example, if a file contains the functions

function y = func1 (x)
  y = func2 (x);
endfunction
function y = func2 (x)
  y = x + 1;
endfunction

then a breakpoint can be set at the start of the subfunction directly with

dbstop func1>func2
⇒ 5

Note that ‘>’ is the character that distinguishes subfunctions from the m-file containing them.

Another simple way of setting a breakpoint in an Octave script is the use of the keyboard function.

: keyboard ()

: keyboard ("prompt")

Stop m-file execution and enter debug mode.

When the keyboard function is executed, Octave prints a prompt and waits for user input. The input strings are then evaluated and the results are printed. This makes it possible to examine the values of variables within a function, and to assign new values if necessary. To leave the prompt and return to normal execution type ‘return’ or ‘dbcont’. The keyboard function does not return an exit status.

If keyboard is invoked without arguments, a default prompt of ‘debug> ’ is used.

See also: dbstop, dbcont, dbquit.

The keyboard function is placed in a script at the point where the user desires that the execution be stopped. It automatically sets the running script into the debug mode.