erl_interface: Refactor documentation

1 files changed, 257 insertions, 258 deletions

diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml
index 516357b6a3..8cc08f86cd 100644
--- a/lib/erl_interface/doc/src/ei_connect.xml
+++ b/lib/erl_interface/doc/src/ei_connect.xml
@@ -11,7 +11,7 @@
       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at
- 
+
           http://www.apache.org/licenses/LICENSE-2.0
 
       Unless required by applicable law or agreed to in writing, software
@@ -19,7 +19,7 @@
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.
-    
+
     </legalnotice>
 
     <title>ei_connect</title>
@@ -29,7 +29,7 @@
     <checked>?</checked>
     <date>2001-09-01</date>
     <rev>A</rev>
-    <file>ei_connect.sgml</file>
+    <file>ei_connect.xml</file>
   </header>
   <lib>ei_connect</lib>
   <libsummary>Communicate with distributed erlang</libsummary>
@@ -72,12 +72,97 @@
       the operations are completed (regardless of the result). To
       avoid problems, leave the socket options alone. Ei will handle
       any socket options that need modification.</p>
-    <p>In all other senses, the <c><![CDATA[_tmo]]></c> functions inherit all 
-      the return values and the semantics from the functions without 
+    <p>In all other senses, the <c><![CDATA[_tmo]]></c> functions inherit all
+      the return values and the semantics from the functions without
       the <c><![CDATA[_tmo]]></c> suffix.</p>
   </section>
   <funcs>
     <func>
+      <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr(const char *addr, int len, int type)</nametext></name>
+      <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr_r(const char *addr, int length,  int type,  struct hostent *hostp, char *buffer,   int buflen,  int *h_errnop)</nametext></name>
+      <name><ret>struct hostent</ret><nametext>*ei_gethostbyname(const char *name)</nametext></name>
+      <name><ret>struct hostent</ret><nametext>*ei_gethostbyname_r(const char *name,  struct hostent *hostp,  char *buffer,  int buflen,  int *h_errnop)</nametext></name>
+      <fsummary>Name lookup functions.</fsummary>
+      <desc>
+        <p>These are convenience functions for some common name lookup functions.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)</nametext></name>
+      <fsummary>Accept a connection from another node.</fsummary>
+      <desc>
+        <p>This function is used by a server process to accept a
+          connection from a client process.</p>
+        <p><c><![CDATA[ec]]></c> is the C-node structure.</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>int</ret><nametext>ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms)</nametext></name>
+      <fsummary>Accept a connection from another node with optional timeout.</fsummary>
+      <desc>
+        <p>ei_accept with an optional timeout argument,
+          see the description at the beginning of this document.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>ei_connect(ei_cnode* ec, char *nodename)</nametext></name>
+      <name><ret>int</ret><nametext>ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)</nametext></name>
+      <fsummary>Establishe a connection to an Erlang node.</fsummary>
+      <desc>
+        <p>These functions set up a connection to an Erlang node.</p>
+        <p><c><![CDATA[ei_xconnect()]]></c> requires the IP address of the remote
+          host and the alive name of the remote node
+          to be specified. <c><![CDATA[ei_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>
+        <p>Example:</p>
+        <code type="none"><![CDATA[
+#define NODE   "[email protected]"
+#define ALIVE  "madonna"
+#define IP_ADDR "150.236.14.75"
+
+/*** Variant 1 ***/
+int fd = ei_connect(&ec, NODE);
+
+/*** Variant 2 ***/
+struct in_addr addr;
+addr.s_addr = inet_addr(IP_ADDR);
+fd = ei_xconnect(&ec, &addr, ALIVE);
+        ]]></code>
+      </desc>
+    </func>
+    <func>
       <name><ret>int</ret><nametext>ei_connect_init(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation)</nametext></name>
       <name><ret>int</ret><nametext>ei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation)</nametext></name>
       <fsummary>Initialize for a connection.</fsummary>
@@ -140,61 +225,58 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_connect(ei_cnode* ec, char *nodename)</nametext></name>
-      <name><ret>int</ret><nametext>ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)</nametext></name>
-      <fsummary>Establishe a connection to an Erlang node</fsummary>
+      <name><ret>int</ret><nametext>ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)</nametext></name>
+      <name><ret>int</ret><nametext>ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms)</nametext></name>
+      <fsummary>Establish a connection to an Erlang node with optional timeout.</fsummary>
       <desc>
