<html lang="en">
<head>
<title>Breakpoints - GNU Octave</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Octave">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Debugging.html#Debugging" title="Debugging">
<link rel="prev" href="Leaving-Debug-Mode.html#Leaving-Debug-Mode" title="Leaving Debug Mode">
<link rel="next" href="Debug-Mode.html#Debug-Mode" title="Debug Mode">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Breakpoints"></a>
<p>
Next: <a rel="next" accesskey="n" href="Debug-Mode.html#Debug-Mode">Debug Mode</a>,
Previous: <a rel="previous" accesskey="p" href="Leaving-Debug-Mode.html#Leaving-Debug-Mode">Leaving Debug Mode</a>,
Up: <a rel="up" accesskey="u" href="Debugging.html#Debugging">Debugging</a>
<hr>
</div>
<h3 class="section">13.3 Breakpoints</h3>
<p>Breakpoints can be set in any Octave function, using the <code>dbstop</code>
function.
<!-- dbstop src/debug.cc -->
<p><a name="doc_002ddbstop"></a>
<div class="defun">
— Loadable Function: <var>rline</var> = <b>dbstop</b> (<var>"func"</var>)<var><a name="index-dbstop-841"></a></var><br>
— Loadable Function: <var>rline</var> = <b>dbstop</b> (<var>"func", line, <small class="dots">...</small></var>)<var><a name="index-dbstop-842"></a></var><br>
<blockquote><p>Set a breakpoint in function <var>func</var>.
<p>Arguments are
<dl>
<dt><var>func</var><dd>Function name as a string variable. When already in debug
mode this should be left out and only the line should be given.
<br><dt><var>line</var><dd>Line number where the breakpoint should be set. Multiple
lines may be given as separate arguments or as a vector.
</dl>
<p>When called with a single argument <var>func</var>, the breakpoint
is set at the first executable line in the named function.
<p>The optional output <var>rline</var> is the real line number where the
breakpoint was set. This can differ from specified line if
the line is not executable. For example, if a breakpoint attempted on a
blank line then Octave will set the real breakpoint at the
next executable line.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002ddbclear.html#doc_002ddbclear">dbclear</a>, <a href="doc_002ddbstatus.html#doc_002ddbstatus">dbstatus</a>, <a href="doc_002ddbstep.html#doc_002ddbstep">dbstep</a>, <a href="doc_002ddebug_005fon_005ferror.html#doc_002ddebug_005fon_005ferror">debug_on_error</a>, <a href="doc_002ddebug_005fon_005fwarning.html#doc_002ddebug_005fon_005fwarning">debug_on_warning</a>, <a href="doc_002ddebug_005fon_005finterrupt.html#doc_002ddebug_005fon_005finterrupt">debug_on_interrupt</a>.
</p></blockquote></div>
<p class="noindent">Note that breakpoints cannot be set in built-in functions
(e.g., <code>sin</code>, etc.) or dynamically loaded function (i.e., oct-files). To
set a breakpoint immediately on entering a function, the breakpoint
should be set to line 1. The leading comment block will be ignored and
the breakpoint will be set to the first executable statement in the
function. For example:
<pre class="example"> dbstop ("asind", 1)
⇒ 28
</pre>
<p class="noindent">Note that the return value of <code>27</code> means that the breakpoint was
effectively set to line 27. The status of breakpoints in a function can
be queried with the <code>dbstatus</code> function.
<!-- dbstatus src/debug.cc -->
<p><a name="doc_002ddbstatus"></a>
<div class="defun">
— Loadable Function: <b>dbstatus</b> ()<var><a name="index-dbstatus-843"></a></var><br>
— Loadable Function: <var>brk_list</var> = <b>dbstatus</b> ()<var><a name="index-dbstatus-844"></a></var><br>
— Loadable Function: <var>brk_list</var> = <b>dbstatus</b> (<var>"func"</var>)<var><a name="index-dbstatus-845"></a></var><br>
<blockquote><p>Report the location of active breakpoints.
<p>When called with no input or output arguments, print the list of
all functions with breakpoints and the line numbers where those
breakpoints are set.
If a function name <var>func</var> is specified then only report breakpoints
for the named function.
<p>The optional return argument <var>brk_list</var> is a struct array with the
following fields.
<dl>
<dt>name<dd>The name of the function with a breakpoint.
<br><dt>file<dd>The name of the m-file where the function code is located.
<br><dt>line<dd>A line number, or vector of line numbers, with a breakpoint.
</dl>
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002ddbclear.html#doc_002ddbclear">dbclear</a>, <a href="doc_002ddbwhere.html#doc_002ddbwhere">dbwhere</a>.
</p></blockquote></div>
<p class="noindent">Taking the above as an example, <code>dbstatus ("asind")</code> should return
28. The breakpoints can then be cleared with the <code>dbclear</code> function
<!-- dbclear src/debug.cc -->
<p><a name="doc_002ddbclear"></a>
<div class="defun">
— Loadable Function: <b>dbclear</b> (<var>"func"</var>)<var><a name="index-dbclear-846"></a></var><br>
— Loadable Function: <b>dbclear</b> (<var>"func", line, <small class="dots">...</small></var>)<var><a name="index-dbclear-847"></a></var><br>
<blockquote><p>Delete a breakpoint in the function <var>func</var>.
<p>Arguments are
<dl>
<dt><var>func</var><dd>Function name as a string variable. When already in debug
mode this should be left out and only the line should be given.
<br><dt><var>line</var><dd>Line number from which to remove a breakpoint. Multiple
lines may be given as separate arguments or as a vector.
</dl>
<p>When called without a line number specification all breakpoints
in the named function are cleared.
<p>If the requested line is not a breakpoint no action is performed.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002ddbstop.html#doc_002ddbstop">dbstop</a>, <a href="doc_002ddbstatus.html#doc_002ddbstatus">dbstatus</a>, <a href="doc_002ddbwhere.html#doc_002ddbwhere">dbwhere</a>.
</p></blockquote></div>
<p class="noindent">These functions can be used to clear all the breakpoints in a function. For
example:
<pre class="example"> dbclear ("asind", dbstatus ("asind"));
</pre>
<p>A breakpoint can be set in a subfunction. For example if a file contains
the functions
<pre class="example"> function y = func1 (x)
y = func2 (x);
endfunction
function y = func2 (x)
y = x + 1;
endfunction
</pre>
<p class="noindent">then a breakpoint can be set at the start of the subfunction directly
with
<pre class="example"> dbstop (["func1", filemarker(), "func2"])
⇒ 5
</pre>
<p>Note that <code>filemarker</code> returns a character that marks the
subfunctions from the file containing them.
<p>Another simple way of setting a breakpoint in an Octave script is the
use of the <code>keyboard</code> function.
<!-- keyboard src/input.cc -->
<p><a name="doc_002dkeyboard"></a>
<div class="defun">
— Built-in Function: <b>keyboard</b> ()<var><a name="index-keyboard-848"></a></var><br>
— Built-in Function: <b>keyboard</b> (<var>prompt</var>)<var><a name="index-keyboard-849"></a></var><br>
<blockquote><p>This function is normally used for simple debugging. When the
<code>keyboard</code> function is executed, Octave prints a prompt and waits
for user input. The input strings are then evaluated and the results
are printed. This makes it possible to examine the values of variables
within a function, and to assign new values if necessary. To leave the
prompt and return to normal execution type ‘<samp><span class="samp">return</span></samp>’ or ‘<samp><span class="samp">dbcont</span></samp>’.
The <code>keyboard</code> function does not return an exit status.
<p>If <code>keyboard</code> is invoked without arguments, a default prompt of
‘<samp><span class="samp">debug> </span></samp>’ is used.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002ddbcont.html#doc_002ddbcont">dbcont</a>, <a href="doc_002ddbquit.html#doc_002ddbquit">dbquit</a>.
</p></blockquote></div>
<p class="noindent">The <code>keyboard</code> function is typically placed in a script at the
point where the user desires that the execution is stopped. It
automatically sets the running script into the debug mode.
</body></html>
