← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to system/doc/reference_manual/errors.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/reference_manual/errors.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2003</year><year>2011</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>Errors and Error Handling</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>errors.xml</file>
 
30
  </header>
 
31
 
 
32
  <section>
 
33
    <title>Terminology</title>
 
34
    <p>Errors can roughly be divided into four different types:</p>
 
35
    <list type="bulleted">
 
36
      <item>Compile-time errors</item>
 
37
      <item>Logical errors</item>
 
38
      <item>Run-time errors</item>
 
39
      <item>Generated errors</item>
 
40
    </list>
 
41
    <p>A compile-time error, for example a syntax error, should not
 
42
      cause much trouble as it is caught by the compiler.</p>
 
43
    <p>A logical error is when a program does not behave as intended,
 
44
      but does not crash. An example could be that nothing happens when
 
45
      a button in a graphical user interface is clicked.</p>
 
46
    <p>A run-time error is when a crash occurs. An example could be
 
47
      when an operator is applied to arguments of the wrong type.
 
48
      The Erlang programming language has built-in features for
 
49
      handling of run-time errors.</p>
 
50
    <p>A run-time error can also be emulated by calling
 
51
      <c>erlang:error(Reason)</c> or <c>erlang:error(Reason, Args)</c>
 
52
      (those appeared in Erlang 5.4/OTP-R10).</p>
 
53
    <p>A run-time error is another name for an exception
 
54
      of class <c>error</c>.
 
55
      </p>
 
56
    <p>A generated error is when the code itself calls
 
57
      <c>exit/1</c> or <c>throw/1</c>. Note that emulated run-time
 
58
      errors are not denoted as generated errors here.
 
59
      </p>
 
60
    <p>Generated errors are exceptions of classes <c>exit</c> and
 
61
      <c>throw</c>.
 
62
      </p>
 
63
    <p>When a run-time error or generated error occurs in Erlang, 
 
64
      execution for the process which evaluated 
 
65
      the erroneous expression is stopped.
 
66
      This is referred to as a <em>failure</em>, that execution or
 
67
      evaluation <em>fails</em>, or that the process <em>fails</em>,
 
68
      <em>terminates</em> or <em>exits</em>. Note that a process may
 
69
      terminate/exit for other reasons than a failure.</p>
 
70
    <p>A process that terminates will emit an <em>exit signal</em> with
 
71
      an <em>exit reason</em> that says something about which error
 
72
      has occurred. Normally, some information about the error will
 
73
      be printed to the terminal.</p>
 
74
  </section>
 
75
 
 
76
  <section>
 
77
    <title>Exceptions</title>
 
78
    <p>Exceptions are run-time errors or generated errors and 
 
79
      are of three different classes, with different origins. The
 
80
      <seealso marker="expressions#try">try</seealso> expression 
 
81
      (appeared in Erlang 5.4/OTP-R10B)
 
82
      can distinguish between the different classes, whereas the
 
83
      <seealso marker="expressions#catch">catch</seealso>
 
84
      expression can not. They are described in the Expressions chapter.</p>
 
85
    <table>
 
86
      <row>
 
87
        <cell align="left" valign="middle"><em>Class</em></cell>
 
88
        <cell align="left" valign="middle"><em>Origin</em></cell>
 
89
      </row>
 
90
      <row>
 
91
        <cell align="left" valign="middle"><c>error</c></cell>
 
92
        <cell align="left" valign="middle">Run-time error for example <c>1+a</c>, or the process called <c>erlang:error/1,2</c> (appeared in Erlang 5.4/OTP-R10B)</cell>
 
93
      </row>
 
94
      <row>
 
95
        <cell align="left" valign="middle"><c>exit</c></cell>
 
96
        <cell align="left" valign="middle">The process called <c>exit/1</c></cell>
 
97
      </row>
 
98
      <row>
 
99
        <cell align="left" valign="middle"><c>throw</c></cell>
 
100
        <cell align="left" valign="middle">The process called <c>throw/1</c></cell>
 
101
      </row>
 
102
      <tcaption>Exception Classes.</tcaption>
 
103
    </table>
 
104
    <p>An exception consists of its class, an exit reason
 
105
      (the <seealso marker="#exit_reasons">Exit Reason</seealso>),
 
106
      and a stack trace (that aids in finding the code location of
 
107
      the exception).</p>
 
108
    <p>The stack trace can be retrieved using
 
109
      <c>erlang:get_stacktrace/0</c> (new in Erlang 5.4/OTP-R10B)
 
110
      from within a <c>try</c> expression, and is returned for 
 
111
      exceptions of class <c>error</c> from a <c>catch</c> expression.</p>
 
112
    <p>An exception of class <c>error</c> is also known as a run-time 
 
113
      error.</p>
 
114
  </section>
 
115
 
 
116
  <section>
 
117
    <title>Handling of Run-Time Errors in Erlang</title>
 
118
 
 
119
    <section>
 
120
      <title>Error Handling Within Processes</title>
 
121
      <p>It is possible to prevent run-time errors and other
 
122
        exceptions from causing
 
123
        the process to terminate by using <c>catch</c> or
 
124
        <c>try</c>, see the Expressions chapter about 
 
