aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc/src/erl_connect.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/erl_interface/doc/src/erl_connect.xml')
-rw-r--r--lib/erl_interface/doc/src/erl_connect.xml566
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&ouml;rn T&ouml;rnkvist</prepared>
+ <responsible>Torbj&ouml;rn T&ouml;rnkvist</responsible>
+ <docno></docno>
+ <approved>Bjarne D&auml;cker</approved>
+ <checked>Torbj&ouml;rn T&ouml;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",
+ &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>
+