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

FreeBSD Manual Pages

  
 
  

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

NAME
       ei_connect - Communicate	with distributed erlang

DESCRIPTION
       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  pro-
       vided by	the Erlang function nodes/0.

       The  environment	 variable  ERL_EPMD_PORT can be	used to	indicate which
       logical cluster a C node	belongs	to.

TIMEOUT	FUNCTIONS
       Most functions appear in	a version with the suffix _tmo appended	to the
       function	name. Those function take an additional	argument, a timeout in
       milliseconds. The semantics is this; for	each  communication  primitive
       involved	 in  the  operation, if	the primitive does not complete	within
       the time	specified, the function	will return  an	 error	and  erl_errno
       will  be	set to ETIMEDOUT. With communication primitive is meant	an op-
       eration on the socket, like connect, accept, recv or send.

       Obviously the timeouts are for implementing  fault  tolerance,  not  to
       keep  hard realtime promises. The _tmo functions	are for	detecting non-
       responsive peers	and to avoid blocking on socket	operations.

       A timeout value of 0 (zero), means that timeouts	are disabled.  Calling
       a  _tmo-function	 with  the last	argument as 0 is therefore exactly the
       same thing as calling the function without the _tmo suffix.

       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 _tmo functions inherit all the return	values
       and the semantics from the functions without the	_tmo suffix.