125
        <seealso marker="expressions#catch">Catch</seealso>
 
126
        and <seealso marker="expressions#try">Try</seealso>.</p>
 
127
    </section>
 
128
 
 
129
    <section>
 
130
      <title>Error Handling Between Processes</title>
 
131
      <p>Processes can monitor other processes and detect process
 
132
        terminations, see
 
133
        the <seealso marker="processes#errors">Processes</seealso>
 
134
        chapter.</p>
 
135
    </section>
 
136
  </section>
 
137
 
 
138
  <section>
 
139
    <marker id="exit_reasons"></marker>
 
140
    <title>Exit Reasons</title>
 
141
    <p>When a run-time error occurs, 
 
142
      that is an exception of class <c>error</c>, 
 
143
      the exit reason is a tuple <c>{Reason,Stack}</c>. 
 
144
      <c>Reason</c> is a term indicating the type of error:</p>
 
145
    <table>
 
146
      <row>
 
147
        <cell align="left" valign="middle"><em>Reason</em></cell>
 
148
        <cell align="left" valign="middle"><em>Type of error</em></cell>
 
149
      </row>
 
150
      <row>
 
151
        <cell align="left" valign="middle"><c>badarg</c></cell>
 
152
        <cell align="left" valign="middle">Bad argument. The argument is of wrong data type, or is otherwise badly formed.</cell>
 
153
      </row>
 
154
      <row>
 
155
        <cell align="left" valign="middle"><c>badarith</c></cell>
 
156
        <cell align="left" valign="middle">Bad argument in an arithmetic expression.</cell>
 
157
      </row>
 
158
      <row>
 
159
        <cell align="left" valign="middle"><c>{badmatch,V}</c></cell>
 
160
        <cell align="left" valign="middle">Evaluation of a match expression failed. The value <c>V</c> did not match.</cell>
 
161
      </row>
 
162
      <row>
 
163
        <cell align="left" valign="middle"><c>function_clause</c></cell>
 
164
        <cell align="left" valign="middle">No matching function clause is found when evaluating a function call.</cell>
 
165
      </row>
 
166
      <row>
 
167
        <cell align="left" valign="middle"><c>{case_clause,V}</c></cell>
 
168
        <cell align="left" valign="middle">No matching branch is found when evaluating a <c>case</c> expression. The value <c>V</c> did not match.</cell>
 
169
      </row>
 
170
      <row>
 
171
        <cell align="left" valign="middle"><c>if_clause</c></cell>
 
172
        <cell align="left" valign="middle">No true branch is found when evaluating an <c>if</c> expression.</cell>
 
173
      </row>
 
174
      <row>
 
175
        <cell align="left" valign="middle"><c>{try_clause,V}</c></cell>
 
176
        <cell align="left" valign="middle">No matching branch is found when evaluating the of-section of a <c>try</c> expression. The value <c>V</c> did not match.</cell>
 
177
      </row>
 
178
      <row>
 
179
        <cell align="left" valign="middle"><c>undef</c></cell>
 
180
        <cell align="left" valign="middle">The function cannot be found when evaluating a function call.</cell>
 
181
      </row>
 
182
      <row>
 
183
        <cell align="left" valign="middle"><c>{badfun,F}</c></cell>
 
184
        <cell align="left" valign="middle">There is something wrong with a fun <c>F</c>.</cell>
 
185
      </row>
 
186
      <row>
 
187
        <cell align="left" valign="middle"><c>{badarity,F}</c></cell>
 
188
        <cell align="left" valign="middle">A fun is applied to the wrong number of arguments. <c>F</c> describes the fun and the arguments.</cell>
 
189
      </row>
 
190
      <row>
 
191
        <cell align="left" valign="middle"><c>timeout_value</c></cell>
 
192
        <cell align="left" valign="middle">The timeout value in a <c>receive..after</c> expression is evaluated to something else than an integer or <c>infinity</c>.</cell>
 
193
      </row>
 
194
      <row>
 
195
        <cell align="left" valign="middle"><c>noproc</c></cell>
 
196
        <cell align="left" valign="middle">Trying to link to a non-existing process.</cell>
 
197
      </row>
 
198
      <row>
 
199
        <cell align="left" valign="middle"><c>{nocatch,V}</c></cell>
 
200
        <cell align="left" valign="middle">Trying to evaluate a <c>throw </c>outside a <c>catch</c>. <c>V</c> is the thrown term.</cell>
 
201
      </row>
 
202
      <row>
 
203
        <cell align="left" valign="middle"><c>system_limit</c></cell>
 
204
        <cell align="left" valign="middle">A system limit has been reached. See Efficiency Guide for information about system limits.</cell>
 
205
      </row>
 
206
      <tcaption>Exit Reasons.</tcaption>
 
207
    </table>
 
208
    <p><c>Stack</c> is the stack of function calls being evaluated
 
209
      when the error occurred, given as a list of tuples
 
210
      <c>{Module,Name,Arity}</c> with the most recent function call
 
211
      first. The most recent function call tuple may in some
 
212
      cases be <c>{Module,Name,[Arg]}</c>.</p>
 
213
  </section>
 
214
</chapter>
 
215