1ei_connect(3)                 C Library Functions                ei_connect(3)
2
3
4

NAME

6       ei_connect - Communicate with distributed Erlang.
7

DESCRIPTION

9   Note:
10       The support for VxWorks is deprecated as of OTP 22, and will be removed
11       in OTP 23.
12
13
14       This module enables C-programs to communicate with Erlang nodes,  using
15       the Erlang distribution over TCP/IP.
16
17       A  C-node appears to Erlang as a hidden node. That is, Erlang processes
18       that know the name of the C-node can communicate with it  in  a  normal
19       manner,  but  the  node  name  is  not shown in the listing provided by
20       erlang:nodes/0 in ERTS.
21
22       The environment variable ERL_EPMD_PORT can be used  to  indicate  which
23       logical cluster a C-node belongs to.
24

TIME-OUT FUNCTIONS

26       Most functions appear in a version with the suffix _tmo appended to the
27       function name. Those functions take an extra argument,  a  time-out  in
28       milliseconds.  The  semantics is this: for each communication primitive
29       involved in the operation, if the primitive does  not  complete  within
30       the  time specified, the function returns an error and erl_errno is set
31       to ETIMEDOUT. With communication primitive is meant an operation on the
32       socket, like connect, accept, recv, or send.
33
34       Clearly the time-outs are for implementing fault tolerance, not to keep
35       hard real-time promises. The _tmo  functions  are  for  detecting  non-
36       responsive peers and to avoid blocking on socket operations.
37
38       A time-out value of 0 (zero) means that time-outs are disabled. Calling
39       a _tmo function with the last argument as 0 is therefore the same thing
40       as calling the function without the _tmo suffix.
41
42       As  with all other functions starting with ei_, you are not expected to
43       put the socket in non-blocking mode yourself in the program. Every  use
44       of  non-blocking  mode  is  embedded inside the time-out functions. The
45       socket will always be back in blocking mode after  the  operations  are
46       completed  (regardless  of  the  result).  To avoid problems, leave the
47       socket options alone. ei handles any socket options that need modifica‐
48       tion.
49
50       In  all  other senses, the _tmo functions inherit all the return values
51       and the semantics from the functions without the _tmo suffix.
52

USER SUPPLIED SOCKET IMPLEMENTATION