-        <p>These functions set up a connection to an Erlang node.</p>
-        <p><c><![CDATA[ei_xconnect()]]></c> requires the IP address of the remote
-          host and the alive name of the remote node
-          to be specified. <c><![CDATA[ei_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>
-        <p>Example:</p>
-        <code type="none"><![CDATA[
-#define NODE   "[email protected]"
-#define ALIVE  "madonna"
-#define IP_ADDR "150.236.14.75"
-
-/*** Variant 1 ***/
-int fd = ei_connect(&ec, NODE);
-
-/*** Variant 2 ***/
-struct in_addr addr;
-addr.s_addr = inet_addr(IP_ADDR);
-fd = ei_xconnect(&ec, &addr, ALIVE);
-        ]]></code>
+        <p>ei_connect and ei_xconnect with an optional timeout argument,
+          see the description at the beginning of this document.</p>
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)</nametext></name>
-      <name><ret>int</ret><nametext>ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms)</nametext></name>
-      <fsummary>Establish a connection to an Erlang node with optional timeout</fsummary>
+      <name><ret>int</ret><nametext>ei_get_tracelevel(void)</nametext></name>
+      <name><ret>void</ret><nametext>ei_set_tracelevel(int level)</nametext></name>
+      <fsummary>Get and set functions for tracing.</fsummary>
       <desc>
-        <p>ei_connect and ei_xconnect with an optional timeout argument,
+        <p>These functions are used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information.
+	See also Debug Information and <c><![CDATA[EI_TRACELEVEL]]></c> below. </p>
+	<p> <c><![CDATA[ei_set_tracelevel]]></c> and <c><![CDATA[ei_get_tracelevel]]></c> are not thread safe.  </p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>ei_publish(ei_cnode *ec, int port)</nametext></name>
+      <fsummary>Publish a node name.</fsummary>
+      <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[ec]]></c> is the C-node structure.</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><c><![CDATA[addr]]></c> is the 32-bit IP address of the local host.</p>
+        <p>To unregister with epmd, simply close the returned
+          descriptor. Do not use <c><![CDATA[ei_unpublish()]]></c>, which is deprecated anyway.</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 <c><![CDATA[EIO]]></c>.</p>
+        <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>ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)</nametext></name>
+      <fsummary>Publish a node name with optional timeout.</fsummary>
+      <desc>
+        <p>ei_publish with an optional timeout argument,
           see the description at the beginning of this document.</p>
       </desc>
     </func>
     <func>
       <name><ret>int</ret><nametext>ei_receive(int fd, unsigned char* bufp, int bufsize)</nametext></name>
-      <fsummary>Receive a message</fsummary>
+      <fsummary>Receive a message.</fsummary>
       <desc>
         <p>This function receives a message consisting of a sequence
           of bytes in the Erlang external format.</p>
@@ -224,17 +306,44 @@ fd = ei_xconnect(&ec, &addr, ALIVE);
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms)</nametext></name>
-      <fsummary>Receive a message with optional timeout</fsummary>
+      <name><ret>int</ret><nametext>ei_receive_encoded(int fd, char **mbufp, int *bufsz,  erlang_msg *msg, int *msglen)</nametext></name>
+      <fsummary>Obsolete function for receiving a message.</fsummary>
       <desc>
-        <p>ei_receive with an optional timeout argument,
+        <p>This function is retained for compatibility with code
+          generated by the interface compiler and with code following
+          examples in the same application.</p>
+        <p>In essence the function performs the same operation as
+          <c><![CDATA[ei_xreceive_msg]]></c>, but instead of using an ei_x_buff, the
+          function expects a pointer to a character pointer
+          (<c><![CDATA[mbufp]]></c>), where the character pointer should point to a
+          memory area allocated by <c><![CDATA[malloc]]></c>. The argument
+          <c><![CDATA[bufsz]]></c> should be a pointer to an integer containing the
+          exact size (in bytes) of the memory area. The function may
+          reallocate the memory area and will in such cases put the new
+          size in <c><![CDATA[*bufsz]]></c> and update <c><![CDATA[*mbufp]]></c>.</p>
+        <p>Furthermore the function returns either ERL_TICK or the
+          <c><![CDATA[msgtype]]></c> field of the <c><![CDATA[erlang_msg *msg]]></c>. The actual
+          length of the message is put in <c><![CDATA[*msglen]]></c>. On error it
+          will return a value <c><![CDATA[< 0]]></c>.</p>
+        <p>It is recommended to use ei_xreceive_msg instead when
+          possible, for the sake of readability. The function will
+          however be retained in the interface for compatibility and
+          will <em>not</em> be removed not be removed in future releases
+          without notice.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>ei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz,  erlang_msg *msg, int *msglen, unsigned timeout_ms)</nametext></name>
+      <fsummary>Obsolete function for receiving a message with timeout.</fsummary>
+      <desc>
+        <p>ei_receive_encoded with an optional timeout argument,
           see the description at the beginning of this document.</p>
       </desc>
     </func>
     <func>
       <name><ret>int</ret><nametext>ei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name>
       <name><ret>int</ret><nametext>ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name>
