diff options
Diffstat (limited to 'lib/erl_interface/doc/src/erl_connect.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/erl_connect.xml | 566 |
1 files changed, 566 insertions, 0 deletions
diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml new file mode 100644 index 0000000000..b2235925b2 --- /dev/null +++ b/lib/erl_interface/doc/src/erl_connect.xml @@ -0,0 +1,566 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE cref SYSTEM "cref.dtd"> + +<cref> + <header> + <copyright> + <year>1996</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>erl_connect</title> + <prepared>Torbjörn Törnkvist</prepared> + <responsible>Torbjörn Törnkvist</responsible> + <docno></docno> + <approved>Bjarne Däcker</approved> + <checked>Torbjörn Törnkvist</checked> + <date>980703</date> + <rev>A</rev> + <file>erl_connect.sgml</file> + </header> + <lib>erl_connect</lib> + <libsummary>Communicate with Distributed Erlang</libsummary> + <description> + <p>This module provides support for communication between distributed + Erlang nodes and C nodes, in a manner that is transparent to Erlang + processes.</p> + <p>A C node appears to Erlang as a + <em>hidden node</em>. + That is, Erlang processes that know the name of the + C node are able to communicate with it in a normal manner, but + the node name will not appear in the listing provided by the + Erlang function <c><![CDATA[nodes/0]]></c>.</p> + </description> + <funcs> + <func> + <name><ret>int</ret><nametext>erl_connect_init(number, cookie, creation)</nametext></name> + <name><ret>int</ret><nametext>erl_connect_xinit(host, alive, node, addr, cookie, creation)</nametext></name> + <fsummary>Initialize communication</fsummary> + <type> + <v>int number;</v> + <v>char *cookie;</v> + <v>short creation;</v> + <v>char *host,*alive,*node;</v> + <v>struct in_addr *addr;</v> + </type> + <desc> + <p>These functions initialize the <c><![CDATA[erl_connect]]></c> + module. In particular, they are used to identify the name of the + C-node from which they are called. One of these functions must + be called before any of the other functions in the erl_connect + module are used.</p> + <p><c><![CDATA[erl_connect_xinit()]]></c> stores for later use information about + the node's host name <c><![CDATA[host]]></c>, alive name <c><![CDATA[alive]]></c>, node + name <c><![CDATA[node]]></c>, IP address <c><![CDATA[addr]]></c>, cookie <c><![CDATA[cookie]]></c>, + and creation number <c><![CDATA[creation]]></c>. <c><![CDATA[erl_connect_init()]]></c> + provides an alternative interface which does not require as much + information from the caller. Instead, <c><![CDATA[erl_connect_init()]]></c> + uses <c><![CDATA[gethostbyname()]]></c> to obtain default values. + </p> + <p>If you use <c><![CDATA[erl_connect_init()]]></c> your node will have a + short name, i.e., it will not be fully qualified. If you need to + use fully qualified (a.k.a. long) names, use + <c><![CDATA[erl_connect_xinit()]]></c> instead. + </p> + <p><c><![CDATA[host]]></c> is the name of the host on which the node is running.</p> + <p><c><![CDATA[alive]]></c> is the alivename of the node.</p> + <p><c><![CDATA[node]]></c> is the name of the node. The nodename should + be of the form <em>alivename@hostname</em>.</p> + <p><c><![CDATA[addr]]></c> is the 32-bit IP address of <c><![CDATA[host]]></c>.</p> + <p><c><![CDATA[cookie]]></c> is the authorization string required for access + to the remote node. If NULL the user HOME directory is + searched for a cookie file <c><![CDATA[.erlang.cookie]]></c>. The path to + the home directory is retrieved from the environment variable + <c><![CDATA[HOME]]></c> on Unix and from the <c><![CDATA[HOMEDRIVE]]></c> and + <c><![CDATA[HOMEPATH]]></c> variables on Windows. Refer to the <c><![CDATA[auth]]></c> + module for more details.</p> + <p><c><![CDATA[creation]]></c> helps identify a particular instance of a C + node. In particular, it can help prevent us from receiving + messages sent to an earlier process with the same registered + name.</p> + <p>A C node acting as a server will be assigned a creation number + when it calls <c><![CDATA[erl_publish()]]></c>.</p> + <p><c><![CDATA[number]]></c> is used by <c><![CDATA[erl_connect_init()]]></c> to + construct the actual node name. In the second example shown + below, <em>"[email protected]"</em> will be the resulting node + name.</p> + <p>Example 1:</p> + <code type="none"><![CDATA[ +struct in_addr addr; +addr = inet_addr("150.236.14.75"); +if (!erl_connect_xinit("chivas", + "madonna", + "[email protected]", + &addr; + "samplecookiestring..."), + 0) + erl_err_quit("<ERROR> when initializing !"); + ]]></code> + <p>Example 2:</p> + <code type="none"><![CDATA[ +if (!erl_connect_init(17, "samplecookiestring...", 0)) + erl_err_quit("<ERROR> when initializing !"); + ]]></code> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_connect(node)</nametext></name> + <name><ret>int</ret><nametext>erl_xconnect(addr, alive)</nametext></name> + <fsummary>Establishe a connection to an Erlang node</fsummary> + <type> + <v>char *node, *alive;</v> + <v>struct in_addr *addr;</v> + </type> + <desc> + <p>These functions set up a connection to an Erlang node.</p> + <p><c><![CDATA[erl_xconnect()]]></c> requires the IP address of the remote + host and the alive name of the remote node + to be specified. <c><![CDATA[erl_connect()]]></c> provides an alternative + interface, and determines the information from the node name + provided.</p> + <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote host.</p> + <p><c><![CDATA[alive]]></c> is the alivename of the remote node.</p> + <p><c><![CDATA[node]]></c> is the name of the remote node.</p> + <p>These functions return an open file descriptor on success, or + a negative value indicating that an error occurred --- in + which case they will set <c><![CDATA[erl_errno]]></c> to one of:</p> + <taglist> + <tag><c><![CDATA[EHOSTUNREACH]]></c></tag> + <item>The remote host <c><![CDATA[node]]></c> is unreachable</item> + <tag><c><![CDATA[ENOMEM]]></c></tag> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + <p>Additionally, <c><![CDATA[errno]]></c> values from + <c><![CDATA[socket]]></c><em>(2)</em> and <c><![CDATA[connect]]></c><em>(2)</em> + system calls may be propagated into <c><![CDATA[erl_errno]]></c>.</p> + <code type="none"><![CDATA[ +#define NODE "[email protected]" +#define ALIVE "madonna" +#define IP_ADDR "150.236.14.75" + +/*** Variant 1 ***/ +erl_connect( NODE ); + +/*** Variant 2 ***/ +struct in_addr addr; +addr = inet_addr(IP_ADDR); +erl_xconnect( &addr , ALIVE ); + ]]></code> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_close_connection(fd)</nametext></name> + <fsummary>Close a connection to an Erlang node</fsummary> + <type> + <v>int fd;</v> + </type> + <desc> + <p>This function closes an open connection to an Erlang node.</p> + <p><c><![CDATA[Fd]]></c> is a file descriptor obtained from + <c><![CDATA[erl_connect()]]></c> or <c><![CDATA[erl_xconnect()]]></c>.</p> + <p>On success, 0 is returned. If the call fails, a non-zero value + is returned, and the reason for + the error can be obtained with the appropriate platform-dependent + call.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_receive(fd, bufp, bufsize)</nametext></name> + <fsummary>Receive a message</fsummary> + <type> + <v>int fd;</v> + <v>char *bufp;</v> + <v>int bufsize;</v> + </type> + <desc> + <p>This function receives a message consisting of a sequence + of bytes in the Erlang external format.</p> + <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> + <p><c><![CDATA[bufp]]></c> is a buffer large enough to hold the expected + message. </p> + <p><c><![CDATA[bufsize]]></c> indicates the size of <c><![CDATA[bufp]]></c>.</p> + <p>If a <em>tick</em> occurs, i.e., the Erlang node on the + other end of the connection has polled this node to see if it + is still alive, the function will return <c><![CDATA[ERL_TICK]]></c> and + no message will be placed in the buffer. Also, + <c><![CDATA[erl_errno]]></c> will be set to <c><![CDATA[EAGAIN]]></c>.</p> + <p>On success, the message is placed in the specified buffer + and the function returns the number of bytes actually read. On + failure, the function returns a negative value and will set + <c><![CDATA[erl_errno]]></c> to one of:</p> + <taglist> + <tag><c><![CDATA[EAGAIN]]></c></tag> + <item>Temporary error: Try again.</item> + <tag><c><![CDATA[EMSGSIZE]]></c></tag> + <item>Buffer too small.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_receive_msg(fd, bufp, bufsize, emsg)</nametext></name> + <fsummary>Receive and decodes a message</fsummary> + <type> + <v>int fd;</v> + <v>unsigned char *bufp;</v> + <v>int bufsize;</v> + <v>ErlMessage *emsg;</v> + </type> + <desc> + <p>This function receives the message into the specified buffer, + and decodes into the <c><![CDATA[(ErlMessage *) emsg]]></c>.</p> + <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> + <p><c><![CDATA[bufp]]></c> is a buffer large enough to hold the expected message.</p> + <p><c><![CDATA[bufsize]]></c> indicates the size of <c><![CDATA[bufp]]></c>.</p> + <p><c><![CDATA[emsg]]></c> is a pointer to an <c><![CDATA[ErlMessage]]></c> structure, + into which the message will be decoded. <c><![CDATA[ErlMessage]]></c> is + defined as follows:</p> + <code type="none"><![CDATA[ +typedef struct { + int type; + ETERM *msg; + ETERM *to; + ETERM *from; + char to_name[MAXREGLEN]; +} ErlMessage; + ]]></code> + <note> + <p>The definition of <c><![CDATA[ErlMessage]]></c> has changed since + earlier versions of Erl_Interface.</p> + </note> + <p><c><![CDATA[type]]></c> identifies the type of message, one of + <c><![CDATA[ERL_SEND]]></c>, <c><![CDATA[ERL_REG_SEND]]></c>, <c><![CDATA[ERL_LINK]]></c>, + <c><![CDATA[ERL_UNLINK]]></c> and <c><![CDATA[ERL_EXIT]]></c>. + </p> + <p>If <c><![CDATA[type]]></c> contains <c><![CDATA[ERL_SEND]]></c> + this indicates that an ordinary send operation has taken + place, and <c><![CDATA[emsg->to]]></c> contains the Pid of the + recipient. If <c><![CDATA[type]]></c> contains <c><![CDATA[ERL_REG_SEND]]></c> then a + registered send operation took place, and <c><![CDATA[emsg->from]]></c> + contains the Pid of the sender. In both cases, the actual + message will be in <c><![CDATA[emsg->msg]]></c>. + </p> + <p>If <c><![CDATA[type]]></c> contains one of <c><![CDATA[ERL_LINK]]></c> or + <c><![CDATA[ERL_UNLINK]]></c>, then <c><![CDATA[emsg->to]]></c> and <c><![CDATA[emsg->from]]></c> + contain the pids of the sender and recipient of the link or unlink. + <c><![CDATA[emsg->msg]]></c> is not used in these cases. + </p> + <p>If <c><![CDATA[type]]></c> contains <c><![CDATA[ERL_EXIT]]></c>, then this + indicates that a link has been broken. In this case, + <c><![CDATA[emsg->to]]></c> and <c><![CDATA[emsg->from]]></c> contain the pids of the + linked processes, and <c><![CDATA[emsg->msg]]></c> contains the reason for + the exit. + </p> + <note> + <p>It is the caller's responsibility to release the + memory pointed to by <c><![CDATA[emsg->msg]]></c>, <c><![CDATA[emsg->to]]></c> and + <c><![CDATA[emsg->from]]></c>.</p> + </note> + <p>If a <em>tick</em> occurs, i.e., the Erlang node on the + other end of the connection has polled this node to see if it + is still alive, the function will return <c><![CDATA[ERL_TICK]]></c> + indicating that the tick has been received and responded to, + but no message will be placed in the buffer. In this case you + should call <c><![CDATA[erl_receive_msg()]]></c> again.</p> + <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the + <c><![CDATA[Emsg]]></c> struct will be initialized as described above, or + <c><![CDATA[ERL_TICK]]></c>, in which case no message is returned. On + failure, the function returns <c><![CDATA[ERL_ERROR]]></c> and will set + <c><![CDATA[erl_errno]]></c> to one of:</p> + <taglist> + <tag><c><![CDATA[EMSGSIZE]]></c></tag> + <item>Buffer too small.</item> + <tag><c><![CDATA[ENOMEM]]></c></tag> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_xreceive_msg(fd, bufpp, bufsizep, emsg)</nametext></name> + <fsummary>Receive and decodes a message</fsummary> + <type> + <v>int fd;</v> + <v>unsigned char **bufpp;</v> + <v>int *bufsizep;</v> + <v>ErlMessage *emsg;</v> + </type> + <desc> + <p>This function is similar to <c><![CDATA[erl_receive_msg]]></c>. The + difference is that <c><![CDATA[erl_xreceive_msg]]></c> expects the buffer to + have been allocated by <c><![CDATA[malloc]]></c>, and reallocates it if the received + message does not fit into the original buffer. For that reason, + both buffer and buffer length are given as pointers - their values + may change by the call. + </p> + <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the + <c><![CDATA[Emsg]]></c> struct will be initialized as described above, or + <c><![CDATA[ERL_TICK]]></c>, in which case no message is returned. On + failure, the function returns <c><![CDATA[ERL_ERROR]]></c> and will set + <c><![CDATA[erl_errno]]></c> to one of:</p> + <taglist> + <tag><c><![CDATA[EMSGSIZE]]></c></tag> + <item>Buffer too small.</item> + <tag><c><![CDATA[ENOMEM]]></c></tag> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name> + <fsummary>Send a message</fsummary> + <type> + <v>int fd;</v> + <v>ETERM *to, *msg;</v> + </type> + <desc> + <p>This function sends an Erlang term to a process.</p> + <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> + <p><c><![CDATA[to]]></c> is an Erlang term containing the Pid of the + intended recipient of the message.</p> + <p><c><![CDATA[msg]]></c> is the Erlang term to be sent.</p> + <p>The function returns 1 if successful, otherwise 0 --- in + which case it will set <c><![CDATA[erl_errno]]></c> to one of:</p> + <taglist> + <tag><c><![CDATA[EINVAL]]></c></tag> + <item>Invalid argument: <c><![CDATA[to]]></c> is not a valid Erlang pid.</item> + <tag><c><![CDATA[ENOMEM]]></c></tag> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_reg_send(fd, to, msg)</nametext></name> + <fsummary>Send a message to a registered name</fsummary> + <type> + <v>int fd;</v> + <v>char *to;</v> + <v>ETERM *msg;</v> + </type> + <desc> + <p>This function sends an Erlang term to a registered process.</p> + <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> + <p><c><![CDATA[to]]></c> is a string containing the registered name of + the intended recipient of the message.</p> + <p><c><![CDATA[msg]]></c> is the Erlang term to be sent.</p> + <p>The function returns 1 if successful, otherwise 0 --- in + which case it will set <c><![CDATA[erl_errno]]></c> to one of:</p> + <taglist> + <tag><c><![CDATA[ENOMEM]]></c></tag> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + </desc> + </func> + <func> + <name><ret>ETERM *</ret><nametext>erl_rpc(fd, mod, fun, args)</nametext></name> + <name><ret>int</ret><nametext>erl_rpc_to(fd, mod, fun, args)</nametext></name> + <name><ret>int</ret><nametext>erl_rpc_from(fd, timeout, emsg)</nametext></name> + <fsummary>Remote Procedure Call</fsummary> + <type> + <v>int fd, timeout;</v> + <v>char *mod, *fun;</v> + <v>ETERM *args;</v> + <v>ErlMessage *emsg;</v> + </type> + <desc> + <p>These functions support calling Erlang functions on remote nodes. + <c><![CDATA[erl_rpc_to()]]></c> sends an rpc request to a remote node and + <c><![CDATA[erl_rpc_from()]]></c> receives the results of such a call. + <c><![CDATA[erl_rpc()]]></c> combines the functionality of these two functions + by sending an rpc request and waiting for the results. See also + <c><![CDATA[rpc:call/4]]></c>. </p> + <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> + <p><c><![CDATA[timeout]]></c> is the maximum time (in ms) to wait for + results. Specify <c><![CDATA[ERL_NO_TIMEOUT]]></c> to wait forever. + When erl_rpc() calls erl_rpc_from(), the call will never + timeout.</p> + <p><c><![CDATA[mod]]></c> is the name of the module containing the function + to be run on the remote node.</p> + <p><c><![CDATA[fun]]></c> is the name of the function to run.</p> + <p><c><![CDATA[args]]></c> is an Erlang list, containing the arguments to be + passed to the function. </p> + <p><c><![CDATA[emsg]]></c> is a message containing the result of the + function call.</p> + <p>The actual message returned by the rpc server + is a 2-tuple <c><![CDATA[{rex,Reply}]]></c>. If you are using + <c><![CDATA[erl_rpc_from()]]></c> in your code then this is the message you + will need to parse. If you are using <c><![CDATA[erl_rpc()]]></c> then the + tuple itself is parsed for you, and the message returned to your + program is the erlang term containing <c><![CDATA[Reply]]></c> only. Replies + to rpc requests are always ERL_SEND messages. + </p> + <note> + <p>It is the caller's responsibility to free the returned + <c><![CDATA[ETERM]]></c> structure as well as the memory pointed to by + <c><![CDATA[emsg->msg]]></c> and <c><![CDATA[emsg->to]]></c>. </p> + </note> + <p><c><![CDATA[erl_rpc()]]></c> returns the remote function's return value (or + <c><![CDATA[NULL]]></c> if it failed). <c><![CDATA[erl_rpc_to()]]></c> returns 0 on + success, and a negative number on failure. <c><![CDATA[erl_rcp_from()]]></c> + returns <c><![CDATA[ERL_MSG]]></c> when successful (with <c><![CDATA[Emsg]]></c> now + containing the reply tuple), and one of <c><![CDATA[ERL_TICK]]></c>, + <c><![CDATA[ERL_TIMEOUT]]></c> and <c><![CDATA[ERL_ERROR]]></c> otherwise. When failing, + all three functions set <c><![CDATA[erl_errno]]></c> to one of:</p> + <taglist> + <tag><c><![CDATA[ENOMEM]]></c></tag> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + <tag><c><![CDATA[ETIMEDOUT]]></c></tag> + <item>Timeout expired.</item> + <tag><c><![CDATA[EAGAIN]]></c></tag> + <item>Temporary error: Try again.</item> + </taglist> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_publish(port)</nametext></name> + <fsummary>Publish a node name</fsummary> + <type> + <v>int port;</v> + </type> + <desc> + <p>These functions are used by a server process to register + with the local name server <em>epmd</em>, thereby allowing + other processes to send messages by using the registered name. + Before calling either of these functions, the process should + have called <c><![CDATA[bind()]]></c> and <c><![CDATA[listen()]]></c> on an open socket.</p> + <p><c><![CDATA[port]]></c> is the local name to register, and should be the + same as the port number that was previously bound to the socket.</p> + <p>To unregister with epmd, simply close the returned + descriptor. See also <c><![CDATA[erl_unpublish()]]></c>. + </p> + <p>On success, the functions return a descriptor connecting the + calling process to epmd. On failure, they return -1 and set + <c><![CDATA[erl_errno]]></c> to:</p> + <taglist> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error</item> + </taglist> + <p>Additionally, <c><![CDATA[errno]]></c> values from <c><![CDATA[socket]]></c><em>(2)</em> + and <c><![CDATA[connect]]></c><em>(2)</em> system calls may be propagated + into <c><![CDATA[erl_errno]]></c>. + </p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_accept(listensock, conp)</nametext></name> + <fsummary>Accept a connection</fsummary> + <type> + <v>int listensock;</v> + <v>ErlConnect *conp;</v> + </type> + <desc> + <p>This function is used by a server process to accept a + connection from a client process.</p> + <p><c><![CDATA[listensock]]></c> is an open socket descriptor on which + <c><![CDATA[listen()]]></c> has previously been called.</p> + <p><c><![CDATA[conp]]></c> is a pointer to an <c><![CDATA[ErlConnect]]></c> struct, + described as follows:</p> + <code type="none"><![CDATA[ +typedef struct { + char ipadr[4]; + char nodename[MAXNODELEN]; +} ErlConnect; + ]]></code> + <p>On success, <c><![CDATA[conp]]></c> is filled in with the address and + node name of the connecting client and a file descriptor is + returned. On failure, <c><![CDATA[ERL_ERROR]]></c> is returned and + <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EIO]]></c>.</p> + </desc> + </func> + <func> + <name><ret>const char *</ret><nametext>erl_thiscookie()</nametext></name> + <name><ret>const char *</ret><nametext>erl_thisnodename()</nametext></name> + <name><ret>const char *</ret><nametext>erl_thishostname()</nametext></name> + <name><ret>const char *</ret><nametext>erl_thisalivename()</nametext></name> + <name><ret>short</ret><nametext>erl_thiscreation()</nametext></name> + <fsummary>Retrieve some values</fsummary> + <desc> + <p>These functions can be used to retrieve information about + the C Node. These values are initially set with + <c><![CDATA[erl_connect_init()]]></c> or <c><![CDATA[erl_connect_xinit()]]></c>.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_unpublish(alive)</nametext></name> + <fsummary>Unpublish a node name</fsummary> + <type> + <v>char *alive;</v> + </type> + <desc> + <p>This function can be called by a process to unregister a + specified node name from epmd on the localhost. This may be + useful, for example, when epmd has not detected the failure of a + node, and will not allow the name to be reused. If you use this + function to unregister your own process, be sure to also close + the descriptor that was returned by <c><![CDATA[erl_publish()]]></c>.</p> + <note> + <p>Careless use of this function may have unpredictable + results, if the registered node is in fact still running.</p> + </note> + <p><c><![CDATA[alive]]></c> is the name of the node to unregister, i.e., the + first component of the nodename, without the <c><![CDATA[@hostname]]></c>.</p> + <p>If the node was successfully unregistered from epmd, the + function returns 0. Otherwise, it returns -1 and sets + <c><![CDATA[erl_errno]]></c> is to <c><![CDATA[EIO]]></c>.</p> + </desc> + </func> + <func> + <name><ret>struct hostent</ret><nametext>*erl_gethostbyname(name)</nametext></name> + <name><ret>struct hostent</ret><nametext>*erl_gethostbyaddr(addr, length, type)</nametext></name> + <name><ret>struct hostent</ret><nametext>*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)</nametext></name> + <name><ret>struct hostent</ret><nametext>*erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop)</nametext></name> + <fsummary>Name lookup functions</fsummary> + <type> + <v>const char *name;</v> + <v>const char *addr;</v> + <v>int length;</v> + <v>int type;</v> + <v>struct hostent *hostp;</v> + <v>char *buffer;</v> + <v>int buflen;</v> + <v>int *h_errnop;</v> + </type> + <desc> + <p>These are convenience functions for some common name lookup functions.</p> + </desc> + </func> + </funcs> + + <section> + <title>Debug Information</title> + <p>If a connection attempt fails, the following can be checked:</p> + <list type="bulleted"> + <item><c><![CDATA[erl_errno]]></c></item> + <item>that the right cookie was used</item> + <item>that <em>epmd</em> is running</item> + <item>the remote Erlang node on the other side is running the same + version of Erlang as the <c><![CDATA[erl_interface]]></c> library.</item> + </list> + </section> +</cref> + |