Main Content

dbstack

Function call stack

Description

dbstack displays the line numbers and file names of the function calls that led to the current pause condition, listed in the order in which they execute. The display starts with the currently executing functions and continues until it reaches the topmost function. Each line number is a hyperlink to that line in the Editor. The notation functionname>localfunctionname describes the location of a local function.

example

dbstack(n) omits the first n stack frames from the display. This syntax can be useful, for example, when issuing a dbstack from within an error handler.

example

dbstack(___, '-completenames') outputs the fully qualified name of each function in the stack.

You can specify '-completenames' with any of the input arguments in the previous syntaxes.

example

ST = dbstack(___) returns the stack trace information in an m-by-1 structure, ST.

example

[ST,I] = dbstack(___) also returns I, the current workspace index.

example

Examples

collapse all

While debugging a MATLAB® code file, issue the dbstack command to view the stack trace information.

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

function n = myfile(x)
n = myfunction(x-1);
end

function z = myfunction(y)
z = 2 / y;
end

Set a breakpoint at myfunction and run myfile with an input of 1. While executing myfunction, MATLAB pauses at the line z = 2/y.

dbstop in myfile>myfunction
myfile(1);

Run the dbstack command. MATLAB displays the line numbers and file names of the function calls that led to the current breakpoint.

dbstack
In myfile>myfunction (line 5)
In myfile (line 2)

Store the complete file name, function name, and line number for each function in the stack while debugging a file.

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

function n = myfile(x)
n = myfunction(x-1);
end

function z = myfunction(y)
z = 2 / y;
end

Set a breakpoint at myfunction and run myfile with an input of 1. While executing myfunction, MATLAB pauses at the line z = 2/y.

dbstop in myfile>myfunction
myfile(1);

Run the dbstack command, omitting the first frame and requesting complete names. MATLAB returns the stack trace information in the specified structure ST.

[ST, I] = dbstack('-completenames', 1)
ST = 

    file: 'C:\myProject\myfile.m'
    name: 'myfile'
    line: 2


I =

     1

Input Arguments

collapse all

Number of frames to omit, specified as a nonnegative integer.

Output Arguments

collapse all

Stack trace information, returned as an m-by-1 structure, where m is the number of functions in the call stack. The structure has these fields.

fileFile in which the function appears. This field is empty if there is no file.
nameFunction name within the file.
lineLine number of function call.

Note

If you step past the end of a file, dbstack returns a negative line number value to identify that special case. For example, if the last line to be executed is line 15, then the dbstack line number is 15 before you execute that line and -15 after.

Current workspace index, returned as a positive integer. The index represents the number of workspaces between your current workspace and the workspace in which MATLAB is currently paused or executing.

Extended Capabilities

Version History

Introduced before R2006a