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

NAME

6       erl_connect - Communicate with distributed Erlang.
7

DESCRIPTION

9       This  module  provides  support  for  communication between distributed
10       Erlang nodes and C-nodes, in a manner that  is  transparent  to  Erlang
11       processes.
12
13       A  C-node appears to Erlang as a hidden node. That is, Erlang processes
14       that know the name of the C-node can communicate with it  in  a  normal
15       manner,  but  the  node name does not appear in the listing provided by
16       erlang:nodes/0 in ERTS.
17

EXPORTS

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

DEBUG INFORMATION

545       If a connection attempt fails, the following can be checked:
546
547         * erl_errno
548
549         * That the correct cookie was used
550
551         * That EPMD is running
552
553         * That the remote Erlang node on the other side is running  the  same
554           version of Erlang as the erl_interface library
555
556Ericsson AB                 erl_interface 3.10.2.2              erl_connect(3)
Impressum