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

NAME

6       erl_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   Note:
15       The old legacy erl_interface library (functions with  prefix  erl_)  is
16       deprecated  as  of OTP 22, and will be removed in OTP 23. This does not
17       apply to the ei library. Reasonably new gcc compilers will issue depre‐
18       cation  warnings.  In order to disable these warnings, define the macro
19       EI_NO_DEPR_WARN.
20
21
22       This module provides  support  for  communication  between  distributed
23       Erlang  nodes  and  C-nodes,  in a manner that is transparent to Erlang
24       processes.
25
26       A C-node appears to Erlang as a hidden node. That is, Erlang  processes
27       that  know  the  name of the C-node can communicate with it in a normal
28       manner, but the node name does not appear in the  listing  provided  by
29       erlang:nodes/0 in ERTS.
30

EXPORTS

32       int erl_accept(listensock, conp)
33
34              Types:
35
36                 int listensock;
37                 ErlConnect *conp;
38
39              This function is used by a server process to accept a connection
40              from a client process.
41
42                * listensock is an open socket descriptor  on  which  listen()
43                  has previously been called.
44
45                * conp is a pointer to an ErlConnect struct, described as fol‐
46                  lows:
47
48              typedef struct {
49                char ipadr[4];
50                char nodename[MAXNODELEN];
51              } ErlConnect;
52
53
54              On success, conp is filled in with the address and node name  of
55              the  connecting  client  and  a  file descriptor is returned. On
56              failure, ERL_ERROR is returned and erl_errno is set to EIO.
57
58       int erl_close_connection(fd)
59
60              Types:
61
62                 int fd;
63
64              Closes an open connection to an Erlang node.
65
66              Fd is a file descriptor obtained from erl_connect() or erl_xcon‐
67              nect().
68
69              Returns  0  on  success.  If the call fails, a non-zero value is
70              returned, and the reason for the error can be obtained with  the
71              appropriate platform-dependent call.
72
73       int erl_connect(node)
74       int erl_xconnect(addr, alive)
75
76              Types:
77
78                 char *node, *alive;
79                 struct in_addr *addr;
80
81              Sets up a connection to an Erlang node.
82
83              erl_xconnect()  requires  the  IP address of the remote host and
84              the alivename of the remote node to be specified.  erl_connect()
85              provides  an  alternative interface, and determines the informa‐
86              tion from the node name provided.
87
88                * addr is the 32-bit IP address of the remote host.
89
90                * alive is the alivename of the remote node.
91
92                * node is the name of the remote node.
93
94              Returns an open file descriptor on success, otherwise a negative
95              value. In the latter case erl_errno is set to one of:
96
97                EHOSTUNREACH:
98                  The remote host node is unreachable.
99
100                ENOMEM:
101                  No more memory is available.
102
103                EIO:
104                  I/O error.
105
106              Also,  errno  values  from socket(2) and connect(2) system calls
107              can be propagated into erl_errno.
108
109              Example:
110
111              #define NODE   "madonna@chivas.du.etx.ericsson.se"
112              #define ALIVE  "madonna"
113              #define IP_ADDR "150.236.14.75"
114
115              /*** Variant 1 ***/
116              erl_connect( NODE );
117
118              /*** Variant 2 ***/
119              struct in_addr addr;
120              addr = inet_addr(IP_ADDR);
121              erl_xconnect( &addr , ALIVE );
122
123
124       int erl_connect_init(number, cookie, creation)
125       int erl_connect_xinit(host, alive, node, addr, cookie, creation)
126
127              Types:
128
129                 int number;
130                 char *cookie;
131                 short creation;
132                 char *host,*alive,*node;
133                 struct in_addr *addr;
134
135              Initializes the erl_connect module. In particular,  these  func‐
136              tions  are  used  to  identify the name of the C-node from which
137              they are called. One of these functions must  be  called  before
138              any of the other functions in the erl_connect module are used.
139
140              erl_connect_xinit() stores for later use information about:
141
142                * Hostname of the node, host
143
144                * Alivename, alive
145
146                * Node name, node
147
148                * IP address, addr
149
150                * Cookie, cookie
151
152                * Creation number, creation
153
154              erl_connect_init()  provides  an alternative interface that does
155              not require  as  much  information  from  the  caller.  Instead,
156              erl_connect_init()  uses  gethostbyname() to obtain default val‐
157              ues.
158
159              If you use erl_connect_init(), your node will have a short name,
160              that  is,  it  will  not  be fully qualified. If you need to use
161              fully qualified (long) names, use erl_connect_xinit() instead.
162
163                * host is the name of the host on which the node is running.
164
165                * alive is the alivename of the node.
166
167                * node is the node name. It  is  to  be  of  the  form  alive‐
168                  name@hostname.
169
170                * addr is the 32-bit IP address of host.
171
172                * cookie  is  the  authorization string required for access to
173                  the remote  node.  If  NULL,  the  user  HOME  directory  is
174                  searched  for  a cookie file .erlang.cookie. The path to the
175                  home directory is retrieved from environment  variable  HOME
176                  on  Unix  and  from  the HOMEDRIVE and HOMEPATH variables on
177                  Windows. For more details, see the auth module in Kernel.
178
179                * creation helps identifying a particular  instance  of  a  C-
180                  node.  In  particular, it can help prevent us from receiving
181                  messages sent to an earlier process with the same registered
182                  name.
183
184              A  C-node  acting as a server is assigned a creation number when
185              it calls erl_publish().
186
187              number is used by erl_connect_init()  to  construct  the  actual
188              node name. In Example 2 below, "c17@a.DNS.name" is the resulting
189              node name.
190
191              Example 1:
192
193              struct in_addr addr;
194              addr = inet_addr("150.236.14.75");
195              if (!erl_connect_xinit("chivas",
196                                     "madonna",
197                                     "madonna@chivas.du.etx.ericsson.se",
198                                     &addr;
199                                     "samplecookiestring..."),
200                                     0)
201                erl_err_quit("<ERROR> when initializing !");
202
203
204              Example 2:
205
206              if (!erl_connect_init(17, "samplecookiestring...", 0))
207                erl_err_quit("<ERROR> when initializing !");
208
209
210       int erl_publish(port)
211
212              Types:
213
214                 int port;
215
216              This function is used by a server process to register  with  the
217              local name server EPMD, thereby allowing other processes to send
218              messages by using the registered name. Before calling this func‐
219              tion,  the  process should have called bind() and listen() on an
220              open socket.
221
222              port is the local name to register, and is to be the same as the
223              port number that was previously bound to the socket.
224
225              To unregister with EPMD, simply close the returned descriptor.
226
227              On  success, a descriptor connecting the calling process to EPMD
228              is returned. On failure, -1 is returned and erl_errno is set to:
229
230                EIO:
231                  I/O error.
232
233              Also, errno values from socket(2) and  connect(2)  system  calls
234              can be propagated into erl_errno.
235
236       int erl_receive(fd, bufp, bufsize)
237
238              Types:
239
240                 int fd;
241                 char *bufp;
242                 int bufsize;
243
244              Receives  a  message  consisting  of  a sequence of bytes in the
245              Erlang external format.
246
247                * fd is an open descriptor to an Erlang connection.
248
249                * bufp is a buffer large enough to hold the expected message.
250
251                * bufsize indicates the size of bufp.
252
253              If a tick occurs, that is, the Erlang node on the other  end  of
254              the connection has polled this node to see if it is still alive,
255              the function returns ERL_TICK and no message is  placed  in  the
256              buffer. Also, erl_errno is set to EAGAIN.
257
258              On  success,  the  message is placed in the specified buffer and
259              the function returns the number of bytes actually read. On fail‐
260              ure, the function returns a negative value and sets erl_errno to
261              one of:
262
263                EAGAIN:
264                  Temporary error: Try again.
265
266                EMSGSIZE:
267                  Buffer is too small.
268
269                EIO:
270                  I/O error.
271
272       int erl_receive_msg(fd, bufp, bufsize, emsg)
273
274              Types:
275
276                 int fd;
277                 unsigned char *bufp;
278                 int bufsize;
279                 ErlMessage *emsg;
280
281              Receives the message into the specified buffer and decodes  into
282              (ErlMessage *) emsg.
283
284                * fd is an open descriptor to an Erlang connection.
285
286                * bufp is a buffer large enough to hold the expected message.
287
288                * bufsize indicates the size of bufp.
289
290                * >emsg is a pointer to an ErlMessage structure into which the
291                  message will be decoded. ErlMessage is defined as follows:
292
293              typedef struct {
294                int type;
295                ETERM *msg;
296                ETERM *to;
297                ETERM *from;
298                char to_name[MAXREGLEN];
299              } ErlMessage;
300
301
302          Note:
303              The definition of ErlMessage has changed since earlier  versions
304              of Erl_Interface.
305
306
307              type identifies the type of message, one of the following:
308
309                ERL_SEND:
310                  An  ordinary  send  operation has occurred and emsg->to con‐
311                  tains the pid of the recipient. The message is in emsg->msg.
312
313                ERL_REG_SEND:
314                  A registered send operation has occurred and emsg->from con‐
315                  tains the pid of the sender. The message is in emsg->msg.
316
317                ERL_LINK or ERL_UNLINK:
318                  emsg->to  and  emsg->from contain the pids of the sender and
319                  recipient of the link or unlink. emsg->msg is not used.
320
321                ERL_EXIT:
322                  A link is broken. emsg->to and emsg->from contain  the  pids
323                  of  the  linked processes, and emsg->msg contains the reason
324                  for the exit.
325
326          Note:
327              It is the caller's responsibility to release the memory  pointed
328              to by emsg->msg, emsg->to, and emsg->from.
329
330
331              If  a  tick occurs, that is, the Erlang node on the other end of
332              the connection has polled this node to see if it is still alive,
333              the  function returns ERL_TICK indicating that the tick has been
334              received and responded to, but no message is placed in the  buf‐
335              fer. In this case you are to call erl_receive_msg() again.
336
337              On  success, the function returns ERL_MSG and the Emsg struct is
338              initialized as described above, or ERL_TICK, in  which  case  no
339              message  is returned. On failure, the function returns ERL_ERROR
340              and sets erl_errno to one of:
341
342                EMSGSIZE:
343                  Buffer is too small.
344
345                ENOMEM:
346                  No more memory is available.
347
348                EIO:
349                  I/O error.
350
351       int erl_reg_send(fd, to, msg)
352
353              Types:
354
355                 int fd;
356                 char *to;
357                 ETERM *msg;
358
359              Sends an Erlang term to a registered process.
360
361                * fd is an open descriptor to an Erlang connection.
362
363                * to is  a  string  containing  the  registered  name  of  the
364                  intended recipient of the message.
365
366                * msg is the Erlang term to be sent.
367
368              Returns  1 on success, otherwise 0. In the latter case erl_errno
369              is set to one of:
370
371                ENOMEM:
372                  No more memory is available.
373
374                EIO:
375                  I/O error.
376
377       ETERM *erl_rpc(fd, mod, fun, args)
378       int erl_rpc_from(fd, timeout, emsg)
379       int erl_rpc_to(fd, mod, fun, args)
380
381              Types:
382
383                 int fd, timeout;
384                 char *mod, *fun;
385                 ETERM *args;
386                 ErlMessage *emsg;
387
388              Supports calling Erlang functions on remote nodes.  erl_rpc_to()
389              sends  an  RPC  request  to  a  remote  node  and erl_rpc_from()
390              receives the results of such  a  call.  erl_rpc()  combines  the
391              functionality  of  these two functions by sending an RPC request
392              and waiting for the results. See also rpc:call/4 in Kernel.
393
394                * fd is an open descriptor to an Erlang connection.
395
396                * timeout is the maximum time (in milliseconds)  to  wait  for
397                  results.  To  wait  forever,  specify  ERL_NO_TIMEOUT.  When
398                  erl_rpc() calls erl_rpc_from(), the call will never timeout.
399
400                * mod is the name of the module containing the function to  be
401                  run on the remote node.
402
403                * fun is the name of the function to run.
404
405                * args  is  an  Erlang  list,  containing  the arguments to be
406                  passed to the function.
407
408                * emsg is a message containing  the  result  of  the  function
409                  call.
410
411              The  actual  message  returned  by  the  RPC server is a 2-tuple
412              {rex,Reply}. If you use erl_rpc_from() in your code, this is the
413              message  you will need to parse. If you use erl_rpc(), the tuple
414              itself is parsed for you, and the message returned to your  pro‐
415              gram  is  the  Erlang term containing Reply only. Replies to RPC
416              requests are always ERL_SEND messages.
417
418          Note:
419              It is the caller's responsibility to  free  the  returned  ETERM
420              structure and the memory pointed to by emsg->msg and emsg->to.
421
422
423              erl_rpc() returns the remote function's return value on success,
424              otherwise NULL.
425
426              erl_rpc_to() returns 0 on success, otherwise a negative number.
427
428              erl_rcp_from() returns ERL_MSG on success (with  Emsg  now  con‐
429              taining  the  reply tuple), otherwise one of ERL_TICK, ERL_TIME‐
430              OUT, or ERL_ERROR.
431
432              When failing, all three functions set erl_errno to one of:
433
434                ENOMEM:
435                  No more memory is available.
436
437                EIO:
438                  I/O error.
439
440                ETIMEDOUT:
441                  Timeout has expired.
442
443                EAGAIN:
444                  Temporary error: Try again.
445
446       int erl_send(fd, to, msg)
447
448              Types:
449
450                 int fd;
451                 ETERM *to, *msg;
452
453              Sends an Erlang term to a process.
454
455                * fd is an open descriptor to an Erlang connection.
456
457                * to is an Erlang term containing  the  pid  of  the  intended
458                  recipient of the message.
459
460                * >msg is the Erlang term to be sent.
461
462              Returns  1 on success, otherwise 0. In the latter case erl_errno
463              is set to one of:
464
465                EINVAL:
466                  Invalid argument: to is not a valid Erlang pid.
467
468                ENOMEM:
469                  No more memory is available.
470
471                EIO:
472                  I/O error.
473
474       const char *erl_thisalivename()
475       const char *erl_thiscookie()
476       short erl_thiscreation()
477       const char *erl_thishostname()
478       const char *erl_thisnodename()
479
480              Retrieves information about the C-node. These  values  are  ini‐
481              tially set with erl_connect_init() or erl_connect_xinit().
482
483       int erl_unpublish(alive)
484
485              Types:
486
487                 char *alive;
488
489              This  function can be called by a process to unregister a speci‐
490              fied node from EPMD on the local host. This is, however, usually
491              not  allowed,  unless  EPMD  was started with flag -relaxed_com‐
492              mand_check, which it normally is not.
493
494              To unregister a node you  have  published,  you  should  instead
495              close the descriptor that was returned by ei_publish().
496
497          Warning:
498              This  function  is  deprecated  and  will be removed in a future
499              release.
500
501
502              alive is the name of the node to unregister, that is, the  first
503              component of the node name, without @hostname.
504
505              If  the  node  was  successfully  unregistered  from  EPMD, 0 is
506              returned, otherwise -1 is returned and erl_errno is set to EIO.
507
508       int erl_xreceive_msg(fd, bufpp, bufsizep, emsg)
509
510              Types:
511
512                 int fd;
513                 unsigned char **bufpp;
514                 int *bufsizep;
515                 ErlMessage *emsg;
516
517              Similar to erl_receive_msg.  The  difference  is  that  erl_xre‐
518              ceive_msg  expects  the buffer to have been allocated by malloc,
519              and reallocates it if the received message does not fit into the
520              original  buffer.  Therefore  both  buffer and buffer length are
521              given as pointers; their values can change by the call.
522
523              On success, the function returns ERL_MSG and the Emsg struct  is
524              initialized  as  described  above, or ERL_TICK, in which case no
525              message is returned. On failure, the function returns  ERL_ERROR
526              and sets erl_errno to one of:
527
528                EMSGSIZE:
529                  Buffer is too small.
530
531                ENOMEM:
532                  No more memory is available.
533
534                EIO:
535                  I/O error.
536
537       struct hostent *erl_gethostbyaddr(addr, length, type)
538       struct  hostent *erl_gethostbyaddr_r(addr, length, type, hostp, buffer,
539       buflen, h_errnop)
540       struct hostent *erl_gethostbyname(name)
541       struct  hostent  *erl_gethostbyname_r(name,  hostp,   buffer,   buflen,
542       h_errnop)
543
544              Types:
545
546                 const char *name;
547                 const char *addr;
548                 int length;
549                 int type;
550                 struct hostent *hostp;
551                 char *buffer;
552                 int buflen;
553                 int *h_errnop;
554
555              Convenience functions for some common name lookup functions.
556

DEBUG INFORMATION

558       If a connection attempt fails, the following can be checked:
559
560         * erl_errno
561
562         * That the correct cookie was used
563
564         * That EPMD is running
565
566         * That  the  remote Erlang node on the other side is running the same
567           version of Erlang as the erl_interface library
568
569Ericsson AB                  erl_interface 3.13.2               erl_connect(3)
Impressum