.TH erl_connect 3erl "erl_interface 3.13.2" "Ericsson AB" "C Library Functions"
.SH NAME
erl_connect \- Communicate with distributed Erlang.
.SH DESCRIPTION
.LP

.RS -4
.B
Note:
.RE
The support for VxWorks is deprecated as of OTP 22, and will be removed in OTP 23\&.

.LP

.RS -4
.B
Note:
.RE
The old legacy \fIerl_interface\fR\& library (functions with prefix \fIerl_\fR\&) is deprecated as of OTP 22, and will be removed in OTP 23\&. This does not apply to the \fIei\fR\& library\&. Reasonably new \fIgcc\fR\& compilers will issue deprecation warnings\&. In order to disable these warnings, define the macro \fIEI_NO_DEPR_WARN\fR\&\&.

.LP
This module provides support for communication between distributed Erlang nodes and C-nodes, in a manner that is transparent to Erlang processes\&.
.LP
A C-node appears to Erlang as a \fIhidden node\fR\&\&. That is, Erlang processes that know the name of the C-node can communicate with it in a normal manner, but the node name does not appear in the listing provided by \fB\fIerlang:nodes/0\fR\&\fR\& in \fIERTS\fR\&\&.
.SH EXPORTS
.LP
.B
int erl_accept(listensock, conp)
.br
.RS
.LP
Types:

.RS 3
int listensock;
.br
ErlConnect *conp;
.br
.RE
.RE
.RS
.LP
This function is used by a server process to accept a connection from a client process\&.
.RS 2
.TP 2
*
\fIlistensock\fR\& is an open socket descriptor on which \fIlisten()\fR\& has previously been called\&.
.LP
.TP 2
*
\fIconp\fR\& is a pointer to an \fIErlConnect\fR\& struct, described as follows:
.LP
.RE

.LP
.nf

typedef struct {
  char ipadr[4];
  char nodename[MAXNODELEN];
} ErlConnect;
        
.fi
.LP
On success, \fIconp\fR\& is filled in with the address and node name of the connecting client and a file descriptor is returned\&. On failure, \fIERL_ERROR\fR\& is returned and \fIerl_errno\fR\& is set to \fIEIO\fR\&\&.
.RE

.LP
.B
int erl_close_connection(fd)
.br
.RS
.LP
Types:

.RS 3
int fd;
.br
.RE
.RE
.RS
.LP
Closes an open connection to an Erlang node\&.
.LP
\fIFd\fR\& is a file descriptor obtained from \fIerl_connect()\fR\& or \fIerl_xconnect()\fR\&\&.
.LP
Returns \fI0\fR\& on success\&. 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\&.
.RE

.LP
.B
int erl_connect(node)
.br
.B
int erl_xconnect(addr, alive)
.br
.RS
.LP
Types:

.RS 3
char *node, *alive;
.br
struct in_addr *addr;
.br
.RE
.RE
.RS
.LP
Sets up a connection to an Erlang node\&.
.LP
\fIerl_xconnect()\fR\& requires the IP address of the remote host and the alivename of the remote node to be specified\&. \fIerl_connect()\fR\& provides an alternative interface, and determines the information from the node name provided\&.
.RS 2
.TP 2
*
\fIaddr\fR\& is the 32-bit IP address of the remote host\&.
.LP
.TP 2
*
\fIalive\fR\& is the alivename of the remote node\&. 
.LP
.TP 2
*
\fInode\fR\& is the name of the remote node\&.
.LP
.RE

.LP
Returns an open file descriptor on success, otherwise a negative value\&. In the latter case \fIerl_errno\fR\& is set to one of:
.RS 2
.TP 2
.B
\fIEHOSTUNREACH\fR\&:
The remote host \fInode\fR\& is unreachable\&.
.TP 2
.B
\fIENOMEM\fR\&:
No more memory is available\&.
.TP 2
.B
\fIEIO\fR\&:
I/O error\&.
.RE
.LP
Also, \fIerrno\fR\& values from \fIsocket\fR\&\fI(2)\fR\& and \fIconnect\fR\&\fI(2)\fR\& system calls can be propagated into \fIerl_errno\fR\&\&.
.LP
\fIExample:\fR\&
.LP
.nf

#define NODE   "madonna@chivas.du.etx.ericsson.se"
#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 );
        
.fi
.RE

.LP
.B
int erl_connect_init(number, cookie, creation)
.br
.B
int erl_connect_xinit(host, alive, node, addr, cookie, creation)
.br
.RS
.LP
Types:

