dbstop

Set breakpoints for debugging

collapse all in page

Syntax

dbstop in file
dbstop in file at location
dbstop in file if expression
dbstop in file at location if expression
dbstop if condition
dbstop(b)

Description

dbstop in file sets a breakpoint at the first executable line in file. When you run file, MATLAB® enters debug mode, pauses execution at the breakpoint, and displays the line where it is paused.

example

dbstop in file at location sets a breakpoint at the specified location. MATLAB execution pauses immediately before that location, unless the location is an anonymous function. If the location is an anonymous function, then execution pauses just after the breakpoint.

example

dbstop in file if expression sets a conditional breakpoint at the first executable line of the file. Execution pauses only if expression evaluates to true (1).

example

dbstop in file at location if expression sets a conditional breakpoint at the specified location. Execution pauses at or just before that location only if the expression evaluates to true.

example

dbstop if condition pauses execution at the line that meets the specified condition, such as error or naninf. Unlike other breakpoints, you do not set this breakpoint at a specific line in a specific file. MATLAB pauses at any line in any file when the specified condition occurs.

example

dbstop(b) restores breakpoints you previously saved to b. The files containing the saved breakpoints must be on the search path or in the current folder. MATLAB assigns breakpoints by line number, so the lines in the file must be the same as when you saved the breakpoints.

example

Examples

collapse all

Set a breakpoint and pause execution at the first executable line of a program.

Create a file, buggy.m, that contains these statements.

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

Issue the dbstop command and run buggy.

dbstop in buggy
buggy(1:5)

MATLAB displays the line where it pauses and enters debug mode.

2   n = length(x);
K>>

Type dbquit to exit debug mode.

Set a breakpoint in a program at the first executable line of a local function.

Create a file, myfile.m, that contains these statements

function n = myfile(x)
n = myfunction(x);

function y = myfunction(x)
y = x + 1;

Set a breakpoint at myfunction.

 dbstop in myfile>myfunction

Set a breakpoint in a program that causes MATLAB to pause after some iterations of a loop.

Create a file, myprogram.m, that contains these statements

x = ones(1,10);

for n = 1:10
x(n) = x(n) + 1;
end

Set a breakpoint to pause when n >= 4, and run the code.

dbstop in myprogram at 4 if n>=4
myprogram

MATLAB pauses at line 4 after 3 iterations of the loop, when n = 4.

4   x(n) = x(n) + 1;
K>>

Type dbquit to exit debug mode.

Set a breakpoint and pause execution if a run-time error occurs.

Create a file, mybuggyprogram.m, that contains these statements.

x = ones(1,10);

for n = 1:10
x(n) = x(n+1) + 1;
end

Set an error breakpoint, and call mybuggyprogram.

dbstop if error
mybuggyprogram

A run-time error occurs, and MATLAB goes into debug mode, pausing at line 4 in mybuggyprogram.m.

Index exceeds matrix dimensions.
Error in mybuggyprogram (line 4)
x(n) = x(n+1) + 1; 
4   x(n) = x(n+1) + 1;

Type dbquit to exit debug mode.

Run MException.last to obtain the error message identifier generated by the program. 

MException.last
ans = 

  MException with properties:

    identifier: 'MATLAB:badsubscript'
       message: 'Index exceeds matrix dimensions.'
         cause: {}
         stack: [1×1 struct]

Clear the error breakpoint and set a new error breakpoint specifying the identifier of the error message to catch. Call mybuggyprogram.

dbclear if error
dbstop if error MATLAB:badsubscript
mybuggyprogram

The same run-time error occurs, and MATLAB goes into debug mode, pausing at line 4 in mybuggyprogram.m.

Index exceeds matrix dimensions.
Error in mybuggyprogram (line 4)
x(n) = x(n+1) + 1; 
4   x(n) = x(n+1) + 1;

Type dbquit to exit debug mode.

Set a breakpoint and pause execution if the code returns a NaN or Inf value.

Create a file, buggy.m, that requires an input vector.

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

Set a warning breakpoint, and call buggy with an input vector containing a 0 as one of its elements.

dbstop if naninf
buggy(0)

