MATLAB Function Reference

dbstop - Set breakpoints

GUI Alternative

Use the Debug menu in most desktop tools, or the context menu in Editor. See details.

Syntax

dbstop in mfile ... dbstop in nonmfile dbstop if error ... dbstop if warning ... dbstop if naninf dbstop if infnan dbstop(s)

Description

dbstop in mfile ... formats are listed here:

Format	Action	Additional Information
`dbstop` `in` `mfile`	Temporarily stops execution of the running `mfile` at the first executable line, putting MATLAB^® software in debug mode. `mfile` must be the name of an M-file, and can include a MATLAB`partialpath`. If the command includes the `-completenames` option, then `mfile` need not be on the path, as long as it is a fully qualified file name. (On Microsoft^®Windows^®, this is a file name that begins with `\\` or with a drive `%` letter followed by a colon. On UNIX^® platforms, this is a file name that begins with `/` or `~`.) `mfile` can include a `filemarker` to specify the path to a particular subfunction or to a nested function within an M-file. The `in` keyword is optional.	If you have graphical debugging enabled, the MATLAB Debugger opens with a breakpoint at the first executable line of `mfile`. You can then use the debugging utilities, review the workspace, or issue any valid MATLAB function. Use `dbcont` or `dbstep` to resume execution of `mfile`. Use `dbquit` to exit from debug mode.
`dbstop` `in` `mfile` `at` `lineno`	Temporarily stops execution of running `mfile` just prior to execution of the line whose number is `lineno`, putting MATLAB in debug mode. If that line is not executable, execution stops and the breakpoint is set at the next executable line following `lineno`. `mfile` must be in a directory that is on the search path, or in the current directory. The `at` keyword is optional.	If you have graphical debugging enabled, MATLAB opens `mfile` with a breakpoint at line `lineno`. When execution stops, you can use the debugging utilities, review the workspace, or issue any valid MATLAB function. Use `dbcont` or `dbstep` to resume execution of `mfile`. Use `dbquit` to exit from debug mode
`dbstop` `in` `mfile` `at` `lineno``@`	Stops just after any call to the first anonymous function in the specified line number in `mfile`.
`dbstop` `in` `mfile` `at` `lineno``@``n`	Stops just after any call to the `n`the anonymous function in the specified line number in `mfile`.
`dbstop` `in` `mfile` `at` `subfun`	Temporarily stops execution of running `mfile` just prior to execution of the subfunction `subfun`, putting MATLAB in debug mode. `mfile` must be in a directory that is on the search path, or in the current directory.	If you have graphical debugging enabled, MATLAB opens `mfile` with a breakpoint at the subfunction `subfun`. You can then use the debugging utilities, review the workspace, or issue any valid MATLAB function. Use `dbcont` or `dbstep` to resume execution of `mfile`. Use `dbquit` to exit from debug mode.
`dbstop` `in` `mfile` `at` `lineno` `if` `expression`	Temporarily stops execution of running `mfile`, just prior to execution of the line whose number is `lineno`, putting MATLAB in debug mode. Execution stops only if expression evaluates to `true`. `expression` is evaluated (as if by `eval`), in `mfile`'s workspace when the breakpoint is encountered, and must evaluate to a scalar logical value (`1` or `0` for true or false). If that line is not executable, execution stops and the breakpoint is set at the next executable line following `lineno`. `mfile` must be in a directory that is on the search path, or in the current directory.	If you have graphical debugging enabled, MATLAB opens `mfile` with a breakpoint at line `lineno`. When execution stops, you can use the debugging utilities, review the workspace, or issue any valid MATLAB function. Use `dbcont` or `dbstep` to resume execution of `mfile`. Use `dbquit` to exit from debug mode.
`dbstop` `in` `mfile` `at` `lineno``@ if` `expression`	Stops just after any call to the first anonymous function in the specified line number in `mfile` if `expression` evaluates to logical `1` (true).
`dbstop` `in` `mfile` `at` `lineno``@``n` `if` `expression`	Stops just after any call to the `n`the anonymous function in the specified line number in `mfile` if `expression` evaluates to logical `1` (true).
`dbstop` `in` `mfile` `if` `expression`	Temporarily stops execution of running `mfile`, at the first executable line, putting MATLAB in debug mode. Execution stops only if `expression` evaluates to logical `1` (true). `expression` is evaluated (as if by `eval`), in `mfile`'s workspace when the breakpoint is encountered, and must evaluate to a scalar logical value (`0` or `1` for true or false). `mfile` must be in a directory on the search path, or in the current directory	If you have graphical debugging enabled, MATLAB opens `mfile` with a breakpoint at the first executable line of `mfile`. You can then use the debugging utilities, review the workspace, or issue any valid MATLAB function. Use `dbcont` or `dbstep` to resume execution of `mfile`. Use `dbquit` to exit from debug mode.
`dbstop` `in` `mfile` `at` `subfun` `if` `expression`	Temporarily stops execution of running `mfile`, just prior to execution of the subfunction `subfun`, putting MATLAB in debug mode. Execution stops only if `expression` evaluates to logical `1` (true). `expression` is evaluated (as if by `eval`), in `mfile`'s workspace when the breakpoint is encountered, and must evaluate to a scalar logical value (`0` or `1` for true or false). `mfile` must be in a directory on the search path, or in the current directory	If you have graphical debugging enabled, MATLAB opens `mfile` with a breakpoint at the subfunction specified by `subfun`. You can then use the debugging utilities, review the workspace, or issue any valid MATLAB function. Use `dbcont` or `dbstep` to resume execution of `mfile`. Use `dbquit` to exit from debug mode.