.RS 3
int number;
.br
char *cookie;
.br
short creation;
.br
char *host,*alive,*node;
.br
struct in_addr *addr;
.br
.RE
.RE
.RS
.LP
Initializes the \fIerl_connect\fR\& module\&. In particular, these functions 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 \fIerl_connect\fR\& module are used\&.
.LP
\fIerl_connect_xinit()\fR\& stores for later use information about:
.RS 2
.TP 2
*
Hostname of the node, \fIhost\fR\&
.LP
.TP 2
*
Alivename, \fIalive\fR\&
.LP
.TP 2
*
Node name, \fInode\fR\&
.LP
.TP 2
*
IP address, \fIaddr\fR\&
.LP
.TP 2
*
Cookie, \fIcookie\fR\&
.LP
.TP 2
*
Creation number, \fIcreation\fR\&
.LP
.RE

.LP
\fIerl_connect_init()\fR\& provides an alternative interface that does not require as much information from the caller\&. Instead, \fIerl_connect_init()\fR\& uses \fIgethostbyname()\fR\& to obtain default values\&.
.LP
If you use \fIerl_connect_init()\fR\&, your node will have a short name, that is, it will not be fully qualified\&. If you need to use fully qualified (long) names, use \fIerl_connect_xinit()\fR\& instead\&.
.RS 2
.TP 2
*
\fIhost\fR\& is the name of the host on which the node is running\&.
.LP
.TP 2
*
\fIalive\fR\& is the alivename of the node\&.
.LP
.TP 2
*
\fInode\fR\& is the node name\&. It is to be of the form \fIalivename@hostname\fR\&\&.
.LP
.TP 2
*
\fIaddr\fR\& is the 32-bit IP address of \fIhost\fR\&\&.
.LP
.TP 2
*
\fIcookie\fR\& is the authorization string required for access to the remote node\&. If \fINULL\fR\&, the user \fIHOME\fR\& directory is searched for a cookie file \fI\&.erlang\&.cookie\fR\&\&. The path to the home directory is retrieved from environment variable \fIHOME\fR\& on Unix and from the \fIHOMEDRIVE\fR\& and \fIHOMEPATH\fR\& variables on Windows\&. For more details, see the \fB\fIauth\fR\&\fR\& module in Kernel\&.
.LP
.TP 2
*
\fIcreation\fR\& helps identifying a particular instance of a C-node\&. In particular, it can help prevent us from receiving messages sent to an earlier process with the same registered name\&.
.LP
.RE

.LP
A C-node acting as a server is assigned a creation number when it calls \fIerl_publish()\fR\&\&.
.LP
\fInumber\fR\& is used by \fIerl_connect_init()\fR\& to construct the actual node name\&. In Example 2 below, \fI"c17@a\&.DNS\&.name"\fR\& is the resulting node name\&.
.LP
\fIExample 1:\fR\&
.LP
.nf

struct in_addr addr;
addr = inet_addr("150.236.14.75");
if (!erl_connect_xinit("chivas",
                       "madonna",
                       "madonna@chivas.du.etx.ericsson.se",
                       &addr;
                       "samplecookiestring..."),
                       0)
  erl_err_quit("<ERROR> when initializing !");
        
.fi
.LP
\fIExample 2:\fR\&
.LP
.nf

if (!erl_connect_init(17, "samplecookiestring...", 0))
  erl_err_quit("<ERROR> when initializing !");
        
.fi
.RE

.LP
.B
int erl_publish(port)
.br
.RS
.LP
Types:

.RS 3
int port;
.br
.RE
.RE
.RS
.LP
This function is 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 this function, the process should have called \fIbind()\fR\& and \fIlisten()\fR\& on an open socket\&.
.LP
\fIport\fR\& is the local name to register, and is to be the same as the port number that was previously bound to the socket\&.
.LP
To unregister with EPMD, simply close the returned descriptor\&.
.LP
On success, a descriptor connecting the calling process to EPMD is returned\&. On failure, \fI-1\fR\& is returned and \fIerl_errno\fR\& is set to:
.RS 2
.TP 2
.B
\fIEIO\fR\&:
I/O error\&.
.RE
.LP
Also, \fIerrno\fR\& values from \fIsocket\fR\&\fI(2)\fR\& and \fIconnect\fR\&\fI(2)\fR\& system calls can be propagated into \fIerl_errno\fR\&\&.
.RE

.LP
.B
int erl_receive(fd, bufp, bufsize)
.br
.RS
.LP
Types:

