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
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Breakpoints (GNU Octave (version 10.3.0))</title>
<meta name="description" content="Breakpoints (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Breakpoints (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Debugging.html" rel="up" title="Debugging">
<link href="Debug-Mode.html" rel="next" title="Debug Mode">
<link href="Leaving-Debug-Mode.html" rel="prev" title="Leaving Debug Mode">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
kbd.kbd {font-style: oblique}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="section-level-extent" id="Breakpoints">
<div class="nav-panel">
<p>
Next: <a href="Debug-Mode.html" accesskey="n" rel="next">Debug Mode</a>, Previous: <a href="Leaving-Debug-Mode.html" accesskey="p" rel="prev">Leaving Debug Mode</a>, Up: <a href="Debugging.html" 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" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Breakpoints-1"><span>13.3 Breakpoints<a class="copiable-link" href="#Breakpoints-1"> ¶</a></span></h3>
<p>Breakpoints can be set in any m-file function by using the <code class="code">dbstop</code>
function.
</p>
<a class="anchor" id="XREFdbstop"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-dbstop"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments"><var class="var">fcn</var></code><a class="copiable-link" href="#index-dbstop"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-1"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments"><var class="var">fcn</var> <var class="var">line</var></code><a class="copiable-link" href="#index-dbstop-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-2"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments"><var class="var">fcn</var> <var class="var">line1</var> <var class="var">line2</var> …</code><a class="copiable-link" href="#index-dbstop-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-3"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments"><var class="var">line1</var> …</code><a class="copiable-link" href="#index-dbstop-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-4"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments">in <var class="var">fcn</var></code><a class="copiable-link" href="#index-dbstop-4"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-5"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments">in <var class="var">fcn</var> at <var class="var">line</var></code><a class="copiable-link" href="#index-dbstop-5"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-6"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments">in <var class="var">fcn</var> at <var class="var">line</var> if "<var class="var">condition</var>"</code><a class="copiable-link" href="#index-dbstop-6"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-7"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments">in <var class="var">class</var> at <var class="var">method</var></code><a class="copiable-link" href="#index-dbstop-7"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-8"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments">if <var class="var">event</var></code><a class="copiable-link" href="#index-dbstop-8"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-9"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments">if <var class="var">event</var> <var class="var">ID</var></code><a class="copiable-link" href="#index-dbstop-9"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-10"><span><strong class="def-name">dbstop</strong> <code class="def-code-arguments">(<var class="var">bp_struct</var>)</code><a class="copiable-link" href="#index-dbstop-10"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstop-11"><span><code class="def-type"><var class="var">rline</var> =</code> <strong class="def-name">dbstop</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-dbstop-11"> ¶</a></span></dt>
<dd>
<p>Set breakpoints for the built-in debugger.
</p>
<p><var class="var">fcn</var> is the name of a function on the current <code class="code">path</code>. When
already in debug mode the <var class="var">fcn</var> argument can be omitted and the current
function will be used. Breakpoints at subfunctions are set with the scope
operator ‘<samp class="samp">></samp>’. For example, If <samp class="file">file.m</samp> has a subfunction
<code class="code">fcn2</code>, then a breakpoint in <code class="code">fcn2</code> can be specified by
<code class="code">file>fcn2</code>.
</p>
<p><var class="var">line</var> is the line number at which to break. If <var class="var">line</var> is not
specified, it defaults to the first executable line in the file
<samp class="file">fcn.m</samp>. Multiple lines can be specified in a single command; when
function syntax is used, the lines may also be passed as a single vector
argument (<code class="code">[<var class="var">line1</var>, <var class="var">line2</var>, …]</code>).
</p>
<p><var class="var">condition</var> is any Octave expression that can be evaluated in the code
context that exists at the breakpoint. When the breakpoint is encountered,
<var class="var">condition</var> will be evaluated, and execution will stop if
<var class="var">condition</var> is true. If <var class="var">condition</var> cannot be evaluated, for
example because it refers to an undefined variable, an error will be thrown.
Expressions with side effects (such as <code class="code">y++ > 1</code>) will alter variables,
and should generally be avoided. Conditions containing quotes (‘<samp class="samp">"</samp>’,
‘<samp class="samp">'</samp>’) or comment characters (‘<samp class="samp">#</samp>’, ‘<samp class="samp">%</samp>’) must be enclosed in
quotes. (This does not apply to conditions entered from the editor’s context
menu.) For example:
</p>
<div class="example">
<pre class="example-preformatted">dbstop in axis at 246 if 'any (opt == "x")'
</pre></div>
<p>The form specifying <var class="var">event</var> does not cause a specific breakpoint at a given
function and line number. Instead it causes debug mode to be entered when
certain unexpected events are encountered. Possible values are
</p>
<dl class="table">
<dt><code class="code">error</code></dt>
<dd><p>Stop when an error is reported. This is equivalent to specifying both
<code class="code">debug_on_error (true)</code> and <code class="code">debug_on_interrupt (true)</code>.
</p>
</dd>
<dt><code class="code">caught error</code></dt>
<dd><p>Stop when an error is caught by a try-catch block (not yet implemented).
</p>
</dd>
<dt><code class="code">interrupt</code></dt>
<dd><p>Stop when an interrupt (<kbd class="kbd">Ctrl-C</kbd>) occurs.
</p>
</dd>
<dt><code class="code">naninf</code></dt>
<dd><p>Stop when code returns a non-finite value (not yet implemented).
</p>
</dd>
<dt><code class="code">warning</code></dt>
<dd><p>Stop when a warning is reported. This is equivalent to specifying
<code class="code">debug_on_warning (true)</code>.
</p></dd>
</dl>
<p>The events <code class="code">error</code>, <code class="code">caught error</code>, and <code class="code">warning</code> can all be
followed by a string specifying an error ID or warning ID. If that is done,
only errors with the specified ID will cause execution to stop. To stop on one
of a set of IDs, multiple <code class="code">dbstop</code> commands must be issued.
</p>
<p>Breakpoints and events can be removed using the <code class="code">dbclear</code> command with
the same syntax.
</p>
<p>It is possible to save all breakpoints and restore them at once by issuing
the commands <code class="code">bp_state = dbstatus; …; dbstop (bp_state)</code>.
</p>
<p>The optional output <var class="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>When a file is re-parsed, such as when it is modified outside the GUI, all
breakpoints within the file are cleared.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdbclear">dbclear</a>, <a class="ref" href="#XREFdbstatus">dbstatus</a>, <a class="ref" href="Debug-Mode.html#XREFdbstep">dbstep</a>, <a class="ref" href="Entering-Debug-Mode.html#XREFdebug_005fon_005ferror">debug_on_error</a>, <a class="ref" href="Entering-Debug-Mode.html#XREFdebug_005fon_005fwarning">debug_on_warning</a>, <a class="ref" 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 class="code">dbstop ("@class/method")</code>). However, breakpoints cannot be set in
built-in functions (e.g., <code class="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">
<div class="group"><pre class="example-preformatted">dbstop ("asind", 1)
⇒ 29
</pre></div></div>
<p>Note that the return value of <code class="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 class="code">dbstatus</code>.
</p>
<a class="anchor" id="XREFdbstatus"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-dbstatus"><span><strong class="def-name">dbstatus</strong><a class="copiable-link" href="#index-dbstatus"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstatus-1"><span><strong class="def-name">dbstatus</strong> <code class="def-code-arguments"><var class="var">fcn</var></code><a class="copiable-link" href="#index-dbstatus-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstatus-2"><span><code class="def-type"><var class="var">bp_list</var> =</code> <strong class="def-name">dbstatus</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-dbstatus-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbstatus-3"><span><code class="def-type"><var class="var">bp_list</var> =</code> <strong class="def-name">dbstatus</strong> <code class="def-code-arguments">(<var class="var">fcn</var>)</code><a class="copiable-link" href="#index-dbstatus-3"> ¶</a></span></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 class="var">fcn</var> is specified then only report breakpoints
for the named function and its subfunctions.
</p>
<p>The optional return argument <var class="var">bp_list</var> is a struct array with the
following fields:
</p>
<dl class="table">
<dt>name</dt>
<dd><p>The name of the function with a breakpoint. A subfunction, say <code class="code">fcn2</code>
within an m-file, say <samp class="file">file.m</samp>, is specified as <code class="code">file>fcn2</code>.
</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>The line number with the breakpoint.
</p>
</dd>
<dt>cond</dt>
<dd><p>The condition that must be satisfied for the breakpoint to be active, or
the empty string for unconditional breakpoints.
</p></dd>
</dl>
<p>If <code class="code">dbstop if error</code> is true but no explicit IDs are specified, the
return value will have an empty field called <code class="code">"errs"</code>. If IDs are
specified, the <code class="code">errs</code> field will have one row per ID. If
<code class="code">dbstop if error</code> is false, there is no <code class="code">"errs"</code> field.
The <code class="code">"warn"</code> field is set similarly by <code class="code">dbstop if warning</code>.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdbstop">dbstop</a>, <a class="ref" href="#XREFdbclear">dbclear</a>, <a class="ref" href="Debug-Mode.html#XREFdbwhere">dbwhere</a>, <a class="ref" href="Debug-Mode.html#XREFdblist">dblist</a>, <a class="ref" href="Call-Stack.html#XREFdbstack">dbstack</a>.
</p></dd></dl>
<p>Reusing the previous example, <code class="code">dbstatus ("asind")</code> will return
29. The breakpoints listed can then be cleared with the <code class="code">dbclear</code>
function.
</p>
<a class="anchor" id="XREFdbclear"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-dbclear"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments"><var class="var">fcn</var></code><a class="copiable-link" href="#index-dbclear"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-1"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments"><var class="var">fcn</var> <var class="var">line</var></code><a class="copiable-link" href="#index-dbclear-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-2"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments"><var class="var">fcn</var> <var class="var">line1</var> <var class="var">line2</var> …</code><a class="copiable-link" href="#index-dbclear-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-3"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments"><var class="var">line</var> …</code><a class="copiable-link" href="#index-dbclear-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-4"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">all</code><a class="copiable-link" href="#index-dbclear-4"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-5"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">in <var class="var">fcn</var></code><a class="copiable-link" href="#index-dbclear-5"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-6"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">in <var class="var">fcn</var> at <var class="var">line</var></code><a class="copiable-link" href="#index-dbclear-6"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-7"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">if <var class="var">event</var></code><a class="copiable-link" href="#index-dbclear-7"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-8"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">("<var class="var">fcn</var>")</code><a class="copiable-link" href="#index-dbclear-8"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-9"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">("<var class="var">fcn</var>", <var class="var">line</var>)</code><a class="copiable-link" href="#index-dbclear-9"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-10"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">("<var class="var">fcn</var>", <var class="var">line1</var>, <var class="var">line2</var>, …)</code><a class="copiable-link" href="#index-dbclear-10"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-11"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">("<var class="var">fcn</var>", <var class="var">line1</var>, …)</code><a class="copiable-link" href="#index-dbclear-11"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-12"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">(<var class="var">line</var>, …)</code><a class="copiable-link" href="#index-dbclear-12"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dbclear-13"><span><strong class="def-name">dbclear</strong> <code class="def-code-arguments">("all")</code><a class="copiable-link" href="#index-dbclear-13"> ¶</a></span></dt>
<dd><p>Delete a breakpoint at line number <var class="var">line</var> in the function <var class="var">fcn</var>.
</p>
<p>Arguments are
</p>
<dl class="table">
<dt><var class="var">fcn</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 class="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>
<dt><var class="var">event</var></dt>
<dd><p>An event such as <code class="code">error</code>, <code class="code">interrupt</code>, or <code class="code">warning</code>
(see <a class="pxref" href="#XREFdbstop"><code class="code">dbstop</code></a> for details).
</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 class="code">"all"</code> will clear all breakpoints from all
files.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdbstop">dbstop</a>, <a class="ref" href="#XREFdbstatus">dbstatus</a>, <a class="ref" 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">
<div class="group"><pre class="example-preformatted">function y = func1 (x)
y = func2 (x);
endfunction
function y = func2 (x)
y = x + 1;
endfunction
</pre></div></div>
<p>then a breakpoint can be set at the start of the subfunction directly with
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">dbstop func1>func2
⇒ 5
</pre></div></div>
<p>Note that ‘<samp class="samp">></samp>’ is the character that distinguishes subfunctions from the
m-file containing them.
</p>
<p>Another simple way of setting a breakpoint in an Octave script is the
use of the <code class="code">keyboard</code> function.
</p>
<a class="anchor" id="XREFkeyboard"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-keyboard"><span><strong class="def-name">keyboard</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-keyboard"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-keyboard-1"><span><strong class="def-name">keyboard</strong> <code class="def-code-arguments">("<var class="var">prompt</var>")</code><a class="copiable-link" href="#index-keyboard-1"> ¶</a></span></dt>
<dd><p>Stop m-file execution and enter debug mode.
</p>
<p>When the <code class="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 class="samp">return</samp>’ or ‘<samp class="samp">dbcont</samp>’.
The <code class="code">keyboard</code> function does not return an exit status.
</p>
<p>If <code class="code">keyboard</code> is invoked without arguments, a default prompt of
‘<samp class="samp">debug> </samp>’ is used.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdbstop">dbstop</a>, <a class="ref" href="Leaving-Debug-Mode.html#XREFdbcont">dbcont</a>, <a class="ref" href="Leaving-Debug-Mode.html#XREFdbquit">dbquit</a>.
</p></dd></dl>
<p>The <code class="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>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Debug-Mode.html">Debug Mode</a>, Previous: <a href="Leaving-Debug-Mode.html">Leaving Debug Mode</a>, Up: <a href="Debugging.html">Debugging</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