A division by zero error occurs, and MATLAB goes into debug mode, pausing at line 3 in buggy.m.

NaN/Inf breakpoint hit for buggy on line 3.

Type dbquit to exit debug mode.

Set, save, clear, and then restore saved breakpoints.

Create a file, buggy.m, which contains these statements.

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

Set an error breakpoint and a standard breakpoint at the second line in buggy.

dbstop at 2 in buggy
dbstop if error

Run dbstatus. MATLAB describes the breakpoints you set.

dbstatus

Breakpoint for buggy is on line 2.
Stop if error.

Assign a structure representing the breakpoints to the variable b, and then save b to the MAT-file buggybrkpnts. Use b=dbstatus('-completenames') to save absolute paths and the breakpoint function nesting sequence.

b = dbstatus('-completenames');
save buggybrkpnts b

Clear all breakpoints.

dbclear all

Restore the breakpoints by loading the MAT-file and calling dbstop with the saved structure, b.

load buggybrkpnts
dbstop(b)

Input Arguments

collapse all

File name, specified as a character vector or string scalar. The file name can include a partial path name for files on the MATLAB search path or an absolute path name for any file. For more information on valid file names in MATLAB, see Specify File Names.

Example: myfile.m

In addition, file can include a filemarker (>) to specify the path to a particular local function or to a nested function within the file.

Example: myfile>myfunction

If file is not a MATLAB code file (for instance, it is a built-in or MDL-file), then MATLAB issues a warning. MATLAB cannot pause in the file, so it pauses before executing the file.

Data Types: char | string

Breakpoint location to set in file, specified as one of these options:

  • Line number in file specified as a character vector or string scalar. The default is 1.

  • Line number in file, located at the anonymous function number and specified as a character vector or string scalar. For example, 1@2 specifies line number 1 at the second anonymous function. The default anonymous function number is 1.

  • Name of a local function in file, specified as a character vector or string scalar.

Note

When setting a breakpoint, you cannot specify location if file includes a filemarker. For example, the command dbstop in myfile>myfilefunction at 5 is invalid.

Data Types: char | string

Logical expression that evaluates to a scalar logical value of 1 or 0, specified as a character vector or string scalar.

Example: n >= 4

Data Types: char | string

Pause condition, specified as one of these options:

  • error — Run-time error that occurs outside a try/catch block. You cannot resume execution after an uncaught run-time error.

    If you want execution to pause only if a specific error occurs, specify the message id. For example:

    • dbstop if error pauses execution at the first run-time error that occurs outside a try/catch block.

    • dbstop if error MATLAB:ls:InputsMustBeStrings pauses execution at the first run-time error outside a try/catch block that has a message ID of MATLAB:ls:InputsMustBeStrings.

  • caught error — Run-time error that occurs within the try portion of a try/catch block. If you want execution to pause only if a specific error occurs, specify the message id.

  • warning — Run-time warning occurs. If you want execution to pause only if a specific warning occurs, specify the message id.

    This condition has no effect if you disable warnings with the warning off all command or if you disable warnings for the specified id. For more information about disabling warnings, see warning.

  • naninf — The code returns an infinite value (Inf) or a value that is not a number (NaN) as a result of an operator, function call, or scalar assignment.

  • unsuppressed output— The code displays an unsuppressed output because the line is not suppressed by a semicolon (;). Outputs that are displayed as the result of a function call, such as from disp or fprintf will not stop execution. (since R2024b)

List of breakpoints previously saved to a structure array using b=dbstatus.

Tips

  • Before you begin debugging, make sure that your program is saved and that the program and any files it calls exist on your search path or in the current folder.

  • To resume execution after a breakpoint pauses execution, use dbcont or dbstep. To exit debug mode, use dbquit. To remove all the breakpoints in the file, use dbclear in filename. To remove all breakpoints in all files, use dbclear all. For more information, see dbclear.

  • MATLAB can become unresponsive when it pauses at a breakpoint while displaying a modal dialog box or figure created by your program. To exit debug mode and return to the MATLAB prompt (>>), use Ctrl+C.

Version History

Introduced before R2006a

expand all

See Also

| | | | | | |

Topics