1erl_connect(3) C Library Functions erl_connect(3)
2
6 erl_connect - Communicate with distributed Erlang.
7
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 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
19 int erl_accept(listensock, conp)
20 Types:
22 int listensock;
24 ErlConnect *conp;
25 This function is used by a server process to accept a connection
27 from a client process.
28 * listensock is an open socket descriptor on which listen()
30 has previously been called.
31 * conp is a pointer to an ErlConnect struct, described as fol‐
33 lows:
34 typedef struct {
36 char ipadr[4];
37 char nodename[MAXNODELEN];
38 } ErlConnect;
39 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 int erl_close_connection(fd)
46 Types:
48 int fd;
50 Closes an open connection to an Erlang node.
52 Fd is a file descriptor obtained from erl_connect() or erl_xcon‐
54 nect().
55 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 int erl_connect(node)
61 int erl_xconnect(addr, alive)
62 Types:
64 char *node, *alive;
66 struct in_addr *addr;
67 Sets up a connection to an Erlang node.
69 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 * addr is the 32-bit IP address of the remote host.
76 * alive is the alivename of the remote node.
78 * node is the name of the remote node.
80 Returns an open file descriptor on success, otherwise a negative
82 value. In the latter case erl_errno is set to one of:
83 EHOSTUNREACH:
85 The remote host node is unreachable.
86 ENOMEM:
88 No more memory is available.
89 EIO:
91 I/O error.
92 Also, errno values from socket(2) and connect(2) system calls
94 can be propagated into erl_errno.
95 Example:
97 #define NODE "madonna@chivas.du.etx.ericsson.se"
99 #define ALIVE "madonna"
100 #define IP_ADDR "150.236.14.75"
101 /*** Variant 1 ***/
103 erl_connect( NODE );
104 /*** Variant 2 ***/
106 struct in_addr addr;
107 addr = inet_addr(IP_ADDR);
108 erl_xconnect( &addr , ALIVE );
109 int erl_connect_init(number, cookie, creation)
112 int erl_connect_xinit(host, alive, node, addr, cookie, creation)
113 Types:
115 int number;
117 char *cookie;
118 short creation;
119 char *host,*alive,*node;
120 struct in_addr *addr;
121 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 erl_connect_xinit() stores for later use information about:
128 * Hostname of the node, host
130 * Alivename, alive
132 * Node name, node
134 * IP address, addr
136 * Cookie, cookie
138 * Creation number, creation
140 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 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 * host is the name of the host on which the node is running.
151 * alive is the alivename of the node.
153 * node is the node name. It is to be of the form alive‐
155 name@hostname.
156 * addr is the 32-bit IP address of host.
158 * 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 * 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 A C-node acting as a server is assigned a creation number when
172 it calls erl_publish().
173 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 Example 1:
179 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 Example 2:
192 if (!erl_connect_init(17, "samplecookiestring...", 0))
194 erl_err_quit("<ERROR> when initializing !");
195 int erl_publish(port)
198 Types:
200 int port;
202 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 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 To unregister with EPMD, simply close the returned descriptor.
213 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 EIO:
218 I/O error.
219 Also, errno values from socket(2) and connect(2) system calls
221 can be propagated into erl_errno.
222 int erl_receive(fd, bufp, bufsize)
224 Types:
226 int fd;
228 char *bufp;
229 int bufsize;
230 Receives a message consisting of a sequence of bytes in the
232 Erlang external format.
233 * fd is an open descriptor to an Erlang connection.
235 * bufp is a buffer large enough to hold the expected message.
237 * bufsize indicates the size of bufp.
239 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 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 EAGAIN:
251 Temporary error: Try again.
252 EMSGSIZE:
254 Buffer is too small.
255 EIO:
257 I/O error.
258 int erl_receive_msg(fd, bufp, bufsize, emsg)
260 Types:
262 int fd;
264 unsigned char *bufp;
265 int bufsize;
266 ErlMessage *emsg;
267 Receives the message into the specified buffer and decodes into
269 (ErlMessage *) emsg.
270 * fd is an open descriptor to an Erlang connection.
272 * bufp is a buffer large enough to hold the expected message.
274 * bufsize indicates the size of bufp.
276 * >emsg is a pointer to an ErlMessage structure into which the
278 message will be decoded. ErlMessage is defined as follows:
279 typedef struct {
281 int type;
282 ETERM *msg;
283 ETERM *to;
284 ETERM *from;
285 char to_name[MAXREGLEN];
286 } ErlMessage;
287 Note:
290 The definition of ErlMessage has changed since earlier versions
291 of Erl_Interface.
292 type identifies the type of message, one of the following:
295 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 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 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 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 Note:
314 It is the caller's responsibility to release the memory pointed
315 to by emsg->msg, emsg->to, and emsg->from.
316 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 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 EMSGSIZE:
330 Buffer is too small.
331 ENOMEM:
333 No more memory is available.
334 EIO:
336 I/O error.
337 int erl_reg_send(fd, to, msg)
339 Types:
341 int fd;
343 char *to;
344 ETERM *msg;
345 Sends an Erlang term to a registered process.
347 * fd is an open descriptor to an Erlang connection.
349 * to is a string containing the registered name of the
351 intended recipient of the message.
352 * msg is the Erlang term to be sent.
354 Returns 1 on success, otherwise 0. In the latter case erl_errno
356 is set to one of:
357 ENOMEM:
359 No more memory is available.
360 EIO:
362 I/O error.
363 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 Types:
369 int fd, timeout;
371 char *mod, *fun;
372 ETERM *args;
373 ErlMessage *emsg;
374 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 * fd is an open descriptor to an Erlang connection.
382 * 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 * mod is the name of the module containing the function to be
388 run on the remote node.
389 * fun is the name of the function to run.
391 * args is an Erlang list, containing the arguments to be
393 passed to the function.
394 * emsg is a message containing the result of the function
396 call.
397 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 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 erl_rpc() returns the remote function's return value on success,
411 otherwise NULL.
412 erl_rpc_to() returns 0 on success, otherwise a negative number.
414 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 When failing, all three functions set erl_errno to one of:
420 ENOMEM:
422 No more memory is available.
423 EIO:
425 I/O error.
426 ETIMEDOUT:
428 Timeout has expired.
429 EAGAIN:
431 Temporary error: Try again.
432 int erl_send(fd, to, msg)
434 Types:
436 int fd;
438 ETERM *to, *msg;
439 Sends an Erlang term to a process.
441 * fd is an open descriptor to an Erlang connection.
443 * to is an Erlang term containing the pid of the intended
445 recipient of the message.
446 * >msg is the Erlang term to be sent.
448 Returns 1 on success, otherwise 0. In the latter case erl_errno
450 is set to one of:
451 EINVAL:
453 Invalid argument: to is not a valid Erlang pid.
454 ENOMEM:
456 No more memory is available.
457 EIO:
459 I/O error.
460 const char *erl_thisalivename()
462 const char *erl_thiscookie()
463 short erl_thiscreation()
464 const char *erl_thishostname()
465 const char *erl_thisnodename()
466 Retrieves information about the C-node. These values are ini‐
468 tially set with erl_connect_init() or erl_connect_xinit().
469 int erl_unpublish(alive)
471 Types:
473 char *alive;
475 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 To unregister a node you have published, you should instead
482 close the descriptor that was returned by ei_publish().
483 Warning:
485 This function is deprecated and will be removed in a future
486 release.
487 alive is the name of the node to unregister, that is, the first
490 component of the node name, without @hostname.
491 If the node was successfully unregistered from EPMD, 0 is
493 returned, otherwise -1 is returned and erl_errno is set to EIO.
494 int erl_xreceive_msg(fd, bufpp, bufsizep, emsg)
496 Types:
498 int fd;
500 unsigned char **bufpp;
501 int *bufsizep;
502 ErlMessage *emsg;
503 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 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 EMSGSIZE:
516 Buffer is too small.
517 ENOMEM:
519 No more memory is available.
520 EIO:
522 I/O error.
523 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 Types:
532 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 Convenience functions for some common name lookup functions.
543
545 If a connection attempt fails, the following can be checked:
546 * erl_errno
548 * That the correct cookie was used
550 * That EPMD is running
552 * That the remote Erlang node on the other side is running the same
554 version of Erlang as the erl_interface library
555Ericsson AB erl_interface 3.10.2.2 erl_connect(3)