-      <fsummary>Receive a message</fsummary>
+      <fsummary>Receive a message.</fsummary>
       <desc>
         <p>These functions receives a message to the buffer in
           <c><![CDATA[x]]></c>.  <c><![CDATA[ei_xreceive_msg]]></c> allows the buffer in
@@ -279,90 +388,23 @@ typedef struct {
     <func>
       <name><ret>int</ret><nametext>ei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned imeout_ms)</nametext></name>
       <name><ret>int</ret><nametext>ei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned timeout_ms)</nametext></name>
-      <fsummary>Receive a message with optional timeout</fsummary>
+      <fsummary>Receive a message with optional timeout.</fsummary>
       <desc>
         <p>ei_receive_msg and ei_xreceive_msg with an optional timeout argument,
           see the description at the beginning of this document.</p>
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_receive_encoded(int fd, char **mbufp, int *bufsz,  erlang_msg *msg, int *msglen)</nametext></name>
-      <fsummary>Obsolete function for receiving a message</fsummary>
-      <desc>
-        <p>This function is retained for compatibility with code
-          generated by the interface compiler and with code following
-          examples in the same application.</p>
-        <p>In essence the function performs the same operation as
-          <c><![CDATA[ei_xreceive_msg]]></c>, but instead of using an ei_x_buff, the
-          function expects a pointer to a character pointer
-          (<c><![CDATA[mbufp]]></c>), where the character pointer should point to a
-          memory area allocated by <c><![CDATA[malloc]]></c>. The argument
-          <c><![CDATA[bufsz]]></c> should be a pointer to an integer containing the
-          exact size (in bytes) of the memory area. The function may
-          reallocate the memory area and will in such cases put the new
-          size in <c><![CDATA[*bufsz]]></c> and update <c><![CDATA[*mbufp]]></c>.</p>
-        <p>Furthermore the function returns either ERL_TICK or the
-          <c><![CDATA[msgtype]]></c> field of the <c><![CDATA[erlang_msg *msg]]></c>. The actual
-          length of the message is put in <c><![CDATA[*msglen]]></c>. On error it
-          will return a value <c><![CDATA[< 0]]></c>.</p>
-        <p>It is recommended to use ei_xreceive_msg instead when
-          possible, for the sake of readability. The function will
-          however be retained in the interface for compatibility and
-          will <em>not</em> be removed not be removed in future releases
-          without notice.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz,  erlang_msg *msg, int *msglen, unsigned timeout_ms)</nametext></name>
-      <fsummary>Obsolete function for receiving a message with timeout</fsummary>
-      <desc>
-        <p>ei_receive_encoded with an optional timeout argument,
-          see the description at the beginning of this document.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_send(int fd, erlang_pid* to, char* buf, int len)</nametext></name>
-      <fsummary>Send a message</fsummary>
-      <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 the Pid of the intended recipient of the
-          message.</p>
-        <p><c><![CDATA[buf]]></c> is the buffer containing the term in binary
-          format.</p>
-        <p><c><![CDATA[len]]></c> is the length of the message in bytes.</p>
-        <p>The function returns 0 if successful, otherwise -1, in the
-          latter case it will set <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name>
-      <fsummary>Send a message with optional timeout</fsummary>
-      <desc>
-        <p>ei_send with an optional timeout argument,
-          see the description at the beginning of this document.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)</nametext></name>
-      <fsummary>Obsolete function to send a message</fsummary>
-      <desc>
-        <p>Works exactly as ei_send, the alternative name retained for
-          backward compatibility. The function will <em>not</em> be
-          removed without notice.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name>
-      <fsummary>Obsolete function to send a message with optional timeout</fsummary>
+      <name><ret>int</ret><nametext>ei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms)</nametext></name>
+      <fsummary>Receive a message with optional timeout.</fsummary>
       <desc>
