Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
erl_connect(3)		      C	Library	Functions		erl_connect(3)

NAME
       erl_connect - Communicate with distributed Erlang.

DESCRIPTION
       This  module provides support for communication between distributed Er-
       lang nodes and C-nodes, in a manner that	is transparent to Erlang  pro-
       cesses.

       A  C-node appears to Erlang as a	hidden node. 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
       erlang:nodes/0 in ERTS.

EXPORTS
       int erl_accept(listensock, conp)

	      Types:

		 int listensock;
		 ErlConnect *conp;

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

		* listensock  is  an  open socket descriptor on	which listen()
		  has previously been called.

		* conp is a pointer to an ErlConnect struct, described as fol-
		  lows:

	      typedef struct {
		char ipadr[4];
		char nodename[MAXNODELEN];
	      }	ErlConnect;

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

       int erl_close_connection(fd)

	      Types:

		 int fd;

	      Closes an	open connection	to an Erlang node.

	      Fd is a file descriptor obtained from erl_connect() or erl_xcon-
	      nect().

	      Returns 0	on success. If the call	fails, a non-zero value	is re-
	      turned,  and  the	 reason	for the	error can be obtained with the
	      appropriate platform-dependent call.

       int erl_connect(node)
       int erl_xconnect(addr, alive)

	      Types:

		 char *node, *alive;
		 struct	in_addr	*addr;

	      Sets up a	connection to an Erlang	node.

	      erl_xconnect() requires the IP address of	the  remote  host  and
	      the  alivename of	the remote node	to be specified. erl_connect()
	      provides an alternative interface, and determines	 the  informa-
	      tion from	the node name provided.

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

		* alive	is the alivename of the	remote node.

		* node is the name of the remote node.

	      Returns an open file descriptor on success, otherwise a negative
	      value. In	the latter case	erl_errno is set to one	of:

		EHOSTUNREACH:
		  The remote host node is unreachable.

		ENOMEM:
		  No more memory is available.

		EIO:
		  I/O error.

	      Also, errno values from socket(2)	and  connect(2)	 system	 calls
	      can be propagated	into erl_errno.

	      Example:

	      #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 );

       int erl_connect_init(number, cookie, creation)
       int erl_connect_xinit(host, alive, node,	addr, cookie, creation)

	      Types:

		 int number;
		 char *cookie;
		 short creation;
		 char *host,*alive,*node;
		 struct	in_addr	*addr;

	      Initializes  the	erl_connect module. In particular, these func-
	      tions 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.

	      erl_connect_xinit() stores for later use information about:

		* Hostname of the node,	host

		* Alivename, alive

		* Node name, node

		* IP address, addr

		* Cookie, cookie

		* Creation number, creation

	      erl_connect_init() provides an alternative interface  that  does
	      not  require  as	much  information  from	 the  caller. Instead,
	      erl_connect_init() uses gethostbyname() to obtain	 default  val-
	      ues.

	      If you use erl_connect_init(), 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	erl_connect_xinit() instead.

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

		* alive	is the alivename of the	node.

		* node	is  the	 node  name.  It  is  to be of the form	alive-
		  name@hostname.

		* addr is the 32-bit IP	address	of host.

		* cookie is the	authorization string required  for  access  to
		  the  remote  node.  If  NULL,	 the  user  HOME  directory is
		  searched for a cookie	file .erlang.cookie. The path  to  the
		  home	directory  is retrieved	from environment variable HOME
		  on Unix and from the HOMEDRIVE  and  HOMEPATH	 variables  on
		  Windows. For more details, see the auth module in Kernel.

		* creation  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.

	      A	C-node acting as a server is assigned a	creation  number  when
	      it calls erl_publish().

	      number  is  used	by  erl_connect_init() to construct the	actual
	      node name. In Example 2 below, "c17@a.DNS.name" is the resulting
	      node name.

	      Example 1:

	      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	!");

	      Example 2:

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

       int erl_publish(port)

	      Types:

		 int port;

	      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 func-
	      tion, the	process	should have called bind() and listen()	on  an
	      open socket.

	      port is the local	name to	register, and is to 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, a descriptor connecting the calling process to  EPMD
	      is returned. On failure, -1 is returned and erl_errno is set to:

		EIO:
		  I/O error.

	      Also,  errno  values  from socket(2) and connect(2) system calls
	      can be propagated	into erl_errno.

       int erl_receive(fd, bufp, bufsize)

	      Types:

		 int fd;
		 char *bufp;
		 int bufsize;

	      Receives a message consisting of a sequence of bytes in the  Er-
	      lang external format.

		* fd is	an open	descriptor to an Erlang	connection.

		* bufp is a buffer large enough	to hold	the expected message.

		* bufsize indicates the	size of	bufp.

	      If  a  tick 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  ERL_TICK and no message is placed	in the
	      buffer. Also, erl_errno is set to	EAGAIN.

	      On success, the message is placed	in the	specified  buffer  and
	      the function returns the number of bytes actually	read. On fail-
	      ure, the function	returns	a negative value and sets erl_errno to
	      one of:

		EAGAIN:
		  Temporary error: Try again.

		EMSGSIZE:
		  Buffer is too	small.

		EIO:
		  I/O error.

       int erl_receive_msg(fd, bufp, bufsize, emsg)

	      Types:

		 int fd;
		 unsigned char *bufp;
		 int bufsize;
		 ErlMessage *emsg;

	      Receives	the message into the specified buffer and decodes into
	      (ErlMessage *) emsg.

		* fd is	an open	descriptor to an Erlang	connection.

		* bufp is a buffer large enough	to hold	the expected message.

		* bufsize indicates the	size of	bufp.

		* >emsg	is a pointer to	an ErlMessage structure	into which the
		  message will be decoded. ErlMessage is defined as follows:

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

	  Note:
	      The  definition of ErlMessage has	changed	since earlier versions
	      of Erl_Interface.

	      type identifies the type of message, one of the following:

		ERL_SEND:
		  An ordinary send operation has occurred  and	emsg-_to  con-
		  tains	the pid	of the recipient. The message is in emsg-_msg.

		ERL_REG_SEND:
		  A registered send operation has occurred and emsg-_from con-
		  tains	the pid	of the sender. The message is in emsg-_msg.

		ERL_LINK or ERL_UNLINK:
		  emsg-_to and emsg-_from contain the pids of the  sender  and
		  recipient of the link	or unlink. emsg-_msg is	not used.

		ERL_EXIT:
		  A  link  is broken. emsg-_to and emsg-_from contain the pids
		  of the linked	processes, and emsg-_msg contains  the	reason
		  for the exit.

	  Note:
	      It  is the caller's responsibility to release the	memory pointed
	      to by emsg-_msg, emsg-_to, and emsg-_from.

	      If a tick	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 ERL_TICK indicating that the	tick has  been
	      received	and responded to, but no message is placed in the buf-
	      fer. In this case	you are	to call	erl_receive_msg() again.

	      On success, the function returns ERL_MSG and the Emsg struct  is
	      initialized  as  described  above, or ERL_TICK, in which case no
	      message is returned. On failure, the function returns  ERL_ERROR
	      and sets erl_errno to one	of:

		EMSGSIZE:
		  Buffer is too	small.

		ENOMEM:
		  No more memory is available.

		EIO:
		  I/O error.

       int erl_reg_send(fd, to,	msg)

	      Types:

		 int fd;
		 char *to;
		 ETERM *msg;

	      Sends an Erlang term to a	registered process.

		* fd is	an open	descriptor to an Erlang	connection.

		* to  is  a  string  containing	the registered name of the in-
		  tended recipient of the message.

		* msg is the Erlang term to be sent.

	      Returns 1	on success, otherwise 0. In the	latter case  erl_errno
	      is set to	one of:

		ENOMEM:
		  No more memory is available.

		EIO:
		  I/O error.

       ETERM *erl_rpc(fd, mod, fun, args)
       int erl_rpc_from(fd, timeout, emsg)
       int erl_rpc_to(fd, mod, fun, args)

	      Types:

		 int fd, timeout;
		 char *mod, *fun;
		 ETERM *args;
		 ErlMessage *emsg;

	      Supports	calling	Erlang functions on remote nodes. erl_rpc_to()
	      sends an RPC request to a	remote	node  and  erl_rpc_from()  re-
	      ceives  the results of such a call. erl_rpc() combines the func-
	      tionality	of these two functions by sending an RPC  request  and
	      waiting for the results. See also	rpc:call/4 in Kernel.

		* fd is	an open	descriptor to an Erlang	connection.

		* timeout  is  the  maximum time (in milliseconds) to wait for
		  results.  To	wait  forever,	specify	 ERL_NO_TIMEOUT.  When
		  erl_rpc() calls erl_rpc_from(), the call will	never timeout.

		* mod  is the name of the module containing the	function to be
		  run on the remote node.

		* fun is the name of the function to run.

		* args is an Erlang  list,  containing	the  arguments	to  be
		  passed to the	function.

		* emsg	is  a  message	containing  the	result of the function
		  call.

	      The actual message returned by  the  RPC	server	is  a  2-tuple
	      {rex,Reply}. If you use erl_rpc_from() in	your code, this	is the
	      message you will need to parse. If you use erl_rpc(), the	 tuple
	      itself  is parsed	for you, and the message returned to your pro-
	      gram is the Erlang term containing Reply only.  Replies  to  RPC
	      requests are always ERL_SEND messages.

	  Note:
	      It  is  the  caller's  responsibility to free the	returned ETERM
	      structure	and the	memory pointed to by emsg-_msg and emsg-_to.

	      erl_rpc()	returns	the remote function's return value on success,
	      otherwise	NULL.

	      erl_rpc_to() returns 0 on	success, otherwise a negative number.

	      erl_rcp_from()  returns  ERL_MSG	on success (with Emsg now con-
	      taining the reply	tuple),	otherwise one of  ERL_TICK,  ERL_TIME-
	      OUT, or ERL_ERROR.

	      When failing, all	three functions	set erl_errno to one of:

		ENOMEM:
		  No more memory is available.

		EIO:
		  I/O error.

		ETIMEDOUT:
		  Timeout has expired.

		EAGAIN:
		  Temporary error: Try again.

       int erl_send(fd,	to, msg)

	      Types:

		 int fd;
		 ETERM *to, *msg;

	      Sends an Erlang term to a	process.

		* fd is	an open	descriptor to an Erlang	connection.

		* to  is an Erlang term	containing the pid of the intended re-
		  cipient of the message.

		* >msg is the Erlang term to be	sent.

	      Returns 1	on success, otherwise 0. In the	latter case  erl_errno
	      is set to	one of:

		EINVAL:
		  Invalid argument: to is not a	valid Erlang pid.

		ENOMEM:
		  No more memory is available.

		EIO:
		  I/O error.

       const char *erl_thisalivename()
       const char *erl_thiscookie()
       short erl_thiscreation()
       const char *erl_thishostname()
       const char *erl_thisnodename()

	      Retrieves	 information  about  the C-node. These values are ini-
	      tially set with erl_connect_init() or erl_connect_xinit().

       int erl_unpublish(alive)

	      Types:

		 char *alive;

	      This function can	be called by a process to unregister a	speci-
	      fied node	from EPMD on the local host. This is, however, usually
	      not allowed, unless EPMD was  started  with  flag	 -relaxed_com-
	      mand_check, which	it normally is not.

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

	  Warning:
	      This function is deprecated and will be removed in a future  re-
	      lease.

	      alive  is	the name of the	node to	unregister, that is, the first
	      component	of the node name, without @hostname.

	      If the node was successfully unregistered	from EPMD,  0  is  re-
	      turned, otherwise	-1 is returned and erl_errno is	set to EIO.

       int erl_xreceive_msg(fd,	bufpp, bufsizep, emsg)

	      Types:

		 int fd;
		 unsigned char **bufpp;
		 int *bufsizep;
		 ErlMessage *emsg;

	      Similar  to  erl_receive_msg.  The  difference  is that erl_xre-
	      ceive_msg	expects	the buffer to have been	allocated  by  malloc,
	      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.

	      On  success, the function	returns	ERL_MSG	and the	Emsg struct is
	      initialized as described above, or ERL_TICK, in  which  case  no
	      message  is returned. On failure,	the function returns ERL_ERROR
	      and sets erl_errno to one	of:

		EMSGSIZE:
		  Buffer is too	small.

		ENOMEM:
		  No more memory is available.

		EIO:
		  I/O error.

       struct hostent *erl_gethostbyaddr(addr, length, type)
       struct hostent *erl_gethostbyaddr_r(addr, length, type, hostp,  buffer,
       buflen, h_errnop)
       struct hostent *erl_gethostbyname(name)
       struct  hostent *erl_gethostbyname_r(name, hostp, buffer, buflen, h_er-
       rnop)

	      Types:

		 const char *name;
		 const char *addr;
		 int length;
		 int type;
		 struct	hostent	*hostp;
		 char *buffer;
		 int buflen;
		 int *h_errnop;

	      Convenience functions for	some common name lookup	functions.

DEBUG INFORMATION
       If a connection attempt fails, the following can	be checked:

	 * erl_errno

	 * That	the correct cookie was used

	 * That	EPMD is	running

	 * That	the remote Erlang node on the other side is running  the  same
	   version of Erlang as	the erl_interface library

Ericsson AB		      erl_interface 3.11		erl_connect(3)

NAME | DESCRIPTION | EXPORTS | DEBUG INFORMATION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=erl_connect&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help