dbstop in nonmfile temporarily stops execution of the running M-file at the point where nonmfile is called. This puts MATLAB in debug mode, where nonmfile is, for example, a built-in or MDL-file. MATLAB issues a warning because it cannot actually stop in the file; rather MATLAB stops prior to the file's execution. Once stopped, you can examine values and code around that point in the execution. Use dbstop in nonmfile with caution because the debugger stops in M-files it uses for running and debugging if they contain nonmfile. As a result, some debugging features do not operate as expected, such as typing help functionname at the K>> prompt.

dbstop if error ... formats are listed here:

Format	Action
`dbstop` `if error`	Stops execution when any M-file you subsequently run produces a run-time error, putting MATLAB in debug mode, paused at the line that generated the error. The errors that stop execution do not include run-time errors that are detected within a `try...catch` block. You cannot resume execution after an uncaught run-time error. Use `dbquit` to exit from debug mode.
`dbstop` `if error` `identifier`	Stops execution when any M-file you subsequently run produces a run-time error whose message identifier is `identifier`, putting MATLAB in debug mode, paused at the line that generated the error. The errors that stop execution do not include run-time errors that are detected within a `try...catch` block. You cannot resume execution after an uncaught run-time error. Use `dbquit` to exit from debug mode.
`dbstop` `if caught error`	Stops execution when any M-file you subsequently run produces a run-time error, putting MATLAB in debug mode, paused at the line in the `try` portion of the block that generated the error. The errors that stop execution are those detected within a `try...catch` block.
`dbstop` `if caught error` `identifier`	Stops execution when any M-file you subsequently run produces a run-time error whose message identifier is `identifier`, putting MATLAB in debug mode, paused at the line in the `try` portion of the block that generated the error. The errors that stop execution are those detected within a `try...catch` block.

dbstop if warning ... formats are listed here:

Format	Action
`dbstop` `if warning`	Stops execution when any M-file you subsequently run produces a run-time warning, putting MATLAB in debug mode, paused at the line that generated the warning. Use `dbcont` or `dbstep` to resume execution.
`dbstop` `if warning` `identifier`	Stops execution when any M-file you subsequently run produces a runtime warning whose message identifier is `identifier`, putting MATLAB in debug mode, paused at the line that generated the warning. Use `dbcont` or `dbstep` to resume execution.