-        <p>ei_send_encoded with an optional timeout argument,
+        <p>ei_receive with an optional timeout argument,
           see the description at the beginning of this document.</p>
       </desc>
     </func>
     <func>
       <name><ret>int</ret><nametext>ei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int len)</nametext></name>
-      <fsummary>Send a message to a registered name</fsummary>
+      <fsummary>Send a message to a registered name.</fsummary>
       <desc>
         <p>This function sends an Erlang term to a registered process.
           </p>
@@ -387,49 +429,17 @@ if (ei_reg_send(&ec, fd, x.buff, x.index) < 0)
     </func>
     <func>
       <name><ret>int</ret><nametext>ei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf, int len, unsigned timeout_ms)</nametext></name>
-      <fsummary>Send a message to a registered name with optional timeout</fsummary>
+      <fsummary>Send a message to a registered name with optional timeout.</fsummary>
       <desc>
         <p>ei_reg_send with an optional timeout argument,
           see the description at the beginning of this document.</p>
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name>
-      <fsummary>Obsolete function to send a message to a registered name</fsummary>
-      <desc>
-        <p>This function is retained for compatibility with code
-          generated by the interface compiler and with code following
-          examples in the same application.</p>
-        <p>The function works as <c><![CDATA[ei_reg_send]]></c> with one
-          exception. Instead of taking the <c><![CDATA[ei_cnode]]></c> as a first
-          argument, it takes a second argument, an <c><![CDATA[erlang_pid]]></c>
-          which should be the process identifier of the sending process
-          (in the erlang distribution protocol). </p>
-        <p>A suitable <c><![CDATA[erlang_pid]]></c> can be constructed from the
-          <c><![CDATA[ei_cnode]]></c> structure by the following example code:</p>
-        <code type="none"><![CDATA[
-          ei_cnode ec;
-          erlang_pid *self;
-          int fd; /* the connection fd */
-          ...
-          self = ei_self(&ec);
-          self->num = fd;
-        ]]></code>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name>
-      <fsummary>Obsolete function to send a message to a registered name with timeout</fsummary>
-      <desc>
-        <p>ei_send_reg_encoded with an optional timeout argument,
-          see the description at the beginning of this document.</p>
-      </desc>
-    </func>
-    <func>
       <name><ret>int</ret><nametext>ei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen, ei_x_buff *x)</nametext></name>
       <name><ret>int</ret><nametext>ei_rpc_to(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen)</nametext></name>
       <name><ret>int</ret><nametext>ei_rpc_from(ei_cnode *ec, int fd, int timeout, erlang_msg *msg, ei_x_buff *x)</nametext></name>
-      <fsummary>Remote Procedure Call from C to Erlang</fsummary>
+      <fsummary>Remote Procedure Call from C to Erlang.</fsummary>
       <desc>
         <p>These functions support calling Erlang functions on remote nodes.
           <c><![CDATA[ei_rpc_to()]]></c> sends an rpc request to a remote node and
@@ -496,95 +506,85 @@ if (ei_decode_version(result.buff, &index) < 0
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_publish(ei_cnode *ec, int port)</nametext></name>
-      <fsummary>Publish a node name</fsummary>
+      <name><ret>erlang_pid *</ret><nametext>ei_self(ei_cnode *ec)</nametext></name>
+      <fsummary>Retrieve the Pid of the C-node.</fsummary>
       <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[ec]]></c> is the C-node structure.</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><c><![CDATA[addr]]></c> is the 32-bit IP address of the local host.</p>
-        <p>To unregister with epmd, simply close the returned
-          descriptor. Do not use <c><![CDATA[ei_unpublish()]]></c>, which is deprecated anyway.</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 <c><![CDATA[EIO]]></c>.</p>
-        <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>
+        <p>This function retrieves the Pid of the C-node. Every C-node
+          has a (pseudo) pid used in <c><![CDATA[ei_send_reg]]></c>, <c><![CDATA[ei_rpc]]></c>
+          and others. This is contained in a field in the <c><![CDATA[ec]]></c>
+          structure. It will be safe for a long time to fetch this
+          field directly from the <c><![CDATA[ei_cnode]]></c> structure.</p>
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)</nametext></name>
-      <fsummary>Publish a node name with optional timeout</fsummary>
+      <name><ret>int</ret><nametext>ei_send(int fd, erlang_pid* to, char* buf, int len)</nametext></name>
+      <fsummary>Send a message.</fsummary>
       <desc>