54       By default ei supplies a TCP/IPv4 socket interface that  is  used  when
55       communicating.  The  user  can  however plug in his/her own IPv4 socket
56       implementation. This, for example, in order to communicate over TLS.  A
57       user supplied socket implementation is plugged in by passing a callback
58       structure to either ei_connect_init_ussi() or ei_connect_xinit_ussi().
59
60       All callbacks in the ei_socket_callbacks structure should  return  zero
61       on success; and a posix error code on failure.
62
63       The addr argument of the listen, accept, and connect callbacks refer to
64       appropriate address structure for currently used protocol. Currently ei
65       only  supports  IPv4.  That  is,  at  this time addr always points to a
66       struct sockaddr_in structure.
67
68       The ei_socket_callbacks structure may be enlarged in  the  future.  All
69       fields not set, needs to be zeroed out.
70
71       typedef struct {
72           int flags;
73           int (*socket)(void **ctx, void *setup_ctx);
74           int   (*close)(void *ctx);
75           int (*listen)(void *ctx, void *addr, int *len, int backlog);
76           int (*accept)(void **ctx, void *addr, int *len, unsigned tmo);
77           int (*connect)(void *ctx, void *addr, int len, unsigned tmo);
78           int (*writev)(void *ctx, const void *iov, int iovcnt, ssize_t *len, unsigned tmo);
79           int (*write)(void *ctx, const char *buf, ssize_t *len, unsigned tmo);
80           int (*read)(void *ctx, char *buf, ssize_t *len, unsigned tmo);
81           int (*handshake_packet_header_size)(void *ctx, int *sz);
82           int (*connect_handshake_complete)(void *ctx);
83           int (*accept_handshake_complete)(void *ctx);
84           int (*get_fd)(void *ctx, int *fd);
85       } ei_socket_callbacks;
86
87
88         flags:
89           Flags  informing  ei  about  the  behaviour of the callbacks. Flags
90           should be bitwise or:ed together. If no flag,  is  set,  the  flags
91           field should contain 0. Currently, supported flags:
92
93           EI_SCLBK_FLG_FULL_IMPL:
94             If  set,  the  accept(), connect(), writev(), write(), and read()
95             callbacks implements timeouts. The timeout is passed in  the  tmo
96             argument  and  is given in milli seconds. Note that the tmo argu‐
97             ment to these callbacks differ from the timeout arguments in  the
98             ei  API.  Zero  means  a  zero timeout. That is, poll and timeout
99             immediately unless the operation is successful.  EI_SCLBK_INF_TMO
100             (max  unsigned) means infinite timeout. The file descriptor is in
101             blocking mode when a callback is called, and it must be in block‐
102             ing mode when the callback returns.
103
104             If not set, ei will implement the timeout using select() in order
105             to determine when to call the callbacks and when to time out. The
106             tmo  arguments of the accept(), connect(), writev(), write(), and
107             read() callbacks should be ignored. The callbacks may  be  called
108             in  non-blocking  mode.  The  callbacks are not allowed to change
109             between blocking and non-blocking mode.  In  order  for  this  to
110             work,  select() needs to interact with the socket primitives used
111             the same way as it interacts with the ordinary socket primitives.
112             If this is not the case, the callbacks need to implement timeouts
113             and this flag should be set.
114
115           More flags may be introduced in the future.
116
117         int (*socket)(void **ctx, void *setup_ctx):
118           Create a socket and a context for the socket.
119
120           On success it should set *ctx to point to a context for the created
121           socket.  This context will be passed to all other socket callbacks.
122           This function will be passed the same setup_context  as  passed  to
123           the  preceeding  ei_connect_init_ussi()  or ei_connect_xinit_ussi()
124           call.
125
126     Note:
127         During the lifetime of a socket, the pointer *ctx has to  remain  the
128         same. That is, it cannot later be relocated.
129
130
131           This callback is mandatory.
132
133         int (*close)(void *ctx):
134           Close the socket identified by ctx and destroy the context.
135
136           This callback is mandatory.
137
138         int (*listen)(void *ctx, void *addr, int *len, int backlog):
139           Bind  the  socket  identified  by ctx to a local interface and then
140           listen on it.
141
142           The addr and len arguments are both  input  and  output  arguments.
143           When called addr points to an address structure of lenght *len con‐
144           taining information on how to bind the socket.  Uppon  return  this
145           callback  should  have  updated the structure referred by addr with
146           information on how the socket actually was bound.  *len  should  be
147           updated  to  reflect  the size of *addr updated. backlog identifies
148           the size of the backlog for the listen socket.
149
150           This callback is mandatory.
151
152         int (*accept)(void **ctx, void *addr, int *len, unsigned tmo):
153           Accept connections on the listen socket identified by *ctx.
154
155           When a connection is accepted, a new context for the accepted  con‐
156           nection  should  be  created and *ctx should be updated to point to
157           the new context for  the  accepted  connection.  When  called  addr
158           points  to an uninitialized address structure of lenght *len. Uppon
159           return this callback should have updated this structure with infor‐
160           mation  about the client address. *len should be updated to reflect
161           the size of *addr updated.
162
163           If the EI_SCLBK_FLG_FULL_IMPL flag has been set, tmo contains time‐
164           out time in milliseconds.
165
166     Note:
167         During  the  lifetime of a socket, the pointer *ctx has to remain the
168         same. That is, it cannot later be relocated.
169
170
171           This callback is mandatory.
172
173         int (*connect)(void *ctx, void *addr, int len, unsigned tmo):
174           Connect the socket identified by ctx to the address  identified  by
175           addr.
176
177           When  called addr points to an address structure of lenght len con‐
178           taining information on where to connect.
179
180           If the EI_SCLBK_FLG_FULL_IMPL flag has been set, tmo contains time‐
181           out time in milliseconds.
182
183           This callback is mandatory.
184
185         int  (*writev)(void *ctx, const void *iov, long iovcnt, ssize_t *len,
186         unsigned tmo):
187           Write data on the connected socket identified by ctx.
188
189           iov points to an array of struct iovec structures of length  iovcnt
190           containing  data  to write to the socket. On success, this callback
191           should set *len to the amount of bytes successfully written on  the
192           socket.
193
194           If the EI_SCLBK_FLG_FULL_IMPL flag has been set, tmo contains time‐
195           out time in milliseconds.
196
197           This callback  is  optional.  Set  the  writev  field  in  the  the
198           ei_socket_callbacks structure to NULL if not implemented.
199
200         int (*write)(void *ctx, const char *buf, ssize_t *len, unsigned tmo):
201           Write data on the connected socket identified by ctx.
202
203           When  called  buf  points to a buffer of length *len containing the
204           data to write on the socket. On success, this callback  should  set
205           *len to the amount of bytes successfully written on the socket.
206
207           If the EI_SCLBK_FLG_FULL_IMPL flag has been set, tmo contains time‐
208           out time in milliseconds.
209
210           This callback is mandatory.
211
212         int (*read)(void *ctx, char *buf, ssize_t *len, unsigned tmo):
213           Read data on the connected socket identified by ctx.
214
215           buf points to a buffer of length *len where the read data should be
216           placed.  On success, this callback should update *len to the amount
217           of bytes successfully read on the socket.
218
219           If the EI_SCLBK_FLG_FULL_IMPL flag has been set, tmo contains time‐
220           out time in milliseconds.
221
222           This callback is mandatory.
223
224         int (*handshake_packet_header_size)(void *ctx, int *sz):
225           Inform  about handshake packet header size to use during the Erlang
226           distribution handshake.
227
228           On success, *sz should be set to the handshake packet  header  size
229           to  use.  Valid  values  are 2 and 4. Erlang TCP distribution use a
230           handshake packet size of 2 and Erlang TLS distribution use a  hand‐
231           shake packet size of 4.
232
233           This callback is mandatory.
234
235         int (*connect_handshake_complete)(void *ctx):
236           Called when a locally started handshake has completed successfully.
237
238           This callback is optional. Set the connect_handshake_complete field
239           in the ei_socket_callbacks structure to NULL if not implemented.
240
241         int (*accept_handshake_complete)(void *ctx):
242           Called when a remotely started  handshake  has  completed  success‐
243           fully.
244
245           This  callback is optional. Set the accept_handshake_complete field
246           in the ei_socket_callbacks structure to NULL if not implemented.
247
248         int (*get_fd)(void *ctx, int *fd):
249           Inform about file descriptor used by the socket which is identified
250           by ctx.
251
252     Note:
253         During  the  lifetime  of a socket, the file descriptor has to remain
254         the same. That is, repeated calls to this callback with the same con‐
255         text should always report the same file descriptor.
256
257         The  file  descriptor  has  to be a real file descriptor. That is, no
258         other operation should be able to get the same file descriptor  until
259         it has been released by the close() callback.
260
261
262           This callback is mandatory.
263

