<!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 -- External Term Format</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="no" title="Match specifications in Erlang" expanded="false">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="loadscrollpos" title="External Term Format" expanded="true">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>8 External Term Format</h1>
<h3><a name="id84356">8.1
Introduction</a></h3>
<p>
The external term format is mainly used in the distribution
mechanism of Erlang.
</p>
<p>
Since Erlang has a fixed number of types, there is no need for a
programmer to define a specification for the external format used
within some application.
All Erlang terms has an external representation and the interpretation
of the different terms are application specific.
</p>
<p>
In Erlang the BIF <span class="bold_code"><a href="javascript:erlhref('../../../doc/../','erts','erlang.html#term_to_binary-1');">term_to_binary/1,2</a></span> is used to convert a
term into the external format.
To convert binary data encoding a term the BIF
<span class="bold_code"><a href="javascript:erlhref('../../../doc/../','erts','erlang.html#binary_to_term-1');">
binary_to_term/1
</a></span>
is used.
</p>
<p>
The distribution does this implicitly when sending messages across
node boundaries.
</p>
<a name="overall_format"></a>
<p>
The overall format of the term format is:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">N</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">131</span></td>
<td align="left" valign="middle"><span class="code">Tag</span></td>
<td align="left" valign="middle"><span class="code">Data</span></td>
</tr>
</table>
<em>Table
8.1:
</em>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>
When messages are
<span class="bold_code"><a href="erl_dist_protocol.html#connected_nodes">passed between
connected nodes</a></span> and a
<span class="bold_code"><a href="#distribution_header">distribution
header</a></span> is used, the first byte containing the version
number (131) is omitted from the terms that follow the distribution
header. This since
the version number is implied by the version number in the
distribution header.
</p>
</p></div>
</div>
<p>
A compressed term looks like this:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">N</td>
</tr>
<tr>
<td align="left" valign="middle">131</td>
<td align="left" valign="middle">80</td>
<td align="left" valign="middle">UncompressedSize</td>
<td align="left" valign="middle">Zlib-compressedData</td>
</tr>
</table>
<em>Table
8.2:
</em>
<p>
Uncompressed Size (unsigned 32 bit integer in big-endian byte order)
is the size of the data before it was compressed.
The compressed data has the following format when it has been
expanded:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">Uncompressed Size</td>
</tr>
<tr>
<td align="left" valign="middle">Tag</td>
<td align="left" valign="middle">Data</td>
</tr>
</table>
<em>Table
8.3:
</em>
<h3><a name="id84636">8.2
Distribution header</a></h3>
<a name="distribution_header"></a>
<p>
As of erts version 5.7.2 the old atom cache protocol was
dropped and a new one was introduced. This atom cache protocol
introduced the distribution header. Nodes with erts versions
earlier than 5.7.2 can still communicate with new nodes,
but no distribution header and no atom cache will be used.</p>
<p>
The distribution header currently only contains an atom cache
reference section, but could in the future contain more
information. The distribution header precedes one or more Erlang
terms on the external format. For more information see the
documentation of the
<span class="bold_code"><a href="erl_dist_protocol.html#connected_nodes">protocol between
connected nodes</a></span> in the
<span class="bold_code"><a href="erl_dist_protocol.html">distribution protocol</a></span>
documentation.
</p>
<p>
<span class="bold_code"><a href="#ATOM_CACHE_REF">ATOM_CACHE_REF</a></span>
entries with corresponding <span class="code">AtomCacheReferenceIndex</span> in terms
encoded on the external format following a distribution header refers
to the atom cache references made in the distribution header. The range
is 0 <= <span class="code">AtomCacheReferenceIndex</span> < 255, i.e., at most 255
different atom cache references from the following terms can be made.
</p>
<p>
The distribution header format is:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">NumberOfAtomCacheRefs/2+1 | 0</td>
<td align="left" valign="middle">N | 0</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">131</span></td>
<td align="left" valign="middle"><span class="code">68</span></td>
<td align="left" valign="middle"><span class="code">NumberOfAtomCacheRefs</span></td>
<td align="left" valign="middle"><span class="code">Flags</span></td>
<td align="left" valign="middle"><span class="code">AtomCacheRefs</span></td>
</tr>
</table>
<em>Table
8.4:
</em>
<p>
<span class="code">Flags</span> consists of <span class="code">NumberOfAtomCacheRefs/2+1</span> bytes,
unless <span class="code">NumberOfAtomCacheRefs</span> is <span class="code">0</span>. If
<span class="code">NumberOfAtomCacheRefs</span> is <span class="code">0</span>, <span class="code">Flags</span> and
<span class="code">AtomCacheRefs</span> are omitted. Each atom cache reference have
a half byte flag field. Flags corresponding to a specific
<span class="code">AtomCacheReferenceIndex</span>, are located in flag byte number
<span class="code">AtomCacheReferenceIndex/2</span>. Flag byte 0 is the first byte
after the <span class="code">NumberOfAtomCacheRefs</span> byte. Flags for an even
<span class="code">AtomCacheReferenceIndex</span> are located in the least significant
half byte and flags for an odd <span class="code">AtomCacheReferenceIndex</span> are
located in the most significant half byte.
</p>
<p>
The flag field of an atom cache reference has the following
format:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1 bit</td>
<td align="left" valign="middle">3 bits</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">NewCacheEntryFlag</span></td>
<td align="left" valign="middle"><span class="code">SegmentIndex</span></td>
</tr>
</table>
<em>Table
8.5:
</em>
<p>
The most significant bit is the <span class="code">NewCacheEntryFlag</span>. If set,
the corresponding cache reference is new. The three least
significant bits are the <span class="code">SegmentIndex</span> of the corresponding
atom cache entry. An atom cache consists of 8 segments each of size
256, i.e., an atom cache can contain 2048 entries.
</p>
<p>
After flag fields for atom cache references, another half byte flag
field is located which has the following format:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">3 bits</td>
<td align="left" valign="middle">1 bit</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">CurrentlyUnused</span></td>
<td align="left" valign="middle"><span class="code">LongAtoms</span></td>
</tr>
</table>
<em>Table
8.6:
</em>
<p>
The least significant bit in that half byte is the <span class="code">LongAtoms</span>
flag. If it is set, 2 bytes are used for atom lengths instead of
1 byte in the distribution header. However, the current emulator
cannot handle long atoms, so it will currently always be 0.
</p>
<p>
After the <span class="code">Flags</span> field follow the <span class="code">AtomCacheRefs</span>. The
first <span class="code">AtomCacheRef</span> is the one corresponding to
<span class="code">AtomCacheReferenceIndex</span> 0. Higher indices follows
in sequence up to index <span class="code">NumberOfAtomCacheRefs - 1</span>.
</p>
<p>
If the <span class="code">NewCacheEntryFlag</span> for the next <span class="code">AtomCacheRef</span> has
been set, a <span class="code">NewAtomCacheRef</span> on the following format will follow:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1 | 2</td>
<td align="left" valign="middle">Length</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">InternalSegmentIndex</span></td>
<td align="left" valign="middle"><span class="code">Length</span></td>
<td align="left" valign="middle"><span class="code">AtomText</span></td>
</tr>
</table>
<em>Table
8.7:
</em>
<p>
<span class="code">InternalSegmentIndex</span> together with the <span class="code">SegmentIndex</span>
completely identify the location of an atom cache entry in the
atom cache. <span class="code">Length</span> is number of one byte characters that
the atom text consists of. Length is a two byte big endian integer
if the <span class="code">LongAtoms</span> flag has been set, otherwise a one byte
integer. Subsequent <span class="code">CachedAtomRef</span>s with the same
<span class="code">SegmentIndex</span> and <span class="code">InternalSegmentIndex</span> as this
<span class="code">NewAtomCacheRef</span> will refer to this atom until a new
<span class="code">NewAtomCacheRef</span> with the same <span class="code">SegmentIndex</span>
and <span class="code">InternalSegmentIndex</span> appear.
</p>
<p>
If the <span class="code">NewCacheEntryFlag</span> for the next <span class="code">AtomCacheRef</span>
has not been set, a <span class="code">CachedAtomRef</span> on the following format
will follow:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">InternalSegmentIndex</span></td>
</tr>
</table>
<em>Table
8.8:
</em>
<p>
<span class="code">InternalSegmentIndex</span> together with the <span class="code">SegmentIndex</span>
identify the location of the atom cache entry in the atom cache.
The atom corresponding to this <span class="code">CachedAtomRef</span> is the
latest <span class="code">NewAtomCacheRef</span> preceding this <span class="code">CachedAtomRef</span>
in another previously passed distribution header.
</p>
<h3><a name="id85209">8.3
ATOM_CACHE_REF</a></h3>
<a name="ATOM_CACHE_REF"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">82</span></td>
<td align="left" valign="middle"><span class="code">AtomCacheReferenceIndex</span></td>
</tr>
</table>
<em>Table
8.9:
</em>
<p>
Refers to the atom with <span class="code">AtomCacheReferenceIndex</span> in the
<span class="bold_code"><a href="#distribution_header">distribution header</a></span>.
</p>
<h3><a name="id85285">8.4
SMALL_INTEGER_EXT</a></h3>
<a name="SMALL_INTEGER_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
</tr>
<tr>
<td align="left" valign="middle">97</td>
<td align="left" valign="middle">Int</td>
</tr>
</table>
<em>Table
8.10:
</em>
<p>
Unsigned 8 bit integer.
</p>
<h3><a name="id85348">8.5
INTEGER_EXT</a></h3>
<a name="INTEGER_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
</tr>
<tr>
<td align="left" valign="middle">98</td>
<td align="left" valign="middle">Int</td>
</tr>
</table>
<em>Table
8.11:
</em>
<p>
Signed 32 bit integer in big-endian format (i.e. MSB first)
</p>
<h3><a name="id85412">8.6
FLOAT_EXT</a></h3>
<a name="FLOAT_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">31</td>
</tr>
<tr>
<td align="left" valign="middle">99</td>
<td align="left" valign="middle">Float String</td>
</tr>
</table>
<em>Table
8.12:
</em>
<p>
A float is stored in string format. the format used in sprintf to
format the float is "%.20e"
(there are more bytes allocated than necessary).
To unpack the float use sscanf with format "%lf".
</p>
<p>
This term is used in minor version 0 of the external format;
it has been superseded by
<span class="bold_code"><a href="#NEW_FLOAT_EXT">
NEW_FLOAT_EXT
</a></span>.
</p>
<h3><a name="id85488">8.7
ATOM_EXT</a></h3>
<a name="ATOM_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">2</td>
<td align="left" valign="middle">Len</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">100</span></td>
<td align="left" valign="middle"><span class="code">Len</span></td>
<td align="left" valign="middle"><span class="code">AtomName</span></td>
</tr>
</table>
<em>Table
8.13:
</em>
<p>
An atom is stored with a 2 byte unsigned length in big-endian order,
followed by <span class="code">Len</span> numbers of 8 bit characters that forms the
<span class="code">AtomName</span>.
Note: The maximum allowed value for <span class="code">Len</span> is 255.
</p>
<h3><a name="id85583">8.8
REFERENCE_EXT</a></h3>
<a name="REFERENCE_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">N</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">1</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">101</span></td>
<td align="left" valign="middle"><span class="code">Node</span></td>
<td align="left" valign="middle"><span class="code">ID</span></td>
<td align="left" valign="middle"><span class="code">Creation</span></td>
</tr>
</table>
<em>Table
8.14:
</em>
<p>
Encode a reference object (an object generated with <span class="code">make_ref/0</span>).
The <span class="code">Node</span> term is an encoded atom, i.e.
<span class="bold_code"><a href="#ATOM_EXT">ATOM_EXT</a></span>,
<span class="bold_code"><a href="#SMALL_ATOM_EXT">SMALL_ATOM_EXT</a></span> or
<span class="bold_code"><a href="#ATOM_CACHE_REF">ATOM_CACHE_REF</a></span>.
The <span class="code">ID</span> field contains a big-endian
unsigned integer,
but <strong>should be regarded as uninterpreted data</strong>
since this field is node specific.
<span class="code">Creation</span> is a byte containing a node serial number that
makes it possible to separate old (crashed) nodes from a new one.
</p>
<p>
In <span class="code">ID</span>, only 18 bits are significant; the rest should be 0.
In <span class="code">Creation</span>, only 2 bits are significant; the rest should be 0.
See <span class="bold_code"><a href="#NEW_REFERENCE_EXT">NEW_REFERENCE_EXT</a></span>.
</p>
<h3><a name="id85741">8.9
PORT_EXT</a></h3>
<a name="PORT_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">N</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">1</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">102</span></td>
<td align="left" valign="middle"><span class="code">Node</span></td>
<td align="left" valign="middle"><span class="code">ID</span></td>
<td align="left" valign="middle"><span class="code">Creation</span></td>
</tr>
</table>
<em>Table
8.15:
</em>
<p>
Encode a port object (obtained form <span class="code">open_port/2</span>).
The <span class="code">ID</span> is a node specific identifier for a local port.
Port operations are not allowed across node boundaries.
The <span class="code">Creation</span> works just like in
<span class="bold_code"><a href="#REFERENCE_EXT">REFERENCE_EXT</a></span>.
</p>
<h3><a name="id85860">8.10
PID_EXT</a></h3>
<a name="PID_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">N</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">1</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">103</span></td>
<td align="left" valign="middle"><span class="code">Node</span></td>
<td align="left" valign="middle"><span class="code">ID</span></td>
<td align="left" valign="middle"><span class="code">Serial</span></td>
<td align="left" valign="middle"><span class="code">Creation</span></td>
</tr>
</table>
<em>Table
8.16:
</em>
<p>
Encode a process identifier object (obtained from <span class="code">spawn/3</span> or
friends).
The <span class="code">ID</span> and <span class="code">Creation</span> fields works just like in
<span class="bold_code"><a href="#REFERENCE_EXT">REFERENCE_EXT</a></span>, while
the <span class="code">Serial</span> field is used to improve safety.
In <span class="code">ID</span>, only 15 bits are significant; the rest should be 0.
</p>
<h3><a name="id86004">8.11
SMALL_TUPLE_EXT</a></h3>
<a name="SMALL_TUPLE_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">N</td>
</tr>
<tr>
<td align="left" valign="middle">104</td>
<td align="left" valign="middle">Arity</td>
<td align="left" valign="middle">Elements</td>
</tr>
</table>
<em>Table
8.17:
</em>
<p>
<span class="code">SMALL_TUPLE_EXT</span> encodes a tuple. The <span class="code">Arity</span>
field is an unsigned byte that determines how many element
that follows in the <span class="code">Elements</span> section.
</p>
<h3><a name="id86096">8.12
LARGE_TUPLE_EXT</a></h3>
<a name="LARGE_TUPLE_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">N</td>
</tr>
<tr>
<td align="left" valign="middle">105</td>
<td align="left" valign="middle">Arity</td>
<td align="left" valign="middle">Elements</td>
</tr>
</table>
<em>Table
8.18:
</em>
<p>
Same as
<span class="bold_code"><a href="#SMALL_TUPLE_EXT">SMALL_TUPLE_EXT</a></span>
with the exception that <span class="code">Arity</span> is an
unsigned 4 byte integer in big endian format.
</p>
<h3><a name="id86186">8.13
NIL_EXT</a></h3>
<a name="NIL_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
</tr>
<tr>
<td align="left" valign="middle">106</td>
</tr>
</table>
<em>Table
8.19:
</em>
<p>
The representation for an empty list, i.e. the Erlang syntax <span class="code">[]</span>.
</p>
<h3><a name="id86237">8.14
STRING_EXT</a></h3>
<a name="STRING_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">2</td>
<td align="left" valign="middle">Len</td>
</tr>
<tr>
<td align="left" valign="middle">107</td>
<td align="left" valign="middle">Length</td>
<td align="left" valign="middle">Characters</td>
</tr>
</table>
<em>Table
8.20:
</em>
<p>
String does NOT have a corresponding Erlang representation,
but is an optimization for sending lists of bytes (integer in
the range 0-255) more efficiently over the distribution.
Since the <span class="code">Length</span> field is an unsigned 2 byte integer
(big endian), implementations must make sure that lists longer than
65535 elements are encoded as
<span class="bold_code"><a href="#LIST_EXT">LIST_EXT</a></span>.
</p>
<h3><a name="id86329">8.15
LIST_EXT</a></h3>
<a name="LIST_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle"> </td>
<td align="left" valign="middle"> </td>
</tr>
<tr>
<td align="left" valign="middle">108</td>
<td align="left" valign="middle">Length</td>
<td align="left" valign="middle">Elements</td>
<td align="left" valign="middle">Tail</td>
</tr>
</table>
<em>Table
8.21:
</em>
<p>
<span class="code">Length</span> is the number of elements that follows in the
<span class="code">Elements</span> section. <span class="code">Tail</span> is the final tail of
the list; it is
<span class="bold_code"><a href="#NIL_EXT">NIL_EXT</a></span>
for a proper list, but may be anything type if the list is
improper (for instance <span class="code">[a|b]</span>).
</p>
<h3><a name="id86448">8.16
BINARY_EXT</a></h3>
<a name="BINARY_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">Len</td>
</tr>
<tr>
<td align="left" valign="middle">109</td>
<td align="left" valign="middle">Len</td>
<td align="left" valign="middle">Data</td>
</tr>
</table>
<em>Table
8.22:
</em>
<p>
Binaries are generated with bit syntax expression or with
<span class="bold_code"><a href="javascript:erlhref('../../../doc/../','erts','erlang.html#list_to_binary-1');">list_to_binary/1</a></span>,
<span class="bold_code"><a href="javascript:erlhref('../../../doc/../','erts','erlang.html#term_to_binary-1');">term_to_binary/1</a></span>,
or as input from binary ports.
The <span class="code">Len</span> length field is an unsigned 4 byte integer
(big endian).
</p>
<h3><a name="id86545">8.17
SMALL_BIG_EXT</a></h3>
<a name="SMALL_BIG_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">n</td>
</tr>
<tr>
<td align="left" valign="middle">110</td>
<td align="left" valign="middle">n</td>
<td align="left" valign="middle">Sign</td>
<td align="left" valign="middle">d(0) ... d(n-1)</td>
</tr>
</table>
<em>Table
8.23:
</em>
<p>
Bignums are stored in unary form with a <span class="code">Sign</span> byte
that is 0 if the binum is positive and 1 if is negative. The
digits are stored with the LSB byte stored first. To
calculate the integer the following formula can be used:<br>
B = 256<br>
(d0*B^0 + d1*B^1 + d2*B^2 + ... d(N-1)*B^(n-1))
</p>
<h3><a name="id86652">8.18
LARGE_BIG_EXT</a></h3>
<a name="LARGE_BIG_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">n</td>
</tr>
<tr>
<td align="left" valign="middle">111</td>
<td align="left" valign="middle">n</td>
<td align="left" valign="middle">Sign</td>
<td align="left" valign="middle">d(0) ... d(n-1)</td>
</tr>
</table>
<em>Table
8.24:
</em>
<p>
Same as <span class="bold_code"><a href="#SMALL_BIG_EXT">SMALL_BIG_EXT</a></span>
with the difference that the length field
is an unsigned 4 byte integer.
</p>
<h3><a name="id86755">8.19
NEW_REFERENCE_EXT</a></h3>
<a name="NEW_REFERENCE_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">2</td>
<td align="left" valign="middle">N</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">N'</td>
</tr>
<tr>
<td align="left" valign="middle">114</td>
<td align="left" valign="middle">Len</td>
<td align="left" valign="middle">Node</td>
<td align="left" valign="middle">Creation</td>
<td align="left" valign="middle">ID ...</td>
</tr>
</table>
<em>Table
8.25:
</em>
<p>
Node and Creation are as in
<span class="bold_code"><a href="#REFERENCE_EXT">REFERENCE_EXT</a></span>.
</p>
<p>
<span class="code">ID</span> contains a sequence of big-endian unsigned integers
(4 bytes each, so <span class="code">N'</span> is a multiple of 4),
but should be regarded as uninterpreted data.
</p>
<p>
<span class="code">N'</span> = 4 * <span class="code">Len</span>.
</p>
<p>
In the first word (four bytes) of <span class="code">ID</span>, only 18 bits are
significant, the rest should be 0.
In <span class="code">Creation</span>, only 2 bits are significant,
the rest should be 0.
</p>
<p>
NEW_REFERENCE_EXT was introduced with distribution version 4.
In version 4, <span class="code">N'</span> should be at most 12.
</p>
<p>
See <span class="bold_code"><a href="#REFERENCE_EXT">REFERENCE_EXT</a></span>).
</p>
<h3><a name="id86928">8.20
SMALL_ATOM_EXT</a></h3>
<a name="SMALL_ATOM_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">Len</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">115</span></td>
<td align="left" valign="middle"><span class="code">Len</span></td>
<td align="left" valign="middle"><span class="code">AtomName</span></td>
</tr>
</table>
<em>Table
8.26:
</em>
<p>
An atom is stored with a 1 byte unsigned length,
followed by <span class="code">Len</span> numbers of 8 bit characters that
forms the <span class="code">AtomName</span>. Longer atoms can be represented
by <span class="bold_code"><a href="#ATOM_EXT">ATOM_EXT</a></span>. <strong>Note</strong>
the <span class="code">SMALL_ATOM_EXT</span> was introduced in erts version 5.7.2 and
require a small atom distribution flag exchanged in the distribution
handshake.
</p>
<h3><a name="id87034">8.21
FUN_EXT</a></h3>
<a name="FUN_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">N1</td>
<td align="left" valign="middle">N2</td>
<td align="left" valign="middle">N3</td>
<td align="left" valign="middle">N4</td>
<td align="left" valign="middle">N5</td>
</tr>
<tr>
<td align="left" valign="middle">117</td>
<td align="left" valign="middle">NumFree</td>
<td align="left" valign="middle">Pid</td>
<td align="left" valign="middle">Module</td>
<td align="left" valign="middle">Index</td>
<td align="left" valign="middle">Uniq</td>
<td align="left" valign="middle">Free vars ...</td>
</tr>
</table>
<em>Table
8.27:
</em>
<dl>
<dt><strong><span class="code">Pid</span></strong></dt>
<dd>
is a process identifier as in
<span class="bold_code"><a href="#PID_EXT">PID_EXT</a></span>.
It represents the process in which the fun was created.
</dd>
<dt><strong><span class="code">Module</span></strong></dt>
<dd>
is an encoded as an atom, using
<span class="bold_code"><a href="#ATOM_EXT">ATOM_EXT</a></span>,
<span class="bold_code"><a href="#SMALL_ATOM_EXT">SMALL_ATOM_EXT</a></span>
or <span class="bold_code"><a href="#ATOM_CACHE_REF">ATOM_CACHE_REF</a></span>.
This is the module that the fun is implemented in.
</dd>
<dt><strong><span class="code">Index</span></strong></dt>
<dd>
is an integer encoded using
<span class="bold_code"><a href="#SMALL_INTEGER_EXT">SMALL_INTEGER_EXT</a></span>
or <span class="bold_code"><a href="#INTEGER_EXT">INTEGER_EXT</a></span>.
It is typically a small index into the module's fun table.
</dd>
<dt><strong><span class="code">Uniq</span></strong></dt>
<dd>
is an integer encoded using
<span class="bold_code"><a href="#SMALL_INTEGER_EXT">SMALL_INTEGER_EXT</a></span> or
<span class="bold_code"><a href="#INTEGER_EXT">INTEGER_EXT</a></span>.
<span class="code">Uniq</span> is the hash value of the parse for the fun.
</dd>
<dt><strong><span class="code">Free vars</span></strong></dt>
<dd>
is <span class="code">NumFree</span> number of terms, each one encoded according
to its type.
</dd>
</dl>
<h3><a name="id87281">8.22
NEW_FUN_EXT</a></h3>
<a name="NEW_FUN_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">16</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">N1</td>
<td align="left" valign="middle">N2</td>
<td align="left" valign="middle">N3</td>
<td align="left" valign="middle">N4</td>
<td align="left" valign="middle">N5</td>
</tr>
<tr>
<td align="left" valign="middle">112</td>
<td align="left" valign="middle">Size</td>
<td align="left" valign="middle">Arity</td>
<td align="left" valign="middle">Uniq</td>
<td align="left" valign="middle">Index</td>
<td align="left" valign="middle">NumFree</td>
<td align="left" valign="middle">Module</td>
<td align="left" valign="middle">OldIndex</td>
<td align="left" valign="middle">OldUniq</td>
<td align="left" valign="middle">Pid</td>
<td align="left" valign="middle">Free Vars</td>
</tr>
</table>
<em>Table
8.28:
</em>
<p>
This is the new encoding of internal funs: <span class="code">fun F/A</span> and
<span class="code">fun(Arg1,..) -> ... end</span>.
</p>
<dl>
<dt><strong><span class="code">Size</span></strong></dt>
<dd>
is the total number of bytes, including the <span class="code">Size</span> field.
</dd>
<dt><strong><span class="code">Arity</span></strong></dt>
<dd>
is the arity of the function implementing the fun.
</dd>
<dt><strong><span class="code">Uniq</span></strong></dt>
<dd>
is the 16 bytes MD5 of the significant parts of the Beam file.
</dd>
<dt><strong><span class="code">Index</span></strong></dt>
<dd>
is an index number. Each fun within a module has an unique
index. <span class="code">Index</span> is stored in big-endian byte order.
</dd>
<dt><strong><span class="code">NumFree</span></strong></dt>
<dd>
is the number of free variables.
</dd>
<dt><strong><span class="code">Module</span></strong></dt>
<dd>
is an encoded as an atom, using
<span class="bold_code"><a href="#ATOM_EXT">ATOM_EXT</a></span>,
<span class="bold_code"><a href="#SMALL_ATOM_EXT">SMALL_ATOM_EXT</a></span> or
<span class="bold_code"><a href="#ATOM_CACHE_REF">ATOM_CACHE_REF</a></span>.
This is the module that the fun is implemented in.
</dd>
<dt><strong><span class="code">OldIndex</span></strong></dt>
<dd>
is an integer encoded using
<span class="bold_code"><a href="#SMALL_INTEGER_EXT">SMALL_INTEGER_EXT</a></span>
or <span class="bold_code"><a href="#INTEGER_EXT">INTEGER_EXT</a></span>.
It is typically a small index into the module's fun table.
</dd>
<dt><strong><span class="code">OldUniq</span></strong></dt>
<dd>
is an integer encoded using
<span class="bold_code"><a href="#SMALL_INTEGER_EXT">SMALL_INTEGER_EXT</a></span>
or
<span class="bold_code"><a href="#INTEGER_EXT">INTEGER_EXT</a></span>.
<span class="code">Uniq</span> is the hash value of the parse tree for the fun.
</dd>
<dt><strong><span class="code">Pid</span></strong></dt>
<dd>
is a process identifier as in
<span class="bold_code"><a href="#PID_EXT">PID_EXT</a></span>.
It represents the process in which
the fun was created.
</dd>
<dt><strong><span class="code">Free vars</span></strong></dt>
<dd>
is <span class="code">NumFree</span> number of terms, each one encoded according
to its type.
</dd>
</dl>
<h3><a name="id87658">8.23
EXPORT_EXT</a></h3>
<a name="EXPORT_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">N1</td>
<td align="left" valign="middle">N2</td>
<td align="left" valign="middle">N3</td>
</tr>
<tr>
<td align="left" valign="middle">113</td>
<td align="left" valign="middle">Module</td>
<td align="left" valign="middle">Function</td>
<td align="left" valign="middle">Arity</td>
</tr>
</table>
<em>Table
8.29:
</em>
<p>
This term is the encoding for external funs: <span class="code">fun M:F/A</span>.
</p>
<p>
<span class="code">Module</span> and <span class="code">Function</span> are atoms
(encoded using <span class="bold_code"><a href="#ATOM_EXT">ATOM_EXT</a></span>,
<span class="bold_code"><a href="#SMALL_ATOM_EXT">SMALL_ATOM_EXT</a></span> or
<span class="bold_code"><a href="#ATOM_CACHE_REF">ATOM_CACHE_REF</a></span>).
</p>
<p>
<span class="code">Arity</span> is an integer encoded using
<span class="bold_code"><a href="#SMALL_INTEGER_EXT">SMALL_INTEGER_EXT</a></span>.
</p>
<h3><a name="id87802">8.24
BIT_BINARY_EXT</a></h3>
<a name="BIT_BINARY_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">4</td>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">Len</td>
</tr>
<tr>
<td align="left" valign="middle">77</td>
<td align="left" valign="middle">Len</td>
<td align="left" valign="middle">Bits</td>
<td align="left" valign="middle">Data</td>
</tr>
</table>
<em>Table
8.30:
</em>
<p>
This term represents a bitstring whose length in bits is not a
multiple of 8 (created using the bit syntax in R12B and later).
The <span class="code">Len</span> field is an unsigned 4 byte integer (big endian).
The <span class="code">Bits</span> field is the number of bits that are used
in the last byte in the data field,
counting from the most significant bit towards the least
significant.
</p>
<h3><a name="id87908">8.25
NEW_FLOAT_EXT</a></h3>
<a name="NEW_FLOAT_EXT"></a>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">1</td>
<td align="left" valign="middle">8</td>
</tr>
<tr>
<td align="left" valign="middle">70</td>
<td align="left" valign="middle">IEEE float</td>
</tr>
</table>
<em>Table
8.31:
</em>
<p>
A float is stored as 8 bytes in big-endian IEEE format.
</p>
<p>
This term is used in minor version 1 of the external format.
</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
168
