1erl_call(1)                      User Commands                     erl_call(1)
2
3
4

NAME

6       erl_call - Call/start a distributed Erlang node.
7

DESCRIPTION

9       erl_call  makes it possible to start and/or communicate with a distrib‐
10       uted Erlang node. It is built upon the Erl_Interface library as an  ex‐
11       ample  application. Its purpose is to use a Unix shell script to inter‐
12       act with a distributed Erlang node. It performs all communication  with
13       the  Erlang rex server, using the standard Erlang RPC facility. It does
14       not require any special software to be run at the Erlang target node.
15
16       The main use is to either start a distributed Erlang node or to make an
17       ordinary  function call. However, it is also possible to pipe an Erlang
18       module to erl_call and have it compiled, or to pipe a sequence  of  Er‐
19       lang expressions to be evaluated (similar to the Erlang shell).
20
21       Options,  which  cause stdin to be read, can be used with advantage, as
22       scripts from within (Unix) shell scripts. Another nice use of  erl_call
23       could be from (HTTP) CGI-bin scripts.
24

EXPORTS

26       erl_call <options>
27
28              Starts/calls Erlang.
29
30              Each  option  flag  is  described below with its name, type, and
31              meaning.
32
33                -a [Mod [Fun [Args]]]]:
34                  (Optional.) Applies the specified function and  returns  the
35                  result. Mod must be specified. However, start and [] are as‐
36                  sumed for unspecified Fun and Args, respectively. Args is to
37                  be  in  the same format as for erlang:apply/3 in ERTS except
38                  only a subset of all terms are  allowed.  The  allowed  term
39                  types  are: list (and string representation of list, that is
40                  "example"), tuple, atom and number.
41
42                  Notice that this flag takes exactly one argument, so quoting
43                  can be necessary to group Mod, Fun, and Args in a manner de‐
44                  pendent on the behavior of your command shell.
45
46                -address [Hostname:]Port:
47                  (One of -n, -name, -sname or -address is required.) Hostname
48                  is the hostname of the machine that is running the peer node
49                  that erl_call shall communicate with. The  default  hostname
50                  is  the hostname of the local machine. Port is the port num‐
51                  ber of the node that erl_call shall  communicate  with.  The
52                  -address  flag  cannot be combined with any of the flags -n,
53                  -name, -sname or -s.
54
55                  The -address flag is typically useful when one wants to call
56                  a node that is running on machine without an accessible epmd
57                  instance.
58
59                -c Cookie:
60                  (Optional.) Use this option to specify a certain cookie.  If
61                  no  cookie  is  specified, the ~/.erlang.cookie file is read
62                  and its content is used as cookie. The Erlang node  we  want
63                  to communicate with must have the same cookie.
64
65                -d:
66                  (Optional.)  Debug mode. This causes all I/O to be output to
67                  the ~/.erl_call.out.Nodename file,  where  Nodename  is  the
68                  node name of the Erlang node in question.
69
70                -e:
71                  (Optional.)  Reads  a  sequence of Erlang expressions, sepa‐
72                  rated by comma (,) and ended with  a  full  stop  (.),  from
73                  stdin  until  EOF (Control-D). Evaluates the expressions and
74                  returns the result from the last expression. Returns {ok,Re‐
75                  sult} on success.
76
77                -fetch_stdout:
78                  (Optional.)  Executes  the code, specified with the -a or -e
79                  option, in a new process that has a group leader  that  for‐
80                  wards  all  stdout  (standard  output)  data  so  that it is
81                  printed to stdout of the erl_call process. This  means  that
82                  stdout  data  that  are  written during the execution of the
83                  called code, by the code and by descendant  processes,  will
84                  be  forwarded  (given  that  the  group  leader has not been
85                  changed by a call to erlang:group_leader/2).
86
87                  The printed data is UTF-8 encoded.
88
89                  This option is only relevant together with the option -a  or
90                  -e.
91
92                  See the documentation of the I/O protocol, for more informa‐
93                  tion about the group leader concept.
94
95            Note:
96                This option only works when erl_call  is  interacting  with  a
97                node with a version greater or equal to OTP-24.
98
99
100                -h HiddenName:
101                  (Optional.)  Specifies  the  name  of  the  hidden node that
102                  erl_call represents.
103
104                -m:
105                  (Optional.) Reads an Erlang module from stdin  and  compiles
106                  it.
107
108                -n Node:
109                  (One  of -n, -name, -sname or -address is required.) Has the
110                  same meaning as -name and can still  be  used  for  backward
111                  compatibility reasons.
112
113                -name Node:
114                  (One  of -n, -name, -sname or -address is required.) Node is
115                  the name of the peer node  to  be  started  or  communicated
116                  with.  It  is  assumed  that Node is started with erl -name,
117                  which means that fully qualified long node names  are  used.
118                  If  option  -s  is specified, an Erlang node will (if neces‐
119                  sary) be started with erl -name.
120
121                -no_result_term:
122                  (Optional.) Do not print the result  term.  This  option  is
123                  only relevant together with the options -a and -e.
124
125                -q:
126                  (Optional.)  Halts the Erlang node specified with switch -n.
127                  This switch overrides switch -s.
128
129                -r:
130                  (Optional.) Generates a random name of the hidden node  that
131                  erl_call represents.
132
133                -R:
134                  (Optional.)  Request  a  dynamic  random name, of the hidden
135                  node that erl_call represents, from the peer node. Supported
136                  since OTP 23. Prefer -R over -r when doing repeated requests
137                  toward the same peer node.
138
139                -s:
140                  (Optional.) Starts a distributed Erlang node  if  necessary.
141                  This  means  that in a sequence of calls, where '-s' and '-n
142                  Node' are constant, only the first call  starts  the  Erlang
143                  node.  This  makes  the rest of the communication very fast.
144                  This flag is currently only available on Unix-like platforms
145                  (Linux, Mac OS X, Solaris, and so on).
146
147                -sname Node:
148                  (One  of -n, -name, -sname or -address is required.) Node is
149                  the name of the peer node  to  be  started  or  communicated
150                  with.  It  is  assumed that Node is started with erl -sname,
151                  which means that short node names are used. If option -s  is
152                  specified, an Erlang node is started (if necessary) with erl
153                  -sname.
154
155                -timeout Seconds:
156                  (Optional.) Aborts the erl_call process  after  the  timeout
157                  expires.  Note  that  this does not abort commands that have
158                  already been started with -a, -e, or similar.
159
160                -v:
161                  (Optional.) Prints a lot of  verbose  information.  This  is
162                  only useful for the developer and maintainer of erl_call.
163
164                -x ErlScript:
165                  (Optional.)  Specifies  another  name  of the Erlang startup
166                  script to be  used.  If  not  specified,  the  standard  erl
167                  startup script is used.
168

