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	are able to communicate	with it	 in  a
       normal  manner,	but  the node name will	not appear in the listing pro-
       vided by	the Erlang function nodes/0.

EXPORTS
       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;

	      These functions initialize the erl_connect module.  In  particu-
	      lar, 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.

	      erl_connect_xinit()  stores  for later use information about the
	      node's host name host, alive name	alive, node name node, IP  ad-
	      dress   addr,  cookie  cookie,  and  creation  number  creation.
	      erl_connect_init() provides an alternative interface which  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,
	      i.e., it will not	be fully qualified. If you need	to  use	 fully
	      qualified	(a.k.a.	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 name of the node. The	nodename should	be of the form
	      alivename@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  the  environment	variable HOME on Unix and from
	      the HOMEDRIVE and	HOMEPATH variables on Windows.	Refer  to  the
	      auth module for more details.

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

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

	      number is	used by	erl_connect_init()  to	construct  the	actual
	      node  name.  In the second example shown below, "c17@a.DNS.name"
	      will be 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_connect(node)
       int erl_xconnect(addr, alive)

	      Types:

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

	      These functions set up a connection to an	Erlang node.

	      erl_xconnect() requires the IP address of	the  remote  host  and
	      the alive	name 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.

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

		EHOSTUNREACH:
		  The remote host node is unreachable

		ENOMEM:
		  No more memory available.

		EIO:
		  I/O error.

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

	      #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_close_connection(fd)

	      Types:

		 int fd;

	      This function closes an open connection to an Erlang node.

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

	      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.

       int erl_receive(fd, bufp, bufsize)

	      Types:

		 int fd;
		 char *bufp;
		 int bufsize;

	      This  function  receives	a  message consisting of a sequence of
	      bytes in the Erlang 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,	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 ERL_TICK and	no message will	be  placed  in
	      the buffer. Also,	erl_errno will be 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 will set erl_er-
	      rno to one of:

		EAGAIN:
		  Temporary error: Try again.

		EMSGSIZE:
		  Buffer too small.

		EIO:
		  I/O error.

       int erl_receive_msg(fd, bufp, bufsize, emsg)

	      Types:

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

	      This function receives the message into  the  specified  buffer,
	      and decodes into the (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  ERL_SEND,
	      ERL_REG_SEND, ERL_LINK, ERL_UNLINK and ERL_EXIT.

	      If type contains ERL_SEND	this indicates that an	ordinary  send
	      operation	 has taken place, and emsg-_to contains	the Pid	of the
	      recipient. If type contains ERL_REG_SEND then a registered  send
	      operation	 took  place,  and  emsg-_from contains	the Pid	of the
	      sender. In both cases, the actual	message	will be	in emsg-_msg.

	      If type contains one of ERL_LINK or  ERL_UNLINK,	then  emsg-_to
	      and  emsg-_from  contain the pids	of the sender and recipient of
	      the link or unlink. emsg-_msg is not used	in these cases.

	      If type contains ERL_EXIT, then this indicates that a  link  has
	      been  broken.  In	this case, 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,	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 ERL_TICK 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 erl_receive_msg() again.

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

		EMSGSIZE:
		  Buffer too small.

		ENOMEM:
		  No more memory available.

		EIO:
		  I/O error.

       int erl_xreceive_msg(fd,	bufpp, bufsizep, emsg)

	      Types:

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

	      This  function  is similar to erl_receive_msg. The difference is
	      that erl_xreceive_msg expects the	buffer to have been  allocated
	      by  malloc,  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 ERL_MSG	and  the  Emsg	struct
	      will  be	initialized  as	described above, or ERL_TICK, in which
	      case no message is returned. On failure,	the  function  returns
	      ERL_ERROR	and will set erl_errno to one of:

		EMSGSIZE:
		  Buffer too small.

		ENOMEM:
		  No more memory available.

		EIO:
		  I/O error.

       int erl_send(fd,	to, msg)

	      Types:

		 int fd;
		 ETERM *to, *msg;

	      This function 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 recipi-
	      ent of the message.

	      msg is the Erlang	term to	be sent.

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

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

		ENOMEM:
		  No more memory available.

		EIO:
		  I/O error.

       int erl_reg_send(fd, to,	msg)

	      Types:

		 int fd;
		 char *to;
		 ETERM *msg;

	      This function 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 intended
	      recipient	of the message.

	      msg is the Erlang	term to	be sent.

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

		ENOMEM:
		  No more memory available.

		EIO:
		  I/O error.

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

	      Types:

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

	      These  functions	support	 calling  Erlang  functions  on	remote
	      nodes. erl_rpc_to() sends	an rpc request to a  remote  node  and
	      erl_rpc_from()  receives	the  results of	such a call. erl_rpc()
	      combines the functionality of these two functions	by sending  an
	      rpc request and waiting for the results. See also	rpc:call/4.

	      fd is an open descriptor to an Erlang connection.

	      timeout is the maximum time (in ms) to wait for results. Specify
	      ERL_NO_TIMEOUT   to   wait   forever.   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 are using erl_rpc_from() in your  code  then
	      this  is	the  message  you will need to parse. If you are using
	      erl_rpc()	then the tuple itself is parsed	for you, and the  mes-
	      sage  returned to	your program is	the erlang term	containing Re-
	      ply only.	Replies	to rpc requests	are always ERL_SEND messages.

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

	      erl_rpc()	returns	the remote function's return value (or NULL if
	      it  failed).  erl_rpc_to()  returns 0 on success,	and a negative
	      number on	failure. erl_rcp_from()	returns	ERL_MSG	when  success-
	      ful  (with  Emsg	now  containing	 the  reply tuple), and	one of
	      ERL_TICK,	ERL_TIMEOUT and	ERL_ERROR otherwise. When failing, all
	      three functions set erl_errno to one of:

		ENOMEM:
		  No more memory available.

		EIO:
		  I/O error.

		ETIMEDOUT:
		  Timeout expired.

		EAGAIN:
		  Temporary error: Try again.

       int erl_publish(port)

	      Types:

		 int port;

	      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 ei-
	      ther of these functions, the process should have	called	bind()
	      and listen() on an open socket.

	      port  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
	      erl_errno	to:

		EIO:
		  I/O error

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

       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 follows:

	      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.

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

	      These  functions can be used to retrieve information about the C
	      Node. These values are initially 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 localhost. This  is  however  usually
	      not  allowed,  unless  epmd  was	started	with the -relaxed_com-
	      mand_check flag, which it	normally isn't.

	      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,  i.e.,  the	 first
	      component	of the nodename, without the @hostname.

	      If  the  node was	successfully unregistered from epmd, the func-
	      tion returns 0. Otherwise, it returns -1 and sets	 erl_errno  is
	      to EIO.

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

	      Types:

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

	      These  are  convenience  functions  for  some common name	lookup
	      functions.

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

	 * erl_errno

	 * that	the right cookie was used

	 * that	epmd is	running

	 * the remote Erlang node on the other side is running the  same  ver-
	   sion	of Erlang as the erl_interface library.

Ericsson AB		     erl_interface 3.7.20		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