From 9f5b69e8def226f1d1ce9262477d5bbd1cbc1fe7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Mon, 17 Oct 2016 15:07:55 +0200 Subject: erl_interface: Refactor documentation --- lib/erl_interface/doc/src/erl_connect.xml | 373 +++++++++++++++--------------- 1 file changed, 186 insertions(+), 187 deletions(-) (limited to 'lib/erl_interface/doc/src/erl_connect.xml') 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. - + erl_connect @@ -30,7 +30,7 @@ Torbjörn Törnkvist 980703 A - erl_connect.sgml + erl_connect.xml erl_connect Communicate with Distributed Erlang @@ -46,10 +46,99 @@ Erlang function .

+ + interl_accept(listensock, conp) + Accept a connection. + + int listensock; + ErlConnect *conp; + + +

This function is used by a server process to accept a + connection from a client process.

+

is an open socket descriptor on which + has previously been called.

+

is a pointer to an struct, + described as follows:

+ +

On success, is filled in with the address and + node name of the connecting client and a file descriptor is + returned. On failure, is returned and + is set to .

+ + + + interl_close_connection(fd) + Close a connection to an Erlang node. + + int fd; + + +

This function closes an open connection to an Erlang node.

+

is a file descriptor obtained from + or .

+

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.

+ + + + interl_connect(node) + interl_xconnect(addr, alive) + Establishe a connection to an Erlang node. + + char *node, *alive; + struct in_addr *addr; + + +

These functions set up a connection to an Erlang node.

+

requires the IP address of the remote + host and the alive name of the remote node + to be specified. provides an alternative + interface, and determines the information from the node name + provided.

+

is the 32-bit IP address of the remote host.

+

is the alivename of the remote node.

+

is the name of the remote node.

+

These functions return an open file descriptor on success, or + a negative value indicating that an error occurred --- in + which case they will set to one of:

+ + + The remote host is unreachable + + No more memory available. + + I/O error. + +

Additionally, values from + (2) and (2) + system calls may be propagated into .

+ + + interl_connect_init(number, cookie, creation) interl_connect_xinit(host, alive, node, addr, cookie, creation) - Initialize communication + Initialize communication. int number; char *cookie; @@ -61,7 +150,7 @@

These functions initialize the 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.

stores for later use information about the node's host name , alive name , node @@ -69,12 +158,12 @@ and creation number . provides an alternative interface which does not require as much information from the caller. Instead, - uses to obtain default values. + uses to obtain default values.

If you use 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 - instead. + instead.

is the name of the host on which the node is running.

is the alivename of the node.

@@ -118,71 +207,38 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) - interl_connect(node) - interl_xconnect(addr, alive) - Establishe a connection to an Erlang node + interl_publish(port) + Publish a node name. - char *node, *alive; - struct in_addr *addr; + int port; -

These functions set up a connection to an Erlang node.

-

requires the IP address of the remote - host and the alive name of the remote node - to be specified. provides an alternative - interface, and determines the information from the node name - provided.

-

is the 32-bit IP address of the remote host.

-

is the alivename of the remote node.

-

is the name of the remote node.

-

These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set to one of:

+

These functions are used by a server process to register + with the local name server epmd, thereby allowing + other processes to send messages by using the registered name. + Before calling either of these functions, the process should + have called and on an open socket.

+

is the local name to register, and should be the + same as the port number that was previously bound to the socket.

+

To unregister with epmd, simply close the returned + descriptor. +

+

On success, the functions return a descriptor connecting the + calling process to epmd. On failure, they return -1 and set + to:

- - The remote host is unreachable - - No more memory available. - I/O error. + I/O error -

Additionally, values from - (2) and (2) - system calls may be propagated into .

- - - - - interl_close_connection(fd) - Close a connection to an Erlang node - - int fd; - - -

This function closes an open connection to an Erlang node.

-

is a file descriptor obtained from - or .

-

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.

+

Additionally, values from (2) + and (2) system calls may be propagated + into . +

interl_receive(fd, bufp, bufsize) - Receive a message + Receive a message. int fd; char *bufp; @@ -216,7 +272,7 @@ erl_xconnect( &addr , ALIVE ); interl_receive_msg(fd, bufp, bufsize, emsg) - Receive and decodes a message + Receive and decodes a message. int fd; unsigned char *bufp; @@ -224,7 +280,7 @@ erl_xconnect( &addr , ALIVE ); ErlMessage *emsg; -

This function receives the message into the specified buffer, +

This function receives the message into the specified buffer, and decodes into the .

is an open descriptor to an Erlang connection.

is a buffer large enough to hold the expected message.