.RS 3
int fd;
.br
char *bufp;
.br
int bufsize;
.br
.RE
.RE
.RS
.LP
Receives a message consisting of a sequence of bytes in the Erlang external format\&.
.RS 2
.TP 2
*
\fIfd\fR\& is an open descriptor to an Erlang connection\&.
.LP
.TP 2
*
\fIbufp\fR\& is a buffer large enough to hold the expected message\&.
.LP
.TP 2
*
\fIbufsize\fR\& indicates the size of \fIbufp\fR\&\&.
.LP
.RE

.LP
If a \fItick\fR\& occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it is still alive, the function returns \fIERL_TICK\fR\& and no message is placed in the buffer\&. Also, \fIerl_errno\fR\& is set to \fIEAGAIN\fR\&\&.
.LP
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 a negative value and sets \fIerl_errno\fR\& to one of:
.RS 2
.TP 2
.B
\fIEAGAIN\fR\&:
Temporary error: Try again\&.
.TP 2
.B
\fIEMSGSIZE\fR\&:
Buffer is too small\&.
.TP 2
.B
\fIEIO\fR\&:
I/O error\&.
.RE
.RE

.LP
.B
int erl_receive_msg(fd, bufp, bufsize, emsg)
.br
.RS
.LP
Types:

.RS 3
int fd;
.br
unsigned char *bufp;
.br
int bufsize;
.br
ErlMessage *emsg;
.br
.RE
.RE
.RS
.LP
Receives the message into the specified buffer and decodes into \fI(ErlMessage *) emsg\fR\&\&.
.RS 2
.TP 2
*
\fIfd\fR\& is an open descriptor to an Erlang connection\&.
.LP
.TP 2
*
\fIbufp\fR\& is a buffer large enough to hold the expected message\&.
.LP
.TP 2
*
\fIbufsize\fR\& indicates the size of \fIbufp\fR\&\&.
.LP
.TP 2
*
>\fIemsg\fR\& is a pointer to an \fIErlMessage\fR\& structure into which the message will be decoded\&. \fIErlMessage\fR\& is defined as follows:
.LP
.RE

.LP
.nf

typedef struct {
  int type;
  ETERM *msg;
  ETERM *to;
  ETERM *from;
  char to_name[MAXREGLEN];
} ErlMessage;
        
.fi
.LP

.RS -4
.B
Note:
.RE
The definition of \fIErlMessage\fR\& has changed since earlier versions of \fIErl_Interface\fR\&\&.

.LP
\fItype\fR\& identifies the type of message, one of the following:
.RS 2
.TP 2
.B
\fIERL_SEND\fR\&:
An ordinary send operation has occurred and \fIemsg->to\fR\& contains the pid of the recipient\&. The message is in \fIemsg->msg\fR\&\&.
.TP 2
.B
\fIERL_REG_SEND\fR\&:
A registered send operation has occurred and \fIemsg->from\fR\& contains the pid of the sender\&. The message is in \fIemsg->msg\fR\&\&.
.TP 2
.B
\fIERL_LINK\fR\& or \fIERL_UNLINK\fR\&:
\fIemsg->to\fR\& and \fIemsg->from\fR\& contain the pids of the sender and recipient of the link or unlink\&. \fIemsg->msg\fR\& is not used\&.
.TP 2
.B
\fIERL_EXIT\fR\&:
A link is broken\&. \fIemsg->to\fR\& and \fIemsg->from\fR\& contain the pids of the linked processes, and \fIemsg->msg\fR\& contains the reason for the exit\&.
.RE
.LP

.RS -4
.B
Note:
.RE
It is the caller\&'s responsibility to release the memory pointed to by \fIemsg->msg\fR\&, \fIemsg->to\fR\&, and \fIemsg->from\fR\&\&.

.LP
If a \fItick\fR\& occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it is still alive, the function returns \fIERL_TICK\fR\& indicating that the tick has been received and responded to, but no message is placed in the buffer\&. In this case you are to call \fIerl_receive_msg()\fR\& again\&.
.LP
On success, the function returns \fIERL_MSG\fR\& and the \fIEmsg\fR\& struct is initialized as described above, or \fIERL_TICK\fR\&, in which case no message is returned\&. On failure, the function returns \fIERL_ERROR\fR\& and sets \fIerl_errno\fR\& to one of:
.RS 2
.TP 2
.B
\fIEMSGSIZE\fR\&:
Buffer is too small\&.
.TP 2
.B
\fIENOMEM\fR\&:
No more memory is available\&.
.TP 2
.B
\fIEIO\fR\&:
I/O error\&.
.RE
.RE