EXPORTS

265       struct hostent *ei_gethostbyaddr(const char *addr, int len, int type)
266       struct  hostent  *ei_gethostbyaddr_r(const char *addr, int length,  int
267       type,   struct  hostent  *hostp,  char  *buffer,    int  buflen,    int
268       *h_errnop)
269       struct hostent *ei_gethostbyname(const char *name)
270       struct  hostent  *ei_gethostbyname_r(const  char *name,  struct hostent
271       *hostp,  char *buffer,  int buflen,  int *h_errnop)
272
273              Convenience functions for some common name lookup functions.
274
275       int ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)
276
277              Used by a server process to accept a connection  from  a  client
278              process.
279
280                * ec is the C-node structure.
281
282                * listensock  is  an  open socket descriptor on which listen()
283                  has previously been called.
284
285                * conp is a pointer to an ErlConnect struct, described as fol‐
286                  lows:
287
288                typedef struct {
289                  char ipadr[4];
290                  char nodename[MAXNODELEN];
291                } ErlConnect;
292
293
294              On  success, conp is filled in with the address and node name of
295              the connecting client and a  file  descriptor  is  returned.  On
296              failure, ERL_ERROR is returned and erl_errno is set to EIO.
297
298       int  ei_accept_tmo(ei_cnode  *ec,  int  listensock,  ErlConnect  *conp,
299       unsigned timeout_ms)
300
301              Equivalent to ei_accept with an optional time-out argument,  see
302              the description at the beginning of this manual page.
303
304       int ei_close_connection(int fd)
305
306              Closes a previously opened connection or listen socket.
307
308       int ei_connect(ei_cnode* ec, char *nodename)
309       int ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)
310
311              Sets up a connection to an Erlang node.
312
313              ei_xconnect() requires the IP address of the remote host and the
314              alive name of the remote node to be specified. ei_connect() pro‐
315              vides  an  alternative  interface and determines the information
316              from the node name provided.
317
318                * addr is the 32-bit IP address of the remote host.
319
320                * alive is the alivename of the remote node.
321
322                * node is the name of the remote node.
323
324              These functions return an open file descriptor on success, or  a
325              negative  value indicating that an error occurred. In the latter
326              case they set erl_errno to one of the following:
327
328                EHOSTUNREACH:
329                  The remote host node is unreachable.
330
331                ENOMEM:
332                  No more memory is available.
333
334                EIO:
335                  I/O error.
336
337              Also, errno values from socket(2) and  connect(2)  system  calls
338              may be propagated into erl_errno.
339
340              Example:
341
342              #define NODE   "madonna@chivas.du.etx.ericsson.se"
343              #define ALIVE  "madonna"
344              #define IP_ADDR "150.236.14.75"
345
346              /*** Variant 1 ***/
347              int fd = ei_connect(&ec, NODE);
348
349              /*** Variant 2 ***/
350              struct in_addr addr;
351              addr.s_addr = inet_addr(IP_ADDR);
352              fd = ei_xconnect(&ec, &addr, ALIVE);
353
354
355       int  ei_connect_init(ei_cnode*  ec,  const  char* this_node_name, const
356       char *cookie, short creation)
357       int  ei_connect_init_ussi(ei_cnode*  ec,  const  char*  this_node_name,
358       const  char  *cookie,  short  creation,  ei_socket_callbacks  *cbs, int
359       cbs_sz, void *setup_context)
360       int ei_connect_xinit(ei_cnode* ec, const char *thishostname, const char
361       *thisalivename,  const char *thisnodename, Erl_IpAddr thisipaddr, const
362       char *cookie, short creation)
363       int ei_connect_xinit_ussi(ei_cnode* ec, const char *thishostname, const
364       char  *thisalivename,  const char *thisnodename, Erl_IpAddr thisipaddr,
365       const char  *cookie,  short  creation,  ei_socket_callbacks  *cbs,  int
366       cbs_sz, void *setup_context)
367
368              Initializes  the  ec  structure,  to  identify the node name and
369              cookie of the server. One of them must be  called  before  other
370              functions  that  works on the ei_cnode type or a file descriptor
371              associated with a connection to another node is used.
372
373                * ec is a structure containing information about  the  C-node.
374                  It  is used in other ei functions for connecting and receiv‐
375                  ing data.
376
377                * this_node_name is the registered name of  the  process  (the
378                  name before '@').
379
380                * cookie is the cookie for the node.
381
382                * creation  identifies a specific instance of a C-node. It can
383                  help prevent the node from receiving  messages  sent  to  an
384                  earlier process with the same registered name.
385
386                * thishostname  is  the name of the machine we are running on.
387                  If long names are to be used, they are to be fully qualified
388                  (that is, durin.erix.ericsson.se instead of durin).
389
390                * thisalivename is the registered name of the process.
391
392                * thisnodename  is  the  full  name of the node, that is, ein‐
393                  ode@durin.
394
395                * thispaddr if the IP address of the host.
396
397                * cbs is a pointer to a callback  structure  implementing  and
398                  alternative socket interface.
399
400                * cbs_sz is the size of the structure pointed to by cbs.
401
402                * setup_context  is  a  pointer  to  a  structure that will be
403                  passed as second argument to the socket callback in the  cbs
404                  structure.
405
406              A  C-node  acting as a server is assigned a creation number when
407              it calls ei_publish().
408
409              A connection is closed by simply closing the socket. For  infor‐
410              mation  about how to close the socket gracefully (when there are
411              outgoing packets before close), see the relevant system documen‐
412              tation.
413
414              These functions return a negative value indicating that an error
415              occurred.
416
417              Example 1:
418
419              int n = 0;
420              struct in_addr addr;
421              ei_cnode ec;
422              addr.s_addr = inet_addr("150.236.14.75");
423              if (ei_connect_xinit(&ec,
424                                   "chivas",
425                                   "madonna",
426                                   "madonna@chivas.du.etx.ericsson.se",
427                                   &addr;
428                                   "cookie...",
429                                   n++) < 0) {
430                  fprintf(stderr,"ERROR when initializing: %d",erl_errno);
431                  exit(-1);
432              }
433
434
435              Example 2:
436
437              if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) {
438                  fprintf(stderr,"ERROR when initializing: %d",erl_errno);
439                  exit(-1);
440              }
441
442
443       int ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)
444       int ei_xconnect_tmo(ei_cnode*  ec,  Erl_IpAddr  adr,  char  *alivename,
445       unsigned timeout_ms)
446
447              Equivalent  to ei_connect and ei_xconnect with an optional time-
448              out argument, see the description at the beginning of this  man‐
449              ual page.
450
451       int ei_get_tracelevel(void)
452       void ei_set_tracelevel(int level)
453
454              Used  to set tracing on the distribution. The levels are differ‐
455              ent verbosity levels. A higher level means more information. See
456              also section  Debug Information.
457
458              These functions are not thread safe.
459
460       int ei_listen(ei_cnode *ec, int *port, int backlog)
461       int ei_xlisten(ei_cnode *ec, Erl_IpAddr adr, int *port, int backlog)
462
463              Used  by  a  server process to setup a listen socket which later
464              can be used for accepting connections from client processes.
465
466                * ec is the C-node structure.
467
468                * adr is local interface to bind to.
469
470                * port is a pointer to an integer containing the  port  number
471                  to  bind to. If *port equals 0 when calling ei_listen(), the
472                  socket will be bound  to  an  ephemeral  port.  On  success,
473                  ei_listen() will update the value of *port to the port actu‐
474                  ally bound to.
475
476                * backlog is maximum backlog of pending connections.
477
478              ei_listen will create a socket, bind to  a  port  on  the  local
479              interface  identified by adr (or all local interfaces if ei_lis‐
480              ten() is called), and mark the socket as a passive socket  (that
481              is,  a  socket  that will be used for accepting incoming connec‐
482              tions).
483
484              On success, a file descriptor is returned which can be used in a
485              call  to  ei_accept().  On  failure,  ERL_ERROR  is returned and
486              erl_errno is set to EIO.
487
488       int ei_publish(ei_cnode *ec, int port)
489
490              Used by a server process to register with the local name  server
491              EPMD, thereby allowing other processes to send messages by using
492              the registered name. Before calling either of  these  functions,
493              the  process  should  have called bind() and listen() on an open
494              socket.
495
496                * ec is the C-node structure.
497
498                * port is the local name to register, and is to be the same as
499                  the port number that was previously bound to the socket.
500
501                * addr is the 32-bit IP address of the local host.
502
503              To  unregister  with EPMD, simply close the returned descriptor.
504              Do not use ei_unpublish(), which is deprecated anyway.
505
506              On success, the function returns  a  descriptor  connecting  the
507              calling  process  to  EPMD.  On  failure,  -1  is  returned  and
508              erl_errno is set to EIO.
509
510              Also, errno values from socket(2) and  connect(2)  system  calls
511              may be propagated into erl_errno.
512
513       int ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)
514
515              Equivalent to ei_publish with an optional time-out argument, see
516              the description at the beginning of this manual page.
517
518       int ei_receive(int fd, unsigned char* bufp, int bufsize)
519
520              Receives a message consisting of a  sequence  of  bytes  in  the
521              Erlang external format.
522
523                * fd  is  an  open  descriptor  to an Erlang connection. It is
524                  obtained from a previous ei_connect or ei_accept.
525
526                * bufp is a buffer large enough to hold the expected message.
527
528                * bufsize indicates the size of bufp.
529
530              If a tick occurs, that is, the Erlang node on the other  end  of
531              the connection has polled this node to see if it is still alive,
532              the function returns ERL_TICK and no message is  placed  in  the
533              buffer. Also, erl_errno is set to EAGAIN.
534
535              On  success,  the  message is placed in the specified buffer and
536              the function returns the number of bytes actually read. On fail‐
537              ure, the function returns ERL_ERROR and sets erl_errno to one of
538              the following:
539
540                EAGAIN:
541                  Temporary error: Try again.
542
543                EMSGSIZE:
544                  Buffer is too small.
545
546                EIO:
547                  I/O error.
548
549       int ei_receive_encoded(int fd, char **mbufp,  int  *bufsz,   erlang_msg
550       *msg, int *msglen)
551
552              This  function is retained for compatibility with code generated
553              by the interface compiler and with code  following  examples  in
554              the same application.
555
556              In  essence, the function performs the same operation as ei_xre‐
557              ceive_msg, but instead  of  using  an  ei_x_buff,  the  function
558              expects  a  pointer  to  a  character pointer (mbufp), where the
559              character pointer is to point to a memory area allocated by mal‐
560              loc.  Argument bufsz is to be a pointer to an integer containing
561              the exact size (in bytes) of the memory area. The  function  may
562              reallocate  the  memory  area and will in such cases put the new
563              size in *bufsz and update *mbufp.
564
565              Returns either ERL_TICK or the msgtype field of  the  erlang_msg
566              *msg.  The  length  of the message is put in *msglen. On error a
567              value < 0 is returned.
568
569              It is recommended to use ei_xreceive_msg instead when  possible,
570              for  the  sake  of  readability.  However,  the function will be
571              retained in the interface for  compatibility  and  will  not  be
572              removed in future releases without prior notice.
573
574       int   ei_receive_encoded_tmo(int   fd,   char   **mbufp,   int  *bufsz,
575       erlang_msg *msg, int *msglen, unsigned timeout_ms)
576
577              Equivalent to ei_receive_encoded with an optional time-out argu‐
578              ment, see the description at the beginning of this manual page.
579
580       int ei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x)
581       int ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)
582
583              Receives  a  message  to the buffer in x. ei_xreceive_msg allows
584              the buffer in x to grow, but ei_receive_msg fails if the message
585              is larger than the pre-allocated buffer in x.
586
587                * fd is an open descriptor to an Erlang connection.
588
589                * msg  is  a  pointer  to an erlang_msg structure and contains
590                  information on the message received.
591
592                * x is buffer obtained from ei_x_new.
593
594              On success, the functions return ERL_MSG and the msg  struct  is
595              initialized. erlang_msg is defined as follows:
596
597              typedef struct {
598                  long msgtype;
599                  erlang_pid from;
600                  erlang_pid to;
601                  char toname[MAXATOMLEN+1];
602                  char cookie[MAXATOMLEN+1];
603                  erlang_trace token;
604              } erlang_msg;
605
606
607              msgtype  identifies  the type of message, and is one of the fol‐
608              lowing:
609
610                ERL_SEND:
611                  Indicates that an  ordinary  send  operation  has  occurred.
612                  msg->to contains the pid of the recipient (the C-node).
613
614                ERL_REG_SEND:
615                  A registered send operation occurred. msg->from contains the
616                  pid of the sender.
617
618                ERL_LINK or ERL_UNLINK:
619                  msg->to and msg->from contain the pids  of  the  sender  and
620                  recipient of the link or unlink.
621
622                ERL_EXIT:
623                  Indicates  a  broken link. msg->to and msg->from contain the
624                  pids of the linked processes.
625
626              The return value is the same as for ei_receive.
627
628       int ei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x,  unsigned
629       imeout_ms)
630       int ei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned
631       timeout_ms)
632
633              Equivalent  to  ei_receive_msg  and  ei_xreceive_msg   with   an
634              optional time-out argument, see the description at the beginning
635              of this manual page.
636
637       int ei_receive_tmo(int fd, unsigned char* bufp, int  bufsize,  unsigned
638       timeout_ms)
639
640              Equivalent to ei_receive with an optional time-out argument, see
641              the description at the beginning of this manual page.
642
643       int ei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int
644       len)
645
646              Sends an Erlang term to a registered process.
647
648                * fd is an open descriptor to an Erlang connection.
649
650                * server_name  is  the registered name of the intended recipi‐
651                  ent.
652
653                * buf is the buffer containing the term in binary format.
654
655                * len is the length of the message in bytes.
656
657              Returns 0 if successful, otherwise -1. In  the  latter  case  it
658              sets erl_errno to EIO.
659
660              Example:
661
662              Send the atom "ok" to the process "worker":
663
664              ei_x_buff x;
665              ei_x_new_with_version(&x);
666              ei_x_encode_atom(&x, "ok");
667              if (ei_reg_send(&ec, fd, x.buff, x.index) < 0)
668                  handle_error();
669
670
671       int ei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf,
672       int len, unsigned timeout_ms)
673
674              Equivalent to ei_reg_send with an  optional  time-out  argument,
675              see the description at the beginning of this manual page.
676
677       int ei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *arg‐
678       buf, int argbuflen, ei_x_buff *x)
679       int ei_rpc_to(ei_cnode *ec, int fd, char *mod, char  *fun,  const  char
680       *argbuf, int argbuflen)
681       int  ei_rpc_from(ei_cnode  *ec,  int  fd, int timeout, erlang_msg *msg,
682       ei_x_buff *x)
683
684              Supports calling Erlang functions on remote  nodes.  ei_rpc_to()
685              sends an RPC request to a remote node and ei_rpc_from() receives
686              the results of such a call. ei_rpc() combines the  functionality
687              of these two functions by sending an RPC request and waiting for
688              the results. See also rpc:call/4 in Kernel.
689
690                * ec is the C-node structure previously initiated by a call to
691                  ei_connect_init() or ei_connect_xinit().
692
693                * fd is an open descriptor to an Erlang connection.
694
695                * timeout  is  the  maximum time (in milliseconds) to wait for
696                  results. Specify ERL_NO_TIMEOUT to  wait  forever.  ei_rpc()
697                  waits  infinitely  for  the  answer,  that is, the call will
698                  never time out.
699
700                * mod is the name of the module containing the function to  be
701                  run on the remote node.
702
703                * fun is the name of the function to run.
704
705                * argbuf is a pointer to a buffer with an encoded Erlang list,
706                  without a version magic number, containing the arguments  to
707                  be passed to the function.
708
709                * argbuflen is the length of the buffer containing the encoded
710                  Erlang list.
711
712                * msg is structure of type erlang_msg and contains information
713                  on the message received. For a description of the erlang_msg
714                  format, see ei_receive_msg.
715
716                * x points to the dynamic buffer that receives the result. For
717                  ei_rpc()  this  is the result without the version magic num‐
718                  ber. For ei_rpc_from() the result returns  a  version  magic
719                  number and a 2-tuple {rex,Reply}.
720
721              ei_rpc()  returns  the  number of bytes in the result on success
722              and -1 on failure. ei_rpc_from() returns the  number  of  bytes,
723              otherwise  one  of  ERL_TICK,  ERL_TIMEOUT,  and ERL_ERROR. When
724              failing, all three functions set erl_errno to one of the follow‐
725              ing:
726
727                EIO:
728                  I/O error.
729
730                ETIMEDOUT:
731                  Time-out expired.
732
733                EAGAIN:
734                  Temporary error: Try again.
735
736              Example:
737
738              Check to see if an Erlang process is alive:
739
740              int index = 0, is_alive;
741              ei_x_buff args, result;
742
743              ei_x_new(&result);
744              ei_x_new(&args);
745              ei_x_encode_list_header(&args, 1);
746              ei_x_encode_pid(&args, &check_pid);
747              ei_x_encode_empty_list(&args);
748
749              if (ei_rpc(&ec, fd, "erlang", "is_process_alive",
750                         args.buff, args.index, &result) < 0)
751                  handle_error();
752
753              if (ei_decode_version(result.buff, &index) < 0
754                  || ei_decode_bool(result.buff, &index, &is_alive) < 0)
755                  handle_error();
756
757
758       erlang_pid *ei_self(ei_cnode *ec)
759
760              Retrieves the pid of the C-node. Every C-node has a (pseudo) pid
761              used in ei_send_reg, ei_rpc, and others. This is contained in  a
762              field  in  the  ec structure. It will be safe for a long time to
763              fetch this field directly from the ei_cnode structure.
764
765       int ei_send(int fd, erlang_pid* to, char* buf, int len)
766
767              Sends an Erlang term to a process.
768
769                * fd is an open descriptor to an Erlang connection.
770
771                * to is the pid of the intended recipient of the message.
772
773                * buf is the buffer containing the term in binary format.
774
775                * len is the length of the message in bytes.
776
777              Returns 0 if successful, otherwise -1. In  the  latter  case  it
778              sets erl_errno to EIO.
779
780       int ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)
781
782              Works  exactly  as ei_send, the alternative name is retained for
783              backward compatibility. The function will not be removed without
784              prior notice.
785
786       int  ei_send_encoded_tmo(int  fd,  erlang_pid*  to, char* buf, int len,
787       unsigned timeout_ms)
788
789              Equivalent to ei_send_encoded with an  optional  time-out  argu‐
790              ment, see the description at the beginning of this manual page.
791
792       int ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to,
793       const char *buf, int len)
794
795              This function is retained for compatibility with code  generated
796              by  the  interface  compiler and with code following examples in
797              the same application.
798
799              The function works as ei_reg_send with one exception. Instead of
800              taking  ei_cnode  as first argument, it takes a second argument,
801              an erlang_pid, which is to be  the  process  identifier  of  the
802              sending process (in the Erlang distribution protocol).
803
804              A  suitable  erlang_pid  can  be  constructed  from the ei_cnode
805              structure by the following example code:
806
807              ei_cnode ec;
808              erlang_pid *self;
809              int fd; /* the connection fd */
810              self = ei_self(&ec);
811              self->num = fd;
812
813
814       int ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const  char
815       *to, const char *buf, int len)
816
817              Equivalent  to  ei_send_reg_encoded  with  an  optional time-out
818              argument, see the description at the beginning  of  this  manual
819              page.
820
821       int  ei_send_tmo(int  fd,  erlang_pid* to, char* buf, int len, unsigned
822       timeout_ms)
823
824              Equivalent to ei_send with an optional  time-out  argument,  see
825              the description at the beginning of this manual page.
826
827       const char *ei_thisnodename(ei_cnode *ec)
828       const char *ei_thishostname(ei_cnode *ec)
829       const char *ei_thisalivename(ei_cnode *ec)
830
831              Can be used to retrieve information about the C-node. These val‐
832              ues  are  initially  set  with  ei_connect_init()   or   ei_con‐
833              nect_xinit().
834
835              These  function  simply  fetch the appropriate field from the ec
836              structure. Read the field directly will probably be safe  for  a
837              long time, so these functions are not really needed.
838
839       int ei_unpublish(ei_cnode *ec)
840
841              Can  be  called by a process to unregister a specified node from
842              EPMD on the local host. This is, however, usually  not  allowed,
843              unless  EPMD was started with flag -relaxed_command_check, which
844              it normally is not.
845
846              To unregister a node you have published, you  should  close  the
847              descriptor that was returned by ei_publish().
848
849          Warning:
850              This  function  is  deprecated  and  will be removed in a future
851              release.
852
853
854              ec is the node structure of the node to unregister.
855
856              If the node was successfully unregistered from EPMD,  the  func‐
857              tion  returns  0. Otherwise, -1 is returned and erl_errno is set
858              to EIO.
859
860       int ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)
861
862              Equivalent to ei_unpublish with an optional  time-out  argument,
863              see the description at the beginning of this manual page.
864

DEBUG INFORMATION

866       If a connection attempt fails, the following can be checked:
867
868         * erl_errno.
869
870         * That the correct cookie was used
871
872         * That EPMD is running
873
874         * That  the  remote Erlang node on the other side is running the same
875           version of Erlang as the ei library
876
877         * That environment variable ERL_EPMD_PORT is set correctly
878
879       The connection attempt can be traced by setting a trace level by either
880       using    ei_set_tracelevel   or   by   setting   environment   variable
881       EI_TRACELEVEL. The trace levels have the following messages:
882
883         * 1: Verbose error messages
884
885         * 2: Above messages and verbose warning messages
886
887         * 3: Above messages and progress reports for connection handling
888
889         * 4: Above messages and progress reports for communication
890
891         * 5: Above messages and progress reports for data conversion
892
893Ericsson AB                  erl_interface 3.13.2                ei_connect(3)
Impressum