.TH erl_connect 3 "erl_interface  3.5.7" "Ericsson AB" "C LIBRARY FUNCTIONS"
.SH NAME
erl_connect \- Communicate with Distributed Erlang
.SH DESCRIPTION
.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 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 \fInodes/0\fR\&.

.SH EXPORTS
.LP
.B
int erl_connect_init(number, cookie, creation)
.br
.B
int erl_connect_xinit(host, alive, node, addr, cookie, creation)
.br
.RS
.TP
Types
int number;
.br
char *cookie;
.br
short creation;
.br
char *host, *alive, *node;
.br
struct in_addr *addr;
.br
.RE
.RS
.LP
These functions initialize the \fIerl_connect\fR 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 module are used\&.
.LP
\fIerl_connect_xinit()\fR stores for later use information about the node\&'s host name \fIhost\fR, alive name \fIalive\fR, node name \fInode\fR, IP address \fIaddr\fR, cookie \fIcookie\fR, and creation number \fIcreation\fR\&. \fIerl_connect_init()\fR provides an alternative interface which 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, i\&.e\&., it will not be fully qualified\&. If you need to use fully qualified (a\&.k\&.a\&. long) names, use \fIerl_connect_xinit()\fR instead\&. 
.LP
\fIhost\fR is the name of the host on which the node is running\&.
.LP
\fIalive\fR is the alivename of the node\&.
.LP
\fInode\fR is the name of the node\&. The nodename should be of the form \fIalivename@hostname\fR\&.
.LP
\fIaddr\fR is the 32-bit IP address of \fIhost\fR\&.
.LP
\fIcookie\fR is the authorization string required for access to the remote node\&. If NULL the user HOME directory is searched for a cookie file \fI\&.erlang\&.cookie\fR\&. The path to the home directory is retrieved from the environment variable \fIHOME\fR on Unix and from the \fIHOMEDRIVE\fR and \fIHOMEPATH\fR variables on Windows\&. Refer to the \fIauth\fR module for more details\&.
.LP
\fIcreation\fR helps identify 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
A C node acting as a server will be 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 the second example shown below, \fI"c17@a\&.DNS\&.name"\fR will be the resulting node name\&.
.LP
Example 1:

.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
Example 2:

.nf
if (!erl_connect_init(17, "samplecookiestring\&.\&.\&.", 0))
  erl_err_quit("<ERROR> when initializing !");
        
.fi
.RE
.LP
.B
int erl_connect(node)
.br
.B
int erl_xconnect(addr, alive)
.br
.RS
.TP
Types
char *node, *alive;
.br
struct in_addr *addr;
.br
.RE
.RS
.LP
These functions set up a connection to an Erlang node\&.
.LP
\fIerl_xconnect()\fR requires the IP address of the remote host and the alive name of the remote node to be specified\&. \fIerl_connect()\fR provides an alternative interface, and determines the information from the node name provided\&.
.LP
\fIaddr\fR is the 32-bit IP address of the remote host\&.
.LP
\fIalive\fR is the alivename of the remote node\&.
.LP
\fInode\fR is the name of the remote node\&.
.LP
These functions return an open file descriptor on success, or a negative value indicating that an error occurred --- in which case they will set \fIerl_errno\fR to one of:
.RS 2
.TP 4
.B
\fIEHOSTUNREACH\fR:
The remote host \fInode\fR is unreachable
.TP 4
.B
\fIENOMEM\fR:
No more memory available\&.
.TP 4
.B
\fIEIO\fR:
I/O error\&.
.RE
.LP
Additionally, \fIerrno\fR values from \fIsocket\fR\fI(2)\fR and \fIconnect\fR\fI(2)\fR system calls may be propagated into \fIerl_errno\fR\&.

