1shell(3) Erlang Module Definition shell(3)
2
3
4
6 shell - The Erlang shell.
7
9 This module provides an Erlang shell.
10
11 The shell is a user interface program for entering expression se‐
12 quences. The expressions are evaluated and a value is returned. The
13 shell provides an Emacs like set of shortcuts for editing the text of
14 the current line. See tty - A Command-Line Interface in the ERTS
15 User's Guide for a list of all available shortcuts. You may also change
16 the shortcuts to suit your preferences more, see edlin - line editor in
17 the shell.
18
19 A history mechanism saves previous commands and their values, which can
20 then be incorporated in later commands. How many commands and results
21 to save can be determined by the user, either interactively, by calling
22 history/1 and results/1, or by setting the application configuration
23 parameters shell_history_length and shell_saved_results for the STDLIB
24 application. The shell history can be saved to disk by setting the ap‐
25 plication configuration parameter shell_history for the Kernel applica‐
26 tion.
27
28 The shell uses a helper process for evaluating commands to protect the
29 history mechanism from exceptions. By default the evaluator process is
30 killed when an exception occurs, but by calling catch_exception/1 or by
31 setting the application configuration parameter shell_catch_exception
32 for the STDLIB application this behavior can be changed. See also the
33 example below.
34
35 Variable bindings, and local process dictionary changes that are gener‐
36 ated in user expressions are preserved, and the variables can be used
37 in later commands to access their values. The bindings can also be for‐
38 gotten so the variables can be reused.
39
40 The special shell commands all have the syntax of (local) function
41 calls. They are evaluated as normal function calls and many commands
42 can be used in one expression sequence.
43
44 If a command (local function call) is not recognized by the shell, an
45 attempt is first made to find the function in module user_default,
46 where customized local commands can be placed. If found, the function
47 is evaluated, otherwise an attempt is made to evaluate the function in
48 module shell_default. Module user_default must be explicitly loaded.
49
50 The shell also permits the user to start multiple concurrent jobs. A
51 job can be regarded as a set of processes that can communicate with the
52 shell.
53
54 There is some support for reading and printing records in the shell.
55 During compilation record expressions are translated to tuple expres‐
56 sions. In runtime it is not known whether a tuple represents a record,
57 and the record definitions used by the compiler are unavailable at run‐
58 time. So, to read the record syntax and print tuples as records when
59 possible, record definitions must be maintained by the shell itself.
60
61 The shell commands for reading, defining, forgetting, listing, and
62 printing records are described below. Notice that each job has its own
63 set of record definitions. To facilitate matters, record definitions in
64 modules shell_default and user_default (if loaded) are read each time a
65 new job is started. For example, adding the following line to user_de‐
66 fault makes the definition of file_info readily available in the shell:
67
68 -include_lib("kernel/include/file.hrl").
69
70 The shell runs in two modes:
71
72 * Normal (possibly restricted) mode, in which commands can be edited
73 and expressions evaluated
74
75 * Job Control Mode, JCL, in which jobs can be started, killed, de‐
76 tached, and connected
77
78 Only the currently connected job can 'talk' to the shell.
79
81 The commands below are the built-in shell commands that are always
82 available. In most system the commands listed in the c(3) module are
83 also available in the shell.
84
85 b():
86 Prints the current variable bindings.
87
88 f():
89 Removes all variable bindings.
90
91 f(X):
92 Removes the binding of variable X.
93
94 Note:
95 If a huge value is stored in a variable binding, you have to both
96 call f(X) and call history(0) or results(0) to free up that memory.
97
98
99 h():
100 Prints the history list.
101
102 history(N):
103 Sets the number of previous commands to keep in the history list to
104 N. The previous number is returned. Defaults to 20.
105
106 results(N):
107 Sets the number of results from previous commands to keep in the
108 history list to N. The previous number is returned. Defaults to 20.
109
110 e(N):
111 Repeats command N, if N is positive. If it is negative, the Nth
112 previous command is repeated (that is, e(-1) repeats the previous
113 command).
114
115 v(N):
116 Uses the return value of command N in the current command, if N is
117 positive. If it is negative, the return value of the Nth previous
118 command is used (that is, v(-1) uses the value of the previous com‐
119 mand).
120
121 help():
122 Evaluates shell_default:help().
123
124 h(Module, Function):
125 Print the documentation for Module:Function in the shell if avail‐
126 able.
127
128 ht(Module, Type):
129 Print the documentation for Module:Type in the shell if available.
130
131 hcb(Module, Callback):
132 Print the documentation for Module:Callback in the shell if avail‐
133 able.
134
135 c(Mod):
136 Evaluates shell_default:c(Mod). This compiles and loads the module
137 Mod and purges old versions of the code, if necessary. Mod can be
138 either a module name or a a source file path, with or without .erl
139 extension.
140
141 catch_exception(Bool):
142 Sets the exception handling of the evaluator process. The previous
143 exception handling is returned. The default (false) is to kill the
144 evaluator process when an exception occurs, which causes the shell
145 to create a new evaluator process. When the exception handling is
146 set to true, the evaluator process lives on. This means, for exam‐
147 ple, that ports and ETS tables as well as processes linked to the
148 evaluator process survive the exception.
149
150 rd(RecordName, RecordDefinition):
151 Defines a record in the shell. RecordName is an atom and RecordDef‐
152 inition lists the field names and the default values. Usually
153 record definitions are made known to the shell by use of the
154 rr/1,2,3 commands described below, but sometimes it is handy to de‐
155 fine records on the fly.
156
157 rf():
158 Removes all record definitions, then reads record definitions from
159 the modules shell_default and user_default (if loaded). Returns the
160 names of the records defined.
161
162 rf(RecordNames):
163 Removes selected record definitions. RecordNames is a record name
164 or a list of record names. To remove all record definitions, use
165 '_'.
166
167 rl():
168 Prints all record definitions.
169
170 rl(RecordNames):
171 Prints selected record definitions. RecordNames is a record name or
172 a list of record names.
173
174 rp(Term):
175 Prints a term using the record definitions known to the shell. All
176 of Term is printed; the depth is not limited as is the case when a
177 return value is printed.
178
179 rr(Module):
180 Reads record definitions from a module's BEAM file. If there are no
181 record definitions in the BEAM file, the source file is located and
182 read instead. Returns the names of the record definitions read.
183 Module is an atom.
184
185 rr(Wildcard):
186 Reads record definitions from files. Existing definitions of any of
187 the record names read are replaced. Wildcard is a wildcard string
188 as defined in filelib(3), but not an atom.
189
190 rr(WildcardOrModule, RecordNames):
191 Reads record definitions from files but discards record names not
192 mentioned in RecordNames (a record name or a list of record names).
193
194 rr(WildcardOrModule, RecordNames, Options):
195 Reads record definitions from files. The compiler options {i, Dir},
196 {d, Macro}, and {d, Macro, Value} are recognized and used for set‐
197 ting up the include path and macro definitions. To read all record
198 definitions, use '_' as value of RecordNames.
199
201 The following example is a long dialog with the shell. Commands start‐
202 ing with > are inputs to the shell. All other lines are output from the
203 shell.
204
205 strider 1> erl
206 Erlang (BEAM) emulator version 5.3 [hipe] [threads:0]
207
208 Eshell V5.3 (abort with ^G)
209 1> Str = "abcd".
210 "abcd"
211
212 Command 1 sets variable Str to string "abcd".
213
214 2> L = length(Str).
215 4
216
217 Command 2 sets L to the length of string Str.
218
219 3> Descriptor = {L, list_to_atom(Str)}.
220 {4,abcd}
221
222 Command 3 builds the tuple Descriptor, evaluating the BIF
223 list_to_atom/1.
224
225 4> L.
226 4
227
228 Command 4 prints the value of variable L.
229
230 5> b().
231 Descriptor = {4,abcd}
232 L = 4
233 Str = "abcd"
234 ok
235
236 Command 5 evaluates the internal shell command b(), which is an abbre‐
237 viation of "bindings". This prints the current shell variables and
238 their bindings. ok at the end is the return value of function b().
239
240 6> f(L).
241 ok
242
243 Command 6 evaluates the internal shell command f(L) (abbreviation of
244 "forget"). The value of variable L is removed.
245
246 7> b().
247 Descriptor = {4,abcd}
248 Str = "abcd"
249 ok
250
251 Command 7 prints the new bindings.
252
253 8> f(L).
254 ok
255
256 Command 8 has no effect, as L has no value.
257
258 9> {L, _} = Descriptor.
259 {4,abcd}
260
261 Command 9 performs a pattern matching operation on Descriptor, binding
262 a new value to L.
263
264 10> L.
265 4
266
267 Command 10 prints the current value of L.
268
269 11> {P, Q, R} = Descriptor.
270 ** exception error: no match of right hand side value {4,abcd}
271
272 Command 11 tries to match {P, Q, R} against Descriptor, which is {4,
273 abc}. The match fails and none of the new variables become bound. The
274 printout starting with "** exception error:" is not the value of the
275 expression (the expression had no value because its evaluation failed),
276 but a warning printed by the system to inform the user that an error
277 has occurred. The values of the other variables (L, Str, and so on) are
278 unchanged.
279
280 12> P.
281 * 1:1: variable 'P' is unbound
282 13> Descriptor.
283 {4,abcd}
284
285 Commands 12 and 13 show that P is unbound because the previous command
286 failed, and that Descriptor has not changed.
287
288 14>{P, Q} = Descriptor.
289 {4,abcd}
290 15> P.
291 4
292
293 Commands 14 and 15 show a correct match where P and Q are bound.
294
295 16> f().
296 ok
297
298 Command 16 clears all bindings.
299
300 The next few commands assume that test1:demo(X) is defined as follows:
301
302 demo(X) ->
303 put(aa, worked),
304 X = 1,
305 X + 10.
306
307 17> put(aa, hello).
308 undefined
309 18> get(aa).
310 hello
311
312 Commands 17 and 18 set and inspect the value of item aa in the process
313 dictionary.
314
315 19> Y = test1:demo(1).
316 11
317
318 Command 19 evaluates test1:demo(1). The evaluation succeeds and the
319 changes made in the process dictionary become visible to the shell. The
320 new value of dictionary item aa can be seen in command 20.
321
322 20> get().
323 [{aa,worked}]
324 21> put(aa, hello).
325 worked
326 22> Z = test1:demo(2).
327 ** exception error: no match of right hand side value 1
328 in function test1:demo/1
329
330 Commands 21 and 22 change the value of dictionary item aa to hello and
331 call test1:demo(2). Evaluation fails and the changes made to the dic‐
332 tionary in test1:demo(2), before the error occurred, are discarded.
333
334 23> Z.
335 * 1:1: variable 'Z' is unbound
336 24> get(aa).
337 hello
338
339 Commands 23 and 24 show that Z was not bound and that dictionary item
340 aa has retained its original value.
341
342 25> erase(), put(aa, hello).
343 undefined
344 26> spawn(test1, demo, [1]).
345 <0.57.0>
346 27> get(aa).
347 hello
348
349 Commands 25, 26, and 27 show the effect of evaluating test1:demo(1) in
350 the background. In this case, the expression is evaluated in a newly
351 spawned process. Any changes made in the process dictionary are local
352 to the newly spawned process and therefore not visible to the shell.
353
354 28> io:format("hello hello\n").
355 hello hello
356 ok
357 29> e(28).
358 hello hello
359 ok
360 30> v(28).
361 ok
362
363 Commands 28, 29 and 30 use the history facilities of the shell. Command
364 29 re-evaluates command 28. Command 30 uses the value (result) of com‐
365 mand 28. In the cases of a pure function (a function with no side ef‐
366 fects), the result is the same. For a function with side effects, the
367 result can be different.
368
369 The next few commands show some record manipulation. It is assumed that
370 ex.erl defines a record as follows:
371
372 -record(rec, {a, b = val()}).
373
374 val() ->
375 3.
376
377 31> c(ex).
378 {ok,ex}
379 32> rr(ex).
380 [rec]
381
382 Commands 31 and 32 compile file ex.erl and read the record definitions
383 in ex.beam. If the compiler did not output any record definitions on
384 the BEAM file, rr(ex) tries to read record definitions from the source
385 file instead.
386
387 33> rl(rec).
388 -record(rec,{a,b = val()}).
389 ok
390
391 Command 33 prints the definition of the record named rec.
392
393 34> #rec{}.
394 ** exception error: undefined shell command val/0
395
396 Command 34 tries to create a rec record, but fails as function val/0 is
397 undefined.
398
399 35> #rec{b = 3}.
400 #rec{a = undefined,b = 3}
401
402 Command 35 shows the workaround: explicitly assign values to record
403 fields that cannot otherwise be initialized.
404
405 36> rp(v(-1)).
406 #rec{a = undefined,b = 3}
407 ok
408
409 Command 36 prints the newly created record using record definitions
410 maintained by the shell.
411
412 37> rd(rec, {f = orddict:new()}).
413 rec
414
415 Command 37 defines a record directly in the shell. The definition re‐
416 places the one read from file ex.beam.
417
418 38> #rec{}.
419 #rec{f = []}
420 ok
421
422 Command 38 creates a record using the new definition, and prints the
423 result.
424
425 39> rd(rec, {c}), A.
426 * 1:15: variable 'A' is unbound
427 40> #rec{}.
428 #rec{c = undefined}
429 ok
430
431 Command 39 and 40 show that record definitions are updated as side ef‐
432 fects. The evaluation of the command fails, but the definition of rec
433 has been carried out.
434
435 For the next command, it is assumed that test1:loop(N) is defined as
436 follows:
437
438 loop(N) ->
439 io:format("Hello Number: ~w~n", [N]),
440 loop(N+1).
441
442 41> test1:loop(0).
443 Hello Number: 0
444 Hello Number: 1
445 Hello Number: 2
446 Hello Number: 3
447
448 User switch command
449 --> i
450 --> c
451 Hello Number: 3374
452 Hello Number: 3375
453 Hello Number: 3376
454 Hello Number: 3377
455 Hello Number: 3378
456 ** exception exit: killed
457
458 Command 41 evaluates test1:loop(0), which puts the system into an infi‐
459 nite loop. At this point the user types ^G (Control G), which suspends
460 output from the current process, which is stuck in a loop, and acti‐
461 vates JCL mode. In JCL mode the user can start and stop jobs.
462
463 In this particular case, command i ("interrupt") terminates the looping
464 program, and command c connects to the shell again. As the process was
465 running in the background before we killed it, more printouts occur be‐
466 fore message "** exception exit: killed" is shown.
467
468 42> E = ets:new(t, []).
469 #Ref<0.1662103692.2407923716.214192>
470
471 Command 42 creates an ETS table.
472
473 43> ets:insert({d,1,2}).
474 ** exception error: undefined function ets:insert/1
475
476 Command 43 tries to insert a tuple into the ETS table, but the first
477 argument (the table) is missing. The exception kills the evaluator
478 process.
479
480 44> ets:insert(E, {d,1,2}).
481 ** exception error: argument is of wrong type
482 in function ets:insert/2
483 called as ets:insert(16,{d,1,2})
484
485 Command 44 corrects the mistake, but the ETS table has been destroyed
486 as it was owned by the killed evaluator process.
487
488 45> f(E).
489 ok
490 46> catch_exception(true).
491 false
492
493 Command 46 sets the exception handling of the evaluator process to
494 true. The exception handling can also be set when starting Erlang by
495 erl -stdlib shell_catch_exception true.
496
497 47> E = ets:new(t, []).
498 #Ref<0.1662103692.2407923716.214197>
499 48> ets:insert({d,1,2}).
500 * exception error: undefined function ets:insert/1
501
502 Command 48 makes the same mistake as in command 43, but this time the
503 evaluator process lives on. The single star at the beginning of the
504 printout signals that the exception has been caught.
505
506 49> ets:insert(E, {d,1,2}).
507 true
508
509 Command 49 successfully inserts the tuple into the ETS table.
510
511 50> ets:insert(#Ref<0.1662103692.2407923716.214197>, {e,3,4}).
512 true
513
514 Command 50 inserts another tuple into the ETS table. This time the
515 first argument is the table identifier itself. The shell can parse com‐
516 mands with pids (<0.60.0>), ports (#Port<0.536>), references
517 (#Ref<0.1662103692.2407792644.214210>), and external functions
518 (#Fun<a.b.1>), but the command fails unless the corresponding pid,
519 port, reference, or function can be created in the running system.
520
521 51> halt().
522 strider 2>
523
524 Command 51 exits the Erlang runtime system.
525
527 When the shell starts, it starts a single evaluator process. This
528 process, together with any local processes that it spawns, is referred
529 to as a job. Only the current job, which is said to be connected, can
530 perform operations with standard I/O. All other jobs, which are said to
531 be detached, are blocked if they attempt to use standard I/O.
532
533 All jobs that do not use standard I/O run in the normal way.
534
535 The shell escape key ^G (Control G) detaches the current job and acti‐
536 vates JCL mode. The JCL mode prompt is "-->". If "?" is entered at the
537 prompt, the following help message is displayed:
538
539 --> ?
540 c [nn] - connect to job
541 i [nn] - interrupt job
542 k [nn] - kill job
543 j - list all jobs
544 s [shell] - start local shell
545 r [node [shell]] - start remote shell
546 q - quit erlang
547 ? | h - this message
548
549 The JCL commands have the following meaning:
550
551 c [nn]:
552 Connects to job number <nn> or the current job. The standard shell
553 is resumed. Operations that use standard I/O by the current job are
554 interleaved with user inputs to the shell.
555
556 i [nn]:
557 Stops the current evaluator process for job number nn or the cur‐
558 rent job, but does not kill the shell process. So, any variable
559 bindings and the process dictionary are preserved and the job can
560 be connected again. This command can be used to interrupt an end‐
561 less loop.
562
563 k [nn]:
564 Kills job number nn or the current job. All spawned processes in
565 the job are killed, provided they have not evaluated the
566 group_leader/1 BIF and are located on the local machine. Processes
567 spawned on remote nodes are not killed.
568
569 j:
570 Lists all jobs. A list of all known jobs is printed. The current
571 job name is prefixed with '*'.
572
573 s:
574 Starts a new job. This is assigned the new index [nn], which can be
575 used in references.
576
577 s [shell]:
578 Starts a new job. This is assigned the new index [nn], which can be
579 used in references. If optional argument shell is specified, it is
580 assumed to be a module that implements an alternative shell.
581
582 r [node]:
583 Starts a remote job on node. This is used in distributed Erlang to
584 allow a shell running on one node to control a number of applica‐
585 tions running on a network of nodes. If optional argument shell is
586 specified, it is assumed to be a module that implements an alterna‐
587 tive shell.
588
589 q:
590 Quits Erlang. Notice that this option is disabled if Erlang is
591 started with the ignore break, +Bi, system flag (which can be use‐
592 ful, for example when running a restricted shell, see the next sec‐
593 tion).
594
595 ?:
596 Displays the help message above.
597
598 The behavior of shell escape can be changed by the STDLIB application
599 variable shell_esc. The value of the variable can be either jcl (erl
600 -stdlib shell_esc jcl) or abort (erl -stdlib shell_esc abort). The
601 first option sets ^G to activate JCL mode (which is also default behav‐
602 ior). The latter sets ^G to terminate the current shell and start a new
603 one. JCL mode cannot be invoked when shell_esc is set to abort.
604
605 If you want an Erlang node to have a remote job active from the start
606 (rather than the default local job), start Erlang with flag -remsh, for
607 example, erl -remsh other_node@other_host
608
610 The shell can be started in a restricted mode. In this mode, the shell
611 evaluates a function call only if allowed. This feature makes it possi‐
612 ble to, for example, prevent a user from accidentally calling a func‐
613 tion from the prompt that could harm a running system (useful in combi‐
614 nation with system flag +Bi).
615
616 When the restricted shell evaluates an expression and encounters a
617 function call or an operator application, it calls a callback function
618 (with information about the function call in question). This callback
619 function returns true to let the shell go ahead with the evaluation, or
620 false to abort it. There are two possible callback functions for the
621 user to implement:
622
623 * local_allowed(Func, ArgList, State) -> {boolean(),NewState}
624
625 This is used to determine if the call to the local function Func
626 with arguments ArgList is to be allowed.
627
628 * non_local_allowed(FuncSpec, ArgList, State) -> {boolean(),NewState}
629 | {{redirect,NewFuncSpec,NewArgList},NewState}
630
631 This is used to determine if the call to non-local function Func‐
632 Spec ({Module,Func} or a fun) with arguments ArgList is to be al‐
633 lowed. The return value {redirect,NewFuncSpec,NewArgList} can be
634 used to let the shell evaluate some other function than the one
635 specified by FuncSpec and ArgList.
636
637 These callback functions are called from local and non-local evaluation
638 function handlers, described in the erl_eval manual page. (Arguments in
639 ArgList are evaluated before the callback functions are called.)
640
641 From OTP 25.0, if there are errors evaluating Erlang constructs, such
642 as badmatch during pattern matching or bad_generator in a comprehen‐
643 sion, the evaluator will dispatch to erlang:raise(error, Reason, Stack‐
644 trace). This call will be checked against the non_local_allowed/3 call‐
645 back function. You can either forbid it, allow it, or redirect to an‐
646 other call of your choice.
647
648 Argument State is a tuple {ShellState,ExprState}. The return value New‐
649 State has the same form. This can be used to carry a state between
650 calls to the callback functions. Data saved in ShellState lives through
651 an entire shell session. Data saved in ExprState lives only through the
652 evaluation of the current expression.
653
654 There are two ways to start a restricted shell session:
655
656 * Use STDLIB application variable restricted_shell and specify, as
657 its value, the name of the callback module. Example (with callback
658 functions implemented in callback_mod.erl): $ erl -stdlib re‐
659 stricted_shell callback_mod.
660
661 * From a normal shell session, call function start_restricted/1. This
662 exits the current evaluator and starts a new one in restricted
663 mode.
664
665 Notes:
666
667 * When restricted shell mode is activated or deactivated, new jobs
668 started on the node run in restricted or normal mode, respectively.
669
670 * If restricted mode has been enabled on a particular node, remote
671 shells connecting to this node also run in restricted mode.
672
673 * The callback functions cannot be used to allow or disallow execu‐
674 tion of functions called from compiled code (only functions called
675 from expressions entered at the shell prompt).
676
677 Errors when loading the callback module is handled in different ways
678 depending on how the restricted shell is activated:
679
680 * If the restricted shell is activated by setting the STDLIB variable
681 during emulator startup, and the callback module cannot be loaded,
682 a default restricted shell allowing only the commands q() and
683 init:stop() is used as fallback.
684
685 * If the restricted shell is activated using start_restricted/1 and
686 the callback module cannot be loaded, an error report is sent to
687 the error logger and the call returns {error,Reason}.
688
690 The default shell prompt function displays the name of the node (if the
691 node can be part of a distributed system) and the current command num‐
692 ber. The user can customize the prompt function by calling
693 prompt_func/1 or by setting application configuration parameter
694 shell_prompt_func for the STDLIB application.
695
696 A customized prompt function is stated as a tuple {Mod, Func}. The
697 function is called as Mod:Func(L), where L is a list of key-value pairs
698 created by the shell. Currently there is only one pair: {history, N},
699 where N is the current command number. The function is to return a list
700 of characters or an atom. This constraint is because of the Erlang I/O
701 protocol. Unicode characters beyond code point 255 are allowed in the
702 list and the atom. Notice that in restricted mode the call Mod:Func(L)
703 must be allowed or the default shell prompt function is called.
704
706 catch_exception(Bool) -> boolean()
707
708 Types:
709
710 Bool = boolean()
711
712 Sets the exception handling of the evaluator process. The previ‐
713 ous exception handling is returned. The default (false) is to
714 kill the evaluator process when an exception occurs, which
715 causes the shell to create a new evaluator process. When the ex‐
716 ception handling is set to true, the evaluator process lives on,
717 which means that, for example, ports and ETS tables as well as
718 processes linked to the evaluator process survive the exception.
719
720 history(N) -> integer() >= 0
721
722 Types:
723
724 N = integer() >= 0
725
726 Sets the number of previous commands to keep in the history list
727 to N. The previous number is returned. Defaults to 20.
728
729 prompt_func(PromptFunc) -> PromptFunc2
730
731 Types:
732
733 PromptFunc = PromptFunc2 = default | {module(), atom()}
734
735 Sets the shell prompt function to PromptFunc. The previous
736 prompt function is returned.
737
738 results(N) -> integer() >= 0
739
740 Types:
741
742 N = integer() >= 0
743
744 Sets the number of results from previous commands to keep in the
745 history list to N. The previous number is returned. Defaults to
746 20.
747
748 start_interactive() -> ok | {error, already_started}
749
750 Starts the interactive shell if it has not already been started.
751 It can be used to programatically start the shell from an es‐
752 cript or when erl is started with the -noinput or -noshell
753 flags.
754
755 start_interactive(InitialShell ::
756 noshell | {module(), atom(), [term()]}) ->
757 ok | {error, already_started}
758
759 start_interactive(InitialShell :: {remote, string()}) ->
760 ok | {error, already_started | noconnection}
761
762 start_interactive(InitialShell ::
763 {node(), {module(), atom(), [term()]}} |
764 {remote,
765 string(),
766 {module(), atom(), [term()]}}) ->
767 ok |
768 {error,
769 already_started | noconnection | badfile |
770 nofile | on_load_failure}
771
772 Starts the interactive shell if it has not already been started.
773 It can be used to programatically start the shell from an es‐
774 cript or when erl is started with the -noinput or -noshell
775 flags. The following options are allowed:
776
777 noshell:
778 Starts the interactive shell as if -noshell was given to
779 erl. This is only useful when erl is started with -noinput
780 and the system want to read input data.
781
782 mfa():
783 Starts the interactive shell using mfa() as the default
784 shell.
785
786 {node(), mfa()}:
787 Starts the interactive shell using mfa() on node() as the
788 default shell.
789
790 {remote, string()}:
791 Starts the interactive shell using as if -remsh was given to
792 erl.
793
794 {remote, string(), mfa()}:
795 Starts the interactive shell using as if -remsh was given to
796 erl but with an alternative shell implementation.
797
798 On error this function will return:
799
800 already_started:
801 if an interactive shell is already started.
802
803 noconnection:
804 if a remote shell was requested but it could not be con‐
805 nected to.
806
807 badfile | nofile | on_load_failure:
808 if a remote shell was requested with a custom mfa(), but the
809 module could not be loaded. See Error Reasons for Code-
810 Loading Functions for a description of the error reasons.
811
812 start_restricted(Module) -> {error, Reason}
813
814 Types:
815
816 Module = module()
817 Reason = code:load_error_rsn()
818
819 Exits a normal shell and starts a restricted shell. Module spec‐
820 ifies the callback module for the functions local_allowed/3 and
821 non_local_allowed/3. The function is meant to be called from the
822 shell.
823
824 If the callback module cannot be loaded, an error tuple is re‐
825 turned. The Reason in the error tuple is the one returned by the
826 code loader when trying to load the code of the callback module.
827
828 stop_restricted() -> no_return()
829
830 Exits a restricted shell and starts a normal shell. The function
831 is meant to be called from the shell.
832
833 strings(Strings) -> Strings2
834
835 Types:
836
837 Strings = Strings2 = boolean()
838
839 Sets pretty printing of lists to Strings. The previous value of
840 the flag is returned.
841
842 The flag can also be set by the STDLIB application variable
843 shell_strings. Defaults to true, which means that lists of inte‐
844 gers are printed using the string syntax, when possible. Value
845 false means that no lists are printed using the string syntax.
846
847 whereis() -> pid() | undefined
848
849 Returns the current shell process on the node where the calling
850 process' group_leader is located. If that node has no shell this
851 function will return undefined.
852
853
854
855Ericsson AB stdlib 5.1.1 shell(3)