👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for shell (linux section 3erl)

shell(3erl)			     Erlang Module Definition			      shell(3erl)

NAME
       shell - The Erlang Shell

DESCRIPTION
       The module shell implements an Erlang shell.

       The  shell  is a user interface program for entering expression sequences. The expressions
       are evaluated and a value is returned. A history mechanism  saves  previous  commands  and
       their  values,  which  can  then  be incorporated in later commands. How many commands and
       results to save can be determined by the user, either interactively, by calling shell:his-
       tory/1  and  shell:results/1  ,	or  by	setting  the application configuration parameters
       shell_history_length and shell_saved_results for the application STDLIB.

       The shell uses a helper process for evaluating commands in order to  protect  the  history
       mechanism  from	exceptions.  By default the evaluator process is killed when an exception
       occurs, but by calling shell:catch_exception/1 or by setting the application configuration
       parameter  shell_catch_exception  for the application STDLIB this behavior can be changed.
       See also the example below.

       Variable bindings, and local process  dictionary  changes  which  are  generated  in  user
       expressions are preserved, and the variables can be used in later commands to access their
       values. The bindings can also be forgotten so the variables can be re-used.

       The special shell commands all have the syntax of (local) function calls. They are  evalu-
       ated as normal function calls and many commands can be used in one expression sequence.

       If  a  command  (local  function call) is not recognized by the shell, an attempt is first
       made to find the function in the module user_default , where customized local commands can
       be  placed.  If	found,	then  the function is evaluated. Otherwise, an attempt is made to
       evaluate the function in the module  shell_default  .  The  module  user_default  must  be
       explicitly loaded.

       The  shell  also permits the user to start multiple concurrent jobs. A job can be regarded
       as a set of processes which can communicate with the shell.

       There is some support for reading and printing records in the  shell.  During  compilation
       record expressions are translated to tuple expressions. In runtime it is not known whether
       a tuple actually represents a record. Nor are the  record  definitions  used  by  compiler
       available  at  runtime.	So in order to read the record syntax and print tuples as records
       when possible, record definitions have to be maintained by the  shell  itself.  The  shell
       commands  for  reading,	defining, forgetting, listing, and printing records are described
       below. Note that each job has its own set of record  definitions.  To  facilitate  matters
       record definitions in the modules shell_default and user_default (if loaded) are read each
       time a new job is started. For instance, adding the line

		 -include_lib("kernel/include/file.hrl").

       to user_default makes the definition of file_info readily available in the shell.

       The shell runs in two modes:

	 * Normal (possibly restricted) mode, in which commands can  be  edited  and  expressions
	   evaluated.

	 * Job Control Mode JCL , in which jobs can be started, killed, detached and connected.

       Only the currently connected job can 'talk' to the shell.

