Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

erl_call (1)

Name

erl_call - Call/start a distributed Erlang node.

Synopsis

Please see following description for synopsis

Description

erl_call(1)                      User Commands                     erl_call(1)



NAME
       erl_call - Call/start a distributed Erlang node.

DESCRIPTION
       erl_call  makes it possible to start and/or communicate with a distrib-
       uted Erlang node. It is built upon  the  Erl_Interface  library  as  an
       example  application.  Its  purpose  is  to  use a Unix shell script to
       interact with a distributed Erlang node. It performs all  communication
       with  the Erlang rex server, using the standard Erlang RPC facility. It
       does not require any special software to be run at  the  Erlang  target
       node.

       The main use is to either start a distributed Erlang node or to make an
       ordinary function call. However, it is also possible to pipe an  Erlang
       module  to  erl_call  and  have  it  compiled, or to pipe a sequence of
       Erlang expressions to be evaluated (similar to the Erlang shell).

       Options, which cause stdin to be read, can be used with  advantage,  as
       scripts  from within (Unix) shell scripts. Another nice use of erl_call
       could be from (HTTP) CGI-bin scripts.

EXPORTS
       erl_call <options>

              Starts/calls Erlang.

              Each option flag is described below with  its  name,  type,  and
              meaning.

                -a [Mod [Fun [Args]]]]:
                  (Optional.)  Applies  the specified function and returns the
                  result. Mod must be specified. However,  start  and  []  are
                  assumed  for unspecified Fun and Args, respectively. Args is
                  to be in the same format as for erlang:apply/3 in ERTS.

                  Notice that this flag takes exactly one argument, so quoting
                  can  be  necessary  to  group Mod, Fun, and Args in a manner
                  dependent on the behavior of your command shell.

                -address [Hostname:]Port:
                  (One of -n, -name, -sname or -address is required.) Hostname
                  is the hostname of the machine that is running the peer node
                  that erl_call shall communicate with. The  default  hostname
                  is  the hostname of the local machine. Port is the port num-
                  ber of the node that erl_call shall  communicate  with.  The
                  -address  flag  cannot be combined with any of the flags -n,
                  -name, -sname or -s.

                  The -address flag is typically useful when one wants to call
                  a node that is running on machine without an accessible epmd
                  instance.

                -c Cookie:
                  (Optional.) Use this option to specify a certain cookie.  If
                  no  cookie  is  specified, the ~/.erlang.cookie file is read
                  and its content is used as cookie. The Erlang node  we  want
                  to communicate with must have the same cookie.

                -d:
                  (Optional.)  Debug mode. This causes all I/O to be output to
                  the ~/.erl_call.out.Nodename file,  where  Nodename  is  the
                  node name of the Erlang node in question.

                -e:
                  (Optional.)  Reads  a  sequence of Erlang expressions, sepa-
                  rated by comma (,) and ended with  a  full  stop  (.),  from
                  stdin  until  EOF (Control-D). Evaluates the expressions and
                  returns  the  result  from  the  last  expression.   Returns
                  {ok,Result} on success.

                -fetch_stdout:
                  (Optional.)  Executes  the code, specified with the -a or -e
                  option, in a new process that has a group leader  that  for-
                  wards  all  stdout  (standard  output)  data  so  that it is
                  printed to stdout of the erl_call process. This  means  that
                  stdout  data  that  are  written during the execution of the
                  called code, by the code and by descendant  processes,  will
                  be  forwarded  (given  that  the  group  leader has not been
                  changed by a call to erlang:group_leader/2).

                  The printed data is UTF-8 encoded.

                  This option is only relevant together with the option -a  or
                  -e.

                  See the documentation of the I/O protocol, for more informa-
                  tion about the group leader concept.

            Note:
                This option only works when erl_call  is  interacting  with  a
                node with a version greater or equal to OTP-24.


                -h HiddenName:
                  (Optional.)  Specifies  the  name  of  the  hidden node that
                  erl_call represents.

                -m:
                  (Optional.) Reads an Erlang module from stdin  and  compiles
                  it.

                -n Node:
                  (One  of -n, -name, -sname or -address is required.) Has the
                  same meaning as -name and can still  be  used  for  backward
                  compatibility reasons.

                -name Node:
                  (One  of -n, -name, -sname or -address is required.) Node is
                  the name of the peer node  to  be  started  or  communicated
                  with.  It  is  assumed  that Node is started with erl -name,
                  which means that fully qualified long node names  are  used.
                  If  option  -s  is specified, an Erlang node will (if neces-
                  sary) be started with erl -name.

                -no_result_term:
                  (Optional.) Do not print the result  term.  This  option  is
                  only relevant together with the options -a and -e.

                -q:
                  (Optional.)  Halts the Erlang node specified with switch -n.
                  This switch overrides switch -s.

                -r:
                  (Optional.) Generates a random name of the hidden node  that
                  erl_call represents.

                -R:
                  (Optional.)  Request  a  dynamic  random name, of the hidden
                  node that erl_call represents, from the peer node. Supported
                  since OTP 23. Prefer -R over -r when doing repeated requests
                  toward the same peer node.

                -s:
                  (Optional.) Starts a distributed Erlang node  if  necessary.
                  This  means  that in a sequence of calls, where '-s' and '-n
                  Node' are constant, only the first call  starts  the  Erlang
                  node.  This  makes  the rest of the communication very fast.
                  This flag is currently only available on Unix-like platforms
                  (Linux, Mac OS X, Solaris, and so on).

                -sname Node:
                  (One  of -n, -name, -sname or -address is required.) Node is
                  the name of the peer node  to  be  started  or  communicated
                  with.  It  is  assumed that Node is started with erl -sname,
                  which means that short node names are used. If option -s  is
                  specified, an Erlang node is started (if necessary) with erl
                  -sname.

                -timeout Seconds:
                  (Optional.) Aborts the erl_call process  after  the  timeout
                  expires.  Note  that  this does not abort commands that have
                  already been started with -a, -e, or similar.

                -v:
                  (Optional.) Prints a lot of  verbose  information.  This  is
                  only useful for the developer and maintainer of erl_call.

                -x ErlScript:
                  (Optional.)  Specifies  another  name  of the Erlang startup
                  script to be  used.  If  not  specified,  the  standard  erl
                  startup script is used.