.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_close_connection(fd)
.br
.RS
.TP
Types
int fd;
.br
.RE
.RS
.LP
This function 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
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\&.
.RE
.LP
.B
int erl_receive(fd, bufp, bufsize)
.br
.RS
.TP
Types
int fd;
.br
char *bufp;
.br
int bufsize;
.br
.RE
.RS
.LP
This function receives a message consisting of a sequence of bytes in the Erlang external format\&.
.LP
\fIfd\fR is an open descriptor to an Erlang connection\&.
.LP
\fIbufp\fR is a buffer large enough to hold the expected message\&. 
.LP
\fIbufsize\fR indicates the size of \fIbufp\fR\&.
.LP
If a \fItick\fR 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 \fIERL_TICK\fR and no message will be placed in the buffer\&. Also, \fIerl_errno\fR will be 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 will set \fIerl_errno\fR to one of:
.RS 2
.TP 4
.B
\fIEAGAIN\fR:
Temporary error: Try again\&.
.TP 4
.B
\fIEMSGSIZE\fR:
Buffer too small\&.
.TP 4
.B
\fIEIO\fR:
I/O error\&.
.RE
.RE
.LP
.B
int erl_receive_msg(fd, bufp, bufsize, emsg)
.br
.RS
.TP
Types
int fd;
.br
unsigned char *bufp;
.br
int bufsize;
.br
ErlMessage *emsg;
.br
.RE
.RS
.LP
This function receives the message into the specified buffer, and decodes into the \fI(ErlMessage *) emsg\fR\&.
.LP
\fIfd\fR is an open descriptor to an Erlang connection\&.
.LP
\fIbufp\fR is a buffer large enough to hold the expected message\&.
.LP
\fIbufsize\fR indicates the size of \fIbufp\fR\&.
.LP
\fIemsg\fR is a pointer to an \fIErlMessage\fR structure, into which the message will be decoded\&. \fIErlMessage\fR is defined as follows:

.nf
typedef struct {
  int type;
  ETERM *msg;
  ETERM *to;
  ETERM *from;
  char to_name[MAXREGLEN];
} ErlMessage;
        
.fi
.SS Note:
.LP
The definition of \fIErlMessage\fR has changed since earlier versions of Erl_Interface\&.