SHELL COMMANDS
	 b() :
	   Prints the current variable bindings.

	 f() :
	   Removes all variable bindings.

	 f(X) :
	   Removes the binding of variable X .

	 h() :
	   Prints the history list.

	 history(N) :
	   Sets  the  number of previous commands to keep in the history list to N . The previous
	   number is returned. The default number is 20.

	 results(N) :
	   Sets the number of results from previous commands to keep in the history list to  N	.
	   The previous number is returned. The default number is 20.

	 e(N) :
	   Repeats the command N , if N is positive. If it is negative, the N th previous command
	   is repeated (i.e., e(-1) repeats the previous command).

	 v(N) :
	   Uses the return value of the command N in the current command, if N is positive. If it
	   is  negative,  the return value of the N th previous command is used (i.e., v(-1) uses
	   the value of the previous command).

	 help() :
	   Evaluates shell_default:help() .

	 c(File) :
	   Evaluates shell_default:c(File) . This compiles and loads code in File and purges  old
	   versions of code, if necessary. Assumes that the file and module names are the same.

	 catch_exception(Bool) :
	   Sets  the exception handling of the evaluator process. The previous exception handling
	   is returned. The default ( false ) is to kill the evaluator process when an	exception
	   occurs,  which  causes the shell to create a new evaluator process. When the exception
	   handling is set to true the evaluator process lives on which means that  for  instance
	   ports  and ETS tables as well as processes linked to the evaluator process survive the
	   exception.

	 rd(RecordName, RecordDefinition) :
	   Defines a record in the shell. RecordName is an atom and  RecordDefinition  lists  the
	   field  names  and the default values. Usually record definitions are made known to the
	   shell by use of the rr commands described below, but sometimes it is handy  to  define
	   records on the fly.

	 rf() :
	   Removes  all  record  definitions,  then  reads  record  definitions  from the modules
	   shell_default and user_default (if loaded). Returns the names of the records defined.

	 rf(RecordNames) :
	   Removes selected record definitions. RecordNames is a record name or a list of  record
	   names. Use '_' to remove all record definitions.

	 rl() :
	   Prints all record definitions.

	 rl(RecordNames) :
	   Prints  selected  record definitions. RecordNames is a record name or a list of record
	   names.

	 rp(Term) :
	   Prints a term using the record definitions known to the shell. All of Term is printed;
	   the depth is not limited as is the case when a return value is printed.

	 rr(Module) :
	   Reads record definitions from a module's BEAM file. If there are no record definitions
	   in the BEAM file, the source file is located and read instead. Returns  the	names  of
	   the record definitions read. Module is an atom.

	 rr(Wildcard) :
	   Reads  record  definitions from files. Existing definitions of any of the record names
	   read are replaced. Wildcard is a wildcard string as defined in filelib(3erl)  but  not
	   an atom.

	 rr(WildcardOrModule, RecordNames) :
	   Reads record definitions from files but discards record names not mentioned in Record-
	   Names (a record name or a list of record names).

	 rr(WildcardOrModule, RecordNames, Options) :
	   Reads record definitions from files. The compiler options {i, Dir} , {d, Macro} ,  and
	   {d,	Macro,	Value}	are recognized and used for setting up the include path and macro
	   definitions. Use '_' as value of RecordNames to read all record definitions.

