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

NAME

6       ei_connect - Communicate with distributed Erlang.
7

DESCRIPTION

9       This  module enables C-programs to communicate with Erlang nodes, using
10       the Erlang distribution over TCP/IP.
11
12       A C-node appears to Erlang as a hidden node. That is, Erlang  processes
13       that  know  the  name of the C-node can communicate with it in a normal
14       manner, but the node name is not shown in the listing provided  by  er‐
15       lang:nodes/0 in ERTS.
16
17       The  environment  variable  ERL_EPMD_PORT can be used to indicate which
18       logical cluster a C-node belongs to.
19

TIME-OUT FUNCTIONS

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

USER SUPPLIED SOCKET IMPLEMENTATION

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

DATA TYPES

244         ei_cnode:
245           Opaque  data  type  representing  a C-node. A ei_cnode structure is
246           initialized by calling ei_connect_init() or friends.
247
248         ei_socket_callbacks:
249
250
251         typedef struct {
252             int flags;
253             int (*socket)(void **ctx, void *setup_ctx);
254             int   (*close)(void *ctx);
255             int (*listen)(void *ctx, void *addr, int *len, int backlog);
256             int (*accept)(void **ctx, void *addr, int *len, unsigned tmo);
257             int (*connect)(void *ctx, void *addr, int len, unsigned tmo);
258             int (*writev)(void *ctx, const void *iov, int iovcnt, ssize_t *len, unsigned tmo);
259             int (*write)(void *ctx, const char *buf, ssize_t *len, unsigned tmo);
260             int (*read)(void *ctx, char *buf, ssize_t *len, unsigned tmo);
261             int (*handshake_packet_header_size)(void *ctx, int *sz);
262             int (*connect_handshake_complete)(void *ctx);
263             int (*accept_handshake_complete)(void *ctx);
264             int (*get_fd)(void *ctx, int *fd);
265         } ei_socket_callbacks;
266
267           Callbacks functions for a User  Supplied  Socket  Implementation  .
268           Documentation  of  each  field  can  be  found in the User Supplied
269           Socket Implementation  section above.
270
271         ErlConnect:
272
273
274         typedef struct {
275             char ipadr[4]; /* Ip v4 address in network byte order */
276             char nodename[MAXNODELEN];
277         } ErlConnect;
278
279           IP v4 address and nodename.
280
281         Erl_IpAddr:
282
283
284         typedef struct {
285             unsigned s_addr; /* Ip v4 address in network byte order */
286         } Erl_IpAddr;
287
288           IP v4 address.
289
290         erlang_msg:
291
292
293         typedef struct {
294             long msgtype;
295             erlang_pid from;
296             erlang_pid to;
297             char toname[MAXATOMLEN+1];
298             char cookie[MAXATOMLEN+1];
299             erlang_trace token;
300         } erlang_msg;
301
302           Information  about  a  message  received  via  ei_receive_msg()  or
303           friends.
304

EXPORTS