@@ -245,9 +301,9 @@ typedef struct {

The definition of has changed since earlier versions of Erl_Interface.

-

identifies the type of message, one of +

identifies the type of message, one of , , , - and . + and .

If contains this indicates that an ordinary send operation has taken @@ -294,66 +350,9 @@ typedef struct { - - interl_xreceive_msg(fd, bufpp, bufsizep, emsg) - Receive and decodes a message - - int fd; - unsigned char **bufpp; - int *bufsizep; - ErlMessage *emsg; - - -

This function is similar to . The - difference is that expects the buffer to - have been allocated by , 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. -

-

On success, the function returns and the - struct will be initialized as described above, or - , in which case no message is returned. On - failure, the function returns and will set - to one of:

- - - Buffer too small. - - No more memory available. - - I/O error. - - - - - interl_send(fd, to, msg) - Send a message - - int fd; - ETERM *to, *msg; - - -

This function sends an Erlang term to a process.

-

is an open descriptor to an Erlang connection.

-

is an Erlang term containing the Pid of the - intended recipient of the message.

-

is the Erlang term to be sent.

-

The function returns 1 if successful, otherwise 0 --- in - which case it will set to one of:

- - - Invalid argument: is not a valid Erlang pid. - - No more memory available. - - I/O error. - - - interl_reg_send(fd, to, msg) - Send a message to a registered name + Send a message to a registered name. int fd; char *to; @@ -377,9 +376,9 @@ typedef struct { ETERM *erl_rpc(fd, mod, fun, args) - interl_rpc_to(fd, mod, fun, args) interl_rpc_from(fd, timeout, emsg) - Remote Procedure Call + interl_rpc_to(fd, mod, fun, args) + Remote Procedure Call. int fd, timeout; char *mod, *fun; @@ -438,68 +437,37 @@ typedef struct { - interl_publish(port) - Publish a node name + interl_send(fd, to, msg) + Send a message. - int port; + int fd; + ETERM *to, *msg; -

These functions are used by a server process to register - with the local name server epmd, thereby allowing - other processes to send messages by using the registered name. - Before calling either of these functions, the process should - have called and on an open socket.

-

is the local name to register, and should be the - same as the port number that was previously bound to the socket.

-

To unregister with epmd, simply close the returned - descriptor. -

-

On success, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - to:

+

This function sends an Erlang term to a process.

+

is an open descriptor to an Erlang connection.

+

is an Erlang term containing the Pid of the + intended recipient of the message.

+

is the Erlang term to be sent.

+

The function returns 1 if successful, otherwise 0 --- in + which case it will set to one of:

+ + Invalid argument: is not a valid Erlang pid. + + No more memory available. - I/O error + I/O error. -

Additionally, values from (2) - and (2) system calls may be propagated - into . -

- - - - interl_accept(listensock, conp) - Accept a connection - - int listensock; - ErlConnect *conp; - - -

This function is used by a server process to accept a - connection from a client process.

-

is an open socket descriptor on which - has previously been called.

-

is a pointer to an struct, - described as follows:

- -

On success, is filled in with the address and - node name of the connecting client and a file descriptor is - returned. On failure, is returned and - is set to .

 - const char *erl_thiscookie() - const char *erl_thisnodename() - const char *erl_thishostname() const char *erl_thisalivename() + const char *erl_thiscookie() shorterl_thiscreation() - Retrieve some values + const char *erl_thishostname() + const char *erl_thisnodename() + Retrieve some values.

These functions can be used to retrieve information about the C Node. These values are initially set with @@ -508,22 +476,22 @@ typedef struct { interl_unpublish(alive) - Forcefully unpublish a node name + Forcefully unpublish a node name. char *alive;

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.

To unregister a node you have published, you should instead - close the descriptor that was returned by - .

+ close the descriptor that was returned by + .

-

This function is deprecated and will be removed in a future +

This function is deprecated and will be removed in a future release.

is the name of the node to unregister, i.e., the @@ -534,11 +502,43 @@ typedef struct { - struct hostent*erl_gethostbyname(name) + interl_xreceive_msg(fd, bufpp, bufsizep, emsg) + Receive and decodes a message. + + int fd; + unsigned char **bufpp; + int *bufsizep; + ErlMessage *emsg; + + +

This function is similar to . The + difference is that expects the buffer to + have been allocated by , 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. +

+

On success, the function returns and the + struct will be initialized as described above, or + , in which case no message is returned. On + failure, the function returns and will set + to one of:

+ + + Buffer too small. + + No more memory available. + + I/O error. + + + + struct hostent*erl_gethostbyaddr(addr, length, type) - struct hostent*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop) struct hostent*erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop) - Name lookup functions + struct hostent*erl_gethostbyname(name) + struct hostent*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop) + Name lookup functions. const char *name; const char *addr; @@ -567,4 +567,3 @@ typedef struct { - -- cgit v1.2.3