ash
SYNOPSIS
ash [ -efIijnsxz ] [ +efIijnsxz ] [ -c command ] [ arg ]
...
COPYRIGHT
Copyright 1989 by Kenneth Almquist.
DESCRIPTION
Ash is a version of sh with features similar to those of
the System V shell. This manual page lists all the fea
tures of ash but concentrates on the ones not in other
shells.
Invocation
If the -c options is given, then the shell executes the
specified shell command. The -s flag cause the shell to
read commands from the standard input (after executing any
command specified with the -c option. If neither the -s
or -c options are set, then the first arg is taken as the
name of a file to read commands from. If this is impossi
ble because there are no arguments following the options,
then ash will set the -s flag and will read commands from
the standard input.
The shell sets the initial value of the positional parame
ters from the args remaining after any arg used as the
name of a file of commands is deleted.
The flags (other than -c) are set by preceding them with
``-'' and cleared by preceding them with ``+''; see the
set builtin command for a list of flags. If no value is
specified for the -i flag, the -s flag is set, and the
standard input and output of the shell are connected to
terminals, then the -i flag will be set. If no value is
specified for the -j flag, then the -j flag will be set if
the -i flag is set.
When the shell is invoked with the -c option, it is good
practice to include the -i flag if the command was entered
interactively by a user. For compatibility with the Sys
tem V shell, the -i option should come after the -c
option.
If the first character of argument zero to the shell is
``-'', the shell is assumed to be a login shell, and the
files /etc/profile and .profile are read if they exist.
If the environment variable SHINIT is set on entry to the
shell, the commands in SHINIT are normally parsed and exe
cuted. SHINIT is not examined if the shell is a login
shell, or if it the shell is running a shell procedure.
(A shell is considered to be running a shell procedure if
``&&'' and ``||'' are binary operators. ``&&'' executes
the first command, and then executes the second command
iff the exit status of the first command is zero. ``||''
is similar, but executes the second command iff the exit
status of the first command is nonzero. ``&&'' and ``||''
both have the same priority.
The ``|'' operator is a binary operator which feeds the
standard output of the first command into the standard
input of the second command. The exit status of the ``|''
operator is the exit status of the second command. ``|''
has a higher priority than ``||'' or ``&&''.
An if command looks like
if list
then list
[ elif list
then list ] ...
[ else list ]
fi
A while command looks like
while list
do list
done
The two lists are executed repeatedly while the exit sta
tus of the first list is zero. The until command is simi
lar, but has the word until in place of while
repeats until the exit status of the first list is zero.
The for command looks like
for variable in word...
do list
done
The words are expanded, and then the list is executed
repeatedly with the variable set to each word in turn. do
and done may be replaced with ``{'' and ``}''.
The break and continue commands look like
break [ num ]
continue [ num ]
Break terminates the num innermost for or while loops.
Continue continues with the next iteration of the num'th
(list)
or
{ list; }
The first of these executes the commands in a subshell.
A function definition looks like
name ( ) command
A function definition is an executable statement; when
executed it installs a function named name and returns an
exit status of zero. The command is normally a list
enclosed between ``{'' and ``}''.
Variables may be declared to be local to a function by
using a local command. This should appear as the first
staement of a function, and looks like
local [ variable | - ] ...
Local is implemented as a builtin command.
When a variable is made local, it inherits the initial
value and exported and readonly flags from the variable
with the same name in the surrounding scope, if there is
one. Otherwise, the variable is initially unset. Ash
uses dynamic scoping, so that if you make the variable x
local to function f, which then calls function g, refer
ences to the variable x made inside g will refer to the
variable x declared inside f, not to the global variable
named x.
The only special parameter than can be made local is
``-''. Making ``-'' local any shell options that are
changed via the set command inside the function to be
restored to their original values when the function
returns.
The return command looks like
return [ exitstatus ]
It terminates the currently executing function. Return is
implemented as a builtin command.
Simple Commands
A simple command is a sequence of words. The execution of
tional parameters (except $0, which remains unchanged) are
set to the parameters to the shell function. The vari
ables which are explicitly placed in the environment of
the command (by placing assignments to them before the
function name) are made local to the function and are set
to values given. Then the command given in the function
definition is executed. The positional parameters are
restored to their original values when the command com
pletes.
Shell builtins are executed internally to the shell, with
out spawning a new process.
When a normal program is executed, the shell runs the pro
gram, passing the parameters and the environment to the
program. If the program is a shell procedure, the shell
will interpret the program in a subshell. The shell will
reinitialize itself in this case, so that the effect will
be as if a new shell had been invoked to handle the shell
procedure, except that the location of commands located in
the parent shell will be remembered by the child. If the
program is a file beginning with ``#!'', the remainder of
the first line specifies an interpreter for the program.
The shell (or the operating system, under Berkeley UNIX)
will run the interpreter in this case. The arguments to
the interpreter will consist of any arguments given on the
first line of the program, followed by the name of the
program, followed by the arguments passed to the program.
Redirection
Input/output redirections can be intermixed with the words
in a simple command and can be placed following any of the
other commands. When redirection occurs, the shell saves
the old values of the file descriptors and restores them
when the command completes. The ``<'', ``>'', and ``>>''
redirections open a file for input, output, and appending,
respectively. The ``<&digit'' and ``>&digit'' makes the
input or output a duplicate of the file descriptor num
bered by the digit. If a minus sign is used in place of a
digit, the standard input or standard output are closed.
The ``<< word'' redirection takes input from a here docu
ment. As the shell encounters ``<<'' redirections, it
collects them. The next time it encounters an unescaped
newline, it reads the documents in turn. The word follow
ing the ``<<'' specifies the contents of the line that
terminates the document. If none of the quoting methods
('', "", or \) are used to enter the word, then the docu
ment is treated like a word inside double quotes: ``$''
and backquote are expanded and backslash can be used to
escape these and to continue long lines. The word cannot
When locating a command, the shell first looks to see if
it has a shell function by that name. Then, if PATH does
not contain an entry for "%builtin", it looks for a
builtin command by that name. Finally, it searches each
entry in PATH in turn for the command.
The value of the PATH variable should be a series of
entries separated by colons. Each entry consists of a
directory name, or a directory name followed by a flag
beginning with a percent sign. The current directory
should be indicated by an empty directory name.
If no percent sign is present, then the entry causes the
shell to search for the command in the specified direc
tory. If the flag is ``%builtin'' then the list of shell
builtin commands is searched. If the flag is ``%func''
then the directory is searched for a file which is read as
input to the shell. This file should define a function
whose name is the name of the command being searched for.
Command names containing a slash are simply executed with
out performing any of the above searches.
The Environment
The environment of a command is a set of name/value pairs.
When the shell is invoked, it reads these names and val
ues, sets the shell variables with these names to the cor
responding values, and marks the variables as exported.
The export command can be used to mark additional vari
ables as exported.
The environment of a command is constructed by construct
ing name/value pairs from all the exported shell vari
ables, and then modifying this set by the assignments
which precede the command, if any.
Expansion
The process of evaluating words when a shell procedure is
executed is called expansion. Expansion consists of four
steps: variable substitution, command substitution, word
splitting, and file name generation. If a word is the
expression following the word case in a case statement,
the file name which follows a redirection symbol, or an
assignment to the environment of a command, then the word
cannot be split into multiple words. In these cases, the
last two steps of the expansion process are omitted.
Variable Substitution
To be written.
writes to the standard output will be captured by the
shell. The final newline (if any) of the output will be
deleted; the rest of the output will be substituted for
the command in the word.
Word Splitting
When the value of a variable or the output of a command is
substituted, the resulting text is subject to word split
ting, unless the dollar sign introducing the variable or
backquotes containing the text were enclosed in double
quotes. In addition, ``$@'' is subject to a special type
of splitting, even in the presence of double quotes.
Ash uses two different splitting algorithms. The normal
approach, which is intended for splitting text separated
by which space, is used if the first character of the
shell variable IFS is a space. Otherwise an alternative
experimental algorithm, which is useful for splitting
(possibly empty) fields separated by a separator charac
ter, is used.
When performing splitting, the shell scans the replacement
text looking for a character (when IFS does not begin with
a space) or a sequence of characters (when IFS does begin
with a space), deletes the character or sequence of char
acters, and spits the word into two strings at that point.
When IFS begins with a space, the shell deletes either of
the strings if they are null. As a special case, if the
word containing the replacement text is the null string,
the word is deleted.
The variable ``$@'' is special in two ways. First, split
ting takes place between the positional parameters, even
if the text is enclosed in double quotes. Second, if the
word containing the replacement text is the null string
and there are no positional parameters, then the word is
deleted. The result of these rules is that "$@" is equiv
alent to "$1" "$2" ... "$n", where n is the number of
positional parameters. (Note that this differs from the
System V shell. The System V documentation claims that
"$@" behaves this way; in fact on the System V shell "$@"
is equivalent to "" when there are no positional
paramteters.)
File Name Generation
Unless the -f flag is set, file name generation is per
formed after word splitting is complete. Each word is
viewed as a series of patterns, separated by slashes. The
process of expansion replaces the word with the names of
all existing files whose names can be formed by replacing
Patterns
A pattern consists of normal characters, which match them
selves, and meta-characters. The meta-characters are
``!'', ``*'', ``?'', and ``[''. These characters lose
there special meanings if they are quoted. When command
or variable substitution is performed and the dollar sign
or back quotes are not double quoted, the value of the
variable or the output of the command is scanned for these
characters and they are turned into meta-characters.
Two exclamation points at the beginning of a pattern func
tion as a ``not'' operator, causing the pattern to match
any string that the remainder of the pattern does not
match. Other occurances of exclamation points in a pat
tern match exclamation points. Two exclamation points are
required rather than one to decrease the incompatibility
with the System V shell (which does not treat exclamation
points specially).
An asterisk (``*'') matches any string of characters. A
question mark matches any single character. A left
bracket (``['') introduces a character class. The end of
the character class is indicated by a ``]''; if the ``]''
is missing then the ``['' matches a ``['' rather than
introducing a character class. A character class matches
any of the characters between the square brackets. A
range of characters may be specified using a minus sign.
The character class may be complemented by making an
exclamation point the first character of the character
class.
To include a ``]'' in a character class, make it the first
character listed (after the ``!'', if any). To include a
minus sign, make it the first or last character listed.
The /u Directory
By convention, the name ``/u/user'' refers to the home
directory of the specified user. There are good reasons
why this feature should be supported by the file system
(using a feature such as symbolic links) rather than by
the shell, but ash is capable of performing this mapping
if the file system doesn't. If the mapping is done by
ash, setting the -f flag will turn it off.
Character Set
Ash silently discards nul characters. Any other character
will be handled correctly by ash, including characters
with the high order bit set.
job, then the null prefix will identify the job, so you
can refer to the job by writing ``%''. The third form
refers to the current job. The current job is the last
job to be stopped while it was in the foreground. (See
the next paragraph.) The last form identifies a job by
giving the process id of the last process in the job.
If the operating system that ash is running on supports
job control, ash will allow you to use it. In this case,
typing the suspend character (typically ^Z) while running
a command will return you to ash and will make the sus
pended command the current job. You can then continue the
job in the background by typing bg, or you can continue it
in the foreground by typing fg.
Atty
If the shell variable ATTY is set, and the shell variable
TERM is not set to ``emacs'', then ash generates appropri
ate escape sequences to talk to atty(1).
Exit Statuses
By tradition, an exit status of zero means that a command
has succeeded and a nonzero exit status indicates that the
command failed. This is better than no convention at all,
but in practice it is extremely useful to allow commands
that succeed to use the exit status to return information
to the caller. A variety of better conventions have been
proposed, but none of them has met with universal
approval. The convention used by ash and all the programs
included in the ash distribution is as follows:
0 Success.
1 Alternate success.
2 Failure.
129-... Command terminated by a signal.
The alternate success return is used by commands to indi
cate various conditions which are not errors but which
can, with a little imagination, be conceived of as less
successful than plain success. For example, test returns
1 when the tested condition is false and getopts returns 1
when there are no more options. Because this convention
is not used universally, the -e option of ash causes the
shell to exit when a command returns 1 even though that
contradicts the convention described here.
When a command is terminated by a signal, the uses 128
plus the signal number as the exit code for the command.
Builtin Commands
This concluding section lists the builtin commands which
bltin command arg...
Execute the specified builtin command. (This is use
ful when you have a shell function with the same name
as a builtin command.)
cd [ directory ]
Switch to the specified directory (default $HOME).
If the an entry for CDPATH appears in the environment
of the cd command or the shell variable CDPATH is set
and the directory name does not begin with a slash,
then the directories listed in CDPATH will be
searched for the specified directory. The format of
CDPATH is the same as that of PATH. In an interac
tive shell, the cd command will print out the name of
the directory that it actually switched to if this is
different from the name that the user gave. These
may be different either because the CDPATH mechanism
was used or because a symbolic link was crossed.
. file
The commands in the specified file are read and exe
cuted by the shell. A path search is not done to
find the file because the directories in PATH gener
ally contain files that are intended to be executed,
not read.
eval string...
The strings are parsed as shell commands and exe
cuted. (This differs from the System V shell, which
concatenates the arguments (separated by spaces) and
parses the result as a single command.)
exec [ command arg... ]
Unless command is omitted, the shell process is
replaced with the specified program (which must be a
real program, not a shell builtin or function). Any
redirections on the exec command are marked as perma
nent, so that they are not undone when the exec com
mand finishes. If the command is not found, the exec
command causes the shell to exit.
exit [ exitstatus ]
Terminate the shell process. If exitstatus is given
it is used as the exit status of the shell; otherwise
the exit status of the preceding command is used.
export name...
The specified names are exported so that they will
appear in the environment of subsequent commands.
The only way to un-export a variable is to unset it.
Ash allows the value of a variable to be set at the
same time it is exported by writing
hash -rv command...
The shell maintains a hash table which remembers the
locations of commands. With no arguments whatsoever,
the hash command prints out the contents of this
table. Entries which have not been looked at since
the last cd command are marked with an asterisk; it
is possible for these entries to be invalid.
With arguments, the hash command removes the speci
fied commands from the hash table (unless they are
functions) and then locates them. With the -v
option, hash prints the locations of the commands as
it finds them. The -r option causes the hash command
to delete all the entries in the hash table except
for functions.
jobid [ job ]
Print the process id's of the processes in the job.
If the job argument is omitted, use the current job.
jobs
This command lists out all the background processes
which are children of the current shell process.
lc [ function-name ]
The function name is defined to execute the last com
mand entered. If the function name is omitted, the
last command executed is executed again. This com
mand only works if the -i flag is set.
pwd
Print the current directory. The builtin command may
differ from the program of the same name because the
builtin command remembers what the current directory
is rather than recomputing it each time. This makes
it faster. However, if the current directory is
renamed, the builtin version of pwd will continue to
print the old name for the directory.
read [ -p prompt ] [ -e ] variable...
The prompt is printed if the -p option is specified
and the standard input is a terminal. Then a line is
read from the standard input. The trailing newline
is deleted from the line and the line is split as
described in the section on word splitting above, and
the pieces are assigned to the variables in order.
If there are more pieces than variables, the remain
ing pieces (along with the characters in IFS that
separated them) are assigned to the last variable.
If there are more variables than pieces, the remain
ing variables are assigned the null string.
readonly name=value
With no arguments the readonly command lists the
names of all read only variables.
set [ { -options | +options | -- } ] arg...
The set command performs three different functions.
With no arguments, it lists the values of all shell
variables.
If options are given, it sets the specified option
flags, or clears them if the option flags are intro
duced with a + rather than a -. Only the first argu
ment to set can contain options. The possible
options are:
-e Causes the shell to exit when a command termi
nates with a nonzero exit status, except when the
exit status of the command is explicitly tested.
The exit status of a command is considered to be
explicitly tested if the command is used to con
trol an if, elif, while, or until; or if the com
mand is the left hand operand of an ``&&'' or
``||'' operator.
-f Turn off file name generation.
-I Cause the shell to ignore end of file conditions.
(This doesn't apply when the shell a script
sourced using the ``.'' command.) The shell
will in fact exit if it gets 50 eof's in a row.
-i Make the shell interactive. This causes the
shell to prompt for input, to trap interrupts, to
ignore quit and terminate signals, and to return
to the main command loop rather than exiting on
error.
-j Turns on Berkeley job control, on systems that
support it. When the shell starts up, the -j is
set by default if the -i flag is set.
-n Causes the shell to read commands but not execute
them. (This is marginally useful for checking
the syntax of scripts.)
-s If this flag is set when the shell starts up, the
shell reads commands from its standard input.
The shell doesn't examine the value of this flag
any other time.
will leave the value of the positional parameters
unchanged, so to set the positional parameters to set
of values that may be empty, execute the command
shift $#
first to clear out the old values of the positional
parameters.
setvar variable value
Assigns value to variable. (In general it is better
to write variable=value rather than using setvar.
Setvar is intended to be used in functions that
assign values to variables whose names are passed as
parameters.)
shift [ n ]
Shift the positional parameters n times. A shift
sets the value of $1 to the value of $2, the value of
$2 to the value of $3, and so on, decreasing the
value of $# by one. If there are zero positional
parameters, shifting doesn't do anything.
trap [ action ] signal...
Cause the shell to parse and execute action when any
of the specified signals are received. The signals
are specified by signal number. Action may be null
or omitted; the former causes the specified signal to
be ignored and the latter causes the default action
to be taken. When the shell forks off a subshell, it
resets trapped (but not ignored) signals to the
default action. The trap command has no effect on
signals that were ignored on entry to the shell.
umask [ mask ]
Set the value of umask (see umask(2)) to the speci
fied octal value. If the argument is omitted, the
umask value is printed.
unset name...
The specified variables and functions are unset and
unexported. If a given name corresponds to both a
variable and a function, both the variable and the
function are unset.
wait [ job ]
Wait for the specified job to complete and return the
exit status of the last process in the job. If the
argument is omitted, wait for all jobs to complete
and the return an exit status of zero.
EXAMPLES
ensures that the function will return an exit status of
zero if it successfully changes to a directory that does
not contain a ``.enter'' file. Redefining existing com
mands is not always a good idea, but this example shows
that you can do it if you want to.
The suspend function distributed with ash looks like
# Copyright (C) 1989 by Kenneth Almquist. All rights reserved.
# This file is part of ash, which is distributed under the terms
# specified by the Ash General Public License.
suspend() {
local -
set +j
kill -TSTP 0
}
This turns off job control and then sends a stop signal to
the current process group, which suspends the shell.
(When job control is turned on, the shell ignores the TSTP
signal.) Job control will be turned back on when the
function returns because ``-'' is local to the function.
As an example of what not to do, consider an earlier ver
sion of suspend:
suspend() {
suspend_flag=$-
set +j
kill -TSTP 0
set -$suspend_flag
}
There are two problems with this. First, suspend_flag is
a global variable rather than a local one, which will
cause problems in the (unlikely) circumstance that the
user is using that variable for some other purpose. Sec
ond, consider what happens if shell received an interrupt
signal after it executes the first set command but before
it executes the second one. The interrupt signal will
abort the shell function, so that the second set command
will never be executed and job control will be left off.
The first version of suspend avoids this problem by turn
ing job control off only in a local copy of the shell
options. The local copy of the shell options is discarded
when the function is terminated, no matter how it is ter
minated.
HINTS
Shell variables can be used to provide abbreviations for
things which you type frequently. For example, I set
export h=$HOME
Word splitting and file name generation are performed by
default, and you have to explicitly use double quotes to
suppress it. This is backwards, but you can learn to live
with it. Just get in the habit of writing double quotes
around variable and command substitutions, and omit them
only when you really want word splitting and file name
generation. If you want word splitting but not file name
generation, use the -f option.
AUTHORS
Kenneth Almquist
SEE ALSO
echo(1), expr(1), line(1), pwd(1), true(1).
BUGS
When command substitution occurs inside a here document,
the commands inside the here document are run with their
standard input closed. For example, the following will
not word because the standard input of the line command
will be closed when the command is run:
cat <<-!
Line 1: $(line)
Line 2: $(line)
!
Unsetting a function which is currently being executed may
cause strange behavior.
The shell syntax allows a here document to be terminated
by an end of file as well as by a line containing the ter
minator word which follows the ``<<''. What this means is
that if you mistype the terminator line, the shell will
silently swallow up the rest of your shell script and
stick it in the here document.
March 7, 1991 SH(1)
|