EXAMPLE
       The following example is a long dialogue with the shell.  Commands  starting  with  >  are
       inputs to the shell. All other lines are output from the shell. All commands in this exam-
       ple are explained at the end of the dialogue. .

       strider 1> erl
       Erlang (BEAM) emulator version 5.3 [hipe] [threads:0]

       Eshell V5.3  (abort with ^G)
       1>Str = "abcd".
       "abcd"
       2> L = length(Str).
       4
       3> Descriptor = {L, list_to_atom(Str)}.
       {4,abcd}
       4> L.
       4
       5> b().
       Descriptor = {4,abcd}
       L = 4
       Str = "abcd"
       ok
       6> f(L).
       ok
       7> b().
       Descriptor = {4,abcd}
       Str = "abcd"
       ok
       8> f(L).
       ok
       9> {L, _} = Descriptor.
       {4,abcd}
       10> L.
       4
       11> {P, Q, R} = Descriptor.
       ** exception error: no match of right hand side value {4,abcd}
       12> P.
       * 1: variable 'P' is unbound **
       13> Descriptor.
       {4,abcd}
       14>{P, Q} = Descriptor.
       {4,abcd}
       15> P.
       4
       16> f().
       ok
       17> put(aa, hello).
       undefined
       18> get(aa).
       hello
       19> Y = test1:demo(1).
       11
       20> get().
       [{aa,worked}]
       21> put(aa, hello).
       worked
       22> Z = test1:demo(2).
       ** exception error: no match of right hand side value 1
	    in function  test1:demo/1
       23> Z.
       * 1: variable 'Z' is unbound **
       24> get(aa).
       hello
       25> erase(), put(aa, hello).
       undefined
       26> spawn(test1, demo, [1]).
       <0.57.0>
       27> get(aa).
       hello
       28> io:format("hello hello\n").
       hello hello
       ok
       29> e(28).
       hello hello
       ok
       30> v(28).
       ok
       31> c(ex).
       {ok,ex}
       32> rr(ex).
       [rec]
       33> rl(rec).
       -record(rec,{a,b = val()}).
       ok
       34> #rec{}.
       ** exception error: undefined shell command val/0
       35> #rec{b = 3}.
       #rec{a = undefined,b = 3}
       36> rp(v(-1)).
       #rec{a = undefined,b = 3}
       ok
       37> rd(rec, {f = orddict:new()}).
       rec
       38> #rec{}.
       #rec{f = []}
       ok
       39> rd(rec, {c}), A.
       * 1: variable 'A' is unbound **
       40> #rec{}.
       #rec{c = undefined}
       ok
       41> test1:loop(0).
       Hello Number: 0
       Hello Number: 1
       Hello Number: 2
       Hello Number: 3

       User switch command
	--> i
	--> c
       Hello Number: 3374
       Hello Number: 3375
       Hello Number: 3376
       Hello Number: 3377
       Hello Number: 3378
       ** exception exit: killed
       42> E = ets:new(t, []).
       17
       43> ets:insert({d,1,2}).
       ** exception error: undefined function ets:insert/1
       44> ets:insert(E, {d,1,2}).
       ** exception error: argument is of wrong type
	    in function  ets:insert/2
	       called as ets:insert(16,{d,1,2})
       45> f(E).
       ok
       46> catch_exception(true).
       false
       47> E = ets:new(t, []).
       18
       48> ets:insert({d,1,2}).
       * exception error: undefined function ets:insert/1
       49> ets:insert(E, {d,1,2}).
       true
       50> halt().
       strider 2>

