aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc/src/ei_connect.xml
diff options
context:
space:
mode:
authorBjörn-Egil Dahlberg <[email protected]>2016-10-17 15:07:55 +0200
committerBjörn-Egil Dahlberg <[email protected]>2016-10-20 14:09:26 +0200
commit9f5b69e8def226f1d1ce9262477d5bbd1cbc1fe7 (patch)
tree6e40fddeea6a39ab6214fe17e1e457bca275efaa /lib/erl_interface/doc/src/ei_connect.xml
parent8cddd5600870c64f27f555144804a1ff4104f7e6 (diff)
downloadotp-9f5b69e8def226f1d1ce9262477d5bbd1cbc1fe7.tar.gz
otp-9f5b69e8def226f1d1ce9262477d5bbd1cbc1fe7.tar.bz2
otp-9f5b69e8def226f1d1ce9262477d5bbd1cbc1fe7.zip
erl_interface: Refactor documentation
Diffstat (limited to 'lib/erl_interface/doc/src/ei_connect.xml')
-rw-r--r--lib/erl_interface/doc/src/ei_connect.xml515
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>
-