dbstack

Function call stack

Syntax

dbstack

dbstack(n)

dbstack(___, '-completenames')

ST = dbstack(___)

[ST,I] = dbstack(___)

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.

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.

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.

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

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

Examples

View Stack Trace Information While Debugging

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 Complete Names for Each Function in Stack

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

n — Number of frames to omit

nonnegative integer

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

Output Arguments

ST — Stack trace information

structure array

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.

file	File in which the function appears. This field is empty if there is no file.
name	Function name within the file.
line	Line 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.

I — Current workspace index

positive integer

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

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a