diff options
Diffstat (limited to 'lib/erl_interface/doc/src/erl_connect.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/erl_connect.xml | 373 |
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örn Tö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> - |