fshell [options] [<script_name>] [<script_args>]
Display help.
Execute the specified one line script.
When running in script mode, keep processing the script even if a previous command has returned an error. Without this option set, an error would cause the processing to abort (and fshell to exit with the error code) unless either &&, || or &| was used to handle the error. For the convenience of scripts that may wish to pass on the flag to sub-instances of fshell, if this flag is specified the environment variable KEEP_GOING is defined.
Set fshell's default current working directory to the given path. Overrides the path inherited from the environment variable PWD.
The name of a script file to be executed. If a path isn't specified, and script_name is not a file in the current working directory, the directory \system\console\scripts is searched on all drives. [filename]
Arguments to be send to the script. Any further arguments or options will be coalesced into this one. [string]
A UNIX-like shell for Symbian OS.
fshell is a console based executable for Symbian OS that behaves somewhat like typical UNIX shells (e.g. Bash, http://www.gnu.org/software/bash/ ). It can be used via a remote console implementation on hardware that doesn't have a full keyboard, giving an experience similar to telnet. fshell contains a set of built-in commands and is also able to launch arbitrary Symbian OS executables. This document describes how to install fshell, how to use its built-in commands and how to use the set of external commands that are also provided.
See Getting Started for a description of how to get console based tools like fshell up and running on the platform you are using. Alternatively, if you would like to configure things yourself, see Console Options for a description of the technology that's available for hosting consoles.
fshell is more like a UNIX shell than a DOS one, so it supports commands like cd Z:\, ls, mkdir and rm. It does also support the DOS-style equivalents z: dir, md, and del via internal fshell aliases. However, you still can't execute eshell *.bat files directly, although you can launch eshell from within fshell by typing 'eshell' so it is possible to run them indirectly if you need to. In practice, many simple bat files can run as fshell scripts due to fshell providing broadly-compatible commands.
At any point through entering a command, pressing the tab key will cause fshell to attempt to complete the part of the line currently being entered. Completion is performed on command names, directory and file names, and environment variables. If a command has been typed, and that command uses a CIF file, completion will additionally be performed on option names. Where the completion choice is ambiguous, a list of choices will be displayed above the line being edited. DOS-style F8 line completion is also supported, this looks in the command history for the first command that matches what has been typed so far. Pressing F8 repeatedly cycles through all the matching commands. For VT100 compatibility (F8 technically only became supported in VT220) F4 has the same effect.
For example:
Input: c:\>under<TAB> Outputs: c:\>undertaker
Input: c:\>kill --<TAB>
Outputs: c:\>kill --
--reason --terminate --panic --thread --match --all
Input: c:\>ls $P<TAB> Outputs: c:\>ls $PWD
The 'up arrow' and 'down arrow' keys can be used to review previously entered commands. The commands entered in a particular session are persisted to disk when fshell is idle or when it is exited.
fshell supports the notion of standard input / ouput. Each command has access to the following IO handles:
fshell arranges for all commands (including external ones run in separate processes) to share its console. This may not seem like a big deal as it's the behaviour you'd expect from using UNIX or DOS, but Symbian OS's default console implementation (econs.dll) and shell implementation (eshell.exe) run external commands in a separate console windows, making it difficult to see any output they may produce because their windows disappear when the command finishes.
With the right configuration tweaks, fshell is capable of 'hooking up' existing CConsoleBase-based command line tools to share fshell's console. In other words fshell can transparently support running legacy command line tools as if they were native fshell tools. The same support is available for PIPS-based tools.
The output of one command to be sent as input to another command. For example:
cat text.txt | match *hello*
This command-line causes the cat command to print the contents of the file text.txt. This output is directed into the match command, which filters out any lines that don't contain the text hello.
The output of commands can be redirected to files. For example:
ls > ls.txt
This causes the output of a directory listing (produced by the ls command) to be redirected to the file ls.txt in the current directory, replacing its current contents. The following command...
ls >> ls.txt
...causes the directory listing to be appended to the current contents of ls.txt.
So far, all the examples have shown how STDOUT can be redirected. It is however also possible to redirect STDERR. For example...
ls 2> stderr.txt > stdout.txt
...redirects STDERR to the file stderr.txt and STDOUT to the file stdout.txt. It is also possible to redirect STDERR to STDOUT (and vice versa), for example:
ls 2>&1 > stderr_and_stdout.txt
Lastly, it is also possible to redirect STDIN to be read from a file rather than from the keyboard. For example...
match *hello* < text.txt
...is equivalent to the first example but avoids using the cat command.
Each command line is treated as a separate job within fshell. Ordinarily, when fshell is executing a job, any characters you enter using the keyboard are directed to the job. The presence of a '&' character at the end a of command line causes it to be run in the background. While such a job is running, fshell will allow you to create and run other command lines. Whilst a job is running in the background, it will not receive any keyboard input.
The following key combinations are intercepted by fshell:
Commands can conditionally execute using the logical 'and' operator &&, the logical 'or' operator || or the (somewhat strange) 'andor' operator &|. For example:
command_1 && command_2
...command_2 is only run if command_1 ran successfully (i.e. returned KErrNone). Or...
command_1 || command_2
...command_2 is only run if command_1 did not run sucessfully (i.e. returned something other than KErrNone).
The 'andor' operator is effectively an alternative for proper block support. It allows a script to contain conditional elements and then execute a block of commands regardless of whether previous ones have returned an error. This might sound like a strange thing to want to do, but it can be useful. For example...
exist some_dir || do_something &| do_something_else
In this example, "do_something" is only executed if "some_dir" does not already exist. However, if "do_something" is run, then "do_something_else" is also guaranteed to also run.
More advanced multi-line conditional statements are possible using the if command. Looping is possible using the while command, or for more basic iterations the repeat or foreach commands.
Environment variables can be defined (and undefined) using the export command. Once defined, variables can be used in fshell command lines (or scripts) by prefixing them with a $ sign as follows:
c:\>export MYVAL 'some value' c:\>echo $MYVAL some value
The var command is useful for manipulating environment variables, particularly in combination with conditional execution:
c:\>export I 3 c:\>var I add 2 c:\>echo "I is now $I" I is now 5
Or, in a script:
export I 0
while I lessthan 10
echo "I is $I"
var I add 1
endwhile
Fshell defines some variables at all times. PWD is set to the current directory, and ? is set to the return code of the last command that ran. For example:
c:\somewhere\>echo "Current dir is: $PWD" Current dir is: c:\somewhere\ c:\somewhere\>error -3 Error: Command "error" failed : KErrCancel (-3) c:\somewhere\>echo "Last command returned $?" Last command returned -3
The special variable FSHELL_PROMPT can be defined to override the default fshell prompt. For example:
c:\>export FSHELL_PROMPT "fsh ^$PWD>" fsh c:\>cd system fsh c:\system\>
Note the use of ^$ to prevent $PWD being expanded when export runs rather than when FSHELL_PROMPT is evaluated by the shell.
See the section on scripting for some further uses of environment variables.
fshell treats the value of the variable ESCAPE (which defaults to ^) as the beginning of an escape sequence. One or more characters following an escape are ignored by fshell's usual string processing. The DOS-style '^' escape is used in preference for the more usual unix '\', because backslash is used as the path separator, and being forced to write cat C:\\dir\\file.txt is considered more inconvenient. It is not recommended to change the escape character, particularly not to '\'.
For example, to get list the contents of a directory whose name contains a space character:
c:\>ls test^ dir test.txt
The following escape sequences have special meanings:
^a (bell)
^b (back space)
^f (form feed)
^n (new line)
^r (carriage return)
^t (horizontal tab)
^v (vertical tab)
^xnn (numeric escape where 'n' is a hex digit)
^Xnn (same as ^x)
^unnnn (numeric escape for a UTF-16 character, where nnnn is a sequence of 4 hex digits)
^Unnnnnnnn (same as ^u but for a UTF-32 character)
^^ (to represent the escape character itself.
if $ESCAPE was a backslash, the sequence would be \\ etc.)
^$ (literal dollar sign. Useful to prevent environment
variable names from being expanded).
For example:
c:\>echo hello^r^x0aworld hello world
Note, the hex value 0x0a corresponds to a new line character, which could have been represented by ^n.
fshell also supports use of single and double quotes around strings. With single quotes environment variables are not expanded and the only supported escape sequence is ^' to produce a literal single quote character. With double quotes, environment variables are expanded and all the above escape sequences are supported. For example:
c:\>export TEST "hello world" c:\>echo '^'$TEST^' will not be expanded' '$TEST' will not be expanded c:\>echo "TEST contains:^r^n$TEST" TEST contains: hello world
If fshell detects that it is launching a PIPS based executable (because it has a UID2 of 0x20004c45, the UID used by the makmake target stdexe), it takes steps to ensure that fshell's native implementations of pipes and environment variables are mapped onto those provided by PIPS. This is done using a helper executable named pipsrun.exe that is responsible for providing the necessary translations. The end result is that the executables that use PIPS can share fshell's console, take part in pipelines and also inherit environment variables.
All commands support the -h (or --help) option, which causes them to display text describing what they do and the syntax they support.
A list of all the supported commands is available here.
fshell supports simple scripting to allow more than one command to be run in succession. Scripts can be invoked in multiple ways:
By running fshell with the script file name as an argument. If a path isn't given, the location \system\console\scripts is searched on all drives if the script isn't found in the current working directory. For example:
c:\>fshell myscript.script # checks for c:\myscript.script and ?:\system\console\scripts\myscript.script c:\>fshell e:\scripts\something # tries to run e:\scripts\something c:\>fshell myscript # checks for c:\myscript, ?:\system\console\scripts\myscript and finally ?:\system\console\scripts\myscript.script
For a script in \system\console\scripts, you can use the name of the script as if it was a normal command, without needing to explicitly type fshell. For example:
c:\>myscript c:\>myscript.script
Scripts in this location will override EXE commands of the same name. Built-in commands cannot be overridden.
By 'executing' the script file itself (this is normally done by selecting the file in the handset's file manager). To support this fshell provides a recognizer plug-in that recognizes files that begin with '#!fshell'. For example:
#!fshell echo 'An example script'
Note, the text following '#!' doesn't need to be 'fshell' - the recognizer will attempt to launch any executable you care to name, providing the script file name in its command line.
Scripts may contain any number of valid fshell command lines. Separate script files may be run in the context of a single fshell instance by using the source command. Note, when fshell runs a script, it defines the following environment variables within itself before doing so:
SCRIPT_PATH
Contains the absolute path (with trailing slash) to the directory that contains the script being executed. This may be used by the script to, for example, load other source files (using source) that exist in the same directory as itself.
SCRIPT_NAME
Contains the name of the script file being executed.
SCRIPT_LINE
Contains the line number of the script that is currently being executed.
$0 ("dollar zero")
The absolute path of the script. Equivalent to $SCRIPT_PATH$SCRIPT_NAME.
$1, $2, etc
If any command line arguments to the script were specified, they are set in the environment. The first argument goes in $1, the second (if present) in $2 etc. For example, a script called envtest.script that just consisted of a call to env would print out something like:
c:\>fshell envtest.script AnArgument "Another argument" Something Else 0=c:\envtest.script 1=AnArgument 2=Another argument 3=Something 4=Else ?=0 ARG_COUNT=4 PWD=c:\ SCRIPT_LINE=1 SCRIPT_NAME=envtest.script SCRIPT_PATH=c:\
ARG_COUNT
The number of arguments to the script. If $ARG_COUNT is 2, there are 2 arguments (in addition to $0), which are named $1 and $2.
All commands, including fshell itself, have the following common set of command line options which control where/how the command runs. These global options are not generally listed when you run command --help. There are no short alternatives for these options.
This allows the console implementation .dll to be overridden. Ordinarily, commands share the console of the fshell instance that launched them. By explicitly specifying a console implementation, a different kind of console may be used to that of the parent fshell instance. Another use of this option is to force the console provider to create a new console window for the command to run in. Note however that not all console implementations support multiple windows. See the consoles documentation for more information.
Only has an effect when used in conjunction with --console. Allows the title of the overridden console window to be specified. Some consoles use this parameter to pass in additional configuration options.
Only has an effect when used in conjunction with --console. Allows the character width and height of the overridden console window to be specified. Note, some console implementations impose restrictions on the minimum and maximum size of their console windows. Generally this option isn't needed any more because in most configurations fshell or the console is capable of auto-detecting the size.
Creates a new persistent console to be used as the console for the command. Cannot be used in conjunction with --console.
This option is internal to fshell and should not be used directly.
When a console is set up as a result of the --console option being specified, the console has the option of outputting debug or diagnostic information to the underlying console, which is usually the context in which the command was launched. The --underlying-console option allows you to override this. If present, text after a colon will be used as the console-title arguments for the underlying console - eg --underlying-console mycons:custom_args Normally only used by the fshell launcher application, this option should be considered internal and unsupported.
Short options may be run together in one block, the only restriction being that an option that takes and argument can only appear as the last option in the block. For example the following are equivalent:
kill --all --thread --match *undertaker
kill -a -T -m *undertaker
kill -aTm *undertaker
Commands that have options that can be specified multiple times can be called in a number of different ways, partly depending on the type of the option. In the most basic case, you can specify the long or the short option repeatedly:
echo --attributes bold --attributes underscore "hello!"
echo -a bold -a underscore "hello!"
For integer options, you can use the above or you can use commas. All of the below are valid fshell syntax and mean exactly the same:
btrace --filter 1 --filter 3
btrace --filter 1,3
btrace -f 1,3
btrace -f1,3
For boolean options, you can additionally specify the short option multiple times in the same block. All of the below mean the same:
fcontacts -v -v list
fcontacts --verbose -v list
fcontacts -vv list
For most commands, it doesn't matter where you put the options - they can go before, after or mixed in with the arguments. The following are all equivalent:
cat --binary file1 file2
cat -b file1 file2
cat file1 file2 -b
cat file1 -b file2
The only exception to this is commands that are designed to take other command-lines as their arguments. These will not parse options themselves if they appear as part of the arguments. For example the repeat command will not parse -k if it appears during the command argument, even though -k is a valid option for repeat. Therefore:
repeat -k 3 ps
is different to:
repeat 3 ps -k
The former means "repeat ps three times, and specify the -k repeat option". The latter means "repeat ps -k three times". Commands that parse in this way can be identified by the phrase "Any further arguments or options will be coalesced into this one." which appears in their documentation. They are specifed in CIF files using the last keyword. The precise rule for how last behaves can be stated as: If the command line following the last argument would need quoting or escaping to make it a single string argument, the string is taken literally as-is. Otherwise, the normal expansions take place:
c:\>echo This^ gets^ expanded^ as^ expected
This gets expanded as expected
c:\>echo "Quoting the entire argument works as normal as well"
Quoting the entire argument works as normal as well
But a command line that has unescaped spaces or quotes will cause the entire thing to be taken literally:
c:\>echo This is taken as one string even though it has spaces and 'unbalanced quotes"
This is taken as one string even though it has spaces and 'unbalanced quotes"
c:\>echo Note how escapes like ^r^n aren't expanded
Note how escapes like ^r^n aren't expanded
c:\>echo "But if it's all in quotes, escapes like ^r^n are expanded"
But if it's all in quotes, escapes like
are expanded
Environment variables are always expanded unless the entire argument is enclosed in 'single quotes'.
Copyright (c) 2006-2011 Accenture. All rights reserved.