.LP
\fItype\fR identifies the type of message, one of \fIERL_SEND\fR, \fIERL_REG_SEND\fR, \fIERL_LINK\fR, \fIERL_UNLINK\fR and \fIERL_EXIT\fR\&. 
.LP
If \fItype\fR contains \fIERL_SEND\fR this indicates that an ordinary send operation has taken place, and \fIemsg->to\fR contains the Pid of the recipient\&. If \fItype\fR contains \fIERL_REG_SEND\fR then a registered send operation took place, and \fIemsg->from\fR contains the Pid of the sender\&. In both cases, the actual message will be in \fIemsg->msg\fR\&. 
.LP
If \fItype\fR contains one of \fIERL_LINK\fR or \fIERL_UNLINK\fR, then \fIemsg->to\fR and \fIemsg->from\fR contain the pids of the sender and receipient of the link or unlink\&. \fIemsg->msg\fR is not used in these cases\&. 
.LP
If \fItype\fR contains \fIERL_EXIT\fR, then this indicates that a link has been broken\&. In this case, \fIemsg->to\fR and \fIemsg->from\fR contain the pids of the linked processes, and \fIemsg->msg\fR contains the reason for the exit\&. 
.SS Note:
.LP
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, 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 \fIERL_TICK\fR indicating that the tick has been received and responded to, but no message will be placed in the buffer\&. In this case you should call \fIerl_receive_msg()\fR again\&.
.LP
On success, the function returns \fIERL_MSG\fR and the \fIEmsg\fR struct will be initialized as described above, or \fIERL_TICK\fR, in which case no message is returned\&. On failure, the function returns \fIERL_ERROR\fR and will set \fIerl_errno\fR to one of:
.RS 2
.TP 4
.B
\fIEMSGSIZE\fR:
Buffer too small\&.
.TP 4
.B
\fIENOMEM\fR:
No more memory available\&.
.TP 4
.B
\fIEIO\fR:
I/O error\&.
.RE
.RE
.LP
.B
int erl_xreceive_msg(fd, bufpp, bufsizep, emsg)
.br
.RS
.TP
Types
int fd;
.br
unsigned char **bufpp;
.br
int *bufsizep;
.br
ErlMessage *emsg;
.br
.RE
.RS
.LP
This function is 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\&. For that reason, both buffer and buffer length are given as pointers - their values may change by the call\&. 
.LP
On success, the function returns \fIERL_MSG\fR and the \fIEmsg\fR struct will be initialized as described above, or \fIERL_TICK\fR, in which case no message is returned\&. On failure, the function returns \fIERL_ERROR\fR and will set \fIerl_errno\fR to one of:
.RS 2
.TP 4
.B
\fIEMSGSIZE\fR:
Buffer too small\&.
.TP 4
.B
\fIENOMEM\fR:
No more memory available\&.
.TP 4
.B
\fIEIO\fR:
I/O error\&.
.RE
.RE
.LP
.B
int erl_send(fd, to, msg)
.br
.RS
.TP
Types
int fd;
.br
ETERM *to, *msg;
.br
.RE
.RS
.LP
This function sends an Erlang term to a process\&.
.LP
\fIfd\fR is an open descriptor to an Erlang connection\&.
.LP
\fIto\fR is an Erlang term containing the Pid of the intended recipient of the message\&.
.LP
\fImsg\fR is the Erlang term to be sent\&.
.LP
The function returns 1 if successful, otherwise 0 --- in which case it will set \fIerl_errno\fR to one of:
.RS 2
.TP 4
.B
\fIEINVAL\fR:
Invalid argument: \fIto\fR is not a valid Erlang pid\&.
.TP 4
.B
\fIENOMEM\fR:
No more memory available\&.
.TP 4
.B
\fIEIO\fR:
I/O error\&.
.RE
.RE
.LP
.B
int erl_reg_send(fd, to, msg)
.br
.RS
.TP
Types
int fd;
.br
char *to;
.br
ETERM *msg;
.br
.RE
.RS
.LP
This function sends an Erlang term to a registered process\&.
.LP
\fIfd\fR is an open descriptor to an Erlang connection\&.
.LP
\fIto\fR is a string containing the registered name of the intended recipient of the message\&.
.LP
\fImsg\fR is the Erlang term to be sent\&.
.LP
The function returns 1 if successful, otherwise 0 --- in which case it will set \fIerl_errno\fR to one of:
.RS 2
.TP 4
.B
\fIENOMEM\fR:
No more memory available\&.
.TP 4
.B
\fIEIO\fR:
I/O error\&.
.RE
.RE
.LP
.B
ETERM * erl_rpc(fd, mod, fun, args)
.br
.B
int erl_rpc_to(fd, mod, fun, args)
.br
.B
int erl_rpc_from(fd, timeout, emsg)
.br
.RS
.TP
Types
int fd, timeout;
.br
char *mod, *fun;
.br
ETERM *args;
.br
ErlMessage *emsg;
.br
.RE
.RS
.LP
These functions support 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 \fIrpc:call/4\fR\&. 
.LP
\fIfd\fR is an open descriptor to an Erlang connection\&.
.LP
\fItimeout\fR is the maximum time (in ms) to wait for results\&. Specify \fIERL_NO_TIMEOUT\fR to wait forever\&. When erl_rpc() calls erl_rpc_from(), the call will never timeout\&.
.LP
\fImod\fR is the name of the module containing the function to be run on the remote node\&.
.LP
\fIfun\fR is the name of the function to run\&.
.LP
\fIargs\fR is an Erlang list, containing the arguments to be passed to the function\&. 
.LP
\fIemsg\fR is a message containing the result of the function call\&.
.LP
The actual message returned by the rpc server is a 2-tuple \fI{rex, Reply}\fR\&. If you are using \fIerl_rpc_from()\fR in your code then this is the message you will need to parse\&. If you are using \fIerl_rpc()\fR then 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 ERL_SEND messages\&. 
.SS Note:
.LP
It is the caller\&'s responsibility to free the returned \fIETERM\fR structure as well as the memory pointed to by \fIemsg->msg\fR and \fIemsg->to\fR\&. 

