1erl_connect(3) C Library Functions erl_connect(3)
2
6 erl_connect - Communicate with distributed Erlang.
7
9 Note:
10 The support for VxWorks is deprecated as of OTP 22, and will be removed
11 in OTP 23.
12 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 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 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
32 int erl_accept(listensock, conp)
33 Types:
35 int listensock;
37 ErlConnect *conp;
38 This function is used by a server process to accept a connection
40 from a client process.
41 * listensock is an open socket descriptor on which listen()
43 has previously been called.
44 * conp is a pointer to an ErlConnect struct, described as fol‐
46 lows:
47 typedef struct {
49 char ipadr[4];
50 char nodename[MAXNODELEN];
51 } ErlConnect;
52 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 int erl_close_connection(fd)
59 Types:
61 int fd;
63 Closes an open connection to an Erlang node.
65 Fd is a file descriptor obtained from erl_connect() or erl_xcon‐
67 nect().
68 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 int erl_connect(node)
74 int erl_xconnect(addr, alive)
75 Types:
77 char *node, *alive;
79 struct in_addr *addr;
80 Sets up a connection to an Erlang node.
82 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 * addr is the 32-bit IP address of the remote host.
89 * alive is the alivename of the remote node.
91 * node is the name of the remote node.
93 Returns an open file descriptor on success, otherwise a negative
95 value. In the latter case erl_errno is set to one of:
96 EHOSTUNREACH:
98 The remote host node is unreachable.
99 ENOMEM:
101 No more memory is available.
102 EIO:
104 I/O error.
105 Also, errno values from socket(2) and connect(2) system calls
107 can be propagated into erl_errno.
108 Example:
110 #define NODE "madonna@chivas.du.etx.ericsson.se"
112 #define ALIVE "madonna"
113 #define IP_ADDR "150.236.14.75"
114 /*** Variant 1 ***/
116 erl_connect( NODE );
117 /*** Variant 2 ***/
119 struct in_addr addr;
120 addr = inet_addr(IP_ADDR);
121 erl_xconnect( &addr , ALIVE );
122 int erl_connect_init(number, cookie, creation)
125 int erl_connect_xinit(host, alive, node, addr, cookie, creation)
126 Types:
128 int number;
130 char *cookie;
131 short creation;
132 char *host,*alive,*node;
133 struct in_addr *addr;
134 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 erl_connect_xinit() stores for later use information about:
141 * Hostname of the node, host
143 * Alivename, alive
145 * Node name, node
147 * IP address, addr
149 * Cookie, cookie
151 * Creation number, creation
153 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 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 * host is the name of the host on which the node is running.
164 * alive is the alivename of the node.
166 * node is the node name. It is to be of the form alive‐
168 name@hostname.
169 * addr is the 32-bit IP address of host.
171 * 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 * 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 A C-node acting as a server is assigned a creation number when
185 it calls erl_publish().
186 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 Example 1:
192 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 Example 2:
205 if (!erl_connect_init(17, "samplecookiestring...", 0))
207 erl_err_quit("<ERROR> when initializing !");
208 int erl_publish(port)
211 Types:
213 int port;
215 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 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 To unregister with EPMD, simply close the returned descriptor.
226 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 EIO:
231 I/O error.
232 Also, errno values from socket(2) and connect(2) system calls
234 can be propagated into erl_errno.
235 int erl_receive(fd, bufp, bufsize)
237 Types:
239 int fd;
241 char *bufp;
242 int bufsize;
243 Receives a message consisting of a sequence of bytes in the
245 Erlang external format.
246 * fd is an open descriptor to an Erlang connection.
248 * bufp is a buffer large enough to hold the expected message.
250 * bufsize indicates the size of bufp.
252 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 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 EAGAIN:
264 Temporary error: Try again.
265 EMSGSIZE:
267 Buffer is too small.
268 EIO:
270 I/O error.
271 int erl_receive_msg(fd, bufp, bufsize, emsg)
273 Types:
275 int fd;
277 unsigned char *bufp;
278 int bufsize;
279 ErlMessage *emsg;
280 Receives the message into the specified buffer and decodes into
282 (ErlMessage *) emsg.
283 * fd is an open descriptor to an Erlang connection.
285 * bufp is a buffer large enough to hold the expected message.
287 * bufsize indicates the size of bufp.
289 * >emsg is a pointer to an ErlMessage structure into which the
291 message will be decoded. ErlMessage is defined as follows:
292 typedef struct {
294 int type;
295 ETERM *msg;
296 ETERM *to;
297 ETERM *from;
298 char to_name[MAXREGLEN];
299 } ErlMessage;
300 Note:
303 The definition of ErlMessage has changed since earlier versions
304 of Erl_Interface.
305 type identifies the type of message, one of the following:
308 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 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 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 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 Note:
327 It is the caller's responsibility to release the memory pointed
328 to by emsg->msg, emsg->to, and emsg->from.
329 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 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 EMSGSIZE:
343 Buffer is too small.
344 ENOMEM:
346 No more memory is available.
347 EIO:
349 I/O error.
350 int erl_reg_send(fd, to, msg)
352 Types:
354 int fd;
356 char *to;
357 ETERM *msg;
358 Sends an Erlang term to a registered process.
360 * fd is an open descriptor to an Erlang connection.
362 * to is a string containing the registered name of the
364 intended recipient of the message.
365 * msg is the Erlang term to be sent.
367 Returns 1 on success, otherwise 0. In the latter case erl_errno
369 is set to one of:
370 ENOMEM:
372 No more memory is available.
373 EIO:
375 I/O error.
376 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 Types:
382 int fd, timeout;
384 char *mod, *fun;
385 ETERM *args;
386 ErlMessage *emsg;
387 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 * fd is an open descriptor to an Erlang connection.
395 * 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 * mod is the name of the module containing the function to be
401 run on the remote node.
402 * fun is the name of the function to run.
404 * args is an Erlang list, containing the arguments to be
406 passed to the function.
407 * emsg is a message containing the result of the function
409 call.
410 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 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 erl_rpc() returns the remote function's return value on success,
424 otherwise NULL.
425 erl_rpc_to() returns 0 on success, otherwise a negative number.
427 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 When failing, all three functions set erl_errno to one of:
433 ENOMEM:
435 No more memory is available.
436 EIO:
438 I/O error.
439 ETIMEDOUT:
441 Timeout has expired.
442 EAGAIN:
444 Temporary error: Try again.
445 int erl_send(fd, to, msg)
447 Types:
449 int fd;
451 ETERM *to, *msg;
452 Sends an Erlang term to a process.
454 * fd is an open descriptor to an Erlang connection.
456 * to is an Erlang term containing the pid of the intended
458 recipient of the message.
459 * >msg is the Erlang term to be sent.
461 Returns 1 on success, otherwise 0. In the latter case erl_errno
463 is set to one of:
464 EINVAL:
466 Invalid argument: to is not a valid Erlang pid.
467 ENOMEM:
469 No more memory is available.
470 EIO:
472 I/O error.
473 const char *erl_thisalivename()
475 const char *erl_thiscookie()
476 short erl_thiscreation()
477 const char *erl_thishostname()
478 const char *erl_thisnodename()
479 Retrieves information about the C-node. These values are ini‐
481 tially set with erl_connect_init() or erl_connect_xinit().
482 int erl_unpublish(alive)
484 Types:
486 char *alive;
488 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 To unregister a node you have published, you should instead
495 close the descriptor that was returned by ei_publish().
496 Warning:
498 This function is deprecated and will be removed in a future
499 release.
500 alive is the name of the node to unregister, that is, the first
503 component of the node name, without @hostname.
504 If the node was successfully unregistered from EPMD, 0 is
506 returned, otherwise -1 is returned and erl_errno is set to EIO.
507 int erl_xreceive_msg(fd, bufpp, bufsizep, emsg)
509 Types:
511 int fd;
513 unsigned char **bufpp;
514 int *bufsizep;
515 ErlMessage *emsg;
516 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 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 EMSGSIZE:
529 Buffer is too small.
530 ENOMEM:
532 No more memory is available.
533 EIO:
535 I/O error.
536 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 Types:
545 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 Convenience functions for some common name lookup functions.
556
558 If a connection attempt fails, the following can be checked:
559 * erl_errno
561 * That the correct cookie was used
563 * That EPMD is running
565 * That the remote Erlang node on the other side is running the same
567 version of Erlang as the erl_interface library
568Ericsson AB erl_interface 3.13 erl_connect(3)