<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:erl="http://erlang.org" 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 -- Erl_Interface User's Guide</title>
</head>
<body>
<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">
<div class="erlang-logo-wrapper"><a href="../../../../doc/index.html"><img alt="Erlang Logo" src="../../../../doc/erlang-logo.png" class="erlang-logo"></a></div>
<p class="section-title">Erl_Interface</p>
<p class="section-subtitle">User's Guide</p>
<p class="section-version">Version 3.10.4</p>
<ul class="panel-sections">
<li><a href="users_guide.html">User's Guide</a></li>
<li><a href="index.html">Reference Manual</a></li>
<li><a href="release_notes.html">Release Notes</a></li>
<li><a href="../pdf/erl_interface-3.10.4.pdf">PDF</a></li>
<li><a href="../../../../doc/index.html">Top</a></li>
</ul>
<ul class="expand-collapse-items">
<li><a href="javascript:openAllFlips()">Expand All</a></li>
<li><a href="javascript:closeAllFlips()">Contract All</a></li>
</ul>
<h3>Chapters</h3>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu"><li id="loadscrollpos" title="Erl_Interface User's Guide" expanded="true">Erl_Interface User's Guide<ul>
<li><a href="ei_users_guide.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ei_users_guide.html#introduction">Introduction</a></li>
<li title="Compiling and Linking Your Code"><a href="ei_users_guide.html#compiling-and-linking-your-code">Compiling and Linking Your Code</a></li>
<li title="Initializing the Erl_Interface Library"><a href="ei_users_guide.html#initializing-the-erl_interface-library">Initializing the Erl_Interface Library</a></li>
<li title="Encoding, Decoding, and Sending Erlang Terms"><a href="ei_users_guide.html#encoding,-decoding,-and-sending-erlang-terms">Encoding, Decoding, and Sending Erlang Terms</a></li>
<li title="Building Terms and Patterns"><a href="ei_users_guide.html#building-terms-and-patterns">Building Terms and Patterns</a></li>
<li title="Pattern Matching"><a href="ei_users_guide.html#pattern-matching">Pattern Matching</a></li>
<li title="Connecting to a Distributed Erlang Node"><a href="ei_users_guide.html#connecting-to-a-distributed-erlang-node">Connecting to a Distributed Erlang Node</a></li>
<li title="Using EPMD"><a href="ei_users_guide.html#using-epmd">Using EPMD</a></li>
<li title="Sending and Receiving Erlang Messages"><a href="ei_users_guide.html#sending-and-receiving-erlang-messages">Sending and Receiving Erlang Messages</a></li>
<li title="Remote Procedure Calls"><a href="ei_users_guide.html#remote-procedure-calls">Remote Procedure Calls</a></li>
<li title="Using Global Names"><a href="ei_users_guide.html#using-global-names">Using Global Names</a></li>
<li title="Using the Registry"><a href="ei_users_guide.html#using-the-registry">Using the Registry</a></li>
</ul>
</li></ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>1 Erl_Interface User's Guide</h1>
<h3><span onMouseOver="document.getElementById('ghlink-introduction-idm281473478025400').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-introduction-idm281473478025400').style.visibility = 'hidden';"><span id="ghlink-introduction-idm281473478025400" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L36" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="introduction" href="#introduction">1.1
Introduction</a></span></h3>
<p>The <span class="code">Erl_Interface</span> library contains functions that help you
integrate programs written in C and Erlang. The functions in
<span class="code">Erl_Interface</span> support the following:</p>
<ul>
<li>Manipulation of data represented as Erlang data types</li>
<li>Conversion of data between C and Erlang formats</li>
<li>Encoding and decoding of Erlang data types for transmission or
storage</li>
<li>Communication between C nodes and Erlang processes</li>
<li>Backup and restore of C node state to and from
<span class="bold_code bc-18"><a href="javascript:erlhref('../../../../doc/../','mnesia','mnesia.html');">Mnesia</a></span>
</li>
</ul>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>By default, the <span class="code">Erl_Interface</span> libraries are only guaranteed
to be compatible with other Erlang/OTP components from the same
release as the libraries themselves. For information about how to
communicate with Erlang/OTP components from earlier releases, see
function <span class="bold_code bc-15"><a href="ei.html#ei_set_compat_rel"><span class="code">ei:ei_set_compat_rel</span></a></span> and
<span class="bold_code bc-15"><a href="erl_eterm.html#erl_set_compat_rel"><span class="code">erl_eterm:erl_set_compat_rel</span></a></span>.</p>
</p></div>
</div>
<h4><span onMouseOver="document.getElementById('ghlink-scope-idm281473478034712').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-scope-idm281473478034712').style.visibility = 'hidden';"><span id="ghlink-scope-idm281473478034712" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L61" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="scope" href="#scope">Scope</a></span></h4>
<p>In the following sections, these topics are described:</p>
<ul>
<li>Compiling your code for use with <span class="code">Erl_Interface</span>
</li>
<li>Initializing <span class="code">Erl_Interface</span>
</li>
<li>Encoding, decoding, and sending Erlang terms</li>
<li>Building terms and patterns</li>
<li>Pattern matching</li>
<li>Connecting to a distributed Erlang node</li>
<li>Using the Erlang Port Mapper Daemon (EPMD)</li>
<li>Sending and receiving Erlang messages</li>
<li>Remote procedure calls</li>
<li>Using global names</li>
<li>Using the registry</li>
</ul>
<h4><span onMouseOver="document.getElementById('ghlink-prerequisites-idm281473478044712').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-prerequisites-idm281473478044712').style.visibility = 'hidden';"><span id="ghlink-prerequisites-idm281473478044712" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L79" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="prerequisites" href="#prerequisites">Prerequisites</a></span></h4>
<p>It is assumed that the reader is familiar with the Erlang programming
language.</p>
<h3><span onMouseOver="document.getElementById('ghlink-compiling-and-linking-your-code-idm281473478046024').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-compiling-and-linking-your-code-idm281473478046024').style.visibility = 'hidden';"><span id="ghlink-compiling-and-linking-your-code-idm281473478046024" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L86" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="compiling-and-linking-your-code" href="#compiling-and-linking-your-code">1.2
Compiling and Linking Your Code</a></span></h3>
<p>To use any of the <span class="code">Erl_Interface</span> functions, include the
following lines in your code:</p>
<div class="example"><pre>#include "erl_interface.h"
#include "ei.h" </pre></div>
<p>Determine where the top directory of your OTP installation is.
To find this, start Erlang and enter the following
command at the Eshell prompt:</p>
<div class="example"><pre>Eshell V4.7.4 (abort with ^G)
1> code:root_dir().
/usr/local/otp </pre></div>
<p>To compile your code, ensure that your C compiler knows where
to find <span class="code">erl_interface.h</span> by specifying an appropriate
<span class="code">-I</span> argument on the command line, or add it to
the <span class="code">CFLAGS</span> definition in your
<span class="code">Makefile</span>. The correct value for this path is
<span class="code">$OTPROOT/lib/erl_interface-$EIVSN/include</span>,
where:</p>
<ul>
<li>
<p><span class="code">$OTPROOT</span> is the path reported by
<span class="code">code:root_dir/0</span> in the example above.</p>
</li>
<li>
<p><span class="code">$EIVSN</span> is the version of the <span class="code">Erl_Interface</span> application,
for example, <span class="code">erl_interface-3.2.3</span>.</p>
</li>
</ul>
<p>Compiling the code:</p>
<div class="example"><pre>$ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c </pre></div>
<p>When linking:</p>
<ul>
<li>Specify the path to <span class="code">liberl_interface.a</span> and
<span class="code">libei.a</span> with
<span class="code">-L$OTPROOT/lib/erl_interface-3.2.3/lib</span>.</li>
<li>Specify the name of the libraries with
<span class="code">-lerl_interface -lei</span>.</li>
</ul>
<p>Do this on the command line or add the flags to the
<span class="code">LDFLAGS</span> definition in your
<span class="code">Makefile</span>.</p>
<p>Linking the code:</p>
<div class="example"><pre>$ ld -L/usr/local/otp/lib/erl_interface-3.2.3/
lib myprog.o -lerl_interface -lei -o myprog </pre></div>
<p>On some systems it can be necessary to link with some more
libraries (for example, <span class="code">libnsl.a</span> and
<span class="code">libsocket.a</span> on Solaris, or
<span class="code">wsock32.lib</span> on Windows) to use the
communication facilities of <span class="code">Erl_Interface</span>.</p>
<p>If you use the <span class="code">Erl_Interface</span> functions in a threaded
application based on POSIX threads or Solaris threads, then
<span class="code">Erl_Interface</span> needs access to some of the synchronization
facilities in your threads package. You must specify extra
compiler flags to indicate which of the packages you use. Define
<span class="code">_REENTRANT</span> and either <span class="code">STHREADS</span> or
<span class="code">PTHREADS</span>. The default is to use POSIX threads if
<span class="code">_REENTRANT</span> is specified.</p>
<h3><span onMouseOver="document.getElementById('ghlink-initializing-the-erl_interface-library-idm281473478072344').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-initializing-the-erl_interface-library-idm281473478072344').style.visibility = 'hidden';"><span id="ghlink-initializing-the-erl_interface-library-idm281473478072344" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L164" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="initializing-the-erl_interface-library" href="#initializing-the-erl_interface-library">1.3
Initializing the Erl_Interface Library</a></span></h3>
<p>Before calling any of the other <span class="code">Erl_Interface</span> functions, call
<span class="code">erl_init()</span> exactly once to initialize the library.
<span class="code">erl_init()</span> takes two arguments. However, the arguments
are no longer used by <span class="code">Erl_Interface</span> and are therefore to be
specified as <span class="code">erl_init(NULL,0)</span>.</p>
<h3><span onMouseOver="document.getElementById('ghlink-encoding,-decoding,-and-sending-erlang-terms-idm281473478075096').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-encoding,-decoding,-and-sending-erlang-terms-idm281473478075096').style.visibility = 'hidden';"><span id="ghlink-encoding,-decoding,-and-sending-erlang-terms-idm281473478075096" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L173" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="encoding,-decoding,-and-sending-erlang-terms" href="#encoding,-decoding,-and-sending-erlang-terms">1.4
Encoding, Decoding, and Sending Erlang Terms</a></span></h3>
<p>Data sent between distributed Erlang nodes is encoded in the
Erlang external format. You must therefore encode and decode
Erlang terms into byte streams if you want to use the distribution
protocol to communicate between a C program and Erlang.</p>
<p>The <span class="code">Erl_Interface</span> library supports this activity. It has
several C functions that create and manipulate Erlang data
structures. The library also contains an encode and a decode function.
The following example shows how to create and encode an Erlang tuple
<span class="code">{tobbe,3928}</span>:</p>
<div class="example"><pre>ETERM *arr[2], *tuple;
char buf[BUFSIZ];
int i;
arr[0] = erl_mk_atom("tobbe");
arr[1] = erl_mk_integer(3928);
tuple = erl_mk_tuple(arr, 2);
i = erl_encode(tuple, buf); </pre></div>
<p>Alternatively, you can use <span class="code">erl_send()</span> and
<span class="code">erl_receive_msg</span>, which handle the encoding and
decoding of messages transparently.</p>
<p>For a complete description, see the following modules:</p>
<ul>
<li>
<span class="bold_code bc-19"><a href="erl_eterm.html"><span class="code">erl_eterm</span></a></span>
for creating Erlang terms</li>
<li>
<span class="bold_code bc-19"><a href="erl_marshal.html"><span class="code">erl_marshal</span></a></span>
for encoding and decoding routines</li>
</ul>
<h3>
<a name="building_terms_and_patterns"></a><span onMouseOver="document.getElementById('ghlink-building-terms-and-patterns-idm281473478085752').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-building-terms-and-patterns-idm281473478085752').style.visibility = 'hidden';"><span id="ghlink-building-terms-and-patterns-idm281473478085752" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L209" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="building-terms-and-patterns" href="#building-terms-and-patterns">1.5
Building Terms and Patterns</a></span>
</h3>
<p>The previous example can be simplified by using the
<span class="bold_code bc-19"><a href="erl_format.html"><span class="code">erl_format</span></a></span> module
to create an Erlang term:</p>
<div class="example"><pre>ETERM *ep;
ep = erl_format("{~a,~i}", "tobbe", 3928); </pre></div>
<p>For a complete description of the different format directives, see
the <span class="bold_code bc-19"><a href="erl_format.html"><span class="code">erl_format</span></a></span> module.</p>
<p>The following example is more complex:</p>
<div class="example"><pre>ETERM *ep;
ep = erl_format("[{name,~a},{age,~i},{data,~w}]",
"madonna",
21,
erl_format("[{adr,~s,~i}]", "E-street", 42));
erl_free_compound(ep); </pre></div>
<p>As in the previous examples, it is your responsibility to free the
memory allocated for Erlang terms. In this example,
<span class="code">erl_free_compound()</span> ensures that the complete term
pointed to by <span class="code">ep</span> is released. This is necessary
because the pointer from the second call to <span class="code">erl_format</span> is lost.</p>
<p>The following example shows a slightly different solution:</p>
<div class="example"><pre>ETERM *ep,*ep2;
ep2 = erl_format("[{adr,~s,~i}]","E-street",42);
ep = erl_format("[{name,~a},{age,~i},{data,~w}]",
"madonna", 21, ep2);
erl_free_term(ep);
erl_free_term(ep2); </pre></div>
<p>In this case, you free the two terms independently. The order in
which you free the terms <span class="code">ep</span> and <span class="code">ep2</span>
is not important,
because the <span class="code">Erl_Interface</span> library uses reference counting to
determine when it is safe to remove objects.</p>
<p>If you are unsure whether you have freed the terms properly, you
can use the following function to see the status of the fixed term
allocator:</p>
<div class="example"><pre>long allocated, freed;
erl_eterm_statistics(&allocated,&freed);
printf("currently allocated blocks: %ld\n",allocated);
printf("length of freelist: %ld\n",freed);
/* really free the freelist */
erl_eterm_release();</pre></div>
<p>For more information, see the
<span class="bold_code bc-19"><a href="erl_malloc.html"><span class="code">erl_malloc</span></a></span> module.</p>
<h3><span onMouseOver="document.getElementById('ghlink-pattern-matching-idm281473478097336').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-pattern-matching-idm281473478097336').style.visibility = 'hidden';"><span id="ghlink-pattern-matching-idm281473478097336" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L274" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="pattern-matching" href="#pattern-matching">1.6
Pattern Matching</a></span></h3>
<p>An Erlang pattern is a term that can contain unbound variables or
<span class="code">"do not care"</span> symbols. Such a pattern can be matched
against a
term and, if the match is successful, any unbound variables in the
pattern will be bound as a side effect. The content of a bound
variable can then be retrieved:</p>
<div class="example"><pre>ETERM *pattern;
pattern = erl_format("{madonna,Age,_}"); </pre></div>
<p>The <span class="bold_code bc-15"><a href="erl_format.html#erl_match"><span class="code">erl_format:erl_match</span></a></span> function
performs pattern matching. It takes a
pattern and a term and tries to match them. As a side effect any unbound
variables in the pattern will be bound. In the following example, a
pattern is created with a variable <span class="code">Age</span>, which is included at two
positions in the tuple. The pattern match is performed as follows:</p>
<ul>
<li>
<p><span class="code">erl_match</span> binds the contents of <span class="code">Age</span> to <span class="code">21</span>
the first time it reaches the variable.</p>
</li>
<li>
<p>The second occurrence of <span class="code">Age</span> causes a test for
equality between the terms, as <span class="code">Age</span> is already bound to
<span class="code">21</span>. As <span class="code">Age</span> is bound to <span class="code">21</span>, the equality test
succeeds and the match continues until the end of the pattern.</p>
</li>
<li>
<p>If the end of the pattern is reached, the match succeeds and you
can retrieve the contents of the variable.</p>
</li>
</ul>
<div class="example"><pre>ETERM *pattern,*term;
pattern = erl_format("{madonna,Age,Age}");
term = erl_format("{madonna,21,21}");
if (erl_match(pattern, term)) {
fprintf(stderr, "Yes, they matched: Age = ");
ep = erl_var_content(pattern, "Age");
erl_print_term(stderr, ep);
fprintf(stderr,"\n");
erl_free_term(ep);
}
erl_free_term(pattern);
erl_free_term(term); </pre></div>
<p>For more information, see the
<span class="bold_code bc-15"><a href="erl_format.html#erl_match"><span class="code">erl_format:erl_match</span></a></span> function.</p>
<h3><span onMouseOver="document.getElementById('ghlink-connecting-to-a-distributed-erlang-node-idm281473478111432').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-connecting-to-a-distributed-erlang-node-idm281473478111432').style.visibility = 'hidden';"><span id="ghlink-connecting-to-a-distributed-erlang-node-idm281473478111432" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L331" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="connecting-to-a-distributed-erlang-node" href="#connecting-to-a-distributed-erlang-node">1.7
Connecting to a Distributed Erlang Node</a></span></h3>
<p>To connect to a distributed Erlang node, you must first
initialize the connection routine with
<span class="bold_code bc-15"><a href="erl_connect.html#erl_connect_init"><span class="code">erl_connect:erl_connect_init</span></a></span>,
which stores information, such as the hostname, node name, and IP
address for later use:</p>
<div class="example"><pre>int identification_number = 99;
int creation=1;
char *cookie="a secret cookie string"; /* An example */
erl_connect_init(identification_number, cookie, creation); </pre></div>
<p>For more information, see the
<span class="bold_code bc-19"><a href="erl_connect.html"><span class="code">erl_connect</span></a></span> module.</p>
<p>After initialization, you set up the connection to the Erlang node.
To specify the Erlang node you want to connect to, use
<span class="code">erl_connect()</span>. The following example sets up the
connection and is to result in a valid socket file descriptor:</p>
<div class="example"><pre>int sockfd;
char *nodename="xyz@chivas.du.etx.ericsson.se"; /* An example */
if ((sockfd = erl_connect(nodename)) < 0)
erl_err_quit("ERROR: erl_connect failed"); </pre></div>
<p><span class="code">erl_err_quit()</span> prints the specified string and
terminates the program. For more information, see the
<span class="bold_code bc-19"><a href="erl_error.html"><span class="code">erl_error</span></a></span> module.</p>
<h3><span onMouseOver="document.getElementById('ghlink-using-epmd-idm281473478423736').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-using-epmd-idm281473478423736').style.visibility = 'hidden';"><span id="ghlink-using-epmd-idm281473478423736" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L365" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="using-epmd" href="#using-epmd">1.8
Using EPMD</a></span></h3>
<p><span class="bold_code bc-18"><a href="javascript:erlhref('../../../../doc/../','erts','epmd.html');"><span class="code">erts:epmd</span></a></span>
is the Erlang Port Mapper Daemon. Distributed
Erlang nodes register with <span class="code">epmd</span> on the local host to
indicate to other nodes that they exist and can accept connections.
<span class="code">epmd</span> maintains a register of
node and port number information, and when a node wishes to connect to
another node, it first contacts <span class="code">epmd</span> to find the
correct port number to connect to.</p>
<p>When you use
<span class="bold_code bc-19"><a href="erl_connect.html"><span class="code">erl_connect</span></a></span>
to connect to an Erlang node, a connection is first made to
<span class="code">epmd</span> and, if the node is known, a
connection is then made to the Erlang node.</p>
<p>C nodes can also register themselves with <span class="code">epmd</span>
if they want other
nodes in the system to be able to find and connect to them.</p>
<p>Before registering with <span class="code">epmd</span>, you must first
create a listen socket and bind it to a port. Then:</p>
<div class="example"><pre>int pub;
pub = erl_publish(port); </pre></div>
<p><span class="code">pub</span> is a file descriptor now connected to
<span class="code">epmd</span>. <span class="code">epmd</span>
monitors the other end of the connection. If it detects that the
connection has been closed, the node becomes unregistered. So, if you
explicitly close the descriptor or if your node fails, it becomes
unregistered from <span class="code">epmd</span>.</p>
<p>Notice that on some systems (such as VxWorks), a failed node is
not detected by this mechanism, as the operating system does not
automatically close descriptors that were left open when the node
failed. If a node has failed in this way, <span class="code">epmd</span>
prevents you from
registering a new node with the old name, as it thinks that the old
name is still in use. In this case, you must unregister the name
explicitly:</p>
<div class="example"><pre>erl_unpublish(node); </pre></div>
<p>This causes <span class="code">epmd</span> to close the connection from the
far end. Notice
that if the name was in fact still in use by a node, the results of
this operation are unpredictable. Also, doing this does not cause the
local end of the connection to close, so resources can be consumed.</p>
<h3><span onMouseOver="document.getElementById('ghlink-sending-and-receiving-erlang-messages-idm281473478435784').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-sending-and-receiving-erlang-messages-idm281473478435784').style.visibility = 'hidden';"><span id="ghlink-sending-and-receiving-erlang-messages-idm281473478435784" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L420" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="sending-and-receiving-erlang-messages" href="#sending-and-receiving-erlang-messages">1.9
Sending and Receiving Erlang Messages</a></span></h3>
<p>Use one of the following two functions to send messages:</p>
<ul>
<li><span class="bold_code bc-15"><a href="erl_connect.html#erl_send"><span class="code">erl_connect:erl_send</span></a></span></li>
<li><span class="bold_code bc-15"><a href="erl_connect.html#erl_reg_send"><span class="code">erl_connect:erl_reg_send</span></a></span></li>
</ul>
<p>As in Erlang, messages can be sent to a
pid or to a registered name. It is easier to send a
message to a registered name, as it avoids the problem of finding
a suitable pid.</p>
<p>Use one of the following two functions to receive messages:</p>
<ul>
<li><span class="bold_code bc-15"><a href="erl_connect.html#erl_receive"><span class="code">erl_connect:erl_receive</span></a></span></li>
<li><span class="bold_code bc-15"><a href="erl_connect.html#erl_receive_msg"><span class="code">erl_connect:erl_receive_msg</span></a></span></li>
</ul>
<p><span class="code">erl_receive()</span> receives the message into a buffer,
while <span class="code">erl_receive_msg()</span> decodes the message into an
Erlang term.</p>
<h4><span onMouseOver="document.getElementById('ghlink-example-of-sending-messages-idm281473478692568').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-example-of-sending-messages-idm281473478692568').style.visibility = 'hidden';"><span id="ghlink-example-of-sending-messages-idm281473478692568" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L449" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="example-of-sending-messages" href="#example-of-sending-messages">Example of Sending Messages</a></span></h4>
<p>In the following example, <span class="code">{Pid, hello_world}</span> is
sent to a registered process <span class="code">my_server</span>. The message
is encoded by <span class="code">erl_send()</span>:</p>
<div class="example"><pre>extern const char *erl_thisnodename(void);
extern short erl_thiscreation(void);
#define SELF(fd) erl_mk_pid(erl_thisnodename(),fd,0,erl_thiscreation())
ETERM *arr[2], *emsg;
int sockfd, creation=1;
arr[0] = SELF(sockfd);
arr[1] = erl_mk_atom("Hello world");
emsg = erl_mk_tuple(arr, 2);
erl_reg_send(sockfd, "my_server", emsg);
erl_free_term(emsg); </pre></div>
<p>The first element of the tuple that is sent is your own
pid. This enables <span class="code">my_server</span> to reply.
For more information about the primitives, see the
<span class="bold_code bc-19"><a href="erl_connect.html"><span class="code">erl_connect</span></a></span> module.</p>
<h4><span onMouseOver="document.getElementById('ghlink-example-of-receiving-messages-idm281473478698808').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-example-of-receiving-messages-idm281473478698808').style.visibility = 'hidden';"><span id="ghlink-example-of-receiving-messages-idm281473478698808" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L475" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="example-of-receiving-messages" href="#example-of-receiving-messages">Example of Receiving Messages</a></span></h4>
<p>In this example, <span class="code">{Pid, Something}</span> is received. The
received pid is then used to return
<span class="code">{goodbye,Pid}</span>.</p>
<div class="example"><pre>ETERM *arr[2], *answer;
int sockfd,rc;
char buf[BUFSIZE];
ErlMessage emsg;
if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) {
arr[0] = erl_mk_atom("goodbye");
arr[1] = erl_element(1, emsg.msg);
answer = erl_mk_tuple(arr, 2);
erl_send(sockfd, arr[1], answer);
erl_free_term(answer);
erl_free_term(emsg.msg);
erl_free_term(emsg.to);
} </pre></div>
<p>To provide robustness, a distributed Erlang node
occasionally polls all its connected neighbors in an attempt to
detect failed nodes or communication links. A node that receives such
a message is expected to respond immediately with an
<span class="code">ERL_TICK</span> message. This is done automatically by
<span class="code">erl_receive()</span>. However, when this has occurred,
<span class="code">erl_receive</span> returns <span class="code">ERL_TICK</span> to
the caller without storing a message into the
<span class="code">ErlMessage</span> structure.</p>
<p>When a message has been received, it is the caller's responsibility
to free the received message <span class="code">emsg.msg</span> and
<span class="code">emsg.to</span> or <span class="code">emsg.from</span>,
depending on the type of message received.</p>
<p>For more information, see the
<span class="bold_code bc-19"><a href="erl_connect.html"><span class="code">erl_connect</span></a></span> and
<span class="bold_code bc-19"><a href="erl_eterm.html"><span class="code">erl_eterm</span></a></span> modules.</p>
<h3><span onMouseOver="document.getElementById('ghlink-remote-procedure-calls-idm281473478197800').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-remote-procedure-calls-idm281473478197800').style.visibility = 'hidden';"><span id="ghlink-remote-procedure-calls-idm281473478197800" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L518" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="remote-procedure-calls" href="#remote-procedure-calls">1.10
Remote Procedure Calls</a></span></h3>
<p>An Erlang node acting as a client to another Erlang node
typically sends a request and waits for a reply. Such a request is
included in a function call at a remote node and is called a remote
procedure call.</p>
<p>The following example shows how the
<span class="code">Erl_Interface</span> library supports remote procedure calls:</p>
<div class="example"><pre>char modname[]=THE_MODNAME;
ETERM *reply,*ep;
ep = erl_format("[~a,[]]", modname);
if (!(reply = erl_rpc(fd, "c", "c", ep)))
erl_err_msg("<ERROR> when compiling file: %s.erl !\n", modname);
erl_free_term(ep);
ep = erl_format("{ok,_}");
if (!erl_match(ep, reply))
erl_err_msg("<ERROR> compiler errors !\n");
erl_free_term(ep);
erl_free_term(reply); </pre></div>
<p><span class="code">c:c/1</span> is called to compile the specified module on
the remote node. <span class="code">erl_match()</span> checks that the
compilation was
successful by testing for the expected <span class="code">ok</span>.</p>
<p>For more information about <span class="code">erl_rpc()</span> and its
companions <span class="code">erl_rpc_to()</span> and
<span class="code">erl_rpc_from()</span>, see the
<span class="bold_code bc-19"><a href="erl_connect.html"><span class="code">erl_connect</span></a></span> module.</p>
<h3><span onMouseOver="document.getElementById('ghlink-using-global-names-idm281473478204840').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-using-global-names-idm281473478204840').style.visibility = 'hidden';"><span id="ghlink-using-global-names-idm281473478204840" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L552" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="using-global-names" href="#using-global-names">1.11
Using Global Names</a></span></h3>
<p>A C node has access to names registered through the
<span class="bold_code bc-18"><a href="javascript:erlhref('../../../../doc/../','kernel','global.html');"><span class="code">global</span></a></span>
module in Kernel. Names can be looked up, allowing the C node to send messages
to named Erlang services. C nodes can also register global names,
allowing them to provide named services to Erlang processes or other C
nodes.</p>
<p><span class="code">Erl_Interface</span> does not provide a native implementation of the
global service. Instead it uses the global services provided by a "nearby"
Erlang node. To use the services described in this section,
it is necessary to first open a connection to an Erlang node.</p>
<p>To see what names there are:</p>
<div class="example"><pre>char **names;
int count;
int i;
names = erl_global_names(fd,&count);
if (names)
for (i=0; i<count; i++)
printf("%s\n",names[i]);
free(names); </pre></div>
<p><span class="bold_code bc-15"><a href="erl_global.html#erl_global_names"><span class="code">erl_global:erl_global_names</span></a></span>
allocates and returns a buffer containing
all the names known to the <span class="code">global</span> module in <span class="code">Kernel</span>.
<span class="code">count</span> is initialized to
indicate the number of names in the array. The array of strings in names
is terminated by a <span class="code">NULL</span> pointer, so it is not necessary to use
<span class="code">count</span> to determine when the last name is reached.</p>
<p>It is the caller's responsibility to free the array.
<span class="code">erl_global_names</span> allocates the array and all the strings
using a single call to <span class="code">malloc()</span>, so
<span class="code">free(names)</span> is all that is necessary.</p>
<p>To look up one of the names:</p>
<div class="example"><pre>ETERM *pid;
char node[256];
pid = erl_global_whereis(fd,"schedule",node); </pre></div>
<p>If <span class="code">"schedule"</span> is known to the
<span class="code">global</span> module in <span class="code">Kernel</span>, an Erlang pid is
returned that can be used to send messages to the schedule service.
Also, <span class="code">node</span> is initialized to contain the name of
the node where the service is registered, so that you can make a
connection to it by simply passing the variable to
<span class="bold_code bc-19"><a href="erl_connect.html"><span class="code">erl_connect</span></a></span>.</p>
<p>Before registering a name, you should already have registered your
port number with <span class="code">epmd</span>. This is not strictly necessary,
but if you
neglect to do so, then other nodes wishing to communicate with your
service cannot find or connect to your process.</p>
<p>Create a pid that Erlang processes can use to communicate with your
service:</p>
<div class="example"><pre>ETERM *pid;
pid = erl_mk_pid(thisnode,14,0,0);
erl_global_register(fd,servicename,pid); </pre></div>
<p>After registering the name, use
<span class="bold_code bc-15"><a href="erl_connect.html#erl_accept"><span class="code">erl_connect:erl_accept</span></a></span>
to wait for incoming connections.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Remember to free <span class="code">pid</span> later with
<span class="bold_code bc-15"><a href="erl_malloc.html#erl_free_term"><span class="code">erl_malloc:erl_free_term</span></a></span>.</p>
</p></div>
</div>
<p>To unregister a name:</p>
<div class="example"><pre>erl_global_unregister(fd,servicename); </pre></div>
<h3><span onMouseOver="document.getElementById('ghlink-using-the-registry-idm281473478571208').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-using-the-registry-idm281473478571208').style.visibility = 'hidden';"><span id="ghlink-using-the-registry-idm281473478571208" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L643" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="using-the-registry" href="#using-the-registry">1.12
Using the Registry</a></span></h3>
<p>This section describes the use of the registry, a simple mechanism
for storing key-value pairs in a C-node, as well as backing them up or
restoring them from an <span class="code">Mnesia</span> table on an Erlang node. For more
detailed information about the individual API functions, see the
<span class="bold_code bc-19"><a href="registry.html"><span class="code">registry</span></a></span> module.</p>
<p>Keys are strings, that is, <span class="code">NULL</span>-terminated arrays of characters, and
values are arbitrary objects. Although integers and floating point numbers
are treated specially by the registry, you can store strings or binary
objects of any type as pointers.</p>
<p>To start, open a registry:</p>
<div class="example"><pre>ei_reg *reg;
reg = ei_reg_open(45); </pre></div>
<p>The number <span class="code">45</span> in the example indicates the approximate number of
objects that you expect to store in the registry. Internally the
registry uses hash tables with collision chaining, so there is no
absolute upper limit on the number of objects that the registry can
contain, but if performance or memory usage is important, then you
are to choose a number accordingly. The registry can be resized later.</p>
<p>You can open as many registries as you like (if memory permits).</p>
<p>Objects are stored and retrieved through set and get functions.
The following example shows how to store integers, floats, strings,
and arbitrary binary objects:</p>
<div class="example"><pre>struct bonk *b = malloc(sizeof(*b));
char *name = malloc(7);
ei_reg_setival(reg,"age",29);
ei_reg_setfval(reg,"height",1.85);
strcpy(name,"Martin");
ei_reg_setsval(reg,"name",name);
b->l = 42;
b->m = 12;
ei_reg_setpval(reg,"jox",b,sizeof(*b)); </pre></div>
<p>If you try to store an object in the registry and there is an
existing object with the same key, the new value replaces the old
one. This is done regardless of whether the new object and the old one
have the same type, so you can, for example, replace a string with an
integer. If the existing value is a string or binary, it is freed
before the new value is assigned.</p>
<p>Stored values are retrieved from the registry as follows:</p>
<div class="example"><pre>long i;
double f;
char *s;
struct bonk *b;
int size;
i = ei_reg_getival(reg,"age");
f = ei_reg_getfval(reg,"height");
s = ei_reg_getsval(reg,"name");
b = ei_reg_getpval(reg,"jox",&size); </pre></div>
<p>In all the above examples, the object must exist and it must be of
the right type for the specified operation. If you do not know the
type of an object, you can ask:</p>
<div class="example"><pre>struct ei_reg_stat buf;
ei_reg_stat(reg,"name",&buf); </pre></div>
<p>Buf is initialized to contain object attributes.</p>
<p>Objects can be removed from the registry:</p>
<div class="example"><pre>ei_reg_delete(reg,"name"); </pre></div>
<p>When you are finished with a registry, close it to remove all the
objects and free the memory back to the system:</p>
<div class="example"><pre>ei_reg_close(reg); </pre></div>
<h4><span onMouseOver="document.getElementById('ghlink-backing-up-the-registry-to-mnesia-idm281473478396744').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-backing-up-the-registry-to-mnesia-idm281473478396744').style.visibility = 'hidden';"><span id="ghlink-backing-up-the-registry-to-mnesia-idm281473478396744" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L733" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="backing-up-the-registry-to-mnesia" href="#backing-up-the-registry-to-mnesia">Backing Up the Registry to Mnesia</a></span></h4>
<p>The contents of a registry can be backed up to
<span class="bold_code bc-18"><a href="javascript:erlhref('../../../../doc/../','mnesia','mnesia.html');"><span class="code">Mnesia</span></a></span> on a "nearby" Erlang
node. You must provide an open connection to the Erlang node
(see <span class="bold_code bc-19"><a href="erl_connect.html"><span class="code">erl_connect</span></a></span>).
Also, <span class="code">Mnesia</span> 3.0 or later must be running
on the Erlang node before the backup is initiated:</p>
<div class="example"><pre>ei_reg_dump(fd, reg, "mtab", dumpflags); </pre></div>
<p>This example back up the contents of the registry to the
specified <span class="code">Mnesia</span> table <span class="code">"mtab"</span>.
Once a registry has been backed
up to <span class="code">Mnesia</span> like this, more backups only affect
objects that have been modified since the most recent backup, that is,
objects that have been created, changed, or deleted. The backup
operation is done as a single atomic transaction, so that either the
entire backup is performed or none of it.</p>
<p>Likewise, a registry can be restored from a <span class="code">Mnesia</span> table:</p>
<div class="example"><pre>ei_reg_restore(fd, reg, "mtab"); </pre></div>
<p>This reads the entire contents of <span class="code">"mtab"</span> into the
specified registry. After the restore, all the objects in the registry
are marked as unmodified, so a later backup only affects
objects that you have modified since the restore.</p>
<p>Notice that if you restore to a non-empty registry, objects in the
table overwrite objects in the registry with the same keys. Also,
the <strong>entire</strong> contents of the registry is marked as unmodified
after the restore, including any modified objects that were not
overwritten by the restore operation. This may not be your
intention.</p>
<h4><span onMouseOver="document.getElementById('ghlink-storing-strings-and-binaries-idm281473478177608').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-storing-strings-and-binaries-idm281473478177608').style.visibility = 'hidden';"><span id="ghlink-storing-strings-and-binaries-idm281473478177608" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/erl_interface/doc/src/ei_users_guide.xml#L772" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="storing-strings-and-binaries" href="#storing-strings-and-binaries">Storing Strings and Binaries</a></span></h4>
<p>When string or binary objects are stored in the registry it is
important that some simple guidelines are followed.</p>
<p>Most importantly, the object must have been created with a single call
to <span class="code">malloc()</span> (or similar), so that it can later be
removed by a single call to <span class="code">free()</span>.
Objects are freed by the registry
when it is closed, or when you assign a new value to an object that
previously contained a string or binary.</p>
<p>Notice that if you store binary objects that are context-dependent
(for example, containing pointers or open file descriptors),
they lose their meaning if they are backed up to a <span class="code">Mnesia</span> table
and later restored in a different context.</p>
<p>When you retrieve a stored string or binary value from the registry,
the registry maintains a pointer to the object and you are passed a
copy of that pointer. You should never free an object retrieved in
this manner because when the registry later attempts to free it, a
runtime error occurs that likely causes the C-node to crash.</p>
<p>You are free to modify the contents of an object retrieved this way.
However, when you do so, the registry is not aware of your changes,
possibly causing it to be missed the next time you make an
<span class="code">Mnesia</span> backup of the registry contents. This can be avoided if
you mark the object as dirty after any such changes with
<span class="bold_code bc-15"><a href="registry.html#ei_reg_markdirty"><span class="code">registry:ei_reg_markdirty</span></a></span>, or pass appropriate flags to
<span class="bold_code bc-15"><a href="registry.html#ei_reg_dump"><span class="code">registry:ei_reg_dump</span></a></span>.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1998-2019 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div>
<script type="text/javascript">window.__otpTopDocDir = '../../../../doc/js/';</script><script type="text/javascript" src="../../../../doc/js/highlight.js"></script>
</body>
</html>