-        <p>ei_publish with an optional timeout argument,
-          see the description at the beginning of this document.</p>
+        <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 the Pid of the intended recipient of the
+          message.</p>
+        <p><c><![CDATA[buf]]></c> is the buffer containing the term in binary
+          format.</p>
+        <p><c><![CDATA[len]]></c> is the length of the message in bytes.</p>
+        <p>The function returns 0 if successful, otherwise -1, in the
+          latter case it will set <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p>
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)</nametext></name>
-      <fsummary>Accept a connection from another node</fsummary>
+      <name><ret>int</ret><nametext>ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)</nametext></name>
+      <fsummary>Obsolete function to send a message.</fsummary>
       <desc>
-        <p>This function is used by a server process to accept a
-          connection from a client process.</p>
-        <p><c><![CDATA[ec]]></c> is the C-node structure.</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>
+        <p>Works exactly as ei_send, the alternative name retained for
+          backward compatibility. The function will <em>not</em> be
+          removed without notice.</p>
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms)</nametext></name>
-      <fsummary>Accept a connection from another node with optional timeout</fsummary>
+      <name><ret>int</ret><nametext>ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name>
+      <fsummary>Obsolete function to send a message with optional timeout.</fsummary>
       <desc>
-        <p>ei_accept with an optional timeout argument,
+        <p>ei_send_encoded with an optional timeout argument,
           see the description at the beginning of this document.</p>
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_unpublish(ei_cnode *ec)</nametext></name>
-      <fsummary>Forcefully unpublish a node name</fsummary>
+      <name><ret>int</ret><nametext>ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name>
+      <fsummary>Obsolete function to send a message to a registered name.</fsummary>
       <desc>
-        <p>This function can be called by a process to unregister a
-          specified node from epmd on the localhost. This is however usually not 
-	  allowed, unless epmd was started with the -relaxed_command_check 
-	  flag, which it normally isn't.</p>
-
-	  <p>To unregister a node you have published, you should
-	  close the descriptor that was returned by  
-	  <c><![CDATA[ei_publish()]]></c>.</p> 
-
-        <warning>
-          <p>This function is deprecated and will be removed in a future 
-	  release.</p>
-        </warning>
-        <p><c><![CDATA[ec]]></c> is the node structure of the node to unregister.</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>
+        <p>This function is retained for compatibility with code
+          generated by the interface compiler and with code following
+          examples in the same application.</p>
+        <p>The function works as <c><![CDATA[ei_reg_send]]></c> with one
+          exception. Instead of taking the <c><![CDATA[ei_cnode]]></c> as a first
+          argument, it takes a second argument, an <c><![CDATA[erlang_pid]]></c>
+          which should be the process identifier of the sending process
+          (in the erlang distribution protocol). </p>
+        <p>A suitable <c><![CDATA[erlang_pid]]></c> can be constructed from the
+          <c><![CDATA[ei_cnode]]></c> structure by the following example code:</p>
+        <code type="none"><![CDATA[
+          ei_cnode ec;
+          erlang_pid *self;
+          int fd; /* the connection fd */
+          ...
+          self = ei_self(&ec);
+          self->num = fd;
+        ]]></code>
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)</nametext></name>
-      <fsummary>Unpublish a node name with optional timeout</fsummary>
+      <name><ret>int</ret><nametext>ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name>
+      <fsummary>Obsolete function to send a message to a registered name with timeout.</fsummary>
       <desc>
-        <p>ei_unpublish with an optional timeout argument,
+        <p>ei_send_reg_encoded with an optional timeout argument,
+          see the description at the beginning of this document.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>ei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name>
+      <fsummary>Send a message with optional timeout.</fsummary>
+      <desc>
+        <p>ei_send with an optional timeout argument,
           see the description at the beginning of this document.</p>
       </desc>
     </func>
