|
2679
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
|
5 @node Error Handling, Input and Output, Functions and Scripts, Top |
|
|
6 @chapter Error Handling |
|
|
7 |
|
|
8 @deftypefn {Built-in Function} {} error (@var{template}, @dots{}) |
|
|
9 The @code{error} function formats the optional arguments under the |
|
|
10 control of the template string @var{template} using the same rules as |
|
|
11 the @code{printf} family of functions (@pxref{Formatted Output}). |
|
|
12 The resulting message is prefixed by the string @samp{error: } and |
|
|
13 printed on the @code{stderr} stream. |
|
|
14 |
|
|
15 Calling @code{error} also sets Octave's internal error state such that |
|
|
16 control will return to the top level without evaluating any more |
|
|
17 commands. This is useful for aborting from functions or scripts. |
|
|
18 |
|
|
19 If the error message does not end with a new line character, Octave will |
|
|
20 print a traceback of all the function calls leading to the error. For |
|
|
21 example, given the following function definitions: |
|
|
22 |
|
|
23 @example |
|
|
24 @group |
|
|
25 function f () g () end |
|
|
26 function g () h () end |
|
|
27 function h () nargin == 1 || error ("nargin != 1"); end |
|
|
28 @end group |
|
|
29 @end example |
|
|
30 |
|
|
31 @noindent |
|
|
32 calling the function @code{f} will result in a list of messages that |
|
|
33 can help you to quickly locate the exact location of the error: |
|
|
34 |
|
|
35 @example |
|
|
36 @group |
|
|
37 f () |
|
|
38 error: nargin != 1 |
|
|
39 error: evaluating index expression near line 1, column 30 |
|
|
40 error: evaluating binary operator `||' near line 1, column 27 |
|
|
41 error: called from `h' |
|
|
42 error: called from `g' |
|
|
43 error: called from `f' |
|
|
44 @end group |
|
|
45 @end example |
|
|
46 |
|
|
47 If the error message ends in a new line character, Octave will print the |
|
|
48 message but will not display any traceback messages as it returns |
|
|
49 control to the top level. For example, modifying the error message |
|
|
50 in the previous example to end in a new line causes Octave to only print |
|
|
51 a single message: |
|
|
52 |
|
|
53 @example |
|
|
54 @group |
|
|
55 function h () nargin == 1 || error ("nargin != 1\n"); end |
|
|
56 f () |
|
|
57 error: nargin != 1 |
|
|
58 @end group |
|
|
59 @end example |
|
|
60 @end deftypefn |
|
|
61 |
|
|
62 @defvr {Built-in Variable} error_text |
|
|
63 This variable contains the the text of error messages that would have |
|
|
64 been printed in the body of the most recent @code{unwind_protect} or |
|
|
65 @code{try} statement or the @var{try} part of the most recent call to |
|
|
66 the @code{eval} function. Outside of the @code{unwind_protect} and |
|
|
67 @code{try} statements or the @code{eval} function, or if no error has |
|
|
68 ocurred within them, the value of @code{error_text} is guaranteed to be |
|
|
69 the empty string. |
|
|
70 |
|
|
71 Note that the message does not include the first @samp{error: } prefix, |
|
|
72 so that it may easily be passed to the @code{error} function without |
|
|
73 additional processing@footnote{Yes, it's a kluge, but it seems to be a |
|
|
74 reasonably useful one.}. |
|
|
75 |
|
|
76 @xref{The try Statement} and @ref{The unwind_protect Statement}. |
|
|
77 @end defvr |
|
|
78 |
|
|
79 @defvr {Built-in Variable} beep_on_error |
|
|
80 If the value of @code{beep_on_error} is nonzero, Octave will try |
|
|
81 to ring your terminal's bell before printing an error message. The |
|
|
82 default value is 0. |
|
|
83 @end defvr |
|
|
84 |
|
|
85 @deftypefn {Built-in Function} {} warning (@var{msg}) |
|
|
86 Print the message @var{msg} prefixed by the string @samp{warning: }. |
|
|
87 @end deftypefn |
|
|
88 |
|
|
89 @deftypefn {Built-in Function} {} usage (@var{msg}) |
|
|
90 Print the message @var{msg}, prefixed by the string @samp{usage: }, and |
|
|
91 set Octave's internal error state such that control will return to the |
|
|
92 top level without evaluating any more commands. This is useful for |
|
|
93 aborting from functions. |
|
|
94 |
|
|
95 After @code{usage} is evaluated, Octave will print a traceback of all |
|
|
96 the function calls leading to the usage message. |
|
|
97 @end deftypefn |
|
|
98 |
|
|
99 The following pair of functions are of limited usefulness, and may be |
|
|
100 removed from future versions of Octave. |
|
|
101 |
|
|
102 @deftypefn {Function File} {} perror (@var{name}, @var{num}) |
|
|
103 Print the error message for function @var{name} corresponding to the |
|
|
104 error number @var{num}. This function is intended to be used to print |
|
|
105 useful error messages for those functions that return numeric error |
|
|
106 codes. |
|
|
107 @end deftypefn |
|
|
108 |
|
|
109 @deftypefn {Function File} {} strerror (@var{name}, @var{num}) |
|
|
110 Return the text of an error message for function @var{name} |
|
|
111 corresponding to the error number @var{num}. This function is intended |
|
|
112 to be used to print useful error messages for those functions that |
|
|
113 return numeric error codes. |
|
|
114 @end deftypefn |
