Content-type: text/html Manpage of SH

SH

Section: Misc. Reference Manual Pages (04/08/99)
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). The current version can be downloaded from http://www.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. GENERAL CONCEPT OF THE SHELL SYNTAX AND SYMBOLS

The general concept of the shell syntax is based on simple commands that are parsed, possibly substituted and, if appropriate, passed to the operating system. A simple command is a sequence of optional variable assignments followed by whitespace-separated words and redirections, and terminated by a control operator. The first word specifies the command to be executed. The remaining words are passed as arguments to the invoked command. The return value of a simple command is its exit status. Several simple commands may be concatenated into a pipe using one of the equivalent pipe symbols (| or !), and several pipes may be concatenated into a list using one of the different list symbols (;, &, &&, ||) and terminated by one of the terminator symbols (;, &, newline). Except in the case where a symbol character is not a legal component of a word such as the & symbol, symbols must be separated with whitespace from words and from each other. This is a fundamental difference to the concept of many computer languages, in particular to the C language. A comparable fundamental difference applies to string elements that must always be marked as such in the C language (using double-quotes) but do not need to be marked in the shell language, since there are only strings anyway. The unspecific use of double-quotes may even lead to unwanted effects, since they specifically protect a string against expansion.

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. Last not least, the character sequence *! causes sh to fork the Mware shell mshell to execute the script file.

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 doubles 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. In addition, the tilde and the following character are replaced by the current working directory, if the tilde is followed by a + sign and by the last working directory, if followed by a - sign, repectively. 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. If the required pipe size cannot be determined dynamically, it is set to 64 kByte.

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.

12.4. Search order for programs and scripts

Both Mware shells shell and mshell search the current execution directory prior to the directories specified in the PATH environment variable, whereas sh uses a more flexible approach and first examines the PATH variables and then the current execution directory. Mware's search order may be forced by specifying the current execution directory as the first element in the PATH environment variable.

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.