dbstop if naninf or dbstop if infnan stops execution when any M-file you subsequently run produces an infinite value (Inf) or a value that is not a number (NaN) as a result of an operator, function call, or scalar assignment, putting MATLAB in debug mode, paused immediately after the line where Inf or NaN was encountered. For convenience, you can use either naninf or infnan—they perform in exactly the same manner. Use dbcont or dbstep to resume execution. Use dbquit to exit from debug mode.

dbstop(s) restores breakpoints previously saved to the structure s using s=dbstatus. The files for which the breakpoints have been saved need to be on the search path or in the current directory. In addition, because the breakpoints are assigned by line number, the lines in the file need to be the same as when the breakpoints were saved, or the results are unpredictable. See the example Restore Saved Breakpoints and dbstatus for more information.

Remarks

Note that MATLAB could become nonresponsive if it stops at a breakpoint while displaying a modal dialog box or figure that your M-file creates. In that event, use Ctrl+C to go the MATLAB prompt.

To open the M-file in the Editor when execution reaches a breakpoint, select Debug > Open M-Files When Debugging.

To stop at each pass through a for loop, do not set the breakpoint at the for statement. For example, in

for n = 1:10 
    m = n+1; 
end

MATLAB executes the for statement only once, which is efficient. Therefore, when you set a breakpoint at the for statement and step through the file, you only stop at the for statement once. Instead place the breakpoint at the next line, m=n+1 to stop at each pass through the loop.

Examples

The file buggy, used in these examples, consists of three lines.

function z = buggy(x)
n = length(x);
z = (1:n)./x;

Stop at First Executable Line

The statements

dbstop in buggy
buggy(2:5)

stop execution at the first executable line in buggy:

n = length(x);

The function

dbstep

advances to the next line, at which point you can examine the value of n.

Stop if Error

Because buggy only works on vectors, it produces an error if the input x is a full matrix. The statements

dbstop if error
buggy(magic(3))

produce

??? Error using ==> ./
Matrix dimensions must agree.
Error in ==> c:\buggy.m
On line 3 ==> z = (1:n)./x;
K>>

and put MATLAB in debug mode.

Stop if InfNaN

In buggy, if any of the elements of the input x is zero, a division by zero occurs. The statements

dbstop if naninf
buggy(0:2)

produce

Warning: Divide by zero.
> In c:\buggy.m at line 3
K>>

and put MATLAB in debug mode.

Stop at Function in File

In this example, MATLAB stops at the newTemp function in the M-file yearlyAvgs:

dbstop in yearlyAvgs>newTemp

Stop at Non M-File

In this example, MATLAB stops at the built-in function clear when you run myfile.m.

dbstop in clear; myfile

MATLAB issues a warning, but permits the stop:

Warning: MATLAB debugger can only stop in M-files, and 
"m_interpreter>clear" is not an M-file.
Instead, the debugger will stop at the point right before 
"m_interpreter>clear" is called.

Execution stops in myfile at the point where the clear function is called.

Restore Saved Breakpoints

Set breakpoints in myfile as follows:
```
dbstop at 12 in myfile
dbstop if error
```

Running dbstatus shows

Breakpoint for myfile is on line 12.
Stop if error.

Save the breakpoints to the structure s, and then save s to the MAT-file myfilebrkpnts.
```
s = dbstatus
save myfilebrkpnts s
```
Use s=dbstatus('completenames') to save absolute paths and the breakpoint function nesting sequence.
At this point, you can end the debugging session and clear all breakpoints, or even end the MATLAB session.
When you want to restore the breakpoints, be sure all of the files containing the breakpoints are on the search path or in the current directory. Then load the MAT-file, which adds s to the workspace, and restore the breakpoints as follows:
```
load myfilebrkpnts
dbstop(s)
```
Verify the breakpoints by running dbstatus, which shows
```
dbstop at 12 in myfile
dbstop if error
```
If you made changes to myfile after saving the breakpoints, the results from restoring the breakpoints are not predictable. For example, if you added a new line prior to line 12 in myfile, the breakpoint will now be set at the new line 12.