EXAMPLES

170       To start an Erlang node and call erlang:time/0:
171
172       erl_call -s -a 'erlang time' -n madonna
173       {18,27,34}
174
175
176       To terminate an Erlang node by calling erlang:halt/0:
177
178       erl_call -s -a 'erlang halt' -n madonna
179
180
181       To apply with many arguments:
182
183       erl_call -s -a 'lists seq [1,10]' -n madonna
184
185
186       To evaluate some expressions (the input ends with EOF (Control-D)):
187
188       erl_call -s -e -n madonna
189       statistics(runtime),
190       X=1,
191       Y=2,
192       {_,T}=statistics(runtime),
193       {X+Y,T}.
194       ^D
195       {ok,{3,0}}
196
197
198       To  compile  a  module and run it (again, the input ends with EOF (Con‐
199       trol-D)):
200
201       (In the example, the output has been formatted afterwards.)
202
203       erl_call -s -m -a procnames -n madonna
204       -module(procnames).
205       -compile(export_all).
206       start() ->
207               P = processes(),
208               F = fun(X) -> {X,process_info(X,registered_name)} end,
209               lists:map(F,[],P).
210       ^D
211       [{<madonna@chivas.du.etx.ericsson.se,0,0>,
212                         {registered_name,init}},
213        {<madonna@chivas.du.etx.ericsson.se,2,0>,
214                         {registered_name,erl_prim_loader}},
215        {<madonna@chivas.du.etx.ericsson.se,4,0>,
216                         {registered_name,error_logger}},
217        {<madonna@chivas.du.etx.ericsson.se,5,0>,
218                         {registered_name,application_controller}},
219        {<madonna@chivas.du.etx.ericsson.se,6,0>,
220                         {registered_name,kernel}},
221        {<madonna@chivas.du.etx.ericsson.se,7,0>,
222                         []},
223        {<madonna@chivas.du.etx.ericsson.se,8,0>,
224                         {registered_name,kernel_sup}},
225        {<madonna@chivas.du.etx.ericsson.se,9,0>,
226                         {registered_name,net_sup}},
227        {<madonna@chivas.du.etx.ericsson.se,10,0>,
228                         {registered_name,net_kernel}},
229        {<madonna@chivas.du.etx.ericsson.se,11,0>,
230                         []},
231        {<madonna@chivas.du.etx.ericsson.se,12,0>,
232                         {registered_name,global_name_server}},
233        {<madonna@chivas.du.etx.ericsson.se,13,0>,
234                         {registered_name,auth}},
235        {<madonna@chivas.du.etx.ericsson.se,14,0>,
236                         {registered_name,rex}},
237        {<madonna@chivas.du.etx.ericsson.se,15,0>,
238                         []},
239        {<madonna@chivas.du.etx.ericsson.se,16,0>,
240                         {registered_name,file_server}},
241        {<madonna@chivas.du.etx.ericsson.se,17,0>,
242                         {registered_name,code_server}},
243        {<madonna@chivas.du.etx.ericsson.se,20,0>,
244                         {registered_name,user}},
245        {<madonna@chivas.du.etx.ericsson.se,38,0>,
246                         []}]
247
248
249       To forward standard output without printing the result term (again, the
250       input ends with EOF (Control-D)):
251
252       erl_call -s -e -sname madonna -fetch_stdout -no_result_term
253       io:format("Number of schedulers: ~p~n", [erlang:system_info(schedulers)]),
254       io:format("Number of logical cores: ~p~n", [erlang:system_info(logical_processors_available)]).
255       ^D
256       Number of schedulers: 8
257       Number of logical cores: 8
258
259
260
261
262Ericsson AB                   erl_interface 5.2.2                  erl_call(1)
Impressum