306       struct hostent *ei_gethostbyaddr(const char *addr, int len, int type)
307       struct  hostent  *ei_gethostbyaddr_r(const char *addr, int length,  int
308       type,  struct hostent *hostp, char *buffer,   int buflen,   int  *h_er‐
309       rnop)
310       struct hostent *ei_gethostbyname(const char *name)
311       struct  hostent  *ei_gethostbyname_r(const  char *name,  struct hostent
312       *hostp,  char *buffer,  int buflen,  int *h_errnop)
313
314              Convenience functions for some common name lookup functions.
315
316       int ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)
317
318              Types:
319
320                 ei_cnode
321                 ErlConnect
322
323              Used by a server process to accept a connection  from  a  client
324              process.
325
326                * ec is the C-node structure.
327
328                * listensock  is  an  open socket descriptor on which listen()
329                  has previously been called.
330
331                * conp is a pointer to an ErlConnect struct.
332
333              On success, conp is filled in with the address and node name  of
334              the  connecting  client  and  a  file descriptor is returned. On
335              failure, ERL_ERROR is returned and erl_errno is set to EIO.
336
337       int ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect  *conp,  un‐
338       signed timeout_ms)
339
340              Types:
341
342                 ei_cnode
343                 ErlConnect
344
345              Equivalent  to ei_accept with an optional time-out argument, see
346              the description at the beginning of this manual page.
347
348       int ei_close_connection(int fd)
349
350              Closes a previously opened connection or listen socket.
351
352       int ei_connect(ei_cnode* ec, char *nodename)
353       int ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)
354       int ei_connect_host_port(ei_cnode* ec, char *hostname, int port)
355       int ei_xconnect_host_port(ei_cnode* ec, Erl_IpAddr adr, int port)
356
357              Types:
358
359                 ei_cnode
360                 Erl_IpAddr
361
362              Sets up a connection to an Erlang node.
363
364              ei_xconnect() requires the IP address of the remote host and the
365              alive name of the remote node to be specified. ei_connect() pro‐
366              vides an alternative interface and  determines  the  information
367              from  the  node name provided. The ei_xconnect_host_port() func‐
368              tion provides yet another alternative that  will  work  even  if
369              there  is  no EPMD instance on the host where the remote node is
370              running. The ei_xconnect_host_port() function  requires  the  IP
371              address and port of the remote node to be specified. The ei_con‐
372              nect_host_port()  function  is  an   alternative   to   ei_xcon‐
373              nect_host_port()  that  lets the user specify a hostname instead
374              of an IP address.
375
376                * adr is the 32-bit IP address of the remote host.
377
378                * alive is the alivename of the remote node.
379
380                * node is the name of the remote node.
381
382                * port is the port number of the remote node.
383
384              These functions return an open file descriptor on success, or  a
385              negative  value indicating that an error occurred. In the latter
386              case they set erl_errno to one of the following:
387
388                EHOSTUNREACH:
389                  The remote host node is unreachable.
390
391                ENOMEM:
392                  No more memory is available.
393
394                EIO:
395                  I/O error.
396
397              Also, errno values from socket(2) and  connect(2)  system  calls
398              may be propagated into erl_errno.
399
400              Example:
401
402              #define NODE   "madonna@chivas.du.etx.ericsson.se"
403              #define ALIVE  "madonna"
404              #define IP_ADDR "150.236.14.75"
405
406              /*** Variant 1 ***/
407              int fd = ei_connect(&ec, NODE);
408
409              /*** Variant 2 ***/
410              struct in_addr addr;
411              addr.s_addr = inet_addr(IP_ADDR);
412              fd = ei_xconnect(&ec, &addr, ALIVE);
413
414
415       int  ei_connect_init(ei_cnode*  ec,  const  char* this_node_name, const
416       char *cookie, unsigned creation)
417       int  ei_connect_init_ussi(ei_cnode*  ec,  const  char*  this_node_name,
418       const  char  *cookie,  unsigned creation, ei_socket_callbacks *cbs, int
419       cbs_sz, void *setup_context)
420       int ei_connect_xinit(ei_cnode* ec, const char *thishostname, const char
421       *thisalivename,  const char *thisnodename, Erl_IpAddr thisipaddr, const
422       char *cookie, unsigned creation)
423       int ei_connect_xinit_ussi(ei_cnode* ec, const char *thishostname, const
424       char  *thisalivename,  const char *thisnodename, Erl_IpAddr thisipaddr,
425       const char *cookie, unsigned creation,  ei_socket_callbacks  *cbs,  int
426       cbs_sz, void *setup_context)
427
428              Types:
429
430                 ei_cnode
431                 Erl_IpAddr
432                 ei_socket_callbacks
433
434              Initializes  the  ec  structure,  to  identify the node name and
435              cookie of the server. One of them must be  called  before  other
436              functions  that  works on the ei_cnode type or a file descriptor
437              associated with a connection to another node is used.
438
439                * ec is a structure containing information about  the  C-node.
440                  It  is used in other ei functions for connecting and receiv‐
441                  ing data.
442
443                * this_node_name is the name of the C-node  (the  name  before
444                  '@' in the full node name).
445
446                * cookie is the cookie for the node.
447
448                * creation  identifies a specific instance of a C-node. It can
449                  help prevent the node from receiving  messages  sent  to  an
450                  earlier process with the same registered name.
451
452            Note:
453                The  type  of the creation argument was changed from short (16
454                bit) to unsigned int (32 bit) in OTP 25. This should cause  no
455                practical problem other than maybe a compiler warning.
456
457
458                * thishostname  is  the name of the machine we are running on.
459                  If long names are to be used, they are to be fully qualified
460                  (that is, durin.erix.ericsson.se instead of durin).
461
462                * thisalivename  is the name of the local C-node (the name be‐
463                  fore '@' in the full node name). Can be NULL (from  OTP  23)
464                  to get a dynamically assigned name from the peer node.
465
466                * thisnodename  is the full name of the local C-node, that is,
467                  mynode@myhost. Can be NULL if thisalivename is NULL.
468
469                * thispaddr if the IP address of the host.
470
471                * cbs is a pointer to a callback  structure  implementing  and
472                  alternative socket interface.
473
474                * cbs_sz is the size of the structure pointed to by cbs.
475
476                * setup_context  is  a  pointer  to  a  structure that will be
477                  passed as second argument to the socket callback in the  cbs
478                  structure.
479
480              A  C-node  acting as a server is assigned a creation number when
481              it calls ei_publish().
482
483              A connection is closed by simply closing the socket. For  infor‐
484              mation  about how to close the socket gracefully (when there are
485              outgoing packets before close), see the relevant system documen‐
486              tation.
487
488              These functions return a negative value indicating that an error
489              occurred.
490
491              Example 1:
492
493              unsigned n = 0;
494              struct in_addr addr;
495              ei_cnode ec;
496              addr.s_addr = inet_addr("150.236.14.75");
497              if (ei_connect_xinit(&ec,
498                                   "chivas",
499                                   "madonna",
500                                   "madonna@chivas.du.etx.ericsson.se",
501                                   &addr;
502                                   "cookie...",
503                                   n++) < 0) {
504                  fprintf(stderr,"ERROR when initializing: %d",erl_errno);
505                  exit(-1);
506              }
507
508
509              Example 2:
510
511              if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) {
512                  fprintf(stderr,"ERROR when initializing: %d",erl_errno);
513                  exit(-1);
514              }
515
516
517       int ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)
518       int ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename,  un‐
519       signed timeout_ms)
520       int  ei_connect_host_port_tmo(ei_cnode*  ec,  char *hostname, int port,
521       unsigned ms)
522       int ei_xconnect_host_port_tmo(ei_cnode* ec, Erl_IpAddr adr,  int  port,
523       unsigned ms)
524
525              Types:
526
527                 ei_cnode
528                 Erl_IpAddr
529
530              Equivalent  to ei_connect, ei_xconnect, ei_connect_host_port and
531              ei_xconnect_host_port with an optional  time-out  argument,  see
532              the description at the beginning of this manual page.
533
534       int ei_get_tracelevel(void)
535       void ei_set_tracelevel(int level)
536
537              Used  to set tracing on the distribution. The levels are differ‐
538              ent verbosity levels. A higher level means more information. See
539              also section  Debug Information.
540
541              These functions are not thread safe.
542
543       int ei_listen(ei_cnode *ec, int *port, int backlog)
544       int ei_xlisten(ei_cnode *ec, Erl_IpAddr adr, int *port, int backlog)
545
546              Types:
547
548                 ei_cnode
549                 Erl_IpAddr
550
551              Used  by  a  server process to setup a listen socket which later
552              can be used for accepting connections from client processes.
553
554                * ec is the C-node structure.
555
556                * adr is local interface to bind to.
557
558                * port is a pointer to an integer containing the  port  number
559                  to  bind to. If *port equals 0 when calling ei_listen(), the
560                  socket will be bound  to  an  ephemeral  port.  On  success,
561                  ei_listen() will update the value of *port to the port actu‐
562                  ally bound to.
563
564                * backlog is maximum backlog of pending connections.
565
566              ei_listen will create a socket, bind to a port on the local  in‐
567              terface  identified  by  adr (or all local interfaces if ei_lis‐
568              ten() is called), and mark the socket as a passive socket  (that
569              is,  a  socket  that will be used for accepting incoming connec‐
570              tions).
571
572              On success, a file descriptor is returned which can be used in a
573              call  to  ei_accept().  On  failure,  ERL_ERROR  is returned and
574              erl_errno is set to EIO.
575
576       int ei_make_pid(ei_cnode *ec, erlang_pid *pid)
577
578              Types:
579
580                 ei_cnode
581                 erlang_pid
582
583              Creates a new process  identifier  in  the  argument  pid.  This
584              process  identifier  refers  to a conseptual process residing on
585              the C-node identified by the argument ec. On success  0  is  re‐
586              turned. On failure ERL_ERROR is returned and erl_errno is set.
587
588              The  C-node identified by ec must have been initialized and must
589              have received a name prior to the call  to  ei_make_pid().  Ini‐
590              tialization of the C-node is done by a call to ei_connect_init()
591              or friends. If the name is dynamically assigned  from  the  peer
592              node, the C-node also has to be connected.
593
594       int ei_make_ref(ei_cnode *ec, erlang_ref *ref)
595
596              Types:
597
598                 ei_cnode
599                 erlang_ref
600
601              Creates  a  new  reference  in  the argument ref. This reference
602              originates from the C-node identified by  the  argument  ec.  On
603              success  0  is  returned.  On  failure ERL_ERROR is returned and
604              erl_errno is set.
605
606              The C-node identified by ec must have been initialized and  must
607              have  received  a  name prior to the call to ei_make_ref(). Ini‐
608              tialization of the C-node is done by a call to ei_connect_init()
609              or  friends.  If  the name is dynamically assigned from the peer
610              node, the C-node also has to be connected.
611
612       int ei_publish(ei_cnode *ec, int port)
613
614              Types:
615
616                 ei_cnode
617
618              Used by a server process to register with the local name  server
619              EPMD, thereby allowing other processes to send messages by using
620              the registered name. Before calling either of  these  functions,
621              the  process  should  have called bind() and listen() on an open
622              socket.
623
624                * ec is the C-node structure.
625
626                * port is the local name to register, and is to be the same as
627                  the port number that was previously bound to the socket.
628
629                * addr is the 32-bit IP address of the local host.
630
631              To  unregister  with EPMD, simply close the returned descriptor.
632              Do not use ei_unpublish(), which is deprecated anyway.
633
634              On success, the function returns  a  descriptor  connecting  the
635              calling  process to EPMD. On failure, -1 is returned and erl_er‐
636              rno is set to EIO.
637
638              Also, errno values from socket(2) and  connect(2)  system  calls
639              may be propagated into erl_errno.
640
641       int ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)
642
643              Types:
644
645                 ei_cnode
646
647              Equivalent to ei_publish with an optional time-out argument, see
648              the description at the beginning of this manual page.
649
650       int ei_receive(int fd, unsigned char* bufp, int bufsize)
651
652              Receives a message consisting of a sequence of bytes in the  Er‐
653              lang external format.
654
655                * fd  is an open descriptor to an Erlang connection. It is ob‐
656                  tained from a previous ei_connect or ei_accept.
657
658                * bufp is a buffer large enough to hold the expected message.
659
660                * bufsize indicates the size of bufp.
661
662              If a tick occurs, that is, the Erlang node on the other  end  of
663              the connection has polled this node to see if it is still alive,
664              the function returns ERL_TICK and no message is  placed  in  the
665              buffer. Also, erl_errno is set to EAGAIN.
666
667              On  success,  the  message is placed in the specified buffer and
668              the function returns the number of bytes actually read. On fail‐
669              ure, the function returns ERL_ERROR and sets erl_errno to one of
670              the following:
671
672                EAGAIN:
673                  Temporary error: Try again.
674
675                EMSGSIZE:
676                  Buffer is too small.
677
678                EIO:
679                  I/O error.
680
681       int ei_receive_encoded(int fd, char **mbufp,  int  *bufsz,   erlang_msg
682       *msg, int *msglen)
683
684              Types:
685
686                 erlang_msg
687
688              This  function is retained for compatibility with code generated
689              by the interface compiler and with code  following  examples  in
690              the same application.
691
692              In  essence, the function performs the same operation as ei_xre‐
693              ceive_msg, but instead of using an ei_x_buff, the  function  ex‐
694              pects  a pointer to a character pointer (mbufp), where the char‐
695              acter pointer is to point to a memory area allocated by  malloc.
696              Argument  bufsz  is to be a pointer to an integer containing the
697              exact size (in bytes) of the memory area. The function  may  re‐
698              allocate the memory area and will in such cases put the new size
699              in *bufsz and update *mbufp.
700
701              Returns either ERL_TICK or the msgtype field of  the  erlang_msg
702              *msg.  The  length  of the message is put in *msglen. On error a
703              value < 0 is returned.
704
705              It is recommended to use ei_xreceive_msg instead when  possible,
706              for  the  sake of readability. However, the function will be re‐
707              tained in the interface for compatibility and will  not  be  re‐
708              moved in future releases without prior notice.
709
710       int  ei_receive_encoded_tmo(int  fd,  char  **mbufp,  int  *bufsz,  er‐
711       lang_msg *msg, int *msglen, unsigned timeout_ms)
712
713              Types:
714
715                 erlang_msg
716
717              Equivalent to ei_receive_encoded with an optional time-out argu‐
718              ment, see the description at the beginning of this manual page.
719
720       int ei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x)
721       int ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)
722
723              Types:
724
725                 ei_x_buff
726                 erlang_msg
727
728              Receives  a  message  to the buffer in x. ei_xreceive_msg allows
729              the buffer in x to grow, but ei_receive_msg fails if the message
730              is larger than the pre-allocated buffer in x.
731
732                * fd is an open descriptor to an Erlang connection.
733
734                * msg is a pointer to an erlang_msg structure and contains in‐
735                  formation on the message received.
736
737                * x is buffer obtained from ei_x_new.
738
739              On success, the functions return ERL_MSG and the msg  struct  is
740              initialized.
741
742              msgtype  identifies  the type of message, and is one of the fol‐
743              lowing:
744
745                ERL_SEND:
746                  Indicates that an  ordinary  send  operation  has  occurred.
747                  msg->to contains the pid of the recipient (the C-node).
748
749                ERL_REG_SEND:
750                  A registered send operation occurred. msg->from contains the
751                  pid of the sender.
752
753                ERL_LINK or ERL_UNLINK:
754                  msg->to and msg->from contain the pids of the sender and re‐
755                  cipient of the link or unlink.
756
757                ERL_EXIT:
758                  Indicates  a  broken link. msg->to and msg->from contain the
759                  pids of the linked processes.
760
761              The return value is the same as for ei_receive.
762
763       int ei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x,  unsigned
764       imeout_ms)
765       int ei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned
766       timeout_ms)
767
768              Types:
769
770                 ei_x_buff
771                 erlang_msg
772
773              Equivalent to ei_receive_msg and  ei_xreceive_msg  with  an  op‐
774              tional  time-out  argument, see the description at the beginning
775              of this manual page.
776
777       int ei_receive_tmo(int fd, unsigned char* bufp, int  bufsize,  unsigned
778       timeout_ms)
779
780              Equivalent to ei_receive with an optional time-out argument, see
781              the description at the beginning of this manual page.
782
783       int ei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int
784       len)
785
786              Types:
787
788                 ei_cnode
789
790              Sends an Erlang term to a registered process.
791
792                * fd is an open descriptor to an Erlang connection.
793
794                * server_name  is  the registered name of the intended recipi‐
795                  ent.
796
797                * buf is the buffer containing the term in binary format.
798
799                * len is the length of the message in bytes.
800
801              Returns 0 if successful, otherwise -1. In  the  latter  case  it
802              sets erl_errno to EIO.
803
804              Example:
805
806              Send the atom "ok" to the process "worker":
807
808              ei_x_buff x;
809              ei_x_new_with_version(&x);
810              ei_x_encode_atom(&x, "ok");
811              if (ei_reg_send(&ec, fd, x.buff, x.index) < 0)
812                  handle_error();
813
814
815       int ei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf,
816       int len, unsigned timeout_ms)
817
818              Types:
819
820                 ei_cnode
821
822              Equivalent to ei_reg_send with an  optional  time-out  argument,
823              see the description at the beginning of this manual page.
824
825       int ei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *arg‐
826       buf, int argbuflen, ei_x_buff *x)
827       int ei_rpc_to(ei_cnode *ec, int fd, char *mod, char  *fun,  const  char
828       *argbuf, int argbuflen)
829       int  ei_xrpc_to(ei_cnode  *ec, int fd, char *mod, char *fun, const char
830       *argbuf, int argbuflen, int flags)
831       int ei_rpc_from(ei_cnode *ec, int fd,  int  timeout,  erlang_msg  *msg,
832       ei_x_buff *x)
833
834              Types:
835
836                 ei_cnode
837                 ei_x_buff
838                 erlang_msg
839
840              Supports  calling  Erlang functions on remote nodes. ei_rpc_to()
841              sends an RPC request to a remote node and ei_rpc_from() receives
842              the  results of such a call. ei_rpc() combines the functionality
843              of these two functions by sending an RPC request and waiting for
844              the results.
845
846              The  ei_xrpc_to() function is equivalent to ei_rpc_to() when its
847              flags parameter is  set  to  0.  When  the  flags  parameter  of
848              ei_xrpc_to()  is  set  to  EI_RPC_FETCH_STDOUT, stdout (standard
849              output) data are forwarded. See the documentation for the  flags
850              parameter  for  more  information  about the EI_RPC_FETCH_STDOUT
851              flag.
852
853              rpc:call/4 in Kernel.
854
855                * ec is the C-node structure previously initiated by a call to
856                  ei_connect_init() or ei_connect_xinit().
857
858                * fd is an open descriptor to an Erlang connection.
859
860                * timeout  is  the  maximum time (in milliseconds) to wait for
861                  results. Specify ERL_NO_TIMEOUT to  wait  forever.  ei_rpc()
862                  waits  infinitely  for  the  answer,  that is, the call will
863                  never time out.
864
865                * mod is the name of the module containing the function to  be
866                  run on the remote node.
867
868                * fun is the name of the function to run.
869
870                * argbuf is a pointer to a buffer with an encoded Erlang list,
871                  without a version magic number, containing the arguments  to
872                  be passed to the function.
873
874                * argbuflen is the length of the buffer containing the encoded
875                  Erlang list.
876
877                * msg is structure of type erlang_msg and contains information
878                  on the message received. For a description of the erlang_msg
879                  format, see ei_receive_msg.
880
881                * x points to the dynamic buffer that receives the result. For
882                  ei_rpc()  this  is the result without the version magic num‐
883                  ber. For an ei_rpc_from() call the result consists of a ver‐
884                  sion  magic  number and a 2-tuple. The 2-tuple can be in one
885                  of the following two forms:
886
887                  {rex,Reply}:
888                     This response value means that the RPC has completed. The
889                    result  value  is the Reply term. This is the only type of
890                    response that one can get from an RPC triggered by a  call
891                    to     ei_rpc_to()    or    ei_xrpc_to()    without    the
892                    EI_RPC_FETCH_STDOUT flag. If the RPC was  triggered  by  a
893                    call  to  ei_xrpc_to()  with  the EI_RPC_FETCH_STDOUT flag
894                    set, then all forwarded stdout data has been received.
895
896                  {rex_stdout,StdOutUTF8Binary}:
897                     This response value can only be obtained if the RPC  call
898                    was   triggered   by  a  call  to  ei_xrpc_to()  with  the
899                    EI_RPC_FETCH_STDOUT flag set. This  response  value  means
900                    that  forwarded  stdout data has been received. The stdout
901                    data is stored in a binary and is UTF-8 encoded.  One  may
902                    need  to call ei_rpc_from() multiple times to read all the
903                    stdout data. The stdout data is received in the same order
904                    as it was written. All forwarded stdout data have been re‐
905                    ceived when a {rex,Reply} tuple has been obtained from  an
906                    ei_rpc_from() call.
907
908                * flags  The  flag  EI_RPC_FETCH_STDOUT  is currently the only
909                  flag   that   is    supported    by    ei_xrpc_to().    When
910                  EI_RPC_FETCH_STDOUT  is set, the called function is executed
911                  in a new process with a group leader that forwards all  std‐
912                  out  data. This means that stdout data that are written dur‐
913                  ing the execution of the  called  function,  by  the  called
914                  function  and  by  descendant  processes,  will be forwarded
915                  (given that the group leader has not been changed by a  call
916                  to erlang:group_leader/2). The forwarded stdout data need to
917                  be collected by a sequence of calls  to  ei_rpc_from().  See
918                  the  description of the x parameter for how ei_rpc_from() is
919                  used to receive stdout data. See the  documentation  of  the
920                  the  I/O  protocol,  for  more  information  about the group
921                  leader concept.
922
923            Note:
924                The flag EI_RPC_FETCH_STDOUT only works when interacting  with
925                a node with a version greater or equal to OTP-24.
926
927
928              ei_rpc()  returns  the  number of bytes in the result on success
929              and -1 on failure. ei_rpc_from() returns the  number  of  bytes,
930              otherwise one of ERL_TICK, ERL_TIMEOUT, and ERL_ERROR. The func‐
931              tions ei_rpc_to() and ei_xrpc_to() returns 0 if successful, oth‐
932              erwise -1. When failing, all four functions set erl_errno to one
933              of the following:
934
935                EIO:
936                  I/O error.
937
938                ETIMEDOUT:
939                  Time-out expired.
940
941                EAGAIN:
942                  Temporary error: Try again.
943
944              Example:
945
946              Check to see if an Erlang process is alive:
947
948              int index = 0, is_alive;
949              ei_x_buff args, result;
950
951              ei_x_new(&result);
952              ei_x_new(&args);
953              ei_x_encode_list_header(&args, 1);
954              ei_x_encode_pid(&args, &check_pid);
955              ei_x_encode_empty_list(&args);
956
957              if (ei_rpc(&ec, fd, "erlang", "is_process_alive",
958                         args.buff, args.index, &result) < 0)
959                  handle_error();
960
961              if (ei_decode_version(result.buff, &index) < 0
962                  || ei_decode_bool(result.buff, &index, &is_alive) < 0)
963                  handle_error();
964
965
966       erlang_pid *ei_self(ei_cnode *ec)
967
968              Types:
969
970                 ei_cnode
971                 erlang_pid
972
973              Retrieves a generic pid  of  the  C-node.  Every  C-node  has  a
974              (pseudo)  pid used in ei_send_reg, ei_rpc(), and others. This is
975              contained in a field in the ec structure.  Do  not  modify  this
976              structure.
977
978              On  success  a pointer to the process identifier is returned. On
979              failure NULL is returned and erl_errno is set.
980
981              The C-node identified by ec must have been initialized and  must
982              have received a name prior to the call to ei_self(). Initializa‐
983              tion of the C-node is done by a  call  to  ei_connect_init()  or
984              friends. If the name is dynamically assigned from the peer node,
985              the C-node also has to be connected.
986
987       int ei_send(int fd, erlang_pid* to, char* buf, int len)
988
989              Types:
990
991                 erlang_pid
992
993              Sends an Erlang term to a process.
994
995                * fd is an open descriptor to an Erlang connection.
996
997                * to is the pid of the intended recipient of the message.
998
999                * buf is the buffer containing the term in binary format.
1000
1001                * len is the length of the message in bytes.
1002
1003              Returns 0 if successful, otherwise -1. In  the  latter  case  it
1004              sets erl_errno to EIO.
1005
1006       int ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)
1007
1008              Types:
1009
1010                 erlang_pid
1011
1012              Works  exactly  as ei_send, the alternative name is retained for
1013              backward compatibility. The function will not be removed without
1014              prior notice.
1015
1016       int ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, un‐
1017       signed timeout_ms)
1018
1019              Types:
1020
1021                 erlang_pid
1022
1023              Equivalent to ei_send_encoded with an  optional  time-out  argu‐
1024              ment, see the description at the beginning of this manual page.
1025
1026       int ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to,
1027       const char *buf, int len)
1028
1029              Types:
1030
1031                 erlang_pid
1032
1033              This function is retained for compatibility with code  generated
1034              by  the  interface  compiler and with code following examples in
1035              the same application.
1036
1037              The function works as ei_reg_send with one exception. Instead of
1038              taking  ei_cnode  as first argument, it takes a second argument,
1039              an erlang_pid, which is to be  the  process  identifier  of  the
1040              sending process (in the Erlang distribution protocol).
1041
1042              A  suitable erlang_pid can be retrieved from the ei_cnode struc‐
1043              ture by calling ei_self(cnode_pointer).
1044
1045       int ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const  char
1046       *to, const char *buf, int len, unsigned timeout_ms)
1047
1048              Types:
1049
1050                 erlang_pid
1051
1052              Equivalent  to ei_send_reg_encoded with an optional time-out ar‐
1053              gument, see the description at  the  beginning  of  this  manual
1054              page.
1055
1056       int  ei_send_tmo(int  fd,  erlang_pid* to, char* buf, int len, unsigned
1057       timeout_ms)
1058
1059              Types:
1060
1061                 erlang_pid
1062
1063              Equivalent to ei_send with an optional  time-out  argument,  see
1064              the description at the beginning of this manual page.
1065
1066       const char *ei_thisnodename(ei_cnode *ec)
1067       const char *ei_thishostname(ei_cnode *ec)
1068       const char *ei_thisalivename(ei_cnode *ec)
1069
1070              Types:
1071
1072                 ei_cnode
1073
1074              Can be used to retrieve information about the C-node. These val‐
1075              ues  are  initially  set  with  ei_connect_init()   or   ei_con‐
1076              nect_xinit().
1077
1078              These  function  simply  fetch the appropriate field from the ec
1079              structure. Read the field directly will probably be safe  for  a
1080              long time, so these functions are not really needed.
1081
1082       int ei_unpublish(ei_cnode *ec)
1083
1084              Types:
1085
1086                 ei_cnode
1087
1088              Can  be  called by a process to unregister a specified node from
1089              EPMD on the local host. This is, however, usually  not  allowed,
1090              unless  EPMD was started with flag -relaxed_command_check, which
1091              it normally is not.
1092
1093              To unregister a node you have published, you  should  close  the
1094              descriptor that was returned by ei_publish().
1095
1096          Warning:
1097              This  function is deprecated and will be removed in a future re‐
1098              lease.
1099
1100
1101              ec is the node structure of the node to unregister.
1102
1103              If the node was successfully unregistered from EPMD,  the  func‐
1104              tion  returns  0. Otherwise, -1 is returned and erl_errno is set
1105              to EIO.
1106
1107       int ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)
1108
1109              Types:
1110
1111                 ei_cnode
1112
1113              Equivalent to ei_unpublish with an optional  time-out  argument,
1114              see the description at the beginning of this manual page.
1115

DEBUG INFORMATION

1117       If a connection attempt fails, the following can be checked:
1118
1119         * erl_errno.
1120
1121         * That the correct cookie was used
1122
1123         * That EPMD is running
1124
1125         * That  the  remote Erlang node on the other side is running the same
1126           version of Erlang as the ei library
1127
1128         * That environment variable ERL_EPMD_PORT is set correctly
1129
1130       The connection attempt can be traced by setting a trace level by either
1131       using    ei_set_tracelevel   or   by   setting   environment   variable
1132       EI_TRACELEVEL. The trace levels have the following messages:
1133
1134         * 1: Verbose error messages
1135
1136         * 2: Above messages and verbose warning messages
1137
1138         * 3: Above messages and progress reports for connection handling
1139
1140         * 4: Above messages and progress reports for communication
1141
1142         * 5: Above messages and progress reports for data conversion
1143
1144Ericsson AB                    erl_interface 5.3                 ei_connect(3)
Impressum