erl_interface: Refactor documentation

1 files changed, 186 insertions, 187 deletions

diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml
index 0fad98cd17..0799e30905 100644
--- a/lib/erl_interface/doc/src/erl_connect.xml
+++ b/lib/erl_interface/doc/src/erl_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>erl_connect</title>
@@ -30,7 +30,7 @@
     <checked>Torbj&ouml;rn T&ouml;rnkvist</checked>
     <date>980703</date>
     <rev>A</rev>
-    <file>erl_connect.sgml</file>
+    <file>erl_connect.xml</file>
   </header>
   <lib>erl_connect</lib>
   <libsummary>Communicate with Distributed Erlang</libsummary>
@@ -47,9 +47,98 @@
   </description>
   <funcs>
     <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>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_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_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>
+      <fsummary>Initialize communication.</fsummary>
       <type>
         <v>int number;</v>
         <v>char *cookie;</v>
@@ -61,7 +150,7 @@
         <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 
+          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
@@ -69,12 +158,12 @@
           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. 
+          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. 
+          <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>
@@ -118,71 +207,38 @@ if (!erl_connect_init(17, "samplecookiestring...", 0))
       </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>
+      <name><ret>int</ret><nametext>erl_publish(port)</nametext></name>
+      <fsummary>Publish a node name.</fsummary>
       <type>
-        <v>char *node, *alive;</v>
-        <v>struct in_addr *addr;</v>
+        <v>int port;</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>
+        <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.
+          </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[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>
+          <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>
+        <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_receive(fd, bufp, bufsize)</nametext></name>
-      <fsummary>Receive a message</fsummary>
+      <fsummary>Receive a message.</fsummary>
       <type>
         <v>int fd;</v>
         <v>char *bufp;</v>
@@ -216,7 +272,7 @@ erl_xconnect( &addr , ALIVE );
     </func>
     <func>
       <name><ret>int</ret><nametext>erl_receive_msg(fd, bufp, bufsize, emsg)</nametext></name>
-      <fsummary>Receive and decodes a message</fsummary>
+      <fsummary>Receive and decodes a message.</fsummary>
       <type>
         <v>int fd;</v>
         <v>unsigned char *bufp;</v>
@@ -224,7 +280,7 @@ erl_xconnect( &addr , ALIVE );
         <v>ErlMessage *emsg;</v>
       </type>
       <desc>
-        <p>This function receives the message into the specified buffer, 
+        <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>
@@ -245,9 +301,9 @@ typedef struct {
           <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 
+        <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>. 
+          <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
@@ -295,65 +351,8 @@ typedef struct {
       </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>
+      <fsummary>Send a message to a registered name.</fsummary>
       <type>
         <v>int fd;</v>
         <v>char *to;</v>
@@ -377,9 +376,9 @@ typedef struct {
     </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>
+      <name><ret>int</ret><nametext>erl_rpc_to(fd, mod, fun, args)</nametext></name>
+      <fsummary>Remote Procedure Call.</fsummary>
       <type>
         <v>int fd, timeout;</v>
         <v>char *mod, *fun;</v>
@@ -438,68 +437,37 @@ typedef struct {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>erl_publish(port)</nametext></name>
-      <fsummary>Publish a node name</fsummary>
+      <name><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name>
+      <fsummary>Send a message.</fsummary>
       <type>
-        <v>int port;</v>
+        <v>int fd;</v>
+        <v>ETERM *to, *msg;</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.
-          </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>
+        <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>
+          <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>const char *</ret><nametext>erl_thiscookie()</nametext></name>
       <name><ret>short</ret><nametext>erl_thiscreation()</nametext></name>
-      <fsummary>Retrieve some values</fsummary>
+      <name><ret>const char *</ret><nametext>erl_thishostname()</nametext></name>
+      <name><ret>const char *</ret><nametext>erl_thisnodename()</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
@@ -508,22 +476,22 @@ typedef struct {
     </func>
     <func>
       <name><ret>int</ret><nametext>erl_unpublish(alive)</nametext></name>
-      <fsummary>Forcefully unpublish a node name</fsummary>
+      <fsummary>Forcefully 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 from epmd on the localhost. This is however usually not 
-	  allowed, unless epmd was started with the -relaxed_command_check 
+          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 instead
-	  close the descriptor that was returned by  
-	  <c><![CDATA[ei_publish()]]></c>.</p> 
+	  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 
+          <p>This function is deprecated and will be removed in a future
 	  release.</p>
         </warning>
         <p><c><![CDATA[alive]]></c> is the name of the node to unregister, i.e., the
@@ -534,11 +502,43 @@ typedef struct {
       </desc>
     </func>
     <func>
-      <name><ret>struct hostent</ret><nametext>*erl_gethostbyname(name)</nametext></name>
+      <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>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>
+      <name><ret>struct hostent</ret><nametext>*erl_gethostbyname(name)</nametext></name>
+      <name><ret>struct hostent</ret><nametext>*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)</nametext></name>
+      <fsummary>Name lookup functions.</fsummary>
       <type>
         <v>const char *name;</v>
         <v>const char *addr;</v>
@@ -567,4 +567,3 @@ typedef struct {
     </list>
   </section>
 </cref>
-