<!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="../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Match specifications in Erlang</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="../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../doc/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="../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/erts-5.9.3.1.pdf">PDF</a><br><a href="../../../doc/index.html">Top</a></small><p><strong>Erlang Run-Time System Application (ERTS)</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="../../../doc/js/flipmenu">
<li id="loadscrollpos" title="Match specifications in Erlang" expanded="true">Match specifications in Erlang<ul>
<li><a href="match_spec.html">
Top of chapter
</a></li>
<li title="Grammar"><a href="match_spec.html#id67432">Grammar</a></li>
<li title="Function descriptions"><a href="match_spec.html#id65382">Function descriptions</a></li>
<li title="Variables and literals"><a href="match_spec.html#id73136">Variables and literals</a></li>
<li title="Execution of the match"><a href="match_spec.html#id73066">Execution of the match</a></li>
<li title="Differences between match specifications in ETS and tracing"><a href="match_spec.html#id69369">Differences between match specifications in ETS and tracing</a></li>
<li title="Examples"><a href="match_spec.html#id69408">Examples</a></li>
</ul>
</li>
<li id="no" title="How to interpret the Erlang crash dumps" expanded="false">How to interpret the Erlang crash dumps<ul>
<li><a href="crash_dump.html">
Top of chapter
</a></li>
<li title="General information"><a href="crash_dump.html#id71973">General information</a></li>
<li title="Memory information"><a href="crash_dump.html#id69719">Memory information</a></li>
<li title="Internal table information"><a href="crash_dump.html#id69746">Internal table information</a></li>
<li title="Allocated areas"><a href="crash_dump.html#id71628">Allocated areas</a></li>
<li title="Allocator"><a href="crash_dump.html#id71654">Allocator</a></li>
<li title="Process information"><a href="crash_dump.html#id71693">Process information</a></li>
<li title="Port information"><a href="crash_dump.html#id70337">Port information</a></li>
<li title="ETS tables"><a href="crash_dump.html#id70354">ETS tables</a></li>
<li title="Timers"><a href="crash_dump.html#id70452">Timers</a></li>
<li title="Distribution information"><a href="crash_dump.html#id77672">Distribution information</a></li>
<li title="Loaded module information"><a href="crash_dump.html#id77796">Loaded module information</a></li>
<li title="Fun information"><a href="crash_dump.html#id77887">Fun information</a></li>
<li title="Process Data"><a href="crash_dump.html#id77959">Process Data</a></li>
<li title="Atoms"><a href="crash_dump.html#id78034">Atoms</a></li>
<li title="Disclaimer"><a href="crash_dump.html#id78051">Disclaimer</a></li>
</ul>
</li>
<li id="no" title="How to implement an alternative carrier for the Erlang distribution" expanded="false">How to implement an alternative carrier for the Erlang distribution<ul>
<li><a href="alt_dist.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="alt_dist.html#id78171">Introduction</a></li>
<li title="The driver"><a href="alt_dist.html#id78261">The driver</a></li>
<li title="Putting it all together"><a href="alt_dist.html#id79511">Putting it all together</a></li>
</ul>
</li>
<li id="no" title="The Abstract Format" expanded="false">The Abstract Format<ul>
<li><a href="absform.html">
Top of chapter
</a></li>
<li title="Module declarations and forms"><a href="absform.html#id79791">Module declarations and forms</a></li>
<li title="Atomic literals"><a href="absform.html#id79999">Atomic literals</a></li>
<li title="Patterns"><a href="absform.html#id80061">Patterns</a></li>
<li title="Expressions"><a href="absform.html#id80275">Expressions</a></li>
<li title="Clauses"><a href="absform.html#id80983">Clauses</a></li>
<li title="Guards"><a href="absform.html#id81203">Guards</a></li>
<li title="The abstract format after preprocessing"><a href="absform.html#id81478">The abstract format after preprocessing</a></li>
</ul>
</li>
<li id="no" title="tty - A command line interface" expanded="false">tty - A command line interface<ul>
<li><a href="tty.html">
Top of chapter
</a></li>
<li title="Normal Mode"><a href="tty.html#id81651">Normal Mode</a></li>
<li title="Shell Break Mode"><a href="tty.html#id82034">Shell Break Mode</a></li>
</ul>
</li>
<li id="no" title="How to implement a driver" expanded="false">How to implement a driver<ul>
<li><a href="driver.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="driver.html#id82159">Introduction</a></li>
<li title="Sample driver"><a href="driver.html#id82191">Sample driver</a></li>
<li title="Compiling and linking the sample driver"><a href="driver.html#id82593">Compiling and linking the sample driver</a></li>
<li title="Calling a driver as a port in Erlang"><a href="driver.html#id82629">Calling a driver as a port in Erlang</a></li>
<li title="Sample asynchronous driver"><a href="driver.html#id82736">Sample asynchronous driver</a></li>
<li title="An asynchronous driver using driver_async"><a href="driver.html#id83010">An asynchronous driver using driver_async</a></li>
</ul>
</li>
<li id="no" title="Inet configuration" expanded="false">Inet configuration<ul>
<li><a href="inet_cfg.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="inet_cfg.html#id83274">Introduction</a></li>
<li title="Configuration Data"><a href="inet_cfg.html#id83378">Configuration Data</a></li>
<li title="User Configuration Example"><a href="inet_cfg.html#id84255">User Configuration Example</a></li>
</ul>
</li>
<li id="no" title="External Term Format" expanded="false">External Term Format<ul>
<li><a href="erl_ext_dist.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="erl_ext_dist.html#id84356">Introduction</a></li>
<li title="Distribution header"><a href="erl_ext_dist.html#id84636">Distribution header</a></li>
<li title="ATOM_CACHE_REF"><a href="erl_ext_dist.html#id85209">ATOM_CACHE_REF</a></li>
<li title="SMALL_INTEGER_EXT"><a href="erl_ext_dist.html#id85285">SMALL_INTEGER_EXT</a></li>
<li title="INTEGER_EXT"><a href="erl_ext_dist.html#id85348">INTEGER_EXT</a></li>
<li title="FLOAT_EXT"><a href="erl_ext_dist.html#id85412">FLOAT_EXT</a></li>
<li title="ATOM_EXT"><a href="erl_ext_dist.html#id85488">ATOM_EXT</a></li>
<li title="REFERENCE_EXT"><a href="erl_ext_dist.html#id85583">REFERENCE_EXT</a></li>
<li title="PORT_EXT"><a href="erl_ext_dist.html#id85741">PORT_EXT</a></li>
<li title="PID_EXT"><a href="erl_ext_dist.html#id85860">PID_EXT</a></li>
<li title="SMALL_TUPLE_EXT"><a href="erl_ext_dist.html#id86004">SMALL_TUPLE_EXT</a></li>
<li title="LARGE_TUPLE_EXT"><a href="erl_ext_dist.html#id86096">LARGE_TUPLE_EXT</a></li>
<li title="NIL_EXT"><a href="erl_ext_dist.html#id86186">NIL_EXT</a></li>
<li title="STRING_EXT"><a href="erl_ext_dist.html#id86237">STRING_EXT</a></li>
<li title="LIST_EXT"><a href="erl_ext_dist.html#id86329">LIST_EXT</a></li>
<li title="BINARY_EXT"><a href="erl_ext_dist.html#id86448">BINARY_EXT</a></li>
<li title="SMALL_BIG_EXT"><a href="erl_ext_dist.html#id86545">SMALL_BIG_EXT</a></li>
<li title="LARGE_BIG_EXT"><a href="erl_ext_dist.html#id86652">LARGE_BIG_EXT</a></li>
<li title="NEW_REFERENCE_EXT"><a href="erl_ext_dist.html#id86755">NEW_REFERENCE_EXT</a></li>
<li title="SMALL_ATOM_EXT"><a href="erl_ext_dist.html#id86928">SMALL_ATOM_EXT</a></li>
<li title="FUN_EXT"><a href="erl_ext_dist.html#id87034">FUN_EXT</a></li>
<li title="NEW_FUN_EXT"><a href="erl_ext_dist.html#id87281">NEW_FUN_EXT</a></li>
<li title="EXPORT_EXT"><a href="erl_ext_dist.html#id87658">EXPORT_EXT</a></li>
<li title="BIT_BINARY_EXT"><a href="erl_ext_dist.html#id87802">BIT_BINARY_EXT</a></li>
<li title="NEW_FLOAT_EXT"><a href="erl_ext_dist.html#id87908">NEW_FLOAT_EXT</a></li>
</ul>
</li>
<li id="no" title="Distribution Protocol" expanded="false">Distribution Protocol<ul>
<li><a href="erl_dist_protocol.html">
Top of chapter
</a></li>
<li title="EPMD Protocol"><a href="erl_dist_protocol.html#id88085">EPMD Protocol</a></li>
<li title="Handshake"><a href="erl_dist_protocol.html#id89383">Handshake</a></li>
<li title="Protocol between connected nodes"><a href="erl_dist_protocol.html#id89399">Protocol between connected nodes</a></li>
<li title="New Ctrlmessages for distrvsn = 1 (OTP R4)"><a href="erl_dist_protocol.html#id89841">New Ctrlmessages for distrvsn = 1 (OTP R4)</a></li>
<li title="New Ctrlmessages for distrvsn = 2"><a href="erl_dist_protocol.html#id89939">New Ctrlmessages for distrvsn = 2</a></li>
<li title="New Ctrlmessages for distrvsn = 3 (OTP R5C)"><a href="erl_dist_protocol.html#id89951">New Ctrlmessages for distrvsn = 3 (OTP R5C)</a></li>
<li title="New Ctrlmessages for distrvsn = 4 (OTP R6)"><a href="erl_dist_protocol.html#id89963">New Ctrlmessages for distrvsn = 4 (OTP R6)</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>1 Match specifications in Erlang</h1>
<p>A "match specification" (match_spec) is an Erlang term describing a
small "program" that will try to match something (either the
parameters to a function as used in the <span class="code">erlang:trace_pattern/2</span>
BIF, or the objects in an ETS table.).
The match_spec in many ways works like a small function in Erlang, but is
interpreted/compiled by the Erlang runtime system to something much more
efficient than calling an Erlang function. The match_spec is also
very limited compared to the expressiveness of real Erlang functions.</p>
<p>Match specifications are given to the BIF <span class="code">erlang:trace_pattern/2</span> to
execute matching of function arguments as well as to define some actions
to be taken when the match succeeds (the <span class="code">MatchBody</span> part). Match
specifications can also be used in ETS, to specify objects to be
returned from an <span class="code">ets:select/2</span> call (or other select
calls). The semantics and restrictions differ slightly when using
match specifications for tracing and in ETS, the differences are
defined in a separate paragraph below.</p>
<p>The most notable difference between a match_spec and an Erlang fun is
of course the syntax. Match specifications are Erlang terms, not
Erlang code. A match_spec also has a somewhat strange concept of
exceptions. An exception (e.g., <span class="code">badarg</span>) in the <span class="code">MatchCondition</span>
part,
which resembles an Erlang guard, will generate immediate failure,
while an exception in the <span class="code">MatchBody</span> part, which resembles the body of an
Erlang function, is implicitly caught and results in the single atom
<span class="code">'EXIT'</span>.
</p>
<h3><a name="id67432">1.1
Grammar</a></h3>
<p>A match_spec used in tracing can be described in this <strong>informal</strong> grammar:</p>
<ul>
<li>MatchExpression ::= [ MatchFunction, ... ]
</li>
<li>MatchFunction ::= { MatchHead, MatchConditions, MatchBody }
</li>
<li>MatchHead ::= MatchVariable | <span class="code">'_'</span> | [ MatchHeadPart, ... ]
</li>
<li>MatchHeadPart ::= term() | MatchVariable | <span class="code">'_'</span>
</li>
<li>MatchVariable ::= '$<number>'
</li>
<li>MatchConditions ::= [ MatchCondition, ...] | <span class="code">[]</span>
</li>
<li>MatchCondition ::= { GuardFunction } |
{ GuardFunction, ConditionExpression, ... }
</li>
<li>BoolFunction ::= <span class="code">is_atom</span> |
<span class="code">is_float</span> | <span class="code">is_integer</span> | <span class="code">is_list</span> |
<span class="code">is_number</span> | <span class="code">is_pid</span> | <span class="code">is_port</span> |
<span class="code">is_reference</span> | <span class="code">is_tuple</span> | <span class="code">is_binary</span> |
<span class="code">is_function</span> | <span class="code">is_record</span> | <span class="code">is_seq_trace</span> |
<span class="code">'and'</span> | <span class="code">'or'</span> | <span class="code">'not'</span> | <span class="code">'xor'</span> |
<span class="code">andalso</span> | <span class="code">orelse</span>
</li>
<li>ConditionExpression ::= ExprMatchVariable | { GuardFunction } |
{ GuardFunction, ConditionExpression, ... } | TermConstruct
</li>
<li>ExprMatchVariable ::= MatchVariable (bound in the MatchHead) |
<span class="code">'$_'</span> | <span class="code">'$$'</span>
</li>
<li>TermConstruct = {{}} | {{ ConditionExpression, ... }} |
<span class="code">[]</span> | [ConditionExpression, ...] | NonCompositeTerm | Constant
</li>
<li>NonCompositeTerm ::= term() (not list or tuple)
</li>
<li>Constant ::= {<span class="code">const</span>, term()}
</li>
<li>GuardFunction ::= BoolFunction | <span class="code">abs</span> |
<span class="code">element</span> | <span class="code">hd</span> | <span class="code">length</span> | <span class="code">node</span> |
<span class="code">round</span> | <span class="code">size</span> | <span class="code">tl</span> | <span class="code">trunc</span> |
<span class="code">'+'</span> | <span class="code">'-'</span> | <span class="code">'*'</span> | <span class="code">'div'</span> |
<span class="code">'rem'</span> | <span class="code">'band'</span> | <span class="code">'bor'</span> | <span class="code">'bxor'</span> |
<span class="code">'bnot'</span> | <span class="code">'bsl'</span> | <span class="code">'bsr'</span> | <span class="code">'>'</span> |
<span class="code">'>='</span> | <span class="code">'<'</span> | <span class="code">'=<'</span> | <span class="code">'=:='</span> |
<span class="code">'=='</span> | <span class="code">'=/='</span> | <span class="code">'/='</span> | <span class="code">self</span> |
<span class="code">get_tcw</span>
</li>
<li>MatchBody ::= [ ActionTerm ]
</li>
<li>ActionTerm ::= ConditionExpression | ActionCall
</li>
<li>ActionCall ::= {ActionFunction} |
{ActionFunction, ActionTerm, ...}
</li>
<li>ActionFunction ::= <span class="code">set_seq_token</span> |
<span class="code">get_seq_token</span> | <span class="code">message</span> |
<span class="code">return_trace</span> | <span class="code">exception_trace</span> | <span class="code">process_dump</span> |
<span class="code">enable_trace</span> | <span class="code">disable_trace</span> | <span class="code">trace</span> |
<span class="code">display</span> | <span class="code">caller</span> | <span class="code">set_tcw</span> |
<span class="code">silent</span>
</li>
</ul>
<p>A match_spec used in ets can be described in this <strong>informal</strong> grammar:</p>
<ul>
<li>MatchExpression ::= [ MatchFunction, ... ]
</li>
<li>MatchFunction ::= { MatchHead, MatchConditions, MatchBody }
</li>
<li>MatchHead ::= MatchVariable | <span class="code">'_'</span> | { MatchHeadPart, ... }
</li>
<li>MatchHeadPart ::= term() | MatchVariable | <span class="code">'_'</span>
</li>
<li>MatchVariable ::= '$<number>'
</li>
<li>MatchConditions ::= [ MatchCondition, ...] | <span class="code">[]</span>
</li>
<li>MatchCondition ::= { GuardFunction } |
{ GuardFunction, ConditionExpression, ... }
</li>
<li>BoolFunction ::= <span class="code">is_atom</span> |
<span class="code">is_float</span> | <span class="code">is_integer</span> | <span class="code">is_list</span> |
<span class="code">is_number</span> | <span class="code">is_pid</span> | <span class="code">is_port</span> |
<span class="code">is_reference</span> | <span class="code">is_tuple</span> | <span class="code">is_binary</span> |
<span class="code">is_function</span> | <span class="code">is_record</span> | <span class="code">is_seq_trace</span> |
<span class="code">'and'</span> | <span class="code">'or'</span> | <span class="code">'not'</span> | <span class="code">'xor'</span> |
<span class="code">andalso</span> | <span class="code">orelse</span>
</li>
<li>ConditionExpression ::= ExprMatchVariable | { GuardFunction } |
{ GuardFunction, ConditionExpression, ... } | TermConstruct
</li>
<li>ExprMatchVariable ::= MatchVariable (bound in the MatchHead) |
<span class="code">'$_'</span> | <span class="code">'$$'</span>
</li>
<li>TermConstruct = {{}} | {{ ConditionExpression, ... }} |
<span class="code">[]</span> | [ConditionExpression, ...] | NonCompositeTerm | Constant
</li>
<li>NonCompositeTerm ::= term() (not list or tuple)
</li>
<li>Constant ::= {<span class="code">const</span>, term()}
</li>
<li>GuardFunction ::= BoolFunction | <span class="code">abs</span> |
<span class="code">element</span> | <span class="code">hd</span> | <span class="code">length</span> | <span class="code">node</span> |
<span class="code">round</span> | <span class="code">size</span> | <span class="code">tl</span> | <span class="code">trunc</span> |
<span class="code">'+'</span> | <span class="code">'-'</span> | <span class="code">'*'</span> | <span class="code">'div'</span> |
<span class="code">'rem'</span> | <span class="code">'band'</span> | <span class="code">'bor'</span> | <span class="code">'bxor'</span> |
<span class="code">'bnot'</span> | <span class="code">'bsl'</span> | <span class="code">'bsr'</span> | <span class="code">'>'</span> |
<span class="code">'>='</span> | <span class="code">'<'</span> | <span class="code">'=<'</span> | <span class="code">'=:='</span> |
<span class="code">'=='</span> | <span class="code">'=/='</span> | <span class="code">'/='</span> | <span class="code">self</span> |
<span class="code">get_tcw</span>
</li>
<li>MatchBody ::= [ ConditionExpression, ... ]</li>
</ul>
<h3><a name="id65382">1.2
Function descriptions</a></h3>
<h4>Functions allowed in all types of match specifications</h4>
<p>The different functions allowed in <span class="code">match_spec</span> work like this:
</p>
<p><strong>is_atom, is_float, is_integer, is_list, is_number, is_pid, is_port, is_reference, is_tuple, is_binary, is_function: </strong> Like the corresponding guard tests in
Erlang, return <span class="code">true</span> or <span class="code">false</span>.
</p>
<p><strong>is_record: </strong>Takes an additional parameter, which SHALL
be the result of <span class="code">record_info(size, <record_type>)</span>,
like in <span class="code">{is_record, '$1', rectype, record_info(size, rectype)}</span>.
</p>
<p><strong>'not': </strong>Negates its single argument (anything other
than <span class="code">false</span> gives <span class="code">false</span>).
</p>
<p><strong>'and': </strong>Returns <span class="code">true</span> if all its arguments
(variable length argument list) evaluate to <span class="code">true</span>, else
<span class="code">false</span>. Evaluation order is undefined.
</p>
<p><strong>'or': </strong>Returns <span class="code">true</span> if any of its arguments
evaluates to <span class="code">true</span>. Variable length argument
list. Evaluation order is undefined.
</p>
<p><strong>andalso: </strong>Like <span class="code">'and'</span>, but quits evaluating its
arguments as soon as one argument evaluates to something else
than true. Arguments are evaluated left to right.
</p>
<p><strong>orelse: </strong>Like <span class="code">'or'</span>, but quits evaluating as soon
as one of its arguments evaluates to <span class="code">true</span>. Arguments are
evaluated left to right.
</p>
<p><strong>'xor': </strong>Only two arguments, of which one has to be true
and the other false to return <span class="code">true</span>; otherwise
<span class="code">'xor'</span> returns false.
</p>
<p><strong>abs, element, hd, length, node, round, size, tl, trunc, '+', '-', '*', 'div', 'rem', 'band', 'bor', 'bxor', 'bnot', 'bsl', 'bsr', '>', '>=', '<', '=<', '=:=', '==', '=/=', '/=', self: </strong>Work as the corresponding Erlang bif's (or
operators). In case of bad arguments, the result depends on
the context. In the <span class="code">MatchConditions</span> part of the
expression, the test fails immediately (like in an Erlang
guard), but in the <span class="code">MatchBody</span>, exceptions are implicitly
caught and the call results in the atom <span class="code">'EXIT'</span>.</p>
<h4>Functions allowed only for tracing</h4>
<p><strong>is_seq_trace: </strong>Returns <span class="code">true</span> if a sequential
trace token is set for the current process, otherwise <span class="code">false</span>.
</p>
<p><strong>set_seq_token:</strong> Works like
<span class="code">seq_trace:set_token/2</span>, but returns <span class="code">true</span> on success
and <span class="code">'EXIT'</span> on error or bad argument. Only allowed in the
<span class="code">MatchBody</span> part and only allowed when tracing.
</p>
<p><strong>get_seq_token:</strong> Works just like
<span class="code">seq_trace:get_token/0</span>, and is only allowed in the
<span class="code">MatchBody</span> part when tracing.
</p>
<p><strong>message:</strong> Sets an additional message appended to the
trace message sent. One can only set one additional message in
the body; subsequent calls will replace the appended message. As
a special case, <span class="code">{message, false}</span> disables sending of
trace messages ('call' and 'return_to')
for this function call, just like if the match_spec had not matched,
which can be useful if only the side effects of
the <span class="code">MatchBody</span> are desired.
Another special case is <span class="code">{message, true}</span> which
sets the default behavior, as if the function had no match_spec,
trace message is sent with no extra
information (if no other calls to <span class="code">message</span> are placed
before <span class="code">{message, true}</span>, it is in fact a "noop").
</p>
<p>Takes one argument, the message. Returns <span class="code">true</span> and can
only be used in the <span class="code">MatchBody</span> part and when tracing.
</p>
<p><strong>return_trace:</strong> Causes a <span class="code">return_from</span> trace
message to be sent upon return from the current function.
Takes no arguments, returns <span class="code">true</span> and can only be used
in the <span class="code">MatchBody</span> part when tracing.
If the process trace flag <span class="code">silent</span>
is active the <span class="code">return_from</span> trace message is inhibited.
</p>
<p>NOTE! If the traced function is tail recursive, this match
spec function destroys that property.
Hence, if a match spec executing this function is used on a
perpetual server process, it may only be active for a limited
time, or the emulator will eventually use all memory in the host
machine and crash. If this match_spec function is inhibited
using the <span class="code">silent</span> process trace flag
tail recursiveness still remains.
</p>
<p><strong>exception_trace:</strong> Same as <strong>return_trace</strong>,
plus; if the traced function exits due to an exception,
an <span class="code">exception_from</span> trace message is generated,
whether the exception is caught or not.
</p>
<p><strong>process_dump:</strong> Returns some textual information about
the current process as a binary. Takes no arguments and is only
allowed in the <span class="code">MatchBody</span> part when tracing.
</p>
<p><strong>enable_trace:</strong> With one parameter this function turns
on tracing like the Erlang call <span class="code">erlang:trace(self(), true, [P2])</span>, where <span class="code">P2</span> is the parameter to
<span class="code">enable_trace</span>. With two parameters, the first parameter
should be either a process identifier or the registered name of
a process. In this case tracing is turned on for the designated
process in the same way as in the Erlang call <span class="code">erlang:trace(P1, true, [P2])</span>, where P1 is the first and P2 is the second
argument. The process <span class="code">P1</span> gets its trace messages sent to the same
tracer as the process executing the statement uses. <span class="code">P1</span>
can <strong>not</strong> be one of the atoms <span class="code">all</span>, <span class="code">new</span> or
<span class="code">existing</span> (unless, of course, they are registered names).
<span class="code">P2</span> can <strong>not</strong> be <span class="code">cpu_timestamp</span> nor
<span class="code">{tracer,_}</span>.
Returns <span class="code">true</span> and may only be used in
the <span class="code">MatchBody</span> part when tracing.
</p>
<p><strong>disable_trace:</strong> With one parameter this function
disables tracing like the Erlang call <span class="code">erlang:trace(self(), false, [P2])</span>, where <span class="code">P2</span> is the parameter to
<span class="code">disable_trace</span>. With two parameters it works like the
Erlang call <span class="code">erlang:trace(P1, false, [P2])</span>, where P1 can
be either a process identifier or a registered name and is given
as the first argument to the match_spec function.
<span class="code">P2</span> can <strong>not</strong> be <span class="code">cpu_timestamp</span> nor
<span class="code">{tracer,_}</span>. Returns
<span class="code">true</span> and may only be used in the <span class="code">MatchBody</span> part
when tracing.
</p>
<p><strong>trace:</strong> With two parameters this function takes a list
of trace flags to disable as first parameter and a list
of trace flags to enable as second parameter. Logically, the
disable list is applied first, but effectively all changes
are applied atomically. The trace flags
are the same as for <span class="code">erlang:trace/3</span> not including
<span class="code">cpu_timestamp</span> but including <span class="code">{tracer,_}</span>. If a
tracer is specified in both lists, the tracer in the
enable list takes precedence. If no tracer is specified the
same tracer as the process executing the match spec is
used. With three parameters to this function the first is
either a process identifier or the registered name of a
process to set trace flags on, the second is the disable
list, and the third is the enable list. Returns
<span class="code">true</span> if any trace property was changed for the
trace target process or <span class="code">false</span> if not. It may only
be used in the <span class="code">MatchBody</span> part when tracing.
</p>
<p><strong>caller:</strong>
Returns the calling function as a tuple {Module,
Function, Arity} or the atom <span class="code">undefined</span> if the calling
function cannot be determined. May only be used in the
<span class="code">MatchBody</span> part when tracing.
</p>
<p>Note that if a "technically built in function" (i.e. a
function not written in Erlang) is traced, the <span class="code">caller</span>
function will sometimes return the atom <span class="code">undefined</span>. The calling
Erlang function is not available during such calls.
</p>
<p><strong>display:</strong> For debugging purposes only; displays the
single argument as an Erlang term on stdout, which is seldom
what is wanted. Returns <span class="code">true</span> and may only be used in the
<span class="code">MatchBody</span> part when tracing.
</p>
<p> <a name="get_tcw"></a>
<strong>get_tcw:</strong>
Takes no argument and returns the value of the node's trace
control word. The same is done by
<span class="code">erlang:system_info(trace_control_word)</span>.
</p>
<p>The trace control word is a 32-bit unsigned integer intended for
generic trace control. The trace control word can be tested and
set both from within trace match specifications and with BIFs.
This call is only allowed when tracing.
</p>
<p> <a name="set_tcw"></a>
<strong>set_tcw:</strong>
Takes one unsigned integer argument, sets the value of
the node's trace control word to the value of the argument
and returns the previous value. The same is done by
<span class="code">erlang:system_flag(trace_control_word, Value)</span>. It is only
allowed to use <span class="code">set_tcw</span> in the <span class="code">MatchBody</span> part
when tracing.
</p>
<p><strong>silent:</strong>
Takes one argument. If the argument is <span class="code">true</span>, the call
trace message mode for the current process is set to silent
for this call and all subsequent, i.e call trace messages
are inhibited even if <span class="code">{message, true}</span> is called in the
<span class="code">MatchBody</span> part for a traced function.
</p>
<p>This mode can also be activated with the <span class="code">silent</span> flag
to <span class="code">erlang:trace/3</span>.
</p>
<p>If the argument is <span class="code">false</span>, the call trace message mode
for the current process is set to normal (non-silent) for
this call and all subsequent.
</p>
<p>If the argument is neither <span class="code">true</span> nor <span class="code">false</span>,
the call trace message mode is unaffected.</p>
<p><strong>Note</strong> that all "function calls" have to be tuples,
even if they take no arguments. The value of <span class="code">self</span> is
the atom() <span class="code">self</span>, but the value of <span class="code">{self}</span> is
the pid() of the current process.</p>
<h3><a name="id73136">1.3
Variables and literals</a></h3>
<p>Variables take the form <span class="code">'$<number>'</span> where
<span class="code"><number></span> is an integer between 0 (zero) and
100000000 (1e+8), the behavior if the number is outside these
limits is <strong>undefined</strong>. In the <span class="code">MatchHead</span> part, the special
variable <span class="code">'_'</span> matches anything, and never gets bound (like
<span class="code">_</span> in Erlang). In the <span class="code">MatchCondition/MatchBody</span>
parts, no unbound variables are allowed, why <span class="code">'_'</span> is
interpreted as itself (an atom). Variables can only be bound in
the <span class="code">MatchHead</span> part. In the <span class="code">MatchBody</span> and
<span class="code">MatchCondition</span> parts, only variables bound previously may
be used. As a special case, in the
<span class="code">MatchCondition/MatchBody</span> parts, the variable <span class="code">'$_'</span>
expands to the whole expression which matched the
<span class="code">MatchHead</span> (i.e., the whole parameter list to the possibly
traced function or the whole matching object in the ets table)
and the variable <span class="code">'$$'</span> expands to a list
of the values of all bound variables in order
(i.e. <span class="code">['$1','$2', ...]</span>).
</p>
<p>In the <span class="code">MatchHead</span> part, all literals (except the variables
noted above) are interpreted as is. In the
<span class="code">MatchCondition/MatchBody</span> parts, however, the
interpretation is in some ways different. Literals in the
<span class="code">MatchCondition/MatchBody</span> can either be written as is,
which works for all literals except tuples, or by using the
special form <span class="code">{const, T}</span>, where <span class="code">T</span> is any Erlang
term. For tuple literals in the match_spec, one can also use
double tuple parentheses, i.e., construct them as a tuple of
arity one containing a single tuple, which is the one to be
constructed. The "double tuple parenthesis" syntax is useful to
construct tuples from already bound variables, like in
<span class="code">{{'$1', [a,b,'$2']}}</span>. Some examples may be needed:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">Expression </td>
<td align="left" valign="middle">Variable bindings </td>
<td align="left" valign="middle">Result </td>
</tr>
<tr>
<td align="left" valign="middle">{{'$1','$2'}} </td>
<td align="left" valign="middle">'$1' = a, '$2' = b</td>
<td align="left" valign="middle">{a,b}</td>
</tr>
<tr>
<td align="left" valign="middle">{const, {'$1', '$2'}} </td>
<td align="left" valign="middle">doesn't matter</td>
<td align="left" valign="middle">{'$1', '$2'}</td>
</tr>
<tr>
<td align="left" valign="middle">a </td>
<td align="left" valign="middle">doesn't matter </td>
<td align="left" valign="middle">a</td>
</tr>
<tr>
<td align="left" valign="middle">'$1' </td>
<td align="left" valign="middle">'$1' = [] </td>
<td align="left" valign="middle">[]</td>
</tr>
<tr>
<td align="left" valign="middle">['$1'] </td>
<td align="left" valign="middle">'$1' = [] </td>
<td align="left" valign="middle">[[]]</td>
</tr>
<tr>
<td align="left" valign="middle">[{{a}}] </td>
<td align="left" valign="middle">doesn't matter</td>
<td align="left" valign="middle">[{a}]</td>
</tr>
<tr>
<td align="left" valign="middle">42 </td>
<td align="left" valign="middle">doesn't matter</td>
<td align="left" valign="middle">42</td>
</tr>
<tr>
<td align="left" valign="middle">"hello" </td>
<td align="left" valign="middle">doesn't matter</td>
<td align="left" valign="middle">"hello"</td>
</tr>
<tr>
<td align="left" valign="middle">$1 </td>
<td align="left" valign="middle">doesn't matter</td>
<td align="left" valign="middle">49 (the ASCII value for the character '1')</td>
</tr>
</table>
<em>Table
1.1:
Literals in the MatchCondition/MatchBody parts of a match_spec</em>
<h3><a name="id73066">1.4
Execution of the match</a></h3>
<p>The execution of the match expression, when the runtime system
decides whether a trace message should be sent, goes as follows:
</p>
<p>For each tuple in the <span class="code">MatchExpression</span> list and while no
match has succeeded:</p>
<ul>
<li>Match the <span class="code">MatchHead</span> part against the arguments to the
function,
binding the <span class="code">'$<number>'</span> variables (much like in
<span class="code">ets:match/2</span>).
If the <span class="code">MatchHead</span> cannot match the arguments, the match fails.
</li>
<li>Evaluate each <span class="code">MatchCondition</span> (where only
<span class="code">'$<number>'</span> variables previously bound in the
<span class="code">MatchHead</span> can occur) and expect it to return the atom
<span class="code">true</span>. As soon as a condition does not evaluate to
<span class="code">true</span>, the match fails. If any BIF call generates an
exception, also fail.
</li>
<li>
<ul>
<li>
<strong>If the match_spec is executing when tracing:</strong><br>
Evaluate each <span class="code">ActionTerm</span> in the same way as the
<span class="code">MatchConditions</span>, but completely ignore the return
values. Regardless of what happens in this part, the match has
succeeded.</li>
<li>
<strong>If the match_spec is executed when selecting objects from an ETS table:</strong><br>
Evaluate the expressions in order and return the value of
the last expression (typically there is only one expression
in this context)</li>
</ul>
</li>
</ul>
<h3><a name="id69369">1.5
Differences between match specifications in ETS and tracing</a></h3>
<p>ETS match specifications are there to produce a return
value. Usually the <span class="code">MatchBody</span> contains one single
<span class="code">ConditionExpression</span> which defines the return value without having
any side effects. Calls with side effects are not allowed in the
ETS context.</p>
<p>When tracing there is no return value to produce, the
match specification either matches or doesn't. The effect when the
expression matches is a trace message rather then a returned
term. The <span class="code">ActionTerm</span>'s are executed as in an imperative
language, i.e. for their side effects. Functions with side effects
are also allowed when tracing.</p>
<p>In ETS the match head is a <span class="code">tuple()</span> (or a single match
variable) while it is a list (or a single match variable) when
tracing.</p>
<h3><a name="id69408">1.6
Examples</a></h3>
<p>Match an argument list of three where the first and third arguments
are equal:</p>
<div class="example"><pre>
[{['$1', '_', '$1'],
[],
[]}]
</pre></div>
<p>Match an argument list of three where the second argument is
a number greater than three:</p>
<div class="example"><pre>
[{['_', '$1', '_'],
[{ '>', '$1', 3}],
[]}]
</pre></div>
<p>Match an argument list of three, where the third argument
is a tuple containing argument one and two <strong>or</strong> a list
beginning with argument one and two (i. e. <span class="code">[a,b,[a,b,c]]</span> or
<span class="code">[a,b,{a,b}]</span>):
</p>
<div class="example"><pre>
[{['$1', '$2', '$3'],
[{orelse,
{'=:=', '$3', {{'$1','$2'}}},
{'and',
{'=:=', '$1', {hd, '$3'}},
{'=:=', '$2', {hd, {tl, '$3'}}}}}],
[]}]
</pre></div>
<p>The above problem may also be solved like this:</p>
<div class="example"><pre>
[{['$1', '$2', {'$1', '$2}], [], []},
{['$1', '$2', ['$1', '$2' | '_']], [], []}]
</pre></div>
<p>Match two arguments where the first is a tuple beginning with
a list which in turn begins with the second argument times
two (i. e. [{[4,x],y},2] or [{[8], y, z},4])</p>
<div class="example"><pre>
[{['$1', '$2'],[{'=:=', {'*', 2, '$2'}, {hd, {element, 1, '$1'}}}],
[]}]
</pre></div>
<p>Match three arguments. When all three are equal and are
numbers, append the process dump to the trace message, else
let the trace message be as is, but set the sequential trace
token label to 4711.</p>
<div class="example"><pre>
[{['$1', '$1', '$1'],
[{is_number, '$1'}],
[{message, {process_dump}}]},
{'_', [], [{set_seq_token, label, 4711}]}]
</pre></div>
<p>As can be noted above, the parameter list can be matched
against a single <span class="code">MatchVariable</span> or an <span class="code">'_'</span>. To replace the
whole
parameter list with a single variable is a special case. In all
other cases the <span class="code">MatchHead</span> has to be a <strong>proper</strong> list.
</p>
<p>Match all objects in an ets table where the first element is
the atom 'strider' and the tuple arity is 3 and return the whole
object.</p>
<div class="example"><pre>
[{{strider,'_','_'},
[],
['$_']}]
</pre></div>
<p>Match all objects in an ets table with arity > 1 and the first
element is 'gandalf', return element 2.</p>
<div class="example"><pre>
[{'$1',
[{'==', gandalf, {element, 1, '$1'}},{'>=',{size, '$1'},2}],
[{element,2,'$1'}]}]
</pre></div>
<p>In the above example, if the first element had been the key,
it's much more efficient to match that key in the <span class="code">MatchHead</span>
part than in the <span class="code">MatchConditions</span> part. The search space of
the tables is restricted with regards to the <span class="code">MatchHead</span> so
that only objects with the matching key are searched.
</p>
<p>Match tuples of 3 elements where the second element is either
'merry' or 'pippin', return the whole objects.</p>
<div class="example"><pre>
[{{'_',merry,'_'},
[],
['$_']},
{{'_',pippin,'_'},
[],
['$_']}]
</pre></div>
<p>The function <span class="code">ets:test_ms/2</span> can be useful for testing
complicated ets matches.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