.LP
.B
int erl_reg_send(fd, to, msg)
.br
.RS
.LP
Types:

.RS 3
int fd;
.br
char *to;
.br
ETERM *msg;
.br
.RE
.RE
.RS
.LP
Sends an Erlang term to a registered process\&.
.RS 2
.TP 2
*
\fIfd\fR\& is an open descriptor to an Erlang connection\&.
.LP
.TP 2
*
\fIto\fR\& is a string containing the registered name of the intended recipient of the message\&.
.LP
.TP 2
*
\fImsg\fR\& is the Erlang term to be sent\&.
.LP
.RE

.LP
Returns \fI1\fR\& on success, otherwise \fI0\fR\&\&. In the latter case \fIerl_errno\fR\& is set to one of:
.RS 2
.TP 2
.B
\fIENOMEM\fR\&:
No more memory is available\&.
.TP 2
.B
\fIEIO\fR\&:
I/O error\&.
.RE
.RE

.LP
.B
ETERM *erl_rpc(fd, mod, fun, args)
.br
.B
int erl_rpc_from(fd, timeout, emsg)
.br
.B
int erl_rpc_to(fd, mod, fun, args)
.br
.RS
.LP
Types:

.RS 3
int fd, timeout;
.br
char *mod, *fun;
.br
ETERM *args;
.br
ErlMessage *emsg;
.br
.RE
.RE
.RS
.LP
Supports calling Erlang functions on remote nodes\&. \fIerl_rpc_to()\fR\& sends an RPC request to a remote node and \fIerl_rpc_from()\fR\& receives the results of such a call\&. \fIerl_rpc()\fR\& combines the functionality of these two functions by sending an RPC request and waiting for the results\&. See also \fB\fIrpc:call/4\fR\&\fR\& in \fIKernel\fR\&\&.
.RS 2
.TP 2
*
\fIfd\fR\& is an open descriptor to an Erlang connection\&.
.LP
.TP 2
*
\fItimeout\fR\& is the maximum time (in milliseconds) to wait for results\&. To wait forever, specify \fIERL_NO_TIMEOUT\fR\&\&. When \fIerl_rpc()\fR\& calls \fIerl_rpc_from()\fR\&, the call will never timeout\&.
.LP
.TP 2
*
\fImod\fR\& is the name of the module containing the function to be run on the remote node\&.
.LP
.TP 2
*
\fIfun\fR\& is the name of the function to run\&. 
.LP
.TP 2
*
\fIargs\fR\& is an Erlang list, containing the arguments to be passed to the function\&.
.LP
.TP 2
*
\fIemsg\fR\& is a message containing the result of the function call\&.
.LP
.RE

.LP
The actual message returned by the RPC server is a 2-tuple \fI{rex,Reply}\fR\&\&. If you use \fIerl_rpc_from()\fR\& in your code, this is the message you will need to parse\&. If you use \fIerl_rpc()\fR\&, the tuple itself is parsed for you, and the message returned to your program is the Erlang term containing \fIReply\fR\& only\&. Replies to RPC requests are always \fIERL_SEND\fR\& messages\&.
.LP

.RS -4
.B
Note:
.RE
It is the caller\&'s responsibility to free the returned \fIETERM\fR\& structure and the memory pointed to by \fIemsg->msg\fR\& and \fIemsg->to\fR\&\&.

.LP
\fIerl_rpc()\fR\& returns the remote function\&'s return value on success, otherwise \fINULL\fR\&\&.
.LP
\fIerl_rpc_to()\fR\& returns \fI0\fR\& on success, otherwise a negative number\&.
.LP
\fIerl_rcp_from()\fR\& returns \fIERL_MSG\fR\& on success (with \fIEmsg\fR\& now containing the reply tuple), otherwise one of \fIERL_TICK\fR\&, \fIERL_TIMEOUT\fR\&, or \fIERL_ERROR\fR\&\&.
.LP
When failing, all three functions set \fIerl_errno\fR\& to one of:
.RS 2
.TP 2
.B
\fIENOMEM\fR\&:
No more memory is available\&.
.TP 2
.B
\fIEIO\fR\&:
I/O error\&.
.TP 2
.B
\fIETIMEDOUT\fR\&:
Timeout has expired\&.
.TP 2
.B
\fIEAGAIN\fR\&:
Temporary error: Try again\&.
.RE
.RE

.LP
.B
int erl_send(fd, to, msg)
.br
.RS
.LP
Types:

