Content-type: text/html
Manpage of SH
SH
Section: Misc. Reference Manual Pages (02/15/97)
Updated: Shell
Index
NAME
sh - A Bourne-like Shell for OS-9/68xxx
SYNTAX
sh [<opts>] [<scriptfile>] [<arg1>] ... [<argn>]
FUNCTION
Operating system user interface (shell)
1. ORIGIN, SUPPORT, NO WARRANTY
This program is based on the shell that was part of the initial release of
Andrew S. Tannenbaum's MINIX. It has been adapted to OS-9/68xxx
through a number of
contributions of OS-9/68xxx enthusiasts,
mostly by Reimer Mellin and released as
part of the TOP software package. In 1992, a user's manual was written by
Carsten Emde who also started a changelog protocol and continued development
and maintenance of the sh sources.
From this time onwards, sh is available
as EFFO (European Forum For OS-9) PD disk. Since then, after more than 2000 hours
of programming and testing, sh became nearly 100% compatible with the
standard OS-9/68xxx shell and the Bourne shell; in addition,
it now offers a large part of the
functionality contained in UNIX shells such as csh and bash.
Since 1994, sh for OS-9 is part of the OS-9 release of reccoware's MGR
graphical window system and in June 1997, sh was first uploaded to
ftp://os9archive.rtsi.com. A limited support and, possibly, bug fixing
are offered (but not guaranteed) via e-mail (carsten@ceag.ch).
Because the program is licensed free of charge, there is no warranty for the
program, to the extent permitted by applicable law. Except when otherwise
stated in writing the copyright holders and/or other parties provide the
program "as is" without warranty of any kind, either expressed or implied,
including, but not limited to, the implied warranties of merchantability and
fitness for a particular purpose. The entire risk as to the quality and
performance of the program is with you. Should the program prove defective,
you assume the cost of all necessary servicing, repair or correction.
In no event unless required by applicable law or agreed to in writing will any
copyright holder, or any other party who may modify and/or redistribute the
program as permitted above, be liable to you for damages, including any
general, special, incidental or consequential damages arising out of the use
or inability to use the program (including but not limited to loss of data or
data being rendered inaccurate or losses sustained by you or third parties or
a failure of the program to operate with any other programs), even if such
holder or other party has been advised of the possibility of such damages.
2. INTRODUCTION
The sh shell program was intended as a surrogate for Mware's shell.
Maximum
attention was, therefore, drawn to offer the basic functionality of the Mware
shell and also of the Bourne shell in order to allow using both
OS-9/68xxx
and UNIX shell scripts. In addition, useful features of the csh and
the bash shell have been integrated.
Compatibility of these four sources was,
however, not always possible: the Bourne shell standard output append symbol
(>>), for example, is the standard
error redirection symbol of the Mware
shell.
In addition, command line editing using uEmacs commands was not always
compatible to the SCF line editing commands of the Mware shell: the Mware
shell's redraw current line command (Ctrl-A)
sets the uEmacs cursor to the beginning of a line. As a general programming
rule, compatibility to 'bash' was given the highest priority followed by
compatibility to 'shell'. There are, however, much more compatibilities than
incompatibilities; normally, it does not take more than a day or two to become
familiar with sh for OS-9/68xxx.
3. GETTING STARTED
3.1. Installation
The sh program is located in the CMDS directory
of the distribution disk.
It does not require other modules such as trap handlers to run. It should
be copied to the system's standard execution directory in such a way that it can be
started by typing the
$ sh
command. Normally, however, sh is started directly from the login procedure
that is defined in the password file. A typical entry in the password file
could have the following definitions:
name,*PW*,<gid>.<uid>,<prio>,.,/dd, \
sh -ep="<$HOST/$USER/sh@>$CWD:"
It may also be a good idea to copy the suggested profile file that is
named dot.profile from the SYS directory to the user's home directory:
$ copy /d0/SYS/dot.profile /dd/.profile
This script contains a number of useful settings. There is also an example
login file called dot.login but this file should better not be copied but
only be used as an example, since many settings are system-specific. These
setup files are searched and read, if available, during the initialization
procedure. The contained commands are executed in the same way as if they
had been entered manually. There is also a way to make system-wide default
definitions by creating the file /dd/SYS/profile.
Settings in this file are
evaluated first so that they may be overwritten by alternative settings in a
particular user's $HOME/.profile file.
Subsequently started sh tasks for
script file execution do not read $HOME/.profile, they only evaluate
/dd/SYS/profile. Therefore, the latter must not include functions, grave
construct, read commands or similar; it is merely intended for alias and
environment settings that are user-independent. When sh exits from a
regular interactive session the files .logout
and /dd/SYS/sh.logout are executed,
if available. The -r command line option can be set to completely disable
processing of all named profile files including $HOME/.login etc. If a
user-defined profile file is specified using
the -f=<profile> command line option, this file is evaluated last.
3.2. Supplementary programs
In addition, the distribution disk contains the following binary programs that
may be required to run UNIX scripts under OS-9/68xxx:
Name | Function
|
|
basename |
Transform a fully-qualified file name into the name of its
last element and, optionally, omit suffix
|
dirname |
Transform a fully-qualified file name into the name of its directory
|
cat |
Same as merge, needed for the creation of here files
|
strcmp |
Extended string comparisons
|
|
The programs basename, dirname and strcmp
kindly have been contributed by M.C. Gregorie <Gregorie@Logica.com>.
3.3. Example scripts
Finally, the distribution disk contains a directory SCRIPTS where a number
of sh scripts can be found. They are mainly intended as examples and for
test purposes but some of them may also be copied into the system's
standard execution directory and used as if they were regular programs:
Name | Function
|
|
find | Find a file in the directory tree
|
which | Search for the location of an executable program
|
dev | Same as devs but with argument
|
irq | Same as irqs but with argument
|
|
The find script contains examples for using
both the strcmp program and a
recursive sh function. As a disadvantage, it is relatively slow so that
for everyday's use or on high-volume hard disks this script is better replaced
by a program. There is also an example for an sh function that makes the
del utility interactive and is intended to be added to a user's local
profile file.
4. COMMAND LINE OPTIONS
The following command line arguments are available:
$ sh -?
Syntax: sh [<opts>] [<script>] [<arg1>] ... [<argn>]
Function: Operating system user interface (shell)
Options:
-b block input path while editing
(default)
-C redirected output requires '-' to
overwrite file
-c exit after reading and executing
one command
-d[=<mode>] enable debug output [for <mode>]
-e[=<path>] print error explanations
[using file <path>]
-f=<profile> process profile file <profile> -g command completion includes
exec dirs
-h=<n> set the # of history lines to <n> -i do not suppress shell messages
(default if interactive)
-l require 'logout' to logout
(default automatic)
-p[=<prompt>] print prompt <prompt> -r do not process default profile
files
-s stop command execution
-t echo input lines
-u display references to unset
variables
-v verbose mode (same as '-t')
-w kill all child processes and abort
if carrier lost
-x exit on error (default if non-interactive)
-y try to make standard input path a tty
All options may be prefixed by an 'n' character to
invert their sense
Some of the options can also be set by environment variables or by built-in
commands:
Option | Environment variable | Built-in command
|
|
-e=<path> | setenv EMSG_FILE <path> |
|
-h=<n> | setenv HISTORY <num> | history <n>
|
-p=<prompt> | setenv PS1 <prompt> |
|
|
In addition, the set <option>
syntax can be used to set options within the
current sh session. If "set -" is entered, all options except -l
are set to their default values as described above.
The environment variable HISTORY,
by default, reflects the current size of the history buffer; setting it to
another value does not influence the current history buffer size, but is taken
as default value in any subsequently called interactive sh session.
4.1. Block input path while editing (-b)
Normally, another program's output cannot be redirected to the standard and
error output paths of an sh session, while sh is reading from its standard
input path, e.g. during command line editing. The -nb
option can be specified
to change this behavior; it causes sh to use another read procedure so that
the terminal is not blocked and another program can write to it. This option
may be helpful to simultaneously use a terminal for both displaying messages
on screen and running an sh session. By default, the -b option is set.
4.2. Disallow files to be overwritten by redirected output (-C)
By default, sh will overwrite any existing file to which output is
redirected using the >, 2>, or >> syntax.
If the -C option is set,
however, sh will write an error message and leave the file intact. This
option is identical to bash and also allows to simulate the redirection
behavior of the Mware shell. A file can be forced to be overwritten, even
if the -C option is set, by using the >-, 2>- or
>>- syntax.
4.3. Exit after reading and executing one command (-c)
The -c option forces sh to interpret the subsequent command line option
as a command, to execute it as it were a script command and to stop execution
thereafter immediately. Therefore, the command
sh -c 'echo output string '
will display the string "output string" on screen, while
sh -c echo output string
executes echo and, therefore, does not display anything on screen.
4.4. Enable debug output (-d[=<mode>])
If an interactive command or an sh script does not execute correctly, the
debug option may be used: The command "set -d"enables debug messages in the
current shell, and the command "sh -d <proc>" shows debug messages during
execution of the procedure <proc>.
Debug messages of any child shell process
(explicit and implicit ones) are enabled by setting the environment variable
SHDEBUG to a non-zero value or to on or ON.
They are disabled when SHDEBUG is unset, set to off, OFF
or 0 (zero).
In addition, the "set -d=<mode>" syntax is available to
separately enable and disable specific debug modes:
<mode> | Debug category | Value
|
|
args |
Command line arguments
| 1
|
evalg |
Grave construct before being evaluated
| 2
|
fork |
Command being executed using chainc() of forkc()
| 4
|
grave |
Evaluated grave construct before being executed
| 8
|
insert |
String to be inserted, e.g. when replacing alias
| 16
|
match |
String subjected to global expression match
| 32
|
search |
Attempts to locate a file for execution
| 64
|
trace |
Intermediate command to be executed
| 128
|
|
These modes are stored internally as a bit pattern;
the SHDEBUG environment
variable is, by default, set to the above given value (or-ed together)
whenever the debug mode changes. If, for example, match
and search debug
modes are requested during execution of the procedure <proc>, the command
sh -d=search -d=fork <proc>
can be entered. The commands
setenv SHDEBUG 68
<proc>
have, however, exactly the same effect, but only in the second example remains
the debug mode enabled during all subsequent calls to sh
(unless SHDEBUG is reset to 0 (zero) or unset).
Finally, the commands
set -d=search -d=fork
<proc>
have, again, the same effect during execution of the procedure
<proc> but, in addition, debugging is enabled in the current shell.
4.5. Print error explanations (-e[=<path>])
By default, the -e option is set to the environment
variable EMSG_FILE or to
/dd/SYS/errmsg if EMSG_FILE is not set, but it can be set to any
other file that contains OS-9/68xxx error messages in the required format.
4.6. Process profile file (-f=<profile>)
The file specified as <profile> is processed before sh starts command
execution but after the default profile files ~/login,
/dd/SYS/profile and ~/.profile have been processed.
This makes it possible to overwrite settings
that have been made in one of the default profile files.
4.7. Command completion includes exec dirs (-g)
Whenever sh is in line editing mode, the cursor is at the first position of
the input line or immediately follows a backquote, and the TAB key is hit,
command completion is activated. By default, commands are searched in the
alias list, in the list of currently available functions and in the list of
built-in commands. The -g option is used to additionally include files in
one of the execution directories (any of the PATH
directories and execution directory).
4.8. Set the # of history lines (-h=<n>)
The default number of history lines is the number specified in the HISTORY
environment variable or 0 (zero), if undefined.
The -h=<n> option can be used to
define any number of history lines between 1 and 500.
4.9. Do not suppress shell messages (-i)
When a program returns another value than 0 (zero) or 1
during an interactive sh
session, this error number and, optionally, the error code are displayed on
screen, since the -i option is automatically set,
if sh runs interactively.
The -ni option that is set by default only during execution of an sh
script can be used to explicitly suppress shell messages. On the other hand,
the -i option can be set to explicitly force error messages even during
script execution.
4.10. Require logout to logout (-l)
The -l option is automatically set, if at least one
keycap entry starts with
the escape character; otherwise, it is unset so that an sh session can be
stopped just by entering the eof character (normally ESC).
4.11. Define prompt (-p[=<prompt>])
By default, the -p option is set to the environment
variable PS1 or, if not
set, to @# for a super-user and to @% for any other user,
respectively. The program entry in the above given password file
sh -ep="<$HOST/$USER/sh@>$CWD:"
will invoke sh, for example, with the prompt
<thlos9/carsten/sh1>/h0/SH/DOC:
and define the standard error message file /dd/SYS/errmsg
for the generation of error texts.
4.12. Do not process default profile files (-r)
Normally, the files ~/login, /dd/SYS/profile and ~/.profile,
and the files /dd/SYS/sh.logout and ~/.logout
are executed before sh begins command
execution and before it exits, respectively.
If the -r option is specified, however, none of the named
files are processed.
4.13. Stop command execution (-s)
This option causes sh to immediately stop command execution; it is only
available during script execution and can, for example, be used for testing and
debugging purposes. Any command after
set -s
is prevented from being executed. It must, however, be noticed that this
command is irreversible, since once command execution has been stopped, no
other command can be executed - even not a
set -ns
command.
4.14. Echo input lines (-t)
Every input line is echoed to the output path of the current sh session.
4.15. Display references to unset variables (-u)
Normally, a reference to an undefined variable does not result in an error
message but the variable is defined and an empty string is assigned to it. In
consequence, it is not possible to differentiate between an undefined variable
and a variable that intentionally has been set to contain an empty string,
e.g. using the assign command
var=""
If, however, the -u option is specified, such differentiation is possible,
since this options causes sh to produce an error message whenever an
undefined variable is referenced.
4.16. Verbose mode (-v)
Every input line is echoed to the output path of the current sh session
(same as -t option).
4.17. Kill all child processes and abort if carrier lost (-w)
To become effective, this option requires that sh is the primary (login)
shell and that the driver of the standard input port supports the installation
of a data-carrier-detect interrupt. If this is the case and the carrier
gets lost, sh sends a HANGUP signal to all child processes and aborts with
error E_HANGUP (220).
4.18. Exit on error (-x)
When this option is set and an error occurs, the current sh session exits
immediately. This is the default behavior during execution of a shell script,
while an interactive sh, by default, does not exit on error.
4.19. Try to make standard input path a tty (-y)
The sh built-in command read requires that standard input path is a
terminal. If an sh script containing the read command is started by
another program that does not provide correct setting of the standard input
path but standard output or standard error output path is a terminal,
the -y
option can be specified in which case sh checks standard output and standard
error path and uses one of them for input, if possible.
5. THE TERMCAP DATA BASE AND COMMAND LINE EDITING AND HISTORY
5.1. The termcap data base
The termcap data base is used for two different purposes; first, to store
specific commands that can be sent to the terminal, e.g. for cursor movement,
and, second, for the interpretation of special key sequences that are sent
by the terminal, e.g. from the arrow keys. The latter are needed for command
line editing and will be covered in the next paragraph.
sh for OS-9/68xxx supports
the following terminal commands that are searched in the termcap data base
when the program starts and whenever the
environment variable TERM is modified:
Action | Default | Termcap
|
| | name
|
|
Pad string | None | pc
|
Clear to end of line | None | ce
|
Backspace cursor | Ctrl-H | bc
|
Enter standout mode | None | so
|
End standout | None | se
|
Bell | Ctrl-G | bl
|
Clear screen | None | cl
|
Special keys on HP terminals | None | hs
|
Enable above special keys | None | hx
|
Normal cursor style for insert mode | None | cQ
|
Cursor style for overstrike mode | None | cI
|
Start keypad transmit mode | None | ks
|
End keypad transmit mode | None | ke
|
|
The strings to start and to stop keypad transmit mode are sent, if set, after
sh enters interactive mode and before sh is finishing, respectively.
The ks string is also sent whenever the TERM
environment variable is modified.
5.2. Command line editing and history
One of the most important features of sh for OS-9/68xxx is the command line
editing and history function. Please note that editing of the current command
line is always active; the history function is only active, if enabled using
the -h=<lines> option when sh is started or
using the "history <lines>" syntax at a later time.
The following commands are available; default keys are used, if the particular
termcap entry is not specified.
Command | Default key | Termcap
|
| | name
|
|
Delete previous character | bse option | -
|
Delete character under cursor | DEL (0x7f) | kD
|
Cursor backward | Ctrl-B | kl
|
Cursor forward | Ctrl-F | kr
|
Next history line | Ctrl-N | kd
|
Previous history line | Ctrl-P | ku
|
Cursor to start of line | Ctrl-A | kh
|
Alternate cursor to start of line | Ctrl-A | ka
|
Cursor to end of line | Ctrl-Z | kH
|
Alternate cursor to end of line | Ctrl-E | kA
|
Clear to end of line | Ctrl-K | kE
|
Reset terminal | Ctrl-G | kS
|
Delete current line | del option | kL
|
Transpose characters | Ctrl-T | kT
|
Toggle insert/overwrite mode | Ctrl-V | kI
|
Complete name | Ctrl-I (TAB) | ta
|
Clear screen | Ctrl-L | kc
|
Insert from paste buffer | Ctrl-Y | ki
|
Abandon edit line | Ctrl-C | kq
|
Reverse-incremental history search | Ctrl-R | kQ
|
Word delete | ESC-d | kX
|
Uppercase word | ESC-u | kU
|
Lowercase word | ESC-l | kY
|
Capitalize word | ESC-c | kC
|
Word forward (next word) | ESC-f | kF
|
Word backward (previous word) | ESC-b | kB
|
New line | eor option | -
|
Logout | eof option | -
|
|
5.3. Detailed description of all line editing commands
- Delete previous character (bse from terminal path options)
-
The character to the left of the cursor, if any, is removed from the current
edit line and the cursor is moved one position to the left. This function is
normally assigned to the backspace (BS) key.
- Delete character under cursor (DEL, kD)
-
The character under the cursor is deleted form the current edit line but the
cursor position remains unchanged. This function is normally assigned to the
delete (DEL) key.
- Cursor backward (Ctrl-B, kl)
-
The cursor is moved one character to the left, if not already at the leftmost
position. This function is normally assigned to the "Arrow left" key.
- Cursor forward (Ctrl-F, kr)
-
The cursor is moved one character to the right, if not already at the rightmost
position. This function is normally assigned to the "Arrow right" key.
- Next history line (Ctrl-N, kd)
-
The current edit line is replaced by the next line in history buffer, if the
history stack pointer does not already point to the last entry, and the
cursor is moved to the end of the line. This function is normally assigned to
the "Arrow down" key.
- Previous history line (Ctrl-P, ku)
-
The current edit line is replaced by the previous line in history buffer, if the
history stack pointer does not already point to the first entry, and the
cursor is moved to the end of the line. This function is normally assigned to
the "Arrow up" key.
- Cursor to start of line (Ctrl-A, kh)
-
The cursor is moved to the first position of the edit line, if not already
there. The content of the current edit line remains unchanged.
- Alternate cursor to start of line (Ctrl-A, ka)
-
Same as above, intended to allow the use of both cursor key (Home) and, for
example, uEmacs control key.
- Cursor to end of line (Ctrl-Z, kH)
-
The cursor is moved past the last position of the edit line, if not already
there. The content of the current edit line remains unchanged.
- Alternate cursor to end of line (Ctrl-E, kA)
-
Same as above, intended to allow the use of both cursor key (End) and, for
example, uEmacs control key.
- Clear to end of line (Ctrl-K, kE)
-
The string from the current cursor position to end of line is deleted and
saved in the paste buffer but not in the history stack. The cursor is not
moved.
- Reset terminal (Ctrl-G, kS)
-
The terminal settings are restored to the condition that was found when sh
was started. This function is intended to cope with a situation when sh has
forked a program that did not restore the terminal settings appropriately.
- Delete current line (del from terminal path options, kL)
-
The entire edit string is deleted and saved in the paste buffer but not in
the history stack. The cursor is moved to the leftmost position.
- Transpose current and previous character (Ctrl-T, kT)
-
The two characters, under the cursor and to the left of the cursor, are
exchanged.
- Toggle insert/overwrite mode (Ctrl-V, kI)
-
By default, any character entered from the keyboard is inserted into the
edit line. This command, if used once, changes to overwrite mode, i.e. a
newly entered character replaces the character under the cursor. If used a
second time, the default behavior is restored.
- Complete name (Ctrl-I, ta)
-
The TAB key (or the key specified by the ta termcap entry)
causes sh to
match the already entered string as a command, as a file name, as a shell
variable name or as a user name, if it is the first word in a line, it is a
valid file name, its first character is $
or its first character is ~,
respectively. In case there is more than one match, the terminal beeps and the
user may hit the same key again in which case the entire list of matching
names is displayed. Should more than 100 names match, the user can suppress
the display. If the completed string specifies a file name or a command, a
space is appended. A slash is appended, if it specifies a valid directory.
The name to be completed may contain wild card characters and regular
expressions. If it is not a shell variable, it may also contain shell
variables and the tilde symbol that are both evaluated before completion
takes place. By default, commands are searched in the alias list, in the list
of currently available functions and in the list of built-in commands. The
files in one of the execution directories (any of the PATH directories and
execution directory) may be included into command name completion by a shell
option (-g). Finally, if the first character of an input line is the
exclamation mark (!) followed by a match string and the completion key is
entered, the most recent history line that matches the string is inserted.
History line completion never reports more than one match, even if there are
less recent entries that also match. As with the normal history syntax, it
is also possible to enter an exclamation mark followed by a number in which
case the history line at this number is inserted. In contrast to the other
completion modes, history line completion is not limited to words - the entire
history line including any white space is inserted.
- Clear screen (Ctrl-L, kc)
-
The screen is cleared, the cursor is moved to the upper left position, and the
current prompt and the current edit line, if any, are written to the first
screen line.
- Insert from paste buffer (Ctrl-Y, ki)
-
Any string that has been saved to paste buffer using the "clear to end of
line", "delete current line" or "abandon edit line" command is pasted into the
current edit line.
- Abandon edit line (Ctrl-C, kq)
-
The current edit line is copied into paste buffer but not saved in history
stack, the string "* Abandon *", a carriage return and a new prompt are
written to screen, and the current edit line is cleared.
- Reverse-incremental history search (Ctrl-R, kQ)
-
Every subsequently entered character is appended to a search string that is
looked up in the history lines starting from the most recent entry. Whenever
this line editing command is entered another time, the next less recent
occurrence of the search string in the history lines is displayed on screen.
If a match cannot be found, the terminal beeps and the display does not change.
The reverse-incremental history search can be left using three different ways:
i) If the enter key is hit, the currently selected history line is copied
into the edit command line and the command is executed. ii) If the left-arrow,
right-arrow or backspace key is hit, the currently selected history line is
copied into the command line, the respective move or backspace command is
applied and edit mode is resumed. iii) If any other non-alphanumeric key is
hit, the search is canceled, the previous edit line is restored and edit mode
is resumed.
- Word delete (ESC-d, kX)
-
The word under the cursor beginning at the current cursor position is copied
into paste buffer and deleted from the current edit line.
- Uppercase word (ESC-u, kU)
-
The characters of the word under the cursor beginning at the current cursor
position are changed to uppercase.
- Lowercase word (ESC-l, kY)
-
The characters of the word under the cursor beginning at the current cursor
position are changed to lowercase.
- Capitalize word (ESC-c, kC)
-
The characters of the word under the cursor beginning at the current cursor
position are changed to lowercase, the first character is made uppercase.
- Word forward (ESC-f, kF)
-
The cursor is moved to the first character of the word that follows the word
under the cursor.
- Word backward (ESC-b, kB)
-
The cursor is moved to the first character of the word that precedes the word
under the cursor.
- New line (eor from terminal path options)
-
The edit function is left, the current edit line is sent to the sh input
line parser and the commands, if any, are executed.
- Logout (eof from terminal path options)
-
If the -l option is not enabled, this character causes sh
to execute $HOME/.logout and /dd/SYS/sh.logout,
to stop execution and to return to
the previous program. If history is enabled, the contents of the history
buffer are written to the file $(HOME)/.sh_history.
6. SYMBOLS
6.1. Pipe symbol (| or !)
Any two commands separated by the pipe symbol are started concurrently the
standard output path of the first program being redirected to the standard
input path of the second program via an unnamed pipe.
6.2. Redirection symbols (<, >, 2>, >>, >+, >-, >&, >&-), Condensed redirection (<>, <>>, <>>>, >>> etc.)
Standard input, standard output and standard error output are redirected
using the <, > and 2> redirection symbols, respectively.
Any existing file is silently overwritten, unless the -C (upper case!) command
line option has been specified. The output is appended, if the >> symbol
("Bourne mode" only) or the >+ is used. If in "Mware mode", the >>
symbol redirects standard error path. By default, sh is in "Bourne mode"; it
is switched to "Mware mode", if * is used as comment symbol in a script. The
# comment symbol switches back to "Bourne mode". The >- symbol
has no special meaning and is not different from the > symbol, if the
-C command line option is not set; otherwise, the >- symbol is required,
if it is intended to overwrite an already existing file. In addition, the outputs from
several paths may be merged together using the <from>>&<to> syntax, where
<from> specifies the output path that is going to be closed and be merged into
path <to>. This syntax is, for example, helpful to grep through a program's
error output. The following command will only display those GNU C compiler
options that are related to the -M option:
gcc2 -? 2>&1 | grep ' -M'
The order in which redirections are specified is significant. The shell
evaluates redirections left-to-right. For example:
cmd 1>file 2>&1
first associates file descriptor 1 with file file. It associates file
descriptor 2 with the file associated with file descriptor 1 (that is, file).
If the order of redirections were reversed, file descriptor 2 would be
associated with the terminal (assuming file descriptor 1 had been) and file
descriptor 1 would be associated with file file.
If a - sign is specified after the merge symbol (&) instead of a path
number, this path is simply closed, e.g. 2>&- will suppress any output
on standard error path.
Finally, the condensed redirection syntax (<>, <>>, <>>>, >>>
etc.) is understood, which may be followed by a + or a - symbol as explained
above. In addition to path number #2, as mentioned above to redirect
standard error output, any other one-digit path number may be specified,
where 0 stands for standard input path, 1 stands for standard
output path and the numbers 3 to 9 may be used to access
either existing paths (passed from the calling procedure) or to create new
ones to be passed to one of sh's child processes. In the latter case,
the number of paths the child process will inherit from sh is implicitly
increased to match the requirements.
6.3. History symbol (!, if first character of an input line)
There are several ways to directly execute commands from the history buffer.
The history symbol alone will execute the most recent command; if followed by
a number, the history line with this number is executed. If the history symbol
is followed by a match string, the most recent command that matches this
string is executed. If the completion key is entered at the end of a line
that starts with the history symbol, history completion is attempted, i.e.
the most recent history line that matches or the history line with the
specified line number, if it exists, is inserted into the current edit line.
6.4. Assignment symbol (=)
A new shell variable is created and a value assigned. The variable var is,
for example, set and defined, if the command
var="sh = flexibility"
is entered. The variable can be recalled when preceded by the $ sign (see
below). By default, the newly created variable is not exported when a child
process is forked. Another assignment may follow immediately on the same line,
e.g.
abc=123 def=456
In addition, a single assignment or several assignments may be followed by
any legal shell command construct, again on the same line. In this special
case, the variables will be made exportable by default and will be removed
after execution of the command. Any existing environment variable may be
shadowed as demonstrated in the example:
# setenv TERM vt100
# echo $TERM
vt100
# TERM=vt320 printenv TERM
vt320
# echo $TERM
vt100
6.5. Variable symbol ($)
Any environment variable and shell variable can be recalled when the
variable's name preceded by the $ sign is entered. The sequence $<n>
recalls the arguments of a shell script or variables that have been set using
the set command. The following shell built-in variables are additionally
available:
Symbol | Returns
|
$# |
the number of arguments (updated)
|
$* |
concatenated command line arguments (updated)
|
"$*" |
command line arguments concatenated with first IFS character (updated)
|
$@ |
concatenated command line arguments (updated)
|
"$@" |
command line arguments expanded into separate words (updated)
|
$- |
shell options (updated)
|
$? |
value returned by the last command or function executed
|
$$ |
the shell's process ID
|
$<n> |
the <n>th command line argument, see above (updated)
|
${~0} |
same as $$
|
${~} |
the shell's parent process ID
|
${~1} |
same as ${~}
|
${~2} |
the shell's grandparent process ID
|
${~<n>} |
the shell's parent process ID degree <n>
|
$! |
the process ID of the last concurrent command
|
$: |
the shell's current priority (updated)
|
$. |
the shell's current user group number (updated)
|
$, |
the shell's current user ID (updated)
|
$var |
value of var, empty if var is not defined.
|
${var} |
same as above, required if var is followed by a
character that could be part of a variable's name.
|
|
The following string substitution operators test for the existence of
a shell variable and allow for substituting default values or aborting
script execution under certain conditions.
Symbol | Returns
|
${var=new} |
value of var if defined, new otherwise.
if undefined, $var is set to new.
|
${var:=new} |
value of var if defined and not empty, new otherwise.
if undefined, $var is set to new.
|
${var-new} |
value of var if defined, new otherwise.
if undefined, $var remains unchanged.
|
${var:-new} |
value of var if defined and not empty, new otherwise.
if undefined, $var remains unchanged.
|
${var+new} |
new if var is defined, empty otherwise.
|
${var:+new} |
new if var is defined and not empty, empty otherwise.
|
${var?} |
value of var if defined,
otherwise "var: parameter not set"is printed and sh aborts, if interactive.
|
${var:?} |
value of var if defined and not empty,
otherwise "var: parameter null or not set" is printed
and sh aborts, if interactive.
|
${var?str} |
value of var if defined, otherwise "var: str"is printed and sh aborts, if interactive.
|
${var:?str} |
value of var if defined and not empty, otherwise
"var: str" is printed and sh aborts, if interactive.
|
|
There is one specific exception from the rule for shell variable evaluation:
The sequence $temp$ is always returned unprocessed so that
OS-9/68xxx V3.0 names
for temporary files (_$temp$_<xxxx>) can be entered
as if there were no $
characters (required for execution of cfp generated files).
6.6. Concurrent execution symbol (&)
A command delimited by the & symbol is executed in the background and its
process ID is written to screen. The wait command can be used to abolish
concurrent execution and to wait until the command is finished.
6.7. Sequential execution symbol (;)
Several commands that are separated by the ; symbol will be executed
sequentially, same as if the commands had been entered separately.
6.8. Evaluation symbol (`)
Any command or list of commands embedded in backquotes will first be
executed and its output be treated as shell input string. If, for example,
only memory resident RBF disk descriptor modules d0 to d3 and
h0 to h3 are to be saved, the commands
for i in `mdir -ut=desc "??" | grep [dh][0-3]`
do
save $i
done
will do the job.
6.9. Comment (# and *) and execution (@ and ~*) symbols
Any line that starts with one of the comment symbols is ignored. There is,
however, one exception from this rule: The first line of a procedure file may
indicate the shell (or any other) program for processing using the #!<prog>
syntax. If a fully qualified file name is specified that cannot be found
(e.g. #!/bin/sh), its base name (sh in
the example) is tried. There are
important differences between the two comment symbols: The # symbol can
appear at the beginning of a word anywhere in a command line and switches the
I/O syntax parser to "Bourne mode" so that the >> redirection syntax is
recognized as append symbol. The * symbol
can only appear in procedure files
and only at the beginning of a command (i.e. at the beginning of a line or
following a semicolon) and switches the I/O parser to "Mware mode" so that the
>> syntax is recognized as redirection of standard error path.
In addition, the execution symbol @ (only if first character of a
procedure file) informs sh that the zsh shell is required, and the
character sequence ~* (only if first two characters of a procedure file)
indicates that this procedure file requires Mware's command file processor
cfp for execution.
6.10. Test symbol ([)
This symbol is merely a synonym for the test command.
In contrast to test,
however, end of the test condition may be marked using the ] character.
6.11. Shell level symbol (@)
This symbol is replaced by the current shell level (stored in the environment
variable _sh).
6.12. Single quote (')
Used to prevent a character, e.g. space, wild card symbol etc., from being
treated by the command line parser. Only the single quote, not the double
quote, also prevents shell variables and backslashes from being evaluated. The
following command allows, for example, to redefine the prompt string:
setenv PS1 '$CWD:'
6.13. Double quote ()
Used to prevent a character, e.g. space, wild card symbol etc., from being
treated by the command line parser. In contrast to single quotes, shell
variables within double quotes are evaluated. The following command will
display all descriptors in memory that have t as first character:
mdir -et=desc "t*"
6.14. Mark symbol (<<)
Used to mark an end-of-file string for so-called "here" documents. Subsequently
entered lines are written to an intermediate file until the mark string is
reached, e.g.:
cat << ENDMARK >textfile
You are reading
the file 'textfile'.
ENDMARK
list textfile
You are reading
the file 'textfile'.
The intermediate file is created on the directory that is specified in the
TMPDIR environment variable or /dd/TMP, if undefined.
It is silently created,
if not yet available. The file name of the temporary file
is sh suffixed by
the 6-digit number of the shell's process ID. Any $, \
or grave (`...`)
construct in the here document are substituted unless the mark string is
quoted or preceded by a backslash. For example, in the following
cat << ENDMARK >pidprio
This shell's pid is $$ and its priority is $:
ENDMARK
list pidprio
This shell's pid is 000012 and its priority is 128
substitution takes place whereas in
cat << 'ENDMARK' >getpid
The shell's pid can be obtained using the $$ symbol
ENDMARK
list getpid
The shell's pid can be obtained using the $$ symbol
the $$ symbol or in
cat << \ENDMARK >getprio
The shell's prio can be obtained using the $: symbol
ENDMARK
list getprio
The shell's prio can be obtained using the $: symbol
the $: symbol is taken literally.
6.15. Escape character symbol (\\)
Used to enter characters that have a special meaning
in the sh context and
also non-printable ASCII characters. The following command, for example,
displays all lines of a text file that contain the dollar character at end of
line:
grep \\\$\$ file.c
Note that the four escape characters have different meanings; the first two
encode the escape character itself to be passed to the grep program,
the two
others are necessary to enter the dollar character without being treated as
the sh variable denominator. The two dollar characters also have different
meanings; the first one specifies anchored search (only at end of line) and
the second specifies the dollar character to search. When received by the
grep program, the command line arguments will be transformed to
grep \$$ file.c
Another example relates to the conversion of UNIX text files to OS-9. The
following command does appropriate translation of the line-feed (0x0a)
line delimiter to carriage-return (0x0d)
tr \\l \\n <unix >os9
and is functionally equivalent to
tr \\0a \\0d <unix >os9
but could also be written as
tr '\l' '\n' <unix >os9
or as
tr '\0a' '\0d' <unix >os9
The built-in echo command recognizes the following
special escape characters:
Symbol | Output | ASCII | Function
|
|
\a | 0x07 | BEL | Alert
|
\b | 0x08 | BS | Backspace
|
\c | Suppress carriage return (same as -r option)
|
\f | 0x0c | FF | Form feed
|
\l | 0x0a | NL | New line
|
\n | 0x0d | CR | Carriage return
|
\r | 0x0d | CR | Carriage return
|
\t | 0x09 | TAB | Forward tab
|
\v | 0x0b | VT | Vertical tab
|
\\ | \ | - | Backslash
|
\OOO |
Any character, if OOO is an octal character that
has a value of less than 256 (octal 377)
|
\XX |
Any character, if XX is a hexadecimal character
(upper or lower case)
|
|
6.16. Home symbol (~)
The tilde is replaced by the current HOME
directory or, if followed by a valid
user name, by this user's home directory. These mechanisms are also available
when the tilde is the first character of a file name that is
subjected to TAB file name completion.
7. ENVIRONMENT VARIABLES
7.1. _sh
This variable contains the shell level, i.e. it can be used to display how
often a child shell has been forked. It cannot be unset.
7.2. EMSG_FILE
The file that may optionally be specified in the EMSG_FILE environment
variable is used for printing error texts, same as -e[=<path>]
command line option. In contrast to the command line option,
the environment variable EMSG_FILE must be set before sh is
started to become effective. Setting it to another value within an
sh session does not influence the current error message file. Whenever
another error message file is specified using the set -e=<path>
command, the environment variable EMSG_FILE is updated
implicitly. It cannot be unset.
7.3. HISTORY
The value that may optionally be specified in the HISTORY
environment variable
defines the size of the history buffer, if set before sh is started. Setting
it to another value within an sh session does not influence the current
history buffer size. Whenever the current history buffer is resized, e.g.
using the "history <num>" command, HISTORY is updated implicitly.
7.4. TMPDIR
The TMPDIR environment variable is used
to store temporary data such as here
documents, default is /dd/TMP. If the specified or the default directory
is not available, it is automatically created when needed for the first time.
The environment variable TMPDIR cannot be unset.
7.5. PATH
The colon-separated directories in the PATH
environment variable are scanned
whenever the first string of an input line is not a built-in command, is not a
fully qualified file name and does not specify an executable module that is
resident in memory.
When a file is found in one of the PATH directories,
an attempt is made to
execute the file; default is /dd/CMDS, if the PATH
variable is empty. The
first file found is executed, irrespective of whether it is a binary program
or a procedure file. In the latter case, the file is, of course, not directly
executed but forked using the shell that is taken from the file (see above)
or, otherwise, that is specified in the SHELL
environment variable. If the file
is not found in one of the PATH directories,
an attempt is made to execute it
from the current execution directory, but this requires that the file has the
execute attribute set. As above, also a file in the current execution directory
may be either a binary program or a procedure file. The dot (.)
symbol in the
PATH list (e.g. .:/dd/CMDS)
has a special meaning: It always refers to the
current data directory and not to the current execution directory, since the
latter is scanned anyway. The same rule applies to the ./ prefix
(e.g. ./procedure) that also refers to the current data directory.
The environment variable PATH cannot be unset.
7.6. HOME
The HOME environment variable is expected to
contain the home directory. This
is the directory where the .profile file is
searched and where the history
file .sh_history is saved, if history is enabled.
The HOME environment variable defaults to /dd. It cannot be unset.
7.7. CDD
The CDD environment variable contains the disk
device of the current data
directory and is automatically updated when a chd command is executed.
It is read-only and cannot be unset.
7.8. CDL
The CDL environment variable contains the
lowest level of the current data
directory (not the entire tree) and is automatically updated when a chd
command is executed. Intended to cope with long $CWD
strings that are part of
the prompt. The PS1 environment variable can, for example, be set to the
expression
<$HOST/$USER/sh@>$CDD/-/$CDL:
instead of
<$HOST/$USER/sh@>$CWD:
so that the prompt remains reasonably short even when the current directory
points to a deep level in the directory tree. The CDL environment
variable is read-only and cannot be unset.
7.9. CDPATH
The CDPATH environment variable may contain a colon separated list of
directories. These directories are searched when the argument to the
"cd <newdir>" or "chd <newdir>" built-in command is not found
in the current directory.
7.10. CWD
The CWD environment variable contains the current data directory and is
automatically updated when a cd or a chd command is executed.
If the CWD environment
is already set when sh for OS-9/68xxx is started,
a "chd $CWD" command is executed
implicitly; it is set to the current directory, otherwise. The
CWD environment variable is read-only and cannot be unset.
7.11. LWD
The LWD environment variable contains the previous current
data directory and is
automatically updated when a cd or a chd command is executed.
7.12. TERM
The TERM environment variable is used to select the appropriate termcap
setting. This is the only environment variable that, by default, also acts on
the current sh session. It cannot be unset.
7.13. IFS
The IFS environment variable contains a list
of characters that separate words in arguments. It cannot be unset.
7.14. OLDPWD
The OLDPWD environment variable contains the previous current data directory
and is automatically updated when a cd or a chd command is executed. Its
behavior is identical to the LWD environment variable.
7.15. PPID
The PPID environment variable contains the process ID of the parent
process of the current sh. It is identical to ${~} and
${~1}, is read-only and cannot be unset.
7.16. PS1
The PS1 environment variable contains the
current prompt string, default for
super user login is "@# ", default for any other login is "@% ".
It cannot be unset.
7.17. PS2
The PS2 environment variable contains the prompt string for a continued
command line, e.g. within quotes or within a do loop; default is > . It
cannot be unset.
7.18. PS3
The PS3 environment variable contains the prompt string for input as
part of the select language construct; default is #? .
It cannot be unset.
7.19. PWD
The PWD environment variable contains the current data directory and is
automatically updated when a cd or a chd command is executed. This
functionality is identical to the CWD environment variable. If PWD,
however, is already set when sh for OS-9 is started, it is - in contrast
to CWD - not considered. The PWD environment variable is read-only
and cannot be unset.
7.20. SHDEBUG
The SHDEBUG environment variable forces the
-d (debug) option to be set on
all dependent sh calls. The debug option is disabled
when SHDEBUG is either
not set or set to 0, OFF or off,
it is enabled when set to a non-zero
value, to ON or on.
7.21. SH_VERSION
The SH_VERSION environment variable contains the edition number of the
currently running instance of sh. It can neither be unset nor set to
another value. If, for example, a script relies on a particular feature
that is only available from edition 142 onwards, the following command
sequence may be used:
req=142
if test -z $SH_VERSION || test $SH_VERSION -lt $req
then
if test -z $SH_VERSION
then
echo Current shell is too old
else
echo Current shell is edition $SH_VERSION
fi
echo Edition $req required
echo Please upgrade
exit 1
fi
8. BUILT-IN COMMANDS
8.1. . <file>
Read and execute commands from <file>. This command is similar to the
profile command of the Mware shell; if compatibility is an issue,
the line
alias profile .
may be added to one of the initialization
scripts (.login, /dd/SYS/profile or .profile).
8.2. :
Does nothing. A zero exit code is returned.
8.3. [
This command is merely a synonym for test. In contrast to test,
however, end of the test condition may be marked using the ] character.
8.4. alias <new> <old>
This command allows to assign the action <old> to the
newly defined string
<new>. The following is an example for useful alias settings
that may be put into the /dd/SYS/profile file:
alias a alias
alias chkdsk dcheck
alias env printenv
alias h history
alias last 'chd $LWD'
alias md makdir
alias profile .
alias rm del
alias rmdir deldir
alias sd srcdbg
alias sy sysdbg
alias type list
The command alias without an argument lists the current contents of the
alias buffer on screen.
8.5. break [<level>]
The break command unconditionally stops the execution
of a for, while or until loop.
Execution is resumed after the end of loop level <level>;
a value of 1 refers to the current loop, 2
refers to to nextmost outer loop
etc. If break is entered without argument, <level>
defaults to 1.
8.6. builtin <builtin> [<args>]
Execute the shell built-in command <builtin> passing
arguments <args>.
Required, if a function has the name of a built-in command, but the built-in
command needs to be executed within that function.
8.7. cd [<dir>]
Make <dir> the current data directory. The CWD
environment variable is also
set to <dir>, the LWD environment variable is
set to the most recent data
directory. If cd is entered without argument, the user's home directory is
made the current data directory. The command "cd -" causes the most recent
data directory to become the current directory (same as "cd $LWD").
8.8. chd [<dir>]
Make <dir> the current data directory. The CWD
environment variable is also
set to <dir>, the LWD environment variable is
set to the most recent data
directory. If chd is entered without argument, the user's home directory is
made the current data directory. The command "chd -" causes the most recent
data directory to become the current directory (same as "chd $LWD").
8.9. chx <dir>
Make <dir> the current execution directory.
8.10. cls
Clear screen.
8.11. dirs
Display the current stack of remembered directories. The popd command is
used to recall a particular directory, the pushd command adds a new
directory to the stack or rearranges it.
8.12. continue [<level>]
The continue statement branches to the beginning
of a for, while or until loop.
Execution is resumed at the beginning of loop level <level>;
a value of 1 refers to the current loop, 2 refers to
to nextmost outer loop
etc. If continue is entered without argument, <level>
defaults to 1.
8.13. echo [-b|-n|-r] <string1> [<string2> ... <stringn>]
Prints the strings to screen. Optionally carriage return is omitted (-r),
one carriage return is printed after every single string (-n),
or backslash
processing of the string is disabled (-b).
The latter is, for example, helpful
to display the current setting of the TERMCAP environment variable that
normally contains backslash characters.
8.14. enable [-n] [<builtin>]
This command allows to enable or to disable (-n)
a shell built-in command so
that a disk command with the same name can be executed. If enable
is entered
without arguments, all shell built-in commands are displayed on screen
preceded by a + or a - sign, if the
particular command is enabled or disabled, respectively.
8.15. eval <cmd>
Evaluate a command and add the result to the shell's internal variable set;
useful to manipulate environment variables.
8.16. ex <cmd>
Execute command <cmd> and leave the current shell.
8.17. exec <cmd>
Same as ex (see above).
8.18. exit [<code>]
Stop execution of sh and return to the previous program. The return value
may be specified explicitly in the <code> argument; it defaults to zero,
otherwise.
8.19. export <name1>[=<value1>] [<name2>=[<value2>] ... <namen>=[<valuen>]]
The specified names are registered for automatic export to the environment of
subsequently executed commands. A list of all exported variables is produced
when export is entered without arguments. In addition, a new value may be
assigned to the variable, if immediately followed by an equal sign and a
value, e.g.
export NEWENV=newval
8.20. false
Returns the boolean value false for condition constructs
such as while or if.
8.21. history [<num>|read|save]
Display the current content of the history buffer, if <num> is not given;
set the length of the history buffer to <num> lines, otherwise.
The contents
of the history buffer are written to the file $HOME/.sh_history
when sh
quits. They are read during initialization of a login shell, but can also be
re-read later by using the "history read" command.
When "history save" is
entered, the currents contents of the history buffer are written to
/$HOME/.sh_history in the same way as when sh quits.
8.22. kill [-<signal>] [-signal=<signal>] <pid1> [<pid2> ... <pidn>]
Send signal <signal> (default 0) to the process or processes
specified as arguments. The argument may be given as process ID or as module
name of the requested process. If the name specifies a module that runs more
than once, a message a displayed and the user is given the choice to kill all
or none of the processes.
Note that the kill signal (signal 0) cannot be caught nor ignored.
8.23. logon
Invoke a new logon procedure, pass the current environment and abandon the
current process. In a first attempt, the program logon is executed;
if this fails, login is tried.
8.24. logout [nohist]
Execute $HOME/.logout and /dd/SYS/sh.logout,
stop execution of sh and
return to the previous program. If history is enabled and the optional
nohist argument is not specified, the contents of the history buffer are
written to the file $(HOME)/.sh_history. If the -l option is not
enabled, entering the end-of-file character from the terminal path options
(normally escape) also causes sh to logout.
8.25. NO
This command is only effective, if followed by CARRIER in which case the
entire command is synonymous to logout. Intended to correctly handle a
situation when the carrier is lost in a modem connection but the serial
interface is not able to detect changes in the DCD line.
8.26. pd [-x]
Display current data directory; the current execution directory is shown
instead, if the -x option is specified. Same as pwd.
8.27. popd [+n]
Removes the entry n from the directory stack.
If popd is entered without
argument, the top directory is removed from the stack and made the current
data directory.
8.28. printenv [<var1> <var2> ... <varn>]
Print all (exportable ) environment variables. This command also excepts a
single argument or several ones that are output, one per line, in the
specified order. Unavailable variables are silently ignored.
8.29. pushd [<dir>] | [+n]
Adds a directory to the top of the directory stack, if <dir> is a valid
directory; otherwise, the directory stack is rotated until the nth
element of
the directory stack is at top. If pushd is entered without argument,
the top
two directories are exchanged. After the rearrangement of the stack, the top
directory is always made the current data directory.
8.30. pwd [-x]
Display current data directory; the current execution directory is shown
instead, if the -x option is specified. Same as pd.
8.31. read <var1> [<var2> ... <varn>]
The read command reads a string that is entered at the keyboard into a
single variable or into several variables. If a single variable is specified,
whitespace is maintained; if several variables are specified, whitespace is
ignored and the separated input tokens are assigned to the variables in the
given order. The read command returns 0 in case of no error; it returns 1,
if end-of-file (normally Escape) is received. A value of 2 or 3 is returned,
if keyboard quit or keyboard abort was entered, respectively. Should a signal
be received during the read command, the number of the signal is returned.
If the -l option is set, end-of-file can be entered by hitting
the end-of-file character twice. The read command is the only shell built-in
that is able to receive input from a pipe, e.g.
procs -e | grep myprog | read id pid grpusr prio memsiz
This makes it possible to easily realize a simple string parser.
8.32. readonly <name1>[=<value1>] [<name2>=[<value2>] ... <namen>=[<valuen>]]
Make the variable specified as argument read-only. Any shell variable
including environment variables can be passed as argument. If, for example,
the TERM variable is intended to be protected against unintentional
changes, the command
readonly TERM
can be used. Any attempt to assign another value to the TERM environment
variable will then result in an error message. In addition, a new value may be
assigned to the variable, if immediately followed by an equal sign and a
value, e.g.
readonly PROTECTVAL=safe
8.33. return [<val>]
A function exits and, optionally, returns the value <val>.
8.34. set <var1> [<var2> ... <varn>]
This command is used to set shell command arguments in the same way, as if they
had been entered when starting the shell. This includes options and other
arguments, but they cannot be mixed. If the first argument to the set
command starts with the - character, all following strings are considered
options; they are taken as arguments, otherwise. To inhibit the login
procedure when the escape character is entered, the command
set -l
can, for example, be used. If set is entered without arguments, a list of
all currently defined environment variables, shell variables and functions is
produced. Finally, "set -" can be entered
in which case all flags except the -l flag will be set to their defaults.
8.35. setenv <variable> <value>
Define the environment <variable> and assign <value> to it.
In contrast to the
assignment command <variable>=<value>, the setenv
command implicitly sets
the variable attribute to "export" so that it is
automatically exported when a child process is forked.
8.36. setpr [<pid> <priority>] [<priority>]
Set the priority of the process with the process ID <pid>
to <priority>.
Alternatively, the default priority for future forks can be set.
If setpr is
entered without arguments, the current default process priority is displayed
on screen.
8.37. setstack [<stack>]
Set the additional data stack to <stack> kByte when forking a program. If
setstack is entered without arguments, the current additional data stack
size is displayed on screen.
8.38. setuid <group.user> | <name>
Set the shell's group and user ID; can only be executed, if the shell process
is owned by a member of the super user group.
8.39. shift <n>
The positional parameters from <n+1> etc. are renamed to $1 etc.
If <n> is not
given, 1 is assumed. The shift command is useful for
command line parsing.
8.40. show
All shell variables including environment variables are displayed on screen.
8.41. suspend [<signal>]
The shell is suspended until the signal <signal> is received.
Any activity is
suspended except that traps for other signals (installed using the "trap
<command> <number>" command) are executed. If <signal> is not
specified, any signal will restart the shell.
8.42. test <opt1> <arg1> <opt2> [<arg2>]
The test command is used to perform a number of unary tests and binary
comparisons; it returns true, if one of the following options is specified
and the respective condition is true:
Paths, descriptors and modules
|
|
-b |
<arg1> is a block device descriptor (RBF/NFS, SBF, CDFM)
|
-d |
<arg1> is an existing path and is a directory
|
-f |
<arg1> is an existing path
|
-h |
always returns false (Unix: <arg1> is a symbolic link)
|
-L |
always returns false (Unix: <arg1> is a symbolic link)
|
-m |
<arg1> is an existing memory module
|
-p |
<arg1> is an existing path and is a named pipe
|
-r |
<arg1> is an existing path and is readable
|
-s |
<arg1> is an existing path and has a size greater than zero
|
-t |
<arg1> is an existing path open to a terminal
|
-w |
<arg1> is an existing path and is writable
|
-x |
<arg1> is an existing path and is an executable file
|
|
Strings
|
|
-z |
<arg1> is an empty string
|
-n |
<arg1> is a non-empty string
|
<arg1> = <arg2> |
true if string <arg1> equals string <arg2>
|
<arg1> != <arg2> |
true if string <arg1> is not equal string <arg2>
|
|
Integers
|
|
-eq |
true if integer <arg1> equals integer <arg2>
|
-ne |
true if integer <arg1> is not equal integer <arg2>
|
-ge |
true if integer <arg1> is greater than or equal <arg2>
|
-gt |
true if integer <arg1> is greater than integer <arg2>
|
-le |
true if integer <arg1> is lower than or equal <arg2>
|
-lt |
true if integer <arg1> is lower than integer <arg2>
|
|
Expressions
|
|
!<arg> |
true if <arg> is false
|
-a |
true if both <arg1> and <arg2> are true
|
-o |
true if either <arg1> or <arg2> is true
|
|
Several logical conditions can be grouped together using parentheses. The
following condition, for example, would return true, if only file1 exists
if test -f file1 -o ( -f file2 -a -f file3 )
while
if test ( -f file1 -o -f file2 ) -a -f file3
would return false in such case. The first example could also have been written
without parentheses.
8.43. trap [<command> <number>]
Define an action to be executed when signal <number> is received;
the command
trap "echo 'You better NOT kill your shell...'" 2
will, for example, display the string "You better NOT kill your shell..."when
Ctrl-E is entered from the keyboard. A trap can
be removed from a signal by
entering trap followed just by that signal number. If trap
is entered
without arguments, a list of all currently trapped signals is produced.
8.44. true
Returns the boolean value true for condition constructs such
as while or if.
8.45. tty [<devno>]
Return the name of the path number <devno>.
If not specified, <devno> defaults to 0 (zero).
8.46. umask [<mask> | <attr>]
Return the current file creation mode mask for files created by sh, if
entered without arguments (default modes are owner read and owner write). A
new file creation mode mask may be entered using the octal number <mask>;
bits
that are set in the mask are cleared in the modes of created files.
Alternatively, new file modes may be entered as they were arguments to the
OS-9/68xxx utility attr. Only owner read/write and
public read/write modes can be set or cleared.
8.47. unalias <alias>
Undefine the string previously assigned to <alias>.
8.48. unset [-f] <function> | <variable>
Make a previously defined function (-f option) undefined.
If the -f option
is not specified, unset is identical to unsetenv
except that no error is
generated, if an attempt is made to unset a non-existing variable.
8.49. unsetenv <variable>
Make a previously defined environment or shell variable undefined.
8.50. version [<help>]
Display sh version, edition and compilation date.
The argument <help> may be
any of c(ommands), k(eycaps), l(anguage), or t(est)
to display a
listing of available shell built-in commands, keycap settings, language
construct elements, or test functions, respectively. A + or -
sign that
precedes the name of a shell built-in command indicates whether that particular
command is currently enabled or not.
8.51. w
Suspend sh until any one child process terminates
and return its termination status.
8.52. wait [<pid>]
Suspend sh until the process with process ID <pid>
has finished and return
its termination status. If no argument is specified, sh waits until all
child processes have finished, in which case the return value is always zero.
9. LANGUAGE CONSTRUCT ELEMENTS
9.1. for <var> [in <val1> <val2> ... <valn>]
The for construct is used to execute loops in shell scripts; every time
the subsequent do .. done segment is executed, <var>
will be set to <val1>, <val2>, until <valn> is reached.
If, for example, library files have to be
scanned for the occurrence of a specific function, the commands
for i in /h0/LIB/*.l
do
echo Scanning $i:
rdump $i -a | grep function
done
may be entered. Shell arguments are used as variable values, if the in
language construct element is omitted.
9.2. select <var> [in <val1> <val2> ... <valn>]
The select construct is intended to let the user select from a list of
values; every value is labeled by a consecutive number starting from 1. The
selected item is assigned to <var> during execution of the subsequent
do .. done segment until a break command is encountered or
until the user has entered EOF condition. An empty string is assigned to
<var>, if an invalid selection is made. The string contained in the
environment variable PS3 is displayed after the variable list. The
following example lets the user select a directory from the PATH
environment variable:
PS3='Execution directory? '
select dir in `echo $PATH | tr ':' ' '`
do
if [ $dir ]
then
echo You selected directory $dir
break
fi
done
It will, for example, ask for a selection
1) .
2) /dd/USR/CMDS
3) /dd/ETC/CMDS
4) /dd/CMDS
Execution directory?
and, if 2 is entered, display
You selected directory /dd/USR/CMDS
9.3. while [!] <condition>
The do .. done segment that follows the while
language construct element
is executed repeatedly, until <condition> becomes false.
Optionally, <condition> may be preceded by the !
operator in which case the sense of <condition> is inverted.
A program will, for example, rerun continuously, if the commands
while true
do
program
done
are entered. Such a command sequence may be useful to exhibit software at a
fair.
9.4. case <var> in
The case construct is used to select among several conditions. A simple
user interface to delete or not a particular file in the current data
directory can, for example, be written as
for i in *
do
echo Delete file $i?
read response
case $response in
y*) del $i ;;
n*) ;;
q*) break
esac
done
The match condition may contain the | (or) symbol
to indicate that several conditions may match, e.g. y*|Y*).
9.5. esac
The esac language construct element is a component of the case
construct, see above.
9.6. do
The do construct is a component of the for, select,
until and while constructs, see above and below.
9.7. done
The done language construct element is a component of
the for, select, until and while constructs, see above
and below.
9.8. if [!] <condition>
The if construct is used to execute one or
several shell commands based upon
the return value of <condition>. Optionally, <condition>
may be preceded by
the ! operator in which case the sense of <condition>
is inverted. Standard
evaluation programs such as cmp, diff or grep
normally return 0 (zero) or 1, if
the program's action fails or not, respectively. The following shell script
can, for example, be used to copy only those files from /h0/CMDS
to /h0/DISK1/CMDS that already exist on /h0/DISK1/CMDS
but are different:
cd /h0/DISK1/CMDS
dir=/h0/CMDS
for i in *
do
if cmp $dir/$i $i -u
then
echo $dir/$i is the same as $i
else
echo $dir/$i is DIFFERENT from $i
copy $dir/$i -rb=64
echo $dir/$i copied to $i
fi
done
9.9. in
The in language construct element may optionally be used as part of
the for loop, see above.
9.10. then
The then language construct element is a required component
of the if and the elif statements, see above.
9.11. else
The else language construct element may optionally be used
within the if construct, see above.
9.12. elif [!] <condition>
The elif language construct element stands for "else if"and may optionally
be used within the if construct, see above.
Optionally, <condition> may be
preceded by the ! operator in which case the sense
of <condition> is inverted.
9.13. until [!] <condition>
The do .. done segment that follows the until
language construct element
is executed repeatedly, as long as <condition> is false.
Optionally, <condition> may be preceded by the !
operator in which case the sense of <condition> is inverted.
9.14. fi
The fi language construct element terminates if and elif
constructs, see above.
9.15. ;;
The ;; language construct element terminates a selection as
part of the case construct, see above.
9.16. <condition> || [!] <condition>
OR operator for condition constructs
following if, elif, while and until.
Optionally, <condition> may be preceded by the ! operator in which
case the sense of <condition> is inverted.
In addition, the OR operator may be
placed between two commands; the second command is then only executed, if the
first one returns false:
false || echo second command is being executed
true || # NEVER REACHED
9.17. <condition> && [!] <condition>
AND operator for condition constructs
following if, elif, while and until.
Optionally, <condition> may be preceded by the ! operator in which
case the sense of <condition> is inverted.
In addition, the AND operator may
be placed between two commands; the second command is then only executed, if
the first one returns true:
true && echo second command is being executed
false && # NEVER REACHED
9.18 (
Start an independent subshell to execute the commands in parentheses. The
return value is that of the last executed command:
echo main shell is shell "#$_sh"(echo subshell is shell "#$_sh")
9.19. )
Selects a condition within a case statement. The condition may contain
the * wildcard character; in addition, the |
character may be used to indicate that one of several conditions may match.
9.20. <name> () { <command1> [<command2>] .. [<commandn>] }
Define the shell function <name>. Any commands that
may legally be typed from
shell prompt may also appear within a command. End of function is assumed and
the function is internally stored and assigned to <name>,
when the }
character is reached. The function can be executed just by entering its name;
it may be inspected by using the set command
without arguments. Any number
of arguments may be passed to the function; they are recalled within the
function using the $<n> syntax. A function may return a value using
the "return <val>" syntax. The return value may be inspected
using the $? syntax
or directly examined in a test statement.
Recursive calls to a function are
allowed. An example for a shell function is given in section 10.4.
9.21. !
The ! language construct element stands for not
and may appear after if, elif, while, until, ||
or &&. It inverts the return value of the
subsequent logical condition.
10. CONSTANTS
10.1. Input buffer from command line
Initial buffer size is 2048 characters, it is expanded dynamically until the
system's memory is exhausted.
10.2. Input buffer from shell script
Initial buffer size is 2048 characters, it is expanded dynamically until the
system's memory is exhausted.
10.3. Input buffer of built-in read command
Initial buffer size of the input line during the built-in read command is
2048 characters, it is expanded dynamically until the system's memory is
exhausted.
10.4. Input buffer for a syntactical element
Initial buffer size for a syntactical element (command, function, alias etc.)
is 507 characters, it is expanded dynamically until the system's memory is
exhausted.
10.5. Maximum nesting depth
Commands may not be nested more deeply than 8 levels.
10.6. Maximum number of history lines
The number of history lines is limited to 500.
10.7. Maximum length of history match string
The string length of a history match string may not exceed 127 characters.
10.8. Maximum number of aliases
The number of aliases is limited to 100.
10.9. Maximum length of alias string
The string length of an alias string may not exceed 127 characters.
10.10. Default pipe length
Pipes for the communication between concurrently executing programs have a
default length of 512 Bytes. If the output of a shell built-in command is
redirected into a pipe, its size is set dynamically.
10.11. Signal numbers that may be trapped
Only signals with a number between #1 and #63 may be trapped.
10.12. Size of paste buffer
The internal paste buffer ("Clear to end of line", "Delete current line",
"Abandon edit line", "Word delete") has a size of 255 characters.
10.13. Signals
Whenever sh receives signal #4 (SIGHUP),
signal #10 (former SIGTERM) or
signal #36 (SIGTERM) and the signal's default action
has not been disabled
using the trap command, sh immediately stops
execution and returns the respective signal number.
11. IMPORTANT FEATURES
11.1. Name completion
The TAB key (or the key specified by the ta termcap entry)
causes sh to
match the already entered string as a command (command name completion), as a
file or directory name (file name completion), as a shell variable (variable
name completion) or as a user (user name completion). If, for example, the
name of the first of the two files
thisfilehasaverylongname1
thisfilehasaverylongname2
in the current directory is required, is it sufficient to enter
t<TAB>1
If the completion key is entered twice
t<TAB><TAB>thisfilehasaverylongname1 thisfilehasaverylongname2
t
a list of all available files is displayed on screen and the original input
line repeated below this list so that editing can be continued immediately.
11.2. Regular expressions
Regular expressions are evaluated whenever a string is entered. If, for
example, all files that have a, b, or c as first
character are to be deleted, the command
del [abc]*
will do the job. Alternatively, the command
del [a-c]*
can be entered for this purpose. The regular expression is also considered
for file name completion. If the first character after the [ symbol is the
exclamation mark ! or the caret symbol ^, the sense of the
comparison is inverted, i.e. only strings that do NOT match the character
class are considered.
11.3. Availability of environment variables
All environment variables are available in a command when
preceded by the $
sign. Inspecting the current setting of the TERM environment variable is,
for example, done by entering the
echo $TERM
command; adding the directory /h0/BIN to the PATH
environment variable can simply be done by entering the
setenv PATH $PATH:/h0/BIN
command.
11.4. Shell functions
Shell functions can easily be created and executed. This can be done from
prompt level but functions may also be part of an sh script. Programming
an sh script that makes use of functions is somewhat similar to writing a
program in the C language. Any number of arguments may be passed to the
function; they are recalled within the function using the $<n> syntax. The
following sh script may serve as an example:
func1() {
echo Executing function 1.
if [ $4 ]
then
echo $1 $2 $3 $4.
return 0
fi
return 1
}
func2() {
echo Executing function 2.
if [ $4 ]
then
echo $1 $2 $3 $4.
return 0
fi
return 2
}
if test $# -eq 0
then
echo "Please use one of 'f1' or 'f2'" 1>&2
echo "as first argument." echo "Optionally, a second argument" 1>&2
echo "can be specified." exit 1
fi
if test $1 = "f1"then
if func1 Command line argument $2
then
echo Arguments printed.
else
echo Function $? executed.
fi
exit 0
fi
if test $1 = "f2"then
if func2 Command line argument $2
then
echo Arguments printed.
else
echo Function $? executed.
fi
exit 0
fi
echo Illegal argument \'"$1"\' 1>&2
exit 1
12. COMPATIBILITY BETWEEN sh AND shell
All main syntax elements are compatible between sh and shell.
There are only a few remaining differences.
12.1. Redirected output overwrites file
In contrast to the Mware shell, sh overwrites files to which
output is redirected. The behavior of the Mware shell can, however, be
simulated by specifying the -C command line option.
12.2. Handling of unmatched wildcards
sh passes wildcard symbols to the called program, if they do not
match. The Mware shell writes the message "Wildcard match failed
for command '<cmd>'" in such a case and does not call the program.
12.3. Built-in command set requires a hyphen for option setting
Hyphens cannot be omitted when specifying options in the set command,
since sh uses the hyphen to distinguish options from arguments.
13. TO DO
13.1. TAB name completion and cursor position
The TAB name completion only works, if the cursor is at the end of the
input line.
13.2. Interrupting execution of . command
When keyboard interrupt or keyboard abort is hit during execution of
a script in the current sh environment (". <file>") sh exits.
Would be preferable, if only execution of the script were stopped.
14. REFERENCES
14.1. Kernighan BW, Pike R (1984): The UNIX programming environment.
Prentice-Hall, Englewood Cliffs, NY. ISBN 0-13-937699-2.
14.2. Bourne SR (1987): The UNIX System V environment.
Addison-Wesley, Reading, MA. ISBN 0-201-18484-2.
14.3. Newham C, Rosenblatt B (1995): Learning the bash shell.
O'Reilly, Sebastopol, CA. ISBN 1-56592-147-X.
Index
- NAME
-
- SYNTAX
-
- FUNCTION
-
- 1. ORIGIN, SUPPORT, NO WARRANTY
-
- 2. INTRODUCTION
-
- 3. GETTING STARTED
-
- 3.1. Installation
-
- 3.2. Supplementary programs
-
- 3.3. Example scripts
-
- 4. COMMAND LINE OPTIONS
-
- 4.1. Block input path while editing (-b)
-
- 4.2. Disallow files to be overwritten by redirected output (-C)
-
- 4.3. Exit after reading and executing one command (-c)
-
- 4.4. Enable debug output (-d[=<mode>])
-
- 4.5. Print error explanations (-e[=<path>])
-
- 4.6. Process profile file (-f=<profile>)
-
- 4.7. Command completion includes exec dirs (-g)
-
- 4.8. Set the # of history lines (-h=<n>)
-
- 4.9. Do not suppress shell messages (-i)
-
- 4.10. Require logout to logout (-l)
-
- 4.11. Define prompt (-p[=<prompt>])
-
- 4.12. Do not process default profile files (-r)
-
- 4.13. Stop command execution (-s)
-
- 4.14. Echo input lines (-t)
-
- 4.15. Display references to unset variables (-u)
-
- 4.16. Verbose mode (-v)
-
- 4.17. Kill all child processes and abort if carrier lost (-w)
-
- 4.18. Exit on error (-x)
-
- 4.19. Try to make standard input path a tty (-y)
-
- 5. THE TERMCAP DATA BASE AND COMMAND LINE EDITING AND HISTORY
-
- 5.1. The termcap data base
-
- 5.2. Command line editing and history
-
- 5.3. Detailed description of all line editing commands
-
- 6. SYMBOLS
-
- 6.1. Pipe symbol (| or !)
-
- 6.2. Redirection symbols (<, >, 2>, >>, >+, >-, >&, >&-), Condensed redirection (<>, <>>, <>>>, >>> etc.)
-
- 6.3. History symbol (!, if first character of an input line)
-
- 6.4. Assignment symbol (=)
-
- 6.5. Variable symbol ($)
-
- 6.6. Concurrent execution symbol (&)
-
- 6.7. Sequential execution symbol (;)
-
- 6.8. Evaluation symbol (`)
-
- 6.9. Comment (# and *) and execution (@ and ~*) symbols
-
- 6.10. Test symbol ([)
-
- 6.11. Shell level symbol (@)
-
- 6.12. Single quote (')
-
- 6.13. Double quote ()
-
- 6.14. Mark symbol (<<)
-
- 6.15. Escape character symbol (\\)
-
- 6.16. Home symbol (~)
-
- 7. ENVIRONMENT VARIABLES
-
- 7.1. _sh
-
- 7.2. EMSG_FILE
-
- 7.3. HISTORY
-
- 7.4. TMPDIR
-
- 7.5. PATH
-
- 7.6. HOME
-
- 7.7. CDD
-
- 7.8. CDL
-
- 7.9. CDPATH
-
- 7.10. CWD
-
- 7.11. LWD
-
- 7.12. TERM
-
- 7.13. IFS
-
- 7.14. OLDPWD
-
- 7.15. PPID
-
- 7.16. PS1
-
- 7.17. PS2
-
- 7.18. PS3
-
- 7.19. PWD
-
- 7.20. SHDEBUG
-
- 7.21. SH_VERSION
-
- 8. BUILT-IN COMMANDS
-
- 8.1. . <file>
-
- 8.2. :
-
- 8.3. [
-
- 8.4. alias <new> <old>
-
- 8.5. break [<level>]
-
- 8.6. builtin <builtin> [<args>]
-
- 8.7. cd [<dir>]
-
- 8.8. chd [<dir>]
-
- 8.9. chx <dir>
-
- 8.10. cls
-
- 8.11. dirs
-
- 8.12. continue [<level>]
-
- 8.13. echo [-b|-n|-r] <string1> [<string2> ... <stringn>]
-
- 8.14. enable [-n] [<builtin>]
-
- 8.15. eval <cmd>
-
- 8.16. ex <cmd>
-
- 8.17. exec <cmd>
-
- 8.18. exit [<code>]
-
- 8.19. export <name1>[=<value1>] [<name2>=[<value2>] ... <namen>=[<valuen>]]
-
- 8.20. false
-
- 8.21. history [<num>|read|save]
-
- 8.22. kill [-<signal>] [-signal=<signal>] <pid1> [<pid2> ... <pidn>]
-
- 8.23. logon
-
- 8.24. logout [nohist]
-
- 8.25. NO
-
- 8.26. pd [-x]
-
- 8.27. popd [+n]
-
- 8.28. printenv [<var1> <var2> ... <varn>]
-
- 8.29. pushd [<dir>] | [+n]
-
- 8.30. pwd [-x]
-
- 8.31. read <var1> [<var2> ... <varn>]
-
- 8.32. readonly <name1>[=<value1>] [<name2>=[<value2>] ... <namen>=[<valuen>]]
-
- 8.33. return [<val>]
-
- 8.34. set <var1> [<var2> ... <varn>]
-
- 8.35. setenv <variable> <value>
-
- 8.36. setpr [<pid> <priority>] [<priority>]
-
- 8.37. setstack [<stack>]
-
- 8.38. setuid <group.user> | <name>
-
- 8.39. shift <n>
-
- 8.40. show
-
- 8.41. suspend [<signal>]
-
- 8.42. test <opt1> <arg1> <opt2> [<arg2>]
-
- 8.43. trap [<command> <number>]
-
- 8.44. true
-
- 8.45. tty [<devno>]
-
- 8.46. umask [<mask> | <attr>]
-
- 8.47. unalias <alias>
-
- 8.48. unset [-f] <function> | <variable>
-
- 8.49. unsetenv <variable>
-
- 8.50. version [<help>]
-
- 8.51. w
-
- 8.52. wait [<pid>]
-
- 9. LANGUAGE CONSTRUCT ELEMENTS
-
- 9.1. for <var> [in <val1> <val2> ... <valn>]
-
- 9.2. select <var> [in <val1> <val2> ... <valn>]
-
- 9.3. while [!] <condition>
-
- 9.4. case <var> in
-
- 9.5. esac
-
- 9.6. do
-
- 9.7. done
-
- 9.8. if [!] <condition>
-
- 9.9. in
-
- 9.10. then
-
- 9.11. else
-
- 9.12. elif [!] <condition>
-
- 9.13. until [!] <condition>
-
- 9.14. fi
-
- 9.15. ;;
-
- 9.16. <condition> || [!] <condition>
-
- 9.17. <condition> && [!] <condition>
-
- 9.18 (
-
- 9.19. )
-
- 9.20. <name> () { <command1> [<command2>] .. [<commandn>] }
-
- 9.21. !
-
- 10. CONSTANTS
-
- 10.1. Input buffer from command line
-
- 10.2. Input buffer from shell script
-
- 10.3. Input buffer of built-in read command
-
- 10.4. Input buffer for a syntactical element
-
- 10.5. Maximum nesting depth
-
- 10.6. Maximum number of history lines
-
- 10.7. Maximum length of history match string
-
- 10.8. Maximum number of aliases
-
- 10.9. Maximum length of alias string
-
- 10.10. Default pipe length
-
- 10.11. Signal numbers that may be trapped
-
- 10.12. Size of paste buffer
-
- 10.13. Signals
-
- 11. IMPORTANT FEATURES
-
- 11.1. Name completion
-
- 11.2. Regular expressions
-
- 11.3. Availability of environment variables
-
- 11.4. Shell functions
-
- 12. COMPATIBILITY BETWEEN sh AND shell
-
- 12.1. Redirected output overwrites file
-
- 12.2. Handling of unmatched wildcards
-
- 12.3. Built-in command set requires a hyphen for option setting
-
- 13. TO DO
-
- 13.1. TAB name completion and cursor position
-
- 13.2. Interrupting execution of . command
-
- 14. REFERENCES
-
- 14.1. Kernighan BW, Pike R (1984): The UNIX programming environment.
-
- 14.2. Bourne SR (1987): The UNIX System V environment.
-
- 14.3. Newham C, Rosenblatt B (1995): Learning the bash shell.
-
This document was created by
man2html,
using the manual pages.
Time: 20:24:25 GMT, June 23, 1997