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>
|
