This module enables C programs to communicate with erlang nodes, using the erlang distribution over TCP/IP.
A C node appears to Erlang as a
hidden node.
That is, Erlang processes that know the name of the
C node are able to communicate with it in a normal manner, but
the node name will not appear in the listing provided by the
Erlang function
The environment variable
Most functions appear in a version with the suffix
Obviously the timeouts are for implementing fault tolerance,
not to keep hard realtime promises. The
A timeout value of
As with all other ei functions, you are not expected to put the socket in non blocking mode yourself in the program. Every use of non blocking mode is embedded inside the timeout functions. The socket will always be back in blocking mode after 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.
In all other senses, the
These function initializes the
A C node acting as a server will be assigned a creation
number when it calls
A connection is closed by simply closing the socket. Refer to system documentation to close the socket gracefully (when there are outgoing packets before close).
This function return a negative value indicating that an error occurred.
Example 1:
Example 2:
These functions set up a connection to an Erlang 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
Additionally,
Example:
ei_connect and ei_xconnect with an optional timeout argument, see the description at the beginning of this document.
This function receives a message consisting of a sequence of bytes in the Erlang external format.
If a tick occurs, i.e., the Erlang node on the
other end of the connection has polled this node to see if it
is still alive, the function will return
On success, the message is placed in the specified buffer
and the function returns the number of bytes actually read. On
failure, the function returns
ei_receive with an optional timeout argument, see the description at the beginning of this document.
These functions receives a message to the buffer in
On success, the function returns
If
If
If
The return value is the same as for
ei_receive_msg and ei_xreceive_msg with an optional timeout argument, see the description at the beginning of this document.
This function is retained for compatibility with code generated by the interface compiler and with code following examples in the same application.
In essence the function performs the same operation as
Furthermore the function returns either ERL_TICK or the
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 not be removed not be removed in future releases without notice.
ei_receive_encoded with an optional timeout argument, see the description at the beginning of this document.
This function sends an Erlang term to a process.
The function returns 0 if successful, otherwise -1, in the
latter case it will set
ei_send with an optional timeout argument, see the description at the beginning of this document.
Works exactly as ei_send, the alternative name retained for backward compatibility. The function will not be removed without notice.
ei_send_encoded with an optional timeout argument, see the description at the beginning of this document.
This function sends an Erlang term to a registered process.
This function sends an Erlang term to a process.
The function returns 0 if successful, otherwise -1, in the
latter case it will set
Example, send the atom "ok" to the process "worker":
ei_reg_send with an optional timeout argument, see the description at the beginning of this document.
This function is retained for compatibility with code generated by the interface compiler and with code following examples in the same application.
The function works as
A suitable
num = fd;
]]>
ei_send_reg_encoded with an optional timeout argument, see the description at the beginning of this document.
These functions support calling Erlang functions on remote nodes.
Example, check to see if an erlang process is alive:
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
To unregister with epmd, simply close the returned
descriptor. See also
On success, the functions return a descriptor connecting the
calling process to epmd. On failure, they return -1 and set
Additionally,
ei_publish with an optional timeout argument, see the description at the beginning of this document.
This function is used by a server process to accept a connection from a client process.
On success,
ei_accept with an optional timeout argument, see the description at the beginning of this document.
This function can be called by a process to unregister a
specified node from epmd on the localhost. This may be
useful, for example, when epmd has not detected the failure of a
node, and will not allow the name to be reused. If you use this
function to unregister your own process, be sure to also close
the descriptor that was returned by
Careless use of this function may have unpredictable results, if the registered node is in fact still running.
If the node was successfully unregistered from epmd, the
function returns 0. Otherwise, it returns -1 and sets
ei_unpublish with an optional timeout argument, see the description at the beginning of this document.
These functions can be used to retrieve information about
the C Node. These values are initially set with
They simply fetches the appropriate field from the
This function retrieves the Pid of the C-node. Every C-node
has a (pseudo) pid used in
These are convenience functions for some common name lookup functions.
If a connection attempt fails, the following can be checked: