Provided by: erlang-manpages_22.0.7+dfsg-1build1_all bug

NAME

       erl_connect - Communicate with distributed Erlang.

DESCRIPTION

   Note:
       The support for VxWorks is deprecated as of OTP 22, and will be removed in OTP 23.

   Note:
       The  old legacy erl_interface library (functions with prefix erl_) is deprecated as of OTP
       22, and will be removed in OTP 23. This does not apply to the ei library.  Reasonably  new
       gcc  compilers will issue deprecation warnings. In order to disable these warnings, define
       the macro EI_NO_DEPR_WARN.

       This module provides support for communication between distributed  Erlang  nodes  and  C-
       nodes, in a manner that is transparent to Erlang processes.

       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 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 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_xconnect().

              Returns  0  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.

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

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

              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 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 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  function,  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 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, 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 failure,  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 contains the pid of the
                  recipient. The message is in emsg->msg.

                ERL_REG_SEND:
                  A registered send operation has occurred and emsg->from contains 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 buffer. 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 intended 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() 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 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
              program  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 containing the reply
              tuple), otherwise one of ERL_TICK, ERL_TIMEOUT, 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  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:

                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  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 specified node  from  EPMD
              on  the  local host. This is, however, usually not allowed, unless EPMD was started
              with flag -relaxed_command_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 release.

              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 returned, 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_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. 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_errnop)

              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