### 13.3 Breakpoints

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

Command: dbstop func
Command: dbstop func line
Command: dbstop func line1 line2 …
Command: dbstop line …
Built-in Function: rline = dbstop ("func")
Built-in Function: rline = dbstop ("func", line)
Built-in Function: rline = dbstop ("func", line1, line2, …)
Built-in Function: dbstop ("func", [line1, …])
Built-in Function: dbstop (line, …)

  Set a breakpoint at line number line in 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 where the breakpoint should be set. Multiple lines may be given as separate arguments or as a vector.

  When called with a single argument func, the breakpoint is set at the first executable line in the named function.

  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.

  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`.

Built-in Function: dbstatus ()
Built-in Function: brk_list = dbstatus ()
Built-in Function: brk_list = dbstatus ("func")

  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.

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

  name

    The name of the function with a breakpoint.

  file

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

  line

    A line number, or vector of line numbers, with a breakpoint.

  Note: When `dbstatus` is called from the debug prompt within a function, the list of breakpoints is automatically trimmed to the breakpoints in the current function.

  See also: dbclear, dbwhere.

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

Command: dbclear func
Command: dbclear func line
Command: dbclear func line1 line2 …
Command: dbclear line …
Command: dbclear all
Built-in Function: dbclear ("func")
Built-in Function: dbclear ("func", line)
Built-in Function: dbclear ("func", line1, line2, …)
Built-in Function: dbclear ("func", [line1, …])
Built-in Function: dbclear (line, …)
Built-in Function: 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.

  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", filemarker(), "func2"])
    ⇒ 5

Note that `filemarker` returns the character that marks subfunctions from the file containing them. Unless the default has been changed this character is ‘`>`’. Thus, a quicker and more normal way to set the breakpoint would be

    dbstop func1>func2

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

Built-in Function: keyboard ()
Built-in Function: keyboard ("prompt")

  This function is normally used for simple debugging. 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.