1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Breakpoints</title>
<meta name="description" content="GNU Octave: Breakpoints">
<meta name="keywords" content="GNU Octave: Breakpoints">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Debugging.html#Debugging" rel="up" title="Debugging">
<link href="Debug-Mode.html#Debug-Mode" rel="next" title="Debug Mode">
<link href="Leaving-Debug-Mode.html#Leaving-Debug-Mode" rel="prev" title="Leaving Debug Mode">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Breakpoints"></a>
<div class="header">
<p>
Next: <a href="Debug-Mode.html#Debug-Mode" accesskey="n" rel="next">Debug Mode</a>, Previous: <a href="Leaving-Debug-Mode.html#Leaving-Debug-Mode" accesskey="p" rel="prev">Leaving Debug Mode</a>, Up: <a href="Debugging.html#Debugging" accesskey="u" rel="up">Debugging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Breakpoints-1"></a>
<h3 class="section">13.3 Breakpoints</h3>
<p>Breakpoints can be set in any m-file function by using the <code>dbstop</code>
function.
</p>
<a name="XREFdbstop"></a><dl>
<dt><a name="index-dbstop"></a>Command: <em></em> <strong>dbstop</strong> <em><var>func</var></em></dt>
<dt><a name="index-dbstop-1"></a>Command: <em></em> <strong>dbstop</strong> <em><var>func</var> <var>line</var></em></dt>
<dt><a name="index-dbstop-2"></a>Command: <em></em> <strong>dbstop</strong> <em><var>func</var> <var>line1</var> <var>line2</var> …</em></dt>
<dt><a name="index-dbstop-3"></a>Command: <em></em> <strong>dbstop</strong> <em><var>line</var> …</em></dt>
<dt><a name="index-dbstop-4"></a>Built-in Function: <em><var>rline</var> =</em> <strong>dbstop</strong> <em>("<var>func</var>")</em></dt>
<dt><a name="index-dbstop-5"></a>Built-in Function: <em><var>rline</var> =</em> <strong>dbstop</strong> <em>("<var>func</var>", <var>line</var>)</em></dt>
<dt><a name="index-dbstop-6"></a>Built-in Function: <em><var>rline</var> =</em> <strong>dbstop</strong> <em>("<var>func</var>", <var>line1</var>, <var>line2</var>, …)</em></dt>
<dt><a name="index-dbstop-7"></a>Built-in Function: <em></em> <strong>dbstop</strong> <em>("<var>func</var>", [<var>line1</var>, …])</em></dt>
<dt><a name="index-dbstop-8"></a>Built-in Function: <em></em> <strong>dbstop</strong> <em>(<var>line</var>, …)</em></dt>
<dd><p>Set a breakpoint at line number <var>line</var> in function <var>func</var>.
</p>
<p>Arguments are
</p>
<dl compact="compact">
<dt><var>func</var></dt>
<dd><p>Function name as a string variable. When already in debug mode this argument
can be omitted and the current function will be used.
</p>
</dd>
<dt><var>line</var></dt>
<dd><p>Line number where the breakpoint should be set. Multiple lines may be given
as separate arguments or as a vector.
</p></dd>
</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>
<p>The optional output <var>rline</var> is the real line number where the breakpoint
was set. This can differ from the 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.
</p>
<p><strong>See also:</strong> <a href="#XREFdbclear">dbclear</a>, <a href="#XREFdbstatus">dbstatus</a>, <a href="Debug-Mode.html#XREFdbstep">dbstep</a>, <a href="Entering-Debug-Mode.html#XREFdebug_005fon_005ferror">debug_on_error</a>, <a href="Entering-Debug-Mode.html#XREFdebug_005fon_005fwarning">debug_on_warning</a>, <a href="Entering-Debug-Mode.html#XREFdebug_005fon_005finterrupt">debug_on_interrupt</a>.
</p></dd></dl>
<p>Breakpoints in class methods are also supported (e.g.,
<code>dbstop ("@class/method")</code>). However, breakpoints cannot be set in
built-in functions (e.g., <code>sin</code>, etc.) or dynamically loaded functions
(i.e., oct-files).
</p>
<p>To set a breakpoint immediately upon entering a function use line number 1, or
omit the line number entirely and just give the function name. When setting
the breakpoint Octave will ignore the leading comment block, and the breakpoint
will be set on the first executable statement in the function. For example:
</p>
<div class="example">
<pre class="example">dbstop ("asind", 1)
⇒ 29
</pre></div>
<p>Note that the return value of <code>29</code> means that the breakpoint was
effectively set to line 29. The status of breakpoints in a function can
be queried with <code>dbstatus</code>.
</p>
<a name="XREFdbstatus"></a><dl>
<dt><a name="index-dbstatus"></a>Built-in Function: <em></em> <strong>dbstatus</strong> <em>()</em></dt>
<dt><a name="index-dbstatus-1"></a>Built-in Function: <em><var>brk_list</var> =</em> <strong>dbstatus</strong> <em>()</em></dt>
<dt><a name="index-dbstatus-2"></a>Built-in Function: <em><var>brk_list</var> =</em> <strong>dbstatus</strong> <em>("<var>func</var>")</em></dt>
<dd><p>Report the location of active breakpoints.
</p>
<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.
</p>
<p>If a function name <var>func</var> is specified then only report breakpoints
for the named function.
</p>
<p>The optional return argument <var>brk_list</var> is a struct array with the
following fields.
</p>
<dl compact="compact">
<dt>name</dt>
<dd><p>The name of the function with a breakpoint.
</p>
</dd>
<dt>file</dt>
<dd><p>The name of the m-file where the function code is located.
</p>
</dd>
<dt>line</dt>
<dd><p>A line number, or vector of line numbers, with a breakpoint.
</p></dd>
</dl>
<p>Note: When <code>dbstatus</code> is called from the debug prompt within a function,
the list of breakpoints is automatically trimmed to the breakpoints in the
current function.
</p>
<p><strong>See also:</strong> <a href="#XREFdbclear">dbclear</a>, <a href="Debug-Mode.html#XREFdbwhere">dbwhere</a>.
</p></dd></dl>
<p>Reusing the previous example, <code>dbstatus ("asind")</code> will return
29. The breakpoints listed can then be cleared with the <code>dbclear</code>
function.
</p>
<a name="XREFdbclear"></a><dl>
<dt><a name="index-dbclear"></a>Command: <em></em> <strong>dbclear</strong> <em><var>func</var></em></dt>
<dt><a name="index-dbclear-1"></a>Command: <em></em> <strong>dbclear</strong> <em><var>func</var> <var>line</var></em></dt>
<dt><a name="index-dbclear-2"></a>Command: <em></em> <strong>dbclear</strong> <em><var>func</var> <var>line1</var> <var>line2</var> …</em></dt>
<dt><a name="index-dbclear-3"></a>Command: <em></em> <strong>dbclear</strong> <em><var>line</var> …</em></dt>
<dt><a name="index-dbclear-4"></a>Command: <em></em> <strong>dbclear</strong> <em>all</em></dt>
<dt><a name="index-dbclear-5"></a>Built-in Function: <em></em> <strong>dbclear</strong> <em>("<var>func</var>")</em></dt>
<dt><a name="index-dbclear-6"></a>Built-in Function: <em></em> <strong>dbclear</strong> <em>("<var>func</var>", <var>line</var>)</em></dt>
<dt><a name="index-dbclear-7"></a>Built-in Function: <em></em> <strong>dbclear</strong> <em>("<var>func</var>", <var>line1</var>, <var>line2</var>, …)</em></dt>
<dt><a name="index-dbclear-8"></a>Built-in Function: <em></em> <strong>dbclear</strong> <em>("<var>func</var>", [<var>line1</var>, …])</em></dt>
<dt><a name="index-dbclear-9"></a>Built-in Function: <em></em> <strong>dbclear</strong> <em>(<var>line</var>, …)</em></dt>
<dt><a name="index-dbclear-10"></a>Built-in Function: <em></em> <strong>dbclear</strong> <em>("all")</em></dt>
<dd><p>Delete a breakpoint at line number <var>line</var> in the function <var>func</var>.
</p>
<p>Arguments are
</p>
<dl compact="compact">
<dt><var>func</var></dt>
<dd><p>Function name as a string variable. When already in debug mode this argument
can be omitted and the current function will be used.
</p>
</dd>
<dt><var>line</var></dt>
<dd><p>Line number from which to remove a breakpoint. Multiple lines may be given
as separate arguments or as a vector.
</p></dd>
</dl>
<p>When called without a line number specification all breakpoints in the named
function are cleared.
</p>
<p>If the requested line is not a breakpoint no action is performed.
</p>
<p>The special keyword <code>"all"</code> will clear all breakpoints from all
files.
</p>
<p><strong>See also:</strong> <a href="#XREFdbstop">dbstop</a>, <a href="#XREFdbstatus">dbstatus</a>, <a href="Debug-Mode.html#XREFdbwhere">dbwhere</a>.
</p></dd></dl>
<p>A breakpoint may also be set in a subfunction. For example, if a file contains
the functions
</p>
<div class="example">
<pre class="example">function y = func1 (x)
y = func2 (x);
endfunction
function y = func2 (x)
y = x + 1;
endfunction
</pre></div>
<p>then a breakpoint can be set at the start of the subfunction directly with
</p>
<div class="example">
<pre class="example">dbstop (["func1", filemarker(), "func2"])
⇒ 5
</pre></div>
<p>Note that <code>filemarker</code> returns the character that marks subfunctions from
the file containing them. Unless the default has been changed this character
is ‘<samp>></samp>’. Thus, a quicker and more normal way to set the breakpoint would
be
</p>
<div class="example">
<pre class="example">dbstop func1>func2
</pre></div>
<p>Another simple way of setting a breakpoint in an Octave script is the
use of the <code>keyboard</code> function.
</p>
<a name="XREFkeyboard"></a><dl>
<dt><a name="index-keyboard"></a>Built-in Function: <em></em> <strong>keyboard</strong> <em>()</em></dt>
<dt><a name="index-keyboard-1"></a>Built-in Function: <em></em> <strong>keyboard</strong> <em>("<var>prompt</var>")</em></dt>
<dd><p>Stop m-file execution and enter debug mode.
</p>
<p>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>return</samp>’ or ‘<samp>dbcont</samp>’.
The <code>keyboard</code> function does not return an exit status.
</p>
<p>If <code>keyboard</code> is invoked without arguments, a default prompt of
‘<samp>debug> </samp>’ is used.
</p>
<p><strong>See also:</strong> <a href="#XREFdbstop">dbstop</a>, <a href="Leaving-Debug-Mode.html#XREFdbcont">dbcont</a>, <a href="Leaving-Debug-Mode.html#XREFdbquit">dbquit</a>.
</p></dd></dl>
<p>The <code>keyboard</code> function is placed in a script at the point where the user
desires that the execution be stopped. It automatically sets the running
script into the debug mode.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Debug-Mode.html#Debug-Mode" accesskey="n" rel="next">Debug Mode</a>, Previous: <a href="Leaving-Debug-Mode.html#Leaving-Debug-Mode" accesskey="p" rel="prev">Leaving Debug Mode</a>, Up: <a href="Debugging.html#Debugging" accesskey="u" rel="up">Debugging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|