Documentation Center

  • Trial Software
  • Product Updates
我们为许可用户提供了部分翻译好的中文文档。您只需登录便可查阅这些文档

dbstop

Set breakpoints for debugging

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(s)

Description

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

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.

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

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

dbstop if condition pauses execution at the line that meets the specified condition.

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

Input Arguments

file

File specification, typically for a MATLAB function, specified as a string. The file specification can include a partial path, but must be in a folder on the search path, or in the current folder.

If the command includes the -completenames option, then the file need not be on the search path, as long as the file specification is a fully qualified name. In addition, filespec can include a filemarker (>) to specify the path to a particular local function or to a nested function within the file.

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 stop in the file, so it pauses before executing the file.

location

Location in file where you want to set a breakpoint, specified as one of the following:

  • lineno

    Line number in file specified as a string. The default is 1.

  • lineno@n

    nth anonymous function on line number, lineno, specified as a string. The default value of n is 1.

  • subfun

    Name of a local function in file, specified as a string.

expression

Code that evaluates (as if by eval) to a scalar logical value of 1 or 0, (true or false, respectively).

condition

Condition that causes execution to pause when that condition evaluates to true. Specify condition as one of the following:

  • 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 stops 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 stop only if a specific error occurs, specify the message id. See the error condition for an example of specifying a message id.

  • warning— Run-time warning occurs. If you want execution to pause only if a specific warning occurs, specify the message id. See the error condition for an example of specifying a message id.

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

  • naninf and infnan

    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. The naninf and infnan conditions have identical effects.

s

Breakpoints previously saved to a structure using s=dbstatus.

Examples

Stop at First Executable Line

This example shows how to set a breakpoint and pause execution at the first executable line in buggy.m.

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

    function z = buggy(x)
    n = length(x);
    z = (1:n)./x;
  2. Issue the dbstop command.

    dbstop in buggy
    
  3. Run buggy.

    buggy(2:5)

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

    2   n = length(x);
    K>> 
  4. Advance to the next line in the file.

    dbstep
  5. Examine the value of n in the Variable Editor.

    openvar('n')
  6. Quit debug mode.

    dbquit

Stop if Error

This example shows how to set a breakpoint and pause execution if a run-time error occurs.

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

    function z = buggy(x)
    n = length(x);
    z = (1:n)./x;
  2. Issue these statements in the Command Window:

    dbstop if error
    buggy(magic(3))

    Because buggy.m works on vectors only, the input in step 2 results in a run-time error. MATLAB goes into debug mode, paused at line 3 in buggy.m.

    Error using  ./ 
    Matrix dimensions must agree.
    
    Error in buggy at 3
    z = (1:n)./x; 
    3   z = (1:n)./x;
  3. Quit debug mode.

    dbquit

Stop if InfNaN

This example shows how to set a breakpoint and pause execution if the code returns a NaN value.

  1. Create a file, buggy.m, containing these statements.

    function z = buggy(x)
    n = length(x);
    z = (1:n)./x;
  2. Issue these commands.

    dbstop if naninf
    buggy(0:2)

    If any of the elements of the input, x, is zero, a division by zero occurs in buggy.m. Therefore, MATLAB returns the following message.

    NaN/Inf breakpoint hit for buggy on line 3.

    MATLAB is in debug mode, paused at line 3.

Stop at Function in File

This example shows how to set a breakpoint in the collatzall program file at the first executable line in the collatzplot_new function.

  1. Copy collatzall.m from the MATLAB examples folder to your current folder.

    copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',...
    'examples','collatzall.m'),'.','f')
    
  2. Open collatzall.m in the Editor.

    open collatzall.m
    
  3. Set the breakpoint.

     dbstop in collatzall>collatzplot_new
    

Stop at File That Is Not a MATLAB Code File

This example shows how to set a breakpoint at the built-in function clear when you run myfile.m.

  1. Create a file, myfile.m, in the Editor, containing these statements.

    function myfile(x)
    n = length(x);
    if n < 10
        disp('length is less than 10')
    else
        disp('length is 10 or greater')
    end
    clear
    disp('Value of n is cleared')
  2. Issue these commands to set the breakpoint.

    x = [1 2 3 4 5 6 7 8 9 10]
    dbstop in clear; myfile(x)

    MATLAB issues a warning, and pauses before the call to the clear function. The warning appears as shown in this image.

Restore Saved Breakpoints

This example shows how to save, and then restore, saved breakpoints.

  1. Copy collatzall.m from the MATLAB examples folder to your current folder.

    copyfile(fullfile(matlabroot,'help','techdoc','matlab_env', ...
        'examples','collatzall.m'),'.','f')
  2. Open collatzall.m in the Editor.

    open collatzall.m
    
  3. Set breakpoints from the Command Window.

    dbstop at 12 in collatzall
    dbstop if error
  4. Run dbstatus.

    dbstatus
    

    MATLAB describes the breakpoints you set.

    Breakpoint for collatzall>collatzplot_new is on line 12.
    Stop if error.
  5. Save the breakpoints to the structure, s, and then save s to the MAT-file, myfilebrkpnts.

    s=dbstatus('-completenames');
    save myfilebrkpnts s

    Using s=dbstatus('-completenames') saves absolute paths and the breakpoint function nesting sequence.

  6. Clear all breakpoints.

    dbclear collatzall
  7. Restore the breakpoints by loading the MAT-file.

    load myfilebrkpnts
    dbstop(s)

    The file (or files) containing the breakpoints must be on the search path or in the current folder.

  8. Verify the breakpoints.

    dbstatus collatzall

More About

expand all

fully qualified name

  • On Microsoft® Windows® platforms, a file name that begins with two back slashes (\\) or with a drive letter followed by a colon (:).

  • On UNIX® platforms, a file name that begins with a slash (/) or a tilde (~).

Tips

  • Use dbcont or dbstep to resume execution after a breakpoint pauses execution. Use dbquit to exit debug mode.

  • If you debug a file that MATLAB uses when running and debugging files, and that file is not a MATLAB code file, then some debugging features do not operate as expected. For instance, typing help functionname at the debug (K>>) prompt will not return help.

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

  • If MATLAB pauses and displays a hyperlinked line number in the Command Window, click the hyperlink, The file opens in the Editor at the line where MATLAB paused execution. For an example of such a link, see the image in Stop at File That Is Not a MATLAB Code File

  • You can set breakpoints only at executable lines in saved files that are in the current folder or in folders on the search path.

  • dbstop if warning has no effect when you disable warnings using warning off all. Similarly, dbstop if warning identifier has no effect when you disable warnings for the specified message identifier. See warning for more information about off, all, and warning off identifier

See Also

| | | | | | | |

Related Examples

Was this topic helpful?