@@ -592,7 +592,7 @@ typedef struct {
       <name><ret>const char *</ret><nametext>ei_thisnodename(ei_cnode *ec)</nametext></name>
       <name><ret>const char *</ret><nametext>ei_thishostname(ei_cnode *ec)</nametext></name>
       <name><ret>const char *</ret><nametext>ei_thisalivename(ei_cnode *ec)</nametext></name>
-      <fsummary>Retrieve some values</fsummary>
+      <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
@@ -603,37 +603,37 @@ typedef struct {
       </desc>
     </func>
     <func>
-      <name><ret>erlang_pid *</ret><nametext>ei_self(ei_cnode *ec)</nametext></name>
-      <fsummary>Retrieve the Pid of the C-node</fsummary>
-      <desc>
-        <p>This function retrieves the Pid of the C-node. Every C-node
-          has a (pseudo) pid used in <c><![CDATA[ei_send_reg]]></c>, <c><![CDATA[ei_rpc]]></c>
-          and others. This is contained in a field in the <c><![CDATA[ec]]></c>
-          structure. It will be safe for a long time to fetch this
-          field directly from the <c><![CDATA[ei_cnode]]></c> structure.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>struct hostent</ret><nametext>*ei_gethostbyname(const char *name)</nametext></name>
-      <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr(const char *addr, int len, int type)</nametext></name>
-      <name><ret>struct hostent</ret><nametext>*ei_gethostbyname_r(const char *name,  struct hostent *hostp,  char *buffer,  int buflen,  int *h_errnop)</nametext></name>
-      <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr_r(const char *addr, int length,  int type,  struct hostent *hostp, char *buffer,   int buflen,  int *h_errnop)</nametext></name>
-      <fsummary>Name lookup functions</fsummary>
+      <name><ret>int</ret><nametext>ei_unpublish(ei_cnode *ec)</nametext></name>
+      <fsummary>Forcefully unpublish a node name.</fsummary>
       <desc>
-        <p>These are convenience functions for some common name lookup functions.</p>
+        <p>This function can be called by a process to unregister a
+          specified node from epmd on the localhost. This is however usually not
+	  allowed, unless epmd was started with the -relaxed_command_check
+	  flag, which it normally isn't.</p>
+
+	  <p>To unregister a node you have published, you should
+	  close the descriptor that was returned by
+	  <c><![CDATA[ei_publish()]]></c>.</p>
+
+        <warning>
+          <p>This function is deprecated and will be removed in a future
+	  release.</p>
+        </warning>
+        <p><c><![CDATA[ec]]></c> is the node structure of the node to unregister.</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>int</ret><nametext>ei_get_tracelevel(void)</nametext></name>
-      <name><ret>void</ret><nametext>ei_set_tracelevel(int level)</nametext></name>
-      <fsummary>Get and set functions for tracing.</fsummary>
+      <name><ret>int</ret><nametext>ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)</nametext></name>
+      <fsummary>Unpublish a node name with optional timeout.</fsummary>
       <desc>
-        <p>These functions are used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information.
-	See also Debug Information and <c><![CDATA[EI_TRACELEVEL]]></c> below. </p>
-	<p> <c><![CDATA[ei_set_tracelevel]]></c> and <c><![CDATA[ei_get_tracelevel]]></c> are not thread safe.  </p>
+        <p>ei_unpublish with an optional timeout argument,
+          see the description at the beginning of this document.</p>
       </desc>
     </func>
-  </funcs>
+ </funcs>
 
   <section>
     <title>Debug Information</title>
@@ -652,13 +652,12 @@ typedef struct {
     <c><![CDATA[ei_set_tracelevel]]></c> or by setting the environment variable <c><![CDATA[EI_TRACELEVEL]]></c>.
     The different tracelevels has the following messages:</p>
     <list>
-    	<item>1: Verbose error messages</item>
-    	<item>2: Above messages and verbose warning messages </item>
-    	<item>3: Above messages and progress reports for connection handling</item>
-    	<item>4: Above messages and progress reports for communication</item>
-    	<item>5: Above messages and progress reports for data conversion</item>
+        <item>1: Verbose error messages</item>
+        <item>2: Above messages and verbose warning messages</item>
+        <item>3: Above messages and progress reports for connection handling</item>
+        <item>4: Above messages and progress reports for communication</item>
+        <item>5: Above messages and progress reports for data conversion</item>
     </list>
   </section>
 
 </cref>
-