.RS 3
int fd;
.br
ETERM *to, *msg;
.br
.RE
.RE
.RS
.LP
Sends an Erlang term to a process\&.
.RS 2
.TP 2
*
\fIfd\fR\& is an open descriptor to an Erlang connection\&.
.LP
.TP 2
*
\fIto\fR\& is an Erlang term containing the pid of the intended recipient of the message\&.
.LP
.TP 2
*
>\fImsg\fR\& is the Erlang term to be sent\&.
.LP
.RE

.LP
Returns \fI1\fR\& on success, otherwise \fI0\fR\&\&. In the latter case \fIerl_errno\fR\& is set to one of:
.RS 2
.TP 2
.B
\fIEINVAL\fR\&:
Invalid argument: \fIto\fR\& is not a valid Erlang pid\&.
.TP 2
.B
\fIENOMEM\fR\&:
No more memory is available\&.
.TP 2
.B
\fIEIO\fR\&:
I/O error\&.
.RE
.RE

.LP
.B
const char *erl_thisalivename()
.br
.B
const char *erl_thiscookie()
.br
.B
short erl_thiscreation()
.br
.B
const char *erl_thishostname()
.br
.B
const char *erl_thisnodename()
.br
.RS
.LP
Retrieves information about the C-node\&. These values are initially set with \fIerl_connect_init()\fR\& or \fIerl_connect_xinit()\fR\&\&.
.RE

.LP
.B
int erl_unpublish(alive)
.br
.RS
.LP
Types:

.RS 3
char *alive;
.br
.RE
.RE
.RS
.LP
This function can be called by a process to unregister a specified node from EPMD on the local host\&. This is, however, usually not allowed, unless EPMD was started with flag \fI-relaxed_command_check\fR\&, which it normally is not\&.
.LP
To unregister a node you have published, you should instead close the descriptor that was returned by \fIei_publish()\fR\&\&.
.LP

.RS -4
.B
Warning:
.RE
This function is deprecated and will be removed in a future release\&.

.LP
\fIalive\fR\& is the name of the node to unregister, that is, the first component of the node name, without \fI@hostname\fR\&\&.
.LP
If the node was successfully unregistered from EPMD, \fI0\fR\& is returned, otherwise \fI-1\fR\& is returned and \fIerl_errno\fR\& is set to \fIEIO\fR\&\&.
.RE

.LP
.B
int erl_xreceive_msg(fd, bufpp, bufsizep, emsg)
.br
.RS
.LP
Types:

.RS 3
int fd;
.br
unsigned char **bufpp;
.br
int *bufsizep;
.br
ErlMessage *emsg;
.br
.RE
.RE
.RS
.LP
Similar to \fIerl_receive_msg\fR\&\&. The difference is that \fIerl_xreceive_msg\fR\& expects the buffer to have been allocated by \fImalloc\fR\&, and reallocates it if the received message does not fit into the original buffer\&. Therefore both buffer and buffer length are given as pointers; their values can change by the call\&.
.LP
On success, the function returns \fIERL_MSG\fR\& and the \fIEmsg\fR\& struct is initialized as described above, or \fIERL_TICK\fR\&, in which case no message is returned\&. On failure, the function returns \fIERL_ERROR\fR\& and sets \fIerl_errno\fR\& to one of:
.RS 2
.TP 2
.B
\fIEMSGSIZE\fR\&:
Buffer is too small\&.
.TP 2
.B
\fIENOMEM\fR\&:
No more memory is available\&.
.TP 2
.B
\fIEIO\fR\&:
I/O error\&.
.RE
.RE

.LP
.B
struct hostent *erl_gethostbyaddr(addr, length, type)
.br
.B
struct hostent *erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop)
.br
.B
struct hostent *erl_gethostbyname(name)
.br
.B
struct hostent *erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)
.br
.RS
.LP
Types:

.RS 3
const char *name;
.br
const char *addr;
.br
int length;
.br
int type;
.br
struct hostent *hostp;
.br
char *buffer;
.br
int buflen;
.br
int *h_errnop;
.br
.RE
.RE
.RS
.LP
Convenience functions for some common name lookup functions\&.
.RE

.SH "DEBUG INFORMATION"

.LP
If a connection attempt fails, the following can be checked:
.RS 2
.TP 2
*
\fIerl_errno\fR\&
.LP
.TP 2
*
That the correct cookie was used
.LP
.TP 2
*
That EPMD is running
.LP
.TP 2
*
That the remote Erlang node on the other side is running the same version of Erlang as the \fIerl_interface\fR\& library
.LP
.RE