EXAMPLES
       To start an Erlang node and call erlang:time/0:

       erl_call -s -a 'erlang time' -n madonna
       {18,27,34}


       To terminate an Erlang node by calling erlang:halt/0:

       erl_call -s -a 'erlang halt' -n madonna


       To apply with many arguments:

       erl_call -s -a 'lists seq [1,10]' -n madonna


       To evaluate some expressions (the input ends with EOF (Control-D)):

       erl_call -s -e -n madonna
       statistics(runtime),
       X=1,
       Y=2,
       {_,T}=statistics(runtime),
       {X+Y,T}.
       ^D
       {ok,{3,0}}


       To  compile  a  module and run it (again, the input ends with EOF (Con-
       trol-D)):

       (In the example, the output has been formatted afterwards.)

       erl_call -s -m -a procnames -n madonna
       -module(procnames).
       -compile(export_all).
       start() ->
               P = processes(),
               F = fun(X) -> {X,process_info(X,registered_name)} end,
               lists:map(F,[],P).
       ^D
       [{<madonna@chivas.du.etx.ericsson.se,0,0>,
                         {registered_name,init}},
        {<madonna@chivas.du.etx.ericsson.se,2,0>,
                         {registered_name,erl_prim_loader}},
        {<madonna@chivas.du.etx.ericsson.se,4,0>,
                         {registered_name,error_logger}},
        {<madonna@chivas.du.etx.ericsson.se,5,0>,
                         {registered_name,application_controller}},
        {<madonna@chivas.du.etx.ericsson.se,6,0>,
                         {registered_name,kernel}},
        {<madonna@chivas.du.etx.ericsson.se,7,0>,
                         []},
        {<madonna@chivas.du.etx.ericsson.se,8,0>,
                         {registered_name,kernel_sup}},
        {<madonna@chivas.du.etx.ericsson.se,9,0>,
                         {registered_name,net_sup}},
        {<madonna@chivas.du.etx.ericsson.se,10,0>,
                         {registered_name,net_kernel}},
        {<madonna@chivas.du.etx.ericsson.se,11,0>,
                         []},
        {<madonna@chivas.du.etx.ericsson.se,12,0>,
                         {registered_name,global_name_server}},
        {<madonna@chivas.du.etx.ericsson.se,13,0>,
                         {registered_name,auth}},
        {<madonna@chivas.du.etx.ericsson.se,14,0>,
                         {registered_name,rex}},
        {<madonna@chivas.du.etx.ericsson.se,15,0>,
                         []},
        {<madonna@chivas.du.etx.ericsson.se,16,0>,
                         {registered_name,file_server}},
        {<madonna@chivas.du.etx.ericsson.se,17,0>,
                         {registered_name,code_server}},
        {<madonna@chivas.du.etx.ericsson.se,20,0>,
                         {registered_name,user}},
        {<madonna@chivas.du.etx.ericsson.se,38,0>,
                         []}]


       To forward standard output without printing the result term (again, the
       input ends with EOF (Control-D)):

       erl_call -s -e -sname madonna -fetch_stdout -no_result_term
       io:format("Number of schedulers: ~p~n", [erlang:system_info(schedulers)]),
       io:format("Number of logical cores: ~p~n", [erlang:system_info(logical_processors_available)]).
       ^D
       Number of schedulers: 8
       Number of logical cores: 8




Ericsson AB                    erl_interface 5.0                   erl_call(1)