<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../otp_doc.css" type="text/css">
<title>Erlang -- Errors and Error Handling</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="../pdf/otp-system-documentation-5.9.3.1.pdf">PDF</a><br><a href="../index.html">Top</a></small><p><strong>Erlang Reference Manual</strong><br><strong>User's Guide</strong><br><small>Version 5.9.3.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="introduction.html">
Top of chapter
</a></li>
<li title="Purpose"><a href="introduction.html#id73748">Purpose</a></li>
<li title="Prerequisites"><a href="introduction.html#id66106">Prerequisites</a></li>
<li title="Document Conventions"><a href="introduction.html#id67296">Document Conventions</a></li>
<li title="Complete List of BIFs"><a href="introduction.html#id68121">Complete List of BIFs</a></li>
<li title="Reserved Words"><a href="introduction.html#id60679">Reserved Words</a></li>
<li title="Character Set"><a href="introduction.html#id61758">Character Set</a></li>
</ul>
</li>
<li id="no" title="Data Types" expanded="false">Data Types<ul>
<li><a href="data_types.html">
Top of chapter
</a></li>
<li title="Terms"><a href="data_types.html#id63330">Terms</a></li>
<li title="Number"><a href="data_types.html#id68697">Number</a></li>
<li title="Atom"><a href="data_types.html#id62285">Atom</a></li>
<li title="Bit Strings and Binaries"><a href="data_types.html#id68011">Bit Strings and Binaries</a></li>
<li title="Reference"><a href="data_types.html#id58120">Reference</a></li>
<li title="Fun"><a href="data_types.html#id67499">Fun</a></li>
<li title="Port Identifier"><a href="data_types.html#id69290">Port Identifier</a></li>
<li title="Pid"><a href="data_types.html#id60853">Pid</a></li>
<li title="Tuple"><a href="data_types.html#id73719">Tuple</a></li>
<li title="List"><a href="data_types.html#id73198">List</a></li>
<li title="String"><a href="data_types.html#id68626">String</a></li>
<li title="Record"><a href="data_types.html#id65682">Record</a></li>
<li title="Boolean"><a href="data_types.html#id67471">Boolean</a></li>
<li title="Escape Sequences"><a href="data_types.html#id73885">Escape Sequences</a></li>
<li title="Type Conversions"><a href="data_types.html#id69219">Type Conversions</a></li>
</ul>
</li>
<li id="no" title="Pattern Matching" expanded="false">Pattern Matching<ul>
<li><a href="patterns.html">
Top of chapter
</a></li>
<li title="Pattern Matching"><a href="patterns.html#id68202">Pattern Matching</a></li>
</ul>
</li>
<li id="no" title="Modules" expanded="false">Modules<ul>
<li><a href="modules.html">
Top of chapter
</a></li>
<li title="Module Syntax"><a href="modules.html#id68326">Module Syntax</a></li>
<li title="Module Attributes"><a href="modules.html#id68358">Module Attributes</a></li>
<li title="Comments"><a href="modules.html#id74337">Comments</a></li>
<li title="The module_info/0 and module_info/1 functions"><a href="modules.html#id74350">The module_info/0 and module_info/1 functions</a></li>
</ul>
</li>
<li id="no" title="Functions" expanded="false">Functions<ul>
<li><a href="functions.html">
Top of chapter
</a></li>
<li title="Function Declaration Syntax"><a href="functions.html#id74609">Function Declaration Syntax</a></li>
<li title="Function Evaluation"><a href="functions.html#id74724">Function Evaluation</a></li>
<li title="Tail recursion"><a href="functions.html#id74875">Tail recursion</a></li>
<li title="Built-In Functions, BIFs"><a href="functions.html#id74908">Built-In Functions, BIFs</a></li>
</ul>
</li>
<li id="no" title="Types and Function Specifications" expanded="false">Types and Function Specifications<ul>
<li><a href="typespec.html">
Top of chapter
</a></li>
<li title="Introduction of Types"><a href="typespec.html#id75024">Introduction of Types</a></li>
<li title="Types and their Syntax"><a href="typespec.html#id75072">Types and their Syntax</a></li>
<li title="Type declarations of user-defined types"><a href="typespec.html#id75688">Type declarations of user-defined types</a></li>
<li title="Type information in record declarations"><a href="typespec.html#id75770">Type information in record declarations</a></li>
<li title="Specifications for functions"><a href="typespec.html#id75847">Specifications for functions</a></li>
</ul>
</li>
<li id="no" title="Expressions" expanded="false">Expressions<ul>
<li><a href="expressions.html">
Top of chapter
</a></li>
<li title="Expression Evaluation"><a href="expressions.html#id76067">Expression Evaluation</a></li>
<li title="Terms"><a href="expressions.html#id76110">Terms</a></li>
<li title="Variables"><a href="expressions.html#id76122">Variables</a></li>
<li title="Patterns"><a href="expressions.html#id76253">Patterns</a></li>
<li title="Match"><a href="expressions.html#id76372">Match</a></li>
<li title="Function Calls"><a href="expressions.html#id76431">Function Calls</a></li>
<li title="If"><a href="expressions.html#id76631">If</a></li>
<li title="Case"><a href="expressions.html#id76696">Case</a></li>
<li title="Send"><a href="expressions.html#id76761">Send</a></li>
<li title="Receive"><a href="expressions.html#id76844">Receive</a></li>
<li title="Term Comparisons"><a href="expressions.html#id77009">Term Comparisons</a></li>
<li title="Arithmetic Expressions"><a href="expressions.html#id77270">Arithmetic Expressions</a></li>
<li title="Boolean Expressions"><a href="expressions.html#id77776">Boolean Expressions</a></li>
<li title="Short-Circuit Expressions"><a href="expressions.html#id77931">Short-Circuit Expressions</a></li>
<li title="List Operations"><a href="expressions.html#id78047">List Operations</a></li>
<li title="Bit Syntax Expressions"><a href="expressions.html#id78116">Bit Syntax Expressions</a></li>
<li title="Fun Expressions"><a href="expressions.html#id78658">Fun Expressions</a></li>
<li title="Catch and Throw"><a href="expressions.html#id78840">Catch and Throw</a></li>
<li title="Try"><a href="expressions.html#id78986">Try</a></li>
<li title="Parenthesized Expressions"><a href="expressions.html#id79344">Parenthesized Expressions</a></li>
<li title="Block Expressions"><a href="expressions.html#id79376">Block Expressions</a></li>
<li title="List Comprehensions"><a href="expressions.html#id79401">List Comprehensions</a></li>
<li title="Bit String Comprehensions"><a href="expressions.html#id79541">Bit String Comprehensions</a></li>
<li title="Guard Sequences"><a href="expressions.html#id79673">Guard Sequences</a></li>
<li title="Operator Precedence"><a href="expressions.html#id80211">Operator Precedence</a></li>
</ul>
</li>
<li id="no" title="The Preprocessor" expanded="false">The Preprocessor<ul>
<li><a href="macros.html">
Top of chapter
</a></li>
<li title="File Inclusion"><a href="macros.html#id80530">File Inclusion</a></li>
<li title="Defining and Using Macros"><a href="macros.html#id80659">Defining and Using Macros</a></li>
<li title="Predefined Macros"><a href="macros.html#id80782">Predefined Macros</a></li>
<li title="Macros Overloading"><a href="macros.html#id80850">Macros Overloading</a></li>
<li title="Flow Control in Macros"><a href="macros.html#id80919">Flow Control in Macros</a></li>
<li title="Stringifying Macro Arguments"><a href="macros.html#id81056">Stringifying Macro Arguments</a></li>
</ul>
</li>
<li id="no" title="Records" expanded="false">Records<ul>
<li><a href="records.html">
Top of chapter
</a></li>
<li title="Defining Records"><a href="records.html#id81178">Defining Records</a></li>
<li title="Creating Records"><a href="records.html#id81209">Creating Records</a></li>
<li title="Accessing Record Fields"><a href="records.html#id81264">Accessing Record Fields</a></li>
<li title="Updating Records"><a href="records.html#id81303">Updating Records</a></li>
<li title="Records in Guards"><a href="records.html#id81336">Records in Guards</a></li>
<li title="Records in Patterns"><a href="records.html#id81368">Records in Patterns</a></li>
<li title="Nested records"><a href="records.html#id81395">Nested records</a></li>
<li title="Internal Representation of Records"><a href="records.html#id81430">Internal Representation of Records</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Errors and Error Handling" expanded="true">Errors and Error Handling<ul>
<li><a href="errors.html">
Top of chapter
</a></li>
<li title="Terminology"><a href="errors.html#id81550">Terminology</a></li>
<li title="Exceptions"><a href="errors.html#id81678">Exceptions</a></li>
<li title="Handling of Run-Time Errors in Erlang"><a href="errors.html#id81851">Handling of Run-Time Errors in Erlang</a></li>
<li title="Exit Reasons"><a href="errors.html#id81913">Exit Reasons</a></li>
</ul>
</li>
<li id="no" title="Processes" expanded="false">Processes<ul>
<li><a href="processes.html">
Top of chapter
</a></li>
<li title="Processes"><a href="processes.html#id82387">Processes</a></li>
<li title="Process Creation"><a href="processes.html#id82400">Process Creation</a></li>
<li title="Registered Processes"><a href="processes.html#id82449">Registered Processes</a></li>
<li title="Process Termination"><a href="processes.html#id82560">Process Termination</a></li>
<li title="Message Sending"><a href="processes.html#id82650">Message Sending</a></li>
<li title="Links"><a href="processes.html#id82679">Links</a></li>
<li title="Error Handling"><a href="processes.html#id82744">Error Handling</a></li>
<li title="Monitors"><a href="processes.html#id82854">Monitors</a></li>
<li title="Process Dictionary"><a href="processes.html#id82946">Process Dictionary</a></li>
</ul>
</li>
<li id="no" title="Distributed Erlang" expanded="false">Distributed Erlang<ul>
<li><a href="distributed.html">
Top of chapter
</a></li>
<li title="Distributed Erlang System"><a href="distributed.html#id83013">Distributed Erlang System</a></li>
<li title="Nodes"><a href="distributed.html#id83044">Nodes</a></li>
<li title="Node Connections"><a href="distributed.html#id83114">Node Connections</a></li>
<li title="epmd"><a href="distributed.html#id83164">epmd</a></li>
<li title="Hidden Nodes"><a href="distributed.html#id83184">Hidden Nodes</a></li>
<li title="C Nodes"><a href="distributed.html#id83230">C Nodes</a></li>
<li title="Security"><a href="distributed.html#id83254">Security</a></li>
<li title="Distribution BIFs"><a href="distributed.html#id83364">Distribution BIFs</a></li>
<li title="Distribution Command Line Flags"><a href="distributed.html#id83662">Distribution Command Line Flags</a></li>
<li title="Distribution Modules"><a href="distributed.html#id83799">Distribution Modules</a></li>
</ul>
</li>
<li id="no" title="Compilation and Code Loading" expanded="false">Compilation and Code Loading<ul>
<li><a href="code_loading.html">
Top of chapter
</a></li>
<li title="Compilation"><a href="code_loading.html#id84002">Compilation</a></li>
<li title="Code Loading"><a href="code_loading.html#id84112">Code Loading</a></li>
<li title="Code Replacement"><a href="code_loading.html#id84159">Code Replacement</a></li>
<li title="Running a function when a module is loaded"><a href="code_loading.html#id84234">Running a function when a module is loaded</a></li>
</ul>
</li>
<li id="no" title="Ports and Port Drivers" expanded="false">Ports and Port Drivers<ul>
<li><a href="ports.html">
Top of chapter
</a></li>
<li title="Ports"><a href="ports.html#id84374">Ports</a></li>
<li title="Port Drivers"><a href="ports.html#id84409">Port Drivers</a></li>
<li title="Port BIFs"><a href="ports.html#id84449">Port BIFs</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>10 Errors and Error Handling</h1>
<h3><a name="id81550">10.1
Terminology</a></h3>
<p>Errors can roughly be divided into four different types:</p>
<ul>
<li>Compile-time errors</li>
<li>Logical errors</li>
<li>Run-time errors</li>
<li>Generated errors</li>
</ul>
<p>A compile-time error, for example a syntax error, should not
cause much trouble as it is caught by the compiler.</p>
<p>A logical error is when a program does not behave as intended,
but does not crash. An example could be that nothing happens when
a button in a graphical user interface is clicked.</p>
<p>A run-time error is when a crash occurs. An example could be
when an operator is applied to arguments of the wrong type.
The Erlang programming language has built-in features for
handling of run-time errors.</p>
<p>A run-time error can also be emulated by calling
<span class="code">erlang:error(Reason)</span> or <span class="code">erlang:error(Reason, Args)</span>
(those appeared in Erlang 5.4/OTP-R10).</p>
<p>A run-time error is another name for an exception
of class <span class="code">error</span>.
</p>
<p>A generated error is when the code itself calls
<span class="code">exit/1</span> or <span class="code">throw/1</span>. Note that emulated run-time
errors are not denoted as generated errors here.
</p>
<p>Generated errors are exceptions of classes <span class="code">exit</span> and
<span class="code">throw</span>.
</p>
<p>When a run-time error or generated error occurs in Erlang,
execution for the process which evaluated
the erroneous expression is stopped.
This is referred to as a <strong>failure</strong>, that execution or
evaluation <strong>fails</strong>, or that the process <strong>fails</strong>,
<strong>terminates</strong> or <strong>exits</strong>. Note that a process may
terminate/exit for other reasons than a failure.</p>
<p>A process that terminates will emit an <strong>exit signal</strong> with
an <strong>exit reason</strong> that says something about which error
has occurred. Normally, some information about the error will
be printed to the terminal.</p>
<h3><a name="id81678">10.2
Exceptions</a></h3>
<p>Exceptions are run-time errors or generated errors and
are of three different classes, with different origins. The
<span class="bold_code"><a href="expressions.html#try">try</a></span> expression
(appeared in Erlang 5.4/OTP-R10B)
can distinguish between the different classes, whereas the
<span class="bold_code"><a href="expressions.html#catch">catch</a></span>
expression can not. They are described in the Expressions chapter.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>Class</strong></td>
<td align="left" valign="middle"><strong>Origin</strong></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">error</span></td>
<td align="left" valign="middle">Run-time error for example <span class="code">1+a</span>, or the process called <span class="code">erlang:error/1,2</span> (appeared in Erlang 5.4/OTP-R10B)</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">exit</span></td>
<td align="left" valign="middle">The process called <span class="code">exit/1</span>
</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">throw</span></td>
<td align="left" valign="middle">The process called <span class="code">throw/1</span>
</td>
</tr>
</table>
<em>Table
10.1:
Exception Classes.</em>
<p>An exception consists of its class, an exit reason
(the <span class="bold_code"><a href="#exit_reasons">Exit Reason</a></span>),
and a stack trace (that aids in finding the code location of
the exception).</p>
<p>The stack trace can be retrieved using
<span class="code">erlang:get_stacktrace/0</span> (new in Erlang 5.4/OTP-R10B)
from within a <span class="code">try</span> expression, and is returned for
exceptions of class <span class="code">error</span> from a <span class="code">catch</span> expression.</p>
<p>An exception of class <span class="code">error</span> is also known as a run-time
error.</p>
<h3><a name="id81851">10.3
Handling of Run-Time Errors in Erlang</a></h3>
<h4>Error Handling Within Processes</h4>
<p>It is possible to prevent run-time errors and other
exceptions from causing
the process to terminate by using <span class="code">catch</span> or
<span class="code">try</span>, see the Expressions chapter about
<span class="bold_code"><a href="expressions.html#catch">Catch</a></span>
and <span class="bold_code"><a href="expressions.html#try">Try</a></span>.</p>
<h4>Error Handling Between Processes</h4>
<p>Processes can monitor other processes and detect process
terminations, see
the <span class="bold_code"><a href="processes.html#errors">Processes</a></span>
chapter.</p>
<h3><a name="id81913">10.4
Exit Reasons</a></h3>
<a name="exit_reasons"></a>
<p>When a run-time error occurs,
that is an exception of class <span class="code">error</span>,
the exit reason is a tuple <span class="code">{Reason,Stack}</span>.
<span class="code">Reason</span> is a term indicating the type of error:</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>Reason</strong></td>
<td align="left" valign="middle"><strong>Type of error</strong></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">badarg</span></td>
<td align="left" valign="middle">Bad argument. The argument is of wrong data type, or is otherwise badly formed.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">badarith</span></td>
<td align="left" valign="middle">Bad argument in an arithmetic expression.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{badmatch,V}</span></td>
<td align="left" valign="middle">Evaluation of a match expression failed. The value <span class="code">V</span> did not match.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">function_clause</span></td>
<td align="left" valign="middle">No matching function clause is found when evaluating a function call.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{case_clause,V}</span></td>
<td align="left" valign="middle">No matching branch is found when evaluating a <span class="code">case</span> expression. The value <span class="code">V</span> did not match.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">if_clause</span></td>
<td align="left" valign="middle">No true branch is found when evaluating an <span class="code">if</span> expression.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{try_clause,V}</span></td>
<td align="left" valign="middle">No matching branch is found when evaluating the of-section of a <span class="code">try</span> expression. The value <span class="code">V</span> did not match.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">undef</span></td>
<td align="left" valign="middle">The function cannot be found when evaluating a function call.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{badfun,F}</span></td>
<td align="left" valign="middle">There is something wrong with a fun <span class="code">F</span>.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{badarity,F}</span></td>
<td align="left" valign="middle">A fun is applied to the wrong number of arguments. <span class="code">F</span> describes the fun and the arguments.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">timeout_value</span></td>
<td align="left" valign="middle">The timeout value in a <span class="code">receive..after</span> expression is evaluated to something else than an integer or <span class="code">infinity</span>.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">noproc</span></td>
<td align="left" valign="middle">Trying to link to a non-existing process.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">{nocatch,V}</span></td>
<td align="left" valign="middle">Trying to evaluate a <span class="code">throw </span>outside a <span class="code">catch</span>. <span class="code">V</span> is the thrown term.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">system_limit</span></td>
<td align="left" valign="middle">A system limit has been reached. See Efficiency Guide for information about system limits.</td>
</tr>
</table>
<em>Table
10.2:
Exit Reasons.</em>
<p><span class="code">Stack</span> is the stack of function calls being evaluated
when the error occurred, given as a list of tuples
<span class="code">{Module,Name,Arity}</span> with the most recent function call
first. The most recent function call tuple may in some
cases be <span class="code">{Module,Name,[Arg]}</span>.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 2003-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
112
