.TH erl_call 1 "erl_interface 4.0.2" "Ericsson AB" "User Commands" .SH NAME erl_call \- Call/start a distributed Erlang node. .SH DESCRIPTION .LP \fIerl_call\fR\& makes it possible to start and/or communicate with a distributed Erlang node\&. It is built upon the \fIErl_Interface\fR\& 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 \fIrex server\fR\&, using the standard Erlang RPC facility\&. It does not require any special software to be run at the Erlang target node\&. .LP 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 \fIerl_call\fR\& and have it compiled, or to pipe a sequence of Erlang expressions to be evaluated (similar to the Erlang shell)\&. .LP Options, which cause \fIstdin\fR\& to be read, can be used with advantage, as scripts from within (Unix) shell scripts\&. Another nice use of \fIerl_call\fR\& could be from (HTTP) CGI-bin scripts\&. .SH EXPORTS .LP .B erl_call .br .RS .LP Starts/calls Erlang\&. .LP Each option flag is described below with its name, type, and meaning\&. .RS 2 .TP 2 .B \fI-a [Mod [Fun [Args]]]]\fR\&: (\fIOptional\&.\fR\&) Applies the specified function and returns the result\&. \fIMod\fR\& must be specified\&. However, \fIstart\fR\& and \fI[]\fR\& are assumed for unspecified \fIFun\fR\& and \fIArgs\fR\&, respectively\&. \fIArgs\fR\& is to be in the same format as for \fIerlang:apply/3\fR\& in \fIERTS\fR\&\&. .RS 2 .LP Notice that this flag takes exactly one argument, so quoting can be necessary to group \fIMod\fR\&, \fIFun\fR\&, and \fIArgs\fR\& in a manner dependent on the behavior of your command shell\&. .RE .TP 2 .B \fI-address [Hostname:]Port\fR\&: (One of \fI-n\fR\&, \fI-name\fR\&, \fI-sname\fR\& or \fI-address\fR\& is required\&.) \fIHostname\fR\& is the hostname of the machine that is running the peer node that \fIerl_call\fR\& shall communicate with\&. The default hostname is the hostname of the local machine\&. \fIPort\fR\& is the port number of the node that \fIerl_call\fR\& shall communicate with\&. The \fI-address\fR\& flag cannot be combined with any of the flags \fI-n\fR\&, \fI-name\fR\&, \fI-sname\fR\& or \fI-s\fR\&\&. .RS 2 .LP The \fI-address\fR\& flag is typically useful when one wants to call a node that is running on machine without an accessible epmd instance\&. .RE .TP 2 .B \fI-c Cookie\fR\&: (\fIOptional\&.\fR\&) Use this option to specify a certain cookie\&. If no cookie is specified, the \fI~/\&.erlang\&.cookie\fR\& file is read and its content is used as cookie\&. The Erlang node we want to communicate with must have the same cookie\&. .TP 2 .B \fI-d\fR\&: (\fIOptional\&.\fR\&) Debug mode\&. This causes all I/O to be output to the \fI~/\&.erl_call\&.out\&.Nodename\fR\& file, where \fINodename\fR\& is the node name of the Erlang node in question\&. .TP 2 .B \fI-e\fR\&: (\fIOptional\&.\fR\&) Reads a sequence of Erlang expressions, separated by comma (,) and ended with a full stop (\&.), from \fIstdin\fR\& until EOF (Control-D)\&. Evaluates the expressions and returns the result from the last expression\&. Returns \fI{ok,Result}\fR\& on success\&. .TP 2 .B \fI-h HiddenName\fR\&: (\fIOptional\&.\fR\&) Specifies the name of the hidden node that \fIerl_call\fR\& represents\&. .TP 2 .B \fI-m\fR\&: (\fIOptional\&.\fR\&) Reads an Erlang module from \fIstdin\fR\& and compiles it\&. .TP 2 .B \fI-n Node\fR\&: (One of \fI-n\fR\&, \fI-name\fR\&, \fI-sname\fR\& or \fI-address\fR\& is required\&.) Has the same meaning as \fI-name\fR\& and can still be used for backward compatibility reasons\&. .TP 2 .B \fI-name Node\fR\&: (One of \fI-n\fR\&, \fI-name\fR\&, \fI-sname\fR\& or \fI-address\fR\& is required\&.) \fINode\fR\& is the name of the peer node to be started or communicated with\&. It is assumed that \fINode\fR\& is started with \fIerl -name\fR\&, which means that fully qualified long node names are used\&. If option \fI-s\fR\& is specified, an Erlang node will (if necessary) be started with \fIerl -name\fR\&\&. .TP 2 .B \fI-q\fR\&: (\fIOptional\&.\fR\&) Halts the Erlang node specified with switch \fI-n\fR\&\&. This switch overrides switch \fI-s\fR\&\&. .TP 2 .B \fI-r\fR\&: (\fIOptional\&.\fR\&) Generates a random name of the hidden node that \fIerl_call\fR\& represents\&. .TP 2 .B \fI-R\fR\&: (\fIOptional\&.\fR\&) Request a dynamic random name, of the hidden node that \fIerl_call\fR\& represents, from the peer node\&. Supported since OTP 23\&. Prefer \fI-R\fR\& over \fI-r\fR\& when doing repeated requests toward the same peer node\&. .TP 2 .B \fI-s\fR\&: (\fIOptional\&.\fR\&) Starts a distributed Erlang node if necessary\&. This means that in a sequence of calls, where \&'\fI-s\fR\&\&' and \&'\fI-n Node\fR\&\&' 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)\&. .TP 2 .B \fI-sname Node\fR\&: (One of \fI-n\fR\&, \fI-name\fR\&, \fI-sname\fR\& or \fI-address\fR\& is required\&.) \fINode\fR\& is the name of the peer node to be started or communicated with\&. It is assumed that \fINode\fR\& is started with \fIerl -sname\fR\&, which means that short node names are used\&. If option \fI-s\fR\& is specified, an Erlang node is started (if necessary) with \fIerl -sname\fR\&\&. .TP 2 .B \fI-timeout Seconds\fR\&: (\fIOptional\&.\fR\&) Aborts the \fIerl_call\fR\& process after the timeout expires\&. Note that this does not abort commands that have already been started with \fI-a\fR\&, \fI-e\fR\&, or similar\&. .TP 2 .B \fI-v\fR\&: (\fIOptional\&.\fR\&) Prints a lot of \fIverbose\fR\& information\&. This is only useful for the developer and maintainer of \fIerl_call\fR\&\&. .TP 2 .B \fI-x ErlScript\fR\&: (\fIOptional\&.\fR\&) Specifies another name of the Erlang startup script to be used\&. If not specified, the standard \fIerl\fR\& startup script is used\&. .RE .RE .SH "EXAMPLES" .LP To start an Erlang node and call \fIerlang:time/0\fR\&: .LP .nf erl_call -s -a 'erlang time' -n madonna {18,27,34} .fi .LP To terminate an Erlang node by calling \fIerlang:halt/0\fR\&: .LP .nf erl_call -s -a 'erlang halt' -n madonna .fi .LP To apply with many arguments: .LP .nf erl_call -s -a 'lists seq [1,10]' -n madonna .fi .LP To evaluate some expressions (\fIthe input ends with EOF (Control-D)\fR\&): .LP .nf erl_call -s -e -n madonna statistics(runtime), X=1, Y=2, {_,T}=statistics(runtime), {X+Y,T}. ^D {ok,{3,0}} .fi .LP To compile a module and run it (\fIagain, the input ends with EOF (Control-D)\fR\&): .LP (In the example, the output has been formatted afterwards\&.) .LP .nf 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 [{, {registered_name,init}}, {, {registered_name,erl_prim_loader}}, {, {registered_name,error_logger}}, {, {registered_name,application_controller}}, {, {registered_name,kernel}}, {, []}, {, {registered_name,kernel_sup}}, {, {registered_name,net_sup}}, {, {registered_name,net_kernel}}, {, []}, {, {registered_name,global_name_server}}, {, {registered_name,auth}}, {, {registered_name,rex}}, {, []}, {, {registered_name,file_server}}, {, {registered_name,code_server}}, {, {registered_name,user}}, {, []}] .fi