.LP
\fIerl_rpc()\fR returns the remote function\&'s return value (or \fINULL\fR if it failed)\&. \fIerl_rpc_to()\fR returns 0 on success, and a negative number on failure\&. \fIerl_rcp_from()\fR returns \fIERL_MSG\fR when successful (with \fIEmsg\fR now containing the reply tuple), and one of \fIERL_TICK\fR, \fIERL_TIMEOUT\fR and \fIERL_ERROR\fR otherwise\&. When failing, all three functions set \fIerl_errno\fR to one of:
.RS 2
.TP 4
.B
\fIENOMEM\fR:
No more memory available\&.
.TP 4
.B
\fIEIO\fR:
I/O error\&.
.TP 4
.B
\fIETIMEDOUT\fR:
Timeout expired\&.
.TP 4
.B
\fIEAGAIN\fR:
Temporary error: Try again\&.
.RE
.RE
.LP
.B
int erl_publish(port)
.br
.RS
.TP
Types
int port;
.br
.RE
.RS
.LP
These functions are used by a server process to register with the local name server \fIepmd\fR, thereby allowing other processes to send messages by using the registered name\&. Before calling either of these functions, the process should have called \fIbind()\fR and \fIlisten()\fR on an open socket\&.
.LP
\fIport\fR is the local name to register, and should be the same as the port number that was previously bound to the socket\&.
.LP
To unregister with epmd, simply close the returned descriptor\&. See also \fIerl_unpublish()\fR\&. 
.LP
On success, the functions return a descriptor connecting the calling process to epmd\&. On failure, they return -1 and set \fIerl_errno\fR to:
.RS 2
.TP 4
.B
\fIEIO\fR:
I/O error
.RE
.LP
Additionally, \fIerrno\fR values from \fIsocket\fR\fI(2)\fR and \fIconnect\fR\fI(2)\fR system calls may be propagated into \fIerl_errno\fR\&. 
.RE
.LP
.B
int erl_accept(listensock, conp)
.br
.RS
.TP
Types
int listensock;
.br
ErlConnect *conp;
.br
.RE
.RS
.LP
This function is used by a server process to accept a connection from a client process\&.
.LP
\fIlistensock\fR is an open socket descriptor on which \fIlisten()\fR has previously been called\&.
.LP
\fIconp\fR is a pointer to an \fIErlConnect\fR struct, described as follows:

.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
const char * erl_thiscookie()
.br
.B
const char * erl_thisnodename()
.br
.B
const char * erl_thishostname()
.br
.B
const char * erl_thisalivename()
.br
.B
short erl_thiscreation()
.br
.RS
.LP
These functions can be used to retrieve 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
.TP
Types
char *alive;
.br
.RE
.RS
.LP
This function can be called by a process to unregister a specified node name 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 \fIerl_publish()\fR\&.
.SS Note:
.LP
Careless use of this function may have unpredictable results, if the registered node is in fact still running\&.

.LP
\fIalive\fR is the name of the node to unregister, i\&.e\&., the first component of the nodename, without the \fI@hostname\fR\&.
.LP
If the node was successfully unregistered from epmd, the function returns 0\&. Otherwise, it returns -1 and sets \fIerl_errno\fR is to \fIEIO\fR\&.
.RE
.LP
.B
struct hostent *erl_gethostbyname(name)
.br
.B
struct hostent *erl_gethostbyaddr(addr, length, type)
.br
.B
struct hostent *erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)
.br
.B
struct hostent *erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop)
.br
.RS
.TP
Types
const char *name;
.br
const char *addr;
.br
int lenght;
.br
int type;
.br
struct hostent *hostp;
.br
char *buffer;
.br
int buflen;
.br
int *h_errnop;
.br
.RE
.RS
.LP
These are convinience 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
.TP 2
*
that the right cookie was used
.TP 2
*
that \fIepmd\fR is running
.TP 2
*
the remote Erlang node on the other side is running the same version of Erlang as the \fIerl_interface\fR library\&.
.RE