EXPORTS
       int ei_connect_init(ei_cnode* ec,  const	 char*	this_node_name,	 const
       char *cookie, short creation)
       int ei_connect_xinit(ei_cnode* ec, const	char *thishostname, const char
       *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr,	 const
       char *cookie, short creation)

	      These  function  initializes  the	 ec structure, to identify the
	      node name	and cookie of the server. One of them has to be	called
	      before other functions that works	on the type ei_cnode or	a file
	      descriptor associated with a  connection	to  another  node  are
	      used.

	      ec is a structure	containing information about the C-node. It is
	      used in other ei functions for connecting	and receiving data.

	      this_node_name is	the registered name of the process  (the  name
	      before '@').

	      cookie is	the cookie for the node.

	      creation identifies a specific instance of a C node. It can help
	      prevent the node from receiving  messages	 sent  to  an  earlier
	      process with the same registered name.

	      thishostname  is	the  name  of the machine we're	running	on. If
	      long names are to	be used, it should be  fully  qualified	 (i.e.
	      durin.erix.ericsson.se instead of	durin).

	      thisalivename is the registered name of the process.

	      thisnodename is the full name of the node, i.e. einode@durin.

	      thispaddr	if the IP address of the host.

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

	      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:

	      int n = 0;
	      struct in_addr addr;
	      ei_cnode ec;
	      addr.s_addr = inet_addr("150.236.14.75");
	      if (ei_connect_xinit(&ec,
				   "chivas",
				   "madonna",
				   "madonna@chivas.du.etx.ericsson.se",
				   &addr;
				   "cookie...",
				   n++)	< 0) {
		  fprintf(stderr,"ERROR	when initializing: %d",erl_errno);
		  exit(-1);
	      }

	      Example 2:

	      if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) {
		  fprintf(stderr,"ERROR	when initializing: %d",erl_errno);
		  exit(-1);
	      }

       int ei_connect(ei_cnode*	ec, char *nodename)
       int ei_xconnect(ei_cnode* ec, Erl_IpAddr	adr, char *alivename)

	      These functions set up a connection to an	Erlang node.

	      ei_xconnect() requires the IP address of the remote host and the
	      alive name of the	remote node to be specified. ei_connect() pro-
	      vides  an	 alternative interface,	and determines the information
	      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.

	      Example:

	      #define NODE   "madonna@chivas.du.etx.ericsson.se"
	      #define ALIVE  "madonna"
	      #define IP_ADDR "150.236.14.75"

	      /*** Variant 1 ***/
	      int fd = ei_connect(&ec, NODE);

	      /*** Variant 2 ***/
	      struct in_addr addr;
	      addr.s_addr = inet_addr(IP_ADDR);
	      fd = ei_xconnect(&ec, &addr, ALIVE);

       int ei_connect_tmo(ei_cnode* ec,	char *nodename,	unsigned timeout_ms)
       int  ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, un-
       signed timeout_ms)

	      ei_connect and ei_xconnect with an  optional  timeout  argument,
	      see the description at the beginning of this document.

       int ei_receive(int fd, unsigned 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.	It is obtained
	      from a previous ei_connect or ei_accept.

	      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	ERL_ERROR and will  set	 erl_errno  to
	      one of:

		EAGAIN:
		  Temporary error: Try again.

		EMSGSIZE:
		  Buffer too small.

		EIO:
		  I/O error.

       int  ei_receive_tmo(int	fd, unsigned char* bufp, int bufsize, unsigned
       timeout_ms)

	      ei_receive with an optional timeout argument, see	 the  descrip-
	      tion at the beginning of this document.

       int ei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x)
       int ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)

	      These  functions	receives a message to the buffer in x. ei_xre-
	      ceive_msg	allows the buffer in x	to  grow,  but	ei_receive_msg
	      fails  if	 the message is	bigger than the	preallocated buffer in
	      x.

	      fd is an open descriptor to an Erlang connection.

	      msg is a pointer to an erlang_msg	structure and contains	infor-
	      mation on	the message received.

	      x	is buffer obtained from	ei_x_new.

	      On success, the function returns ERL_MSG and the msg struct will
	      be initialized. erlang_msg is defined as follows:

	      typedef struct {
		  long msgtype;
		  erlang_pid from;
		  erlang_pid to;
		  char toname[MAXATOMLEN+1];
		  char cookie[MAXATOMLEN+1];
		  erlang_trace token;
	      }	erlang_msg;

	      msgtype identifies the type of message, and is one of  ERL_SEND,
	      ERL_REG_SEND, ERL_LINK, ERL_UNLINK and ERL_EXIT.

	      If  msgtype is ERL_SEND this indicates that an ordinary send op-
	      eration has taken	place, and msg-_to contains the	Pid of the re-
	      cipient  (the C-node). If	type is	ERL_REG_SEND then a registered
	      send operation took place, and msg-_from contains	the Pid	of the
	      sender.

	      If msgtype is ERL_LINK or	ERL_UNLINK, then msg-_to and msg-_from
	      contain the pids of the sender and recipient of the link or  un-
	      link.

	      If msgtype is ERL_EXIT, then this	indicates that a link has been
	      broken. In this case, msg-_to and	msg-_from contain the pids  of
	      the linked processes.

	      The return value is the same as for ei_receive, see above.

       int  ei_receive_msg_tmo(int fd, erlang_msg* msg,	ei_x_buff* x, unsigned
       imeout_ms)
       int ei_xreceive_msg_tmo(int fd, erlang_msg* msg,	ei_x_buff* x, unsigned
       timeout_ms)

	      ei_receive_msg  and ei_xreceive_msg with an optional timeout ar-
	      gument, see the description at the beginning of this document.

       int ei_receive_encoded(int fd, char **mbufp,  int  *bufsz,   erlang_msg
       *msg, int *msglen)

	      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 ei_xre-
	      ceive_msg, but instead of	using an ei_x_buff, the	 function  ex-
	      pects  a pointer to a character pointer (mbufp), where the char-
	      acter pointer should point to a memory area allocated by malloc.
	      The  argument bufsz should be a pointer to an integer containing
	      the exact	size (in bytes)	of the memory area. The	 function  may
	      reallocate  the  memory  area and	will in	such cases put the new
	      size in *bufsz and update	*mbufp.

	      Furthermore the function returns either ERL_TICK or the  msgtype
	      field  of	 the erlang_msg	*msg. The actual length	of the message
	      is put in	*msglen. On error it will return a value _ 0.

	      It is recommended	to use ei_xreceive_msg instead when  possible,
	      for  the	sake  of readability. The function will	however	be re-
	      tained in	the interface for compatibility	and will  not  be  re-
	      moved not	be removed in future releases without notice.

       int  ei_receive_encoded_tmo(int	fd,  char  **mbufp,  int  *bufsz,  er-
       lang_msg	*msg, int *msglen, unsigned timeout_ms)

	      ei_receive_encoded with an optional timeout  argument,  see  the
	      description at the beginning of this document.

       int ei_send(int fd, erlang_pid* to, char* buf, int len)

	      This function sends an Erlang term to a process.

	      fd is an open descriptor to an Erlang connection.

	      to is the	Pid of the intended recipient of the message.

	      buf is the buffer	containing the term in binary format.

	      len is the length	of the message in bytes.

	      The  function returns 0 if successful, otherwise -1, in the lat-
	      ter case it will set erl_errno to	EIO.

       int ei_send_tmo(int fd, erlang_pid* to, char* buf,  int	len,  unsigned
       timeout_ms)

	      ei_send  with  an	optional timeout argument, see the description
	      at the beginning of this document.

       int ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)

	      Works exactly as ei_send,	 the  alternative  name	 retained  for
	      backward compatibility. The function will	not be removed without
	      notice.

       int ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, un-
       signed timeout_ms)

	      ei_send_encoded  with  an	optional timeout argument, see the de-
	      scription	at the beginning of this document.

       int ei_reg_send(ei_cnode* ec, int fd, char* server_name,	char* buf, int
       len)

	      This function sends an Erlang term to a registered process.

	      This function sends an Erlang term to a process.

	      fd is an open descriptor to an Erlang connection.

	      server_name is the registered name of the	intended recipient.

	      buf is the buffer	containing the term in binary format.

	      len is the length	of the message in bytes.

	      The  function returns 0 if successful, otherwise -1, in the lat-
	      ter case it will set erl_errno to	EIO.

	      Example, send the	atom "ok" to the process "worker":

	      ei_x_buff	x;
	      ei_x_new_with_version(&x);
	      ei_x_encode_atom(&x, "ok");
	      if (ei_reg_send(&ec, fd, x.buff, x.index)	< 0)
		  handle_error();

       int ei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf,
       int len,	unsigned timeout_ms)

	      ei_reg_send  with	an optional timeout argument, see the descrip-
	      tion at the beginning of this document.

       int ei_send_reg_encoded(int fd, const erlang_pid	*from, const char *to,
       const char *buf,	int len)

	      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 ei_reg_send	with one exception. Instead of
	      taking the ei_cnode as a first argument, it takes	a second argu-
	      ment,  an	 erlang_pid  which should be the process identifier of
	      the sending process (in the erlang distribution protocol).

	      A	suitable erlang_pid  can  be  constructed  from	 the  ei_cnode
	      structure	by the following example code:

			ei_cnode ec;
			erlang_pid *self;
			int fd;	/* the connection fd */
			...
			self = ei_self(&ec);
			self->num = fd;

       int  ei_send_reg_encoded_tmo(int	fd, const erlang_pid *from, const char
       *to, const char *buf, int len)

	      ei_send_reg_encoded with an optional timeout argument,  see  the
	      description at the beginning of this document.

       int ei_rpc(ei_cnode *ec,	int fd,	char *mod, char	*fun, const char *arg-
       buf, int	argbuflen, ei_x_buff *x)
       int ei_rpc_to(ei_cnode *ec, int fd, char	*mod, char  *fun,  const  char
       *argbuf,	int argbuflen)
       int  ei_rpc_from(ei_cnode  *ec,	int  fd, int timeout, erlang_msg *msg,
       ei_x_buff *x)

	      These functions  support	calling	 Erlang	 functions  on	remote
	      nodes.  ei_rpc_to()  sends  an  rpc request to a remote node and
	      ei_rpc_from() receives the results of such a call. ei_rpc() com-
	      bines the	functionality of these two functions by	sending	an rpc
	      request and waiting for the results. See also rpc:call/4.

	      ec is the	C-node structure previously initiated  by  a  call  to
	      ei_connect_init()	or ei_connect_xinit()

	      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. ei_rpc()	will  wait  infinitely
	      for the answer, i.e. the call will never time out.

	      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.

	      argbuf is	a pointer to a buffer with  an	encoded	 Erlang	 list,
	      without  a  version magic	number,	containing the arguments to be
	      passed to	the function.

	      argbuflen	is the length of the buffer containing the encoded Er-
	      lang list.

	      msg structure of type erlang_msg and contains information	on the
	      message received.	See ei_receive_msg() for a description of  the
	      erlang_msg format.

	      x	points to the dynamic buffer that receives the result. For for
	      ei_rpc() this will be the	result without the version magic  num-
	      ber.  For	 ei_rpc_from()	the result will	return a version magic
	      number and a 2-tuple {rex,Reply}.

	      ei_rpc() returns the number of bytes in the  result  on  success
	      and  -1 on failure. ei_rpc_from()	returns	number of bytes	or one
	      of ERL_TICK, ERL_TIMEOUT and ERL_ERROR otherwise.	When  failing,
	      all three	functions set erl_errno	to one of:

		EIO:
		  I/O error.

		ETIMEDOUT:
		  Timeout expired.

		EAGAIN:
		  Temporary error: Try again.

	      Example, check to	see if an erlang process is alive:

	      int index	= 0, is_alive;
	      ei_x_buff	args, result;

	      ei_x_new(&result);
	      ei_x_new(&args);
	      ei_x_encode_list_header(&args, 1);
	      ei_x_encode_pid(&args, &check_pid);
	      ei_x_encode_empty_list(&args);

	      if (ei_rpc(&ec, fd, "erlang", "is_process_alive",
			 args.buff, args.index,	&result) < 0)
		  handle_error();

	      if (ei_decode_version(result.buff, &index) < 0
		  || ei_decode_bool(result.buff, &index, &is_alive) < 0)
		  handle_error();

       int ei_publish(ei_cnode *ec, 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.

	      ec is the	C-node structure.

	      port  is	the  local name	to register, and should	be the same as
	      the port number that was previously bound	to the socket.

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

	      To unregister with epmd, simply close the	 returned  descriptor.
	      Do not use ei_unpublish(), which is deprecated anyway.

	      On  success,  the	 functions  return a descriptor	connecting the
	      calling process to epmd. On failure,  they  return  -1  and  set
	      erl_errno	to EIO.

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

       int ei_publish_tmo(ei_cnode *ec,	int port, unsigned timeout_ms)

	      ei_publish with an optional timeout argument, see	 the  descrip-
	      tion at the beginning of this document.

       int ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)

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

	      ec is the	C-node structure.

	      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.

       int  ei_accept_tmo(ei_cnode  *ec, int listensock, ErlConnect *conp, un-
       signed timeout_ms)

	      ei_accept	with an	optional timeout argument, see the description
	      at the beginning of this document.

       int ei_unpublish(ei_cnode *ec)

	      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  close  the
	      descriptor that was returned by ei_publish().

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

	      ec is the	node structure of the node to unregister.

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

       int ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)

	      ei_unpublish with	an optional timeout argument, see the descrip-
	      tion at the beginning of this document.

       const char *ei_thisnodename(ei_cnode *ec)
       const char *ei_thishostname(ei_cnode *ec)
       const char *ei_thisalivename(ei_cnode *ec)

	      These  functions can be used to retrieve information about the C
	      Node. These values are initially set with	 ei_connect_init()  or
	      ei_connect_xinit().

	      They simply fetches the appropriate field	from the ec structure.
	      Read the field directly will probably be safe for	a  long	 time,
	      so these functions are not really	needed.

       erlang_pid *ei_self(ei_cnode *ec)

	      This  function retrieves the Pid of the C-node. Every C-node has
	      a	(pseudo) pid used in ei_send_reg, ei_rpc and others.  This  is
	      contained	 in a field in the ec structure. It will be safe for a
	      long time	to fetch this field directly from the ei_cnode	struc-
	      ture.

       struct hostent *ei_gethostbyname(const char *name)
       struct hostent *ei_gethostbyaddr(const char *addr, int len, int type)
       struct  hostent	*ei_gethostbyname_r(const  char	*name,	struct hostent
       *hostp,	char *buffer,  int buflen,  int	*h_errnop)
       struct hostent *ei_gethostbyaddr_r(const	char *addr, int	 length,   int
       type,   struct  hostent *hostp, char *buffer,   int buflen,  int	*h_er-
       rnop)

	      These are	convenience functions  for  some  common  name	lookup
	      functions.

       int ei_get_tracelevel(void)
       void ei_set_tracelevel(int level)

	      These functions are used to set tracing on the distribution. The
	      levels are different verbosity levels. A higher level means more
	      information. See also Debug Information and EI_TRACELEVEL	below.

	      ei_set_tracelevel	and ei_get_tracelevel are not thread safe.

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 ei library.

	 * the environment variable ERL_EPMD_PORT is set correctly.

       The connection attempt can be traced by setting a tracelevel by	either
       using   ei_set_tracelevel   or  by  setting  the	 environment  variable
       EI_TRACELEVEL. The different tracelevels	has the	following messages:

	 * 1: Verbose error messages

	 * 2: Above messages and verbose warning messages

	 * 3: Above messages and progress reports for connection handling

	 * 4: Above messages and progress reports for communication

	 * 5: Above messages and progress reports for data conversion

Ericsson AB		     erl_interface 3.7.20		 ei_connect(3)

NAME | DESCRIPTION | TIMEOUT FUNCTIONS | EXPORTS | DEBUG INFORMATION

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

home | help