COMMENTS
       Command 1 sets the variable Str to the string "abcd" .

       Command 2 sets L to the length of the string evaluating the BIF atom_to_list .

       Command 3 builds the tuple Descriptor .

       Command 4 prints the value of the variable L .

       Command 5 evaluates the internal shell command b() , which is an  abbreviation  of  "bind-
       ings".  This  prints  the current shell variables and their bindings. The ok at the end is
       the return value of the b() function.

       Command 6 f(L) evaluates the internal shell command f(L) (abbreviation of  "forget").  The
       value of the variable L is removed.

       Command 7 prints the new bindings.

       Command 8 has no effect since L has no value.

       Command 9 performs a pattern matching operation on Descriptor , binding a new value to L .

       Command 10 prints the current value of L .

       Command 11 tries to match {P, Q, R} against Descriptor which is {4, abc} . The match fails
       and none of the new variables become bound. The printout  starting  with  "  **	exception
       error: " is not the value of the expression (the expression had no value because its eval-
       uation failed), but rather a warning printed by the system to  inform  the  user  that  an
       error has occurred. The values of the other variables ( L , Str , etc.) are unchanged.

       Commands  12  and  13 show that P is unbound because the previous command failed, and that
       Descriptor has not changed.

       Commands 14 and 15 show a correct match where P and Q are bound.

       Command 16 clears all bindings.

       The next few commands assume that test1:demo(X) is defined in the following way:

       demo(X) ->
	   put(aa, worked),
	   X = 1,
	   X + 10.

       Commands 17 and 18 set and inspect the value of the item aa in the process dictionary.

       Command 19 evaluates test1:demo(1) . The evaluation succeeds and the changes made  in  the
       process	dictionary  become  visible to the shell. The new value of the dictionary item aa
       can be seen in command 20.

       Commands 21 and 22 change  the  value  of  the  dictionary  item  aa  to  hello	and  call
       test1:demo(2) . Evaluation fails and the changes made to the dictionary in test1:demo(2) ,
       before the error occurred, are discarded.

       Commands 23 and 24 show that Z was not bound and that the dictionary item aa has  retained
       its original value.

       Commands  25,  26 and 27 show the effect of evaluating test1:demo(1) in the background. In
       this case, the expression is evaluated in a newly spawned process. Any changes made in the
       process dictionary are local to the newly spawned process and therefore not visible to the
       shell.

       Commands 28, 29 and 30 use the history facilities of the shell.

       Command 29 is e(28) . This re-evaluates command 28. Command 30 is v(28) .  This	uses  the
       value  (result)	of  command  28. In the cases of a pure function (a function with no side
       effects), the result is the same. For a function with side effects, the result can be dif-
       ferent.

       The  next  few commands show some record manipulation. It is assumed that ex.erl defines a
       record like this:

       -record(rec, {a, b = val()}).

       val() ->
	   3.

       Commands 31 and 32 compiles the file ex.erl and reads the record definitions in ex.beam	.
       If  the	compiler  did not output any record definitions on the BEAM file, rr(ex) tries to
       read record definitions from the source file instead.

       Command 33 prints the definition of the record named rec .

       Command 34 tries to create a rec record, but fails since the function val/0 is  undefined.
       Command	35  shows  the	workaround: explicitly assign values to record fields that cannot
       otherwise be initialized.

       Command 36 prints the newly created record using  record  definitions  maintained  by  the
       shell.

       Command	37  defines  a record directly in the shell. The definition replaces the one read
       from the file ex.beam .

       Command 38 creates a record using the new definition, and prints the result.

       Command 39 and 40 show that record definitions are updated as side effects. The evaluation
       of the command fails but the definition of rec has been carried out.

       For the next command, it is assumed that test1:loop(N) is defined in the following way:

       loop(N) ->
	   io:format("Hello Number: ~w~n", [N]),
	   loop(N+1).

       Command	41 evaluates test1:loop(0) , which puts the system into an infinite loop. At this
       point the user types Control G , which suspends output from the current process, which  is
       stuck in a loop, and activates JCL mode. In JCL mode the user can start and stop jobs.

       In this particular case, the i command ("interrupt") is used to terminate the looping pro-
       gram, and the c command is used to connect to the shell again. Since the process was  run-
       ning  in  the background before we killed it, there will be more printouts before the " **
       exception exit: killed " message is shown.

       Command 42 creates an ETS table.

       Command 43 tries to insert a tuple into the ETS table but the first argument  (the  table)
       is missing. The exception kills the evaluator process.

       Command	44  corrects the mistake, but the ETS table has been destroyed since it was owned
       by the killed evaluator process.

       Command 46 sets the exception handling of the evaluator process to true	.  The	exception
       handling  can  also be set when starting Erlang, like this: erl -stdlib shell_catch_excep-
       tion true .

       Command 48 makes the same mistake as in command 43, but this time  the  evaluator  process
       lives  on. The single star at the beginning of the printout signals that the exception has
       been caught.

       Command 49 successfully inserts the tuple into the ETS table.

       The halt() command exits the Erlang runtime system.

JCL MODE
       When the shell starts, it starts a single evaluator process. This process,  together  with
       any local processes which it spawns, is referred to as a job . Only the current job, which
       is said to be connected , can perform operations with standard IO. All other  jobs,  which
       are said to be detached , are blocked if they attempt to use standard IO.

       All jobs which do not use standard IO run in the normal way.

       The  shell  escape key ^G (Control G) detaches the current job and activates JCL mode. The
       JCL mode prompt is "-->" . If "?" is entered at the prompt, the following help message  is
       displayed:

		 --> ?
		 c [nn] 	   - connect to job
		 i [nn] 	   - interrupt job
		 k [nn] 	   - kill job
		 j		   - list all jobs
		 s [shell]	   - start local shell
		 r [node [shell]]  - start remote shell
		 q	  - quit erlang
		 ? | h		   - this message

       The JCL commands have the following meaning:

	 c [nn] :
	   Connects  to job number <nn> or the current job. The standard shell is resumed. Opera-
	   tions which use standard IO by the current job will be interleaved with user inputs to
	   the shell.

	 i [nn] :
	   Stops the current evaluator process for job number nn or the current job, but does not
	   kill the shell process. Accordingly, any variable bindings and the process  dictionary
	   will  be  preserved	and  the  job can be connected again. This command can be used to
	   interrupt an endless loop.

	 k [nn] :
	   Kills job number nn or the current job. All spawned processes in the job  are  killed,
	   provided  they  have not evaluated the group_leader/1 BIF and are located on the local
	   machine. Processes spawned on remote nodes will not be killed.

	 j :
	   Lists all jobs. A list of all known jobs is printed. The current job name is  prefixed
	   with '*'.

	 s :
	   Starts a new job. This will be assigned the new index [nn] which can be used in refer-
	   ences.

	 s [shell] :
	   Starts a new job. This will be assigned the new index [nn] which can be used in refer-
	   ences.  If  the  optional  argument	shell is given, it is assumed to be a module that
	   implements an alternative shell.

	 r [node] :
	   Starts a remote job on node . This is used in distributed Erlang to allow a shell run-
	   ning on one node to control a number of applications running on a network of nodes. If
	   the optional argument shell is given, it is assumed to be a module that implements  an
	   alternative shell.

	 q :
	   Quits  Erlang.  Note that this option is disabled if Erlang is started with the ignore
	   break, +Bi , system flag (which may be useful e.g. when running  a  restricted  shell,
	   see below).

	 ? :
	   Displays this message.

       It  is  possible  to alter the behavior of shell escape by means of the STDLIB application
       variable shell_esc . The value of the variable can be either jcl ( erl  -stdlib	shell_esc
       jcl  )  or abort ( erl -stdlib shell_esc abort ). The first option sets ^G to activate JCL
       mode (which is also default behavior). The latter sets ^G to terminate the  current  shell
       and start a new one. JCL mode cannot be invoked when shell_esc is set to abort .

       If  you	want  an  Erlang node to have a remote job active from the start (rather than the
       default local job), you start Erlang with the -remsh flag. Example: erl	-sname	this_node
       -remsh other_node@other_host

RESTRICTED SHELL
       The  shell  may be started in a restricted mode. In this mode, the shell evaluates a func-
       tion call only if allowed. This feature makes it possible to, for example, prevent a  user
       from  accidentally  calling  a  function  from the prompt that could harm a running system
       (useful in combination with the the system flag +Bi ).

       When the restricted shell evaluates an expression and encounters a  function  call  or  an
       operator  application,  it  calls a callback function (with information about the function
       call in question). This callback function returns true to let the shell go ahead with  the
       evaluation,  or	false to abort it. There are two possible callback functions for the user
       to implement:

       local_allowed(Func, ArgList, State) -> {true,NewState} | {false,NewState}

       to determine if the call to the local function  Func  with  arguments  ArgList  should  be
       allowed.

       non_local_allowed(FuncSpec,  ArgList, State) -> {true,NewState} | {false,NewState} | {{re-
       direct,NewFuncSpec,NewArgList},NewState}

       to determine if the call to non-local function FuncSpec ( {Module,Func}	or  a  fun)  with
       arguments  ArgList  should  be allowed. The return value {redirect,NewFuncSpec,NewArgList}
       can be used to let the shell evaluate some other function than the one specified by  Func-
       Spec and ArgList .

       These  callback	functions are in fact called from local and non-local evaluation function
       handlers, described in the erl_eval manual  page.  (Arguments  in  ArgList  are	evaluated
       before the callback functions are called.)

       The  State  argument is a tuple {ShellState,ExprState} . The return value NewState has the
       same form. This may be used to carry a state between calls to the callback functions. Data
       saved  in  ShellState lives through an entire shell session. Data saved in ExprState lives
       only through the evaluation of the current expression.

       There are two ways to start a restricted shell session:

	 * Use the STDLIB application variable restricted_shell and specify, as  its  value,  the
	   name  of  the  callback  module. Example (with callback functions implemented in call-
	   back_mod.erl): $ erl -stdlib restricted_shell callback_mod

	 * From a normal shell session, call function shell:start_restricted/1 . This  exits  the
	   current evaluator and starts a new one in restricted mode.

       Notes:

	 * When  restricted  shell mode is activated or deactivated, new jobs started on the node
	   will run in restricted or normal mode respectively.

	 * If restricted mode has been enabled on a particular node, remote shells connecting  to
	   this node will also run in restricted mode.

	 * The	callback  functions  cannot  be  used to allow or disallow execution of functions
	   called from compiled code (only functions called from expressions entered at the shell
	   prompt).

       Errors  when loading the callback module is handled in different ways depending on how the
       restricted shell is activated:

	 * If the restricted shell is activated by setting the kernel  variable  during  emulator
	   startup  and the callback module cannot be loaded, a default restricted shell allowing
	   only the commands q() and init:stop() is used as fallback.

	 * If the restricted shell is activated using shell:start_restricted/1 and  the  callback
	   module  cannot  be  loaded,	an  error report is sent to the error logger and the call
	   returns {error,Reason} .

PROMPTING
       The default shell prompt function displays the name of the node (if the node can  be  part
       of a distributed system) and the current command number. The user can customize the prompt
       function by calling shell:prompt_func/1 or by setting the application configuration param-
       eter shell_prompt_func for the application STDLIB.

       A  customized prompt function is stated as a tuple {Mod, Func} . The function is called as
       Mod:Func(L) , where L is a list of key-value pairs created by the shell.  Currently  there
       is  only  one  pair:  {history,	N}  , where N is the current command number. The function
       should return a list of characters or an atom. This constraint is due to the  Erlang  I/O-
       protocol.  Unicode  characters  beyond codepoint 255 are allowed in the list. Note that in
       restricted mode the call Mod:Func(L) must be allowed or the default shell prompt  function
       will be called.

EXPORTS
       history(N) -> integer()

	      Types  N = integer()

	      Sets  the number of previous commands to keep in the history list to N . The previ-
	      ous number is returned. The default number is 20.

       results(N) -> integer()

	      Types  N = integer()

	      Sets the number of results from previous commands to keep in the history list to	N
	      . The previous number is returned. The default number is 20.

       catch_exception(Bool) -> Bool

	      Types  Bool = bool()

	      Sets  the  exception handling of the evaluator process. The previous exception han-
	      dling is returned. The default ( false ) is to kill the evaluator process  when  an
	      exception  occurs,  which  causes the shell to create a new evaluator process. When
	      the exception handling is set to true the evaluator process lives  on  which  means
	      that for instance ports and ETS tables as well as processes linked to the evaluator
	      process survive the exception.

       prompt_func(PromptFunc) -> prompt_func()

	      Types  PromptFunc = prompt_func()
		     prompt_func() = default | {Mod, Func}
		     Mod = Func = atom()

	      Sets the shell prompt function to PromptFunc .  The  previous  prompt  function  is
	      returned.

       start_restricted(Module) -> ok | {error, Reason}

	      Types  Module = atom()
		     Reason = atom()

	      Exits  a	normal shell and starts a restricted shell. Module specifies the callback
	      module for the functions local_allowed/3 and non_local_allowed/3 . The function  is
	      meant to be called from the shell.

	      If  the callback module cannot be loaded, an error tuple is returned. The Reason in
	      the error tuple is the one returned by the code loader when trying to load the code
	      of the callback module.

       stop_restricted() -> ok

	      Exits  a	restricted  shell  and starts a normal shell. The function is meant to be
	      called from the shell.

Ericsson AB				  stdlib 1.17.3 			      shell(3erl)


All times are GMT -4. The time now is 12:10 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password