bashref.texi

android-w.song.android.widget

@node Special Parameters
@subsection Special Parameters
@cindex parameters, special

The shell treats several parameters specially.  These parameters may
only be referenced; assignment to them is not allowed.

@vtable @code

@item *
Expands to the positional parameters, starting from one.  When the
expansion occurs within double quotes, it expands to a single word
with the value of each parameter separated by the first character
of the @env{IFS}
special variable.  That is, @code{"$*"} is equivalent
to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
is the first character of the value of the @code{IFS}
variable.
If @env{IFS} is unset, the parameters are separated by spaces.
If @env{IFS} is null, the parameters are joined without intervening
separators.


@item @@
Expands to the positional parameters, starting from one.  When the
expansion occurs within double quotes, each parameter expands to a
separate word.  That is, @code{"$@@"} is equivalent to
@code{"$1" "$2" @dots{}}.
If the double-quoted expansion occurs within a word, the expansion of
the first parameter is joined with the beginning part of the original
word, and the expansion of the last parameter is joined with the last
part of the original word.
When there are no positional parameters, @code{"$@@"} and
@code{$@@}
expand to nothing (i.e., they are removed).

@item #
Expands to the number of positional parameters in decimal.

@item ?
Expands to the exit status of the most recently executed foreground
pipeline.

@item -
(A hyphen.)  Expands to the current option flags as specified upon
invocation, by the @code{set}
builtin command, or those set by the shell itself
(such as the @option{-i} option).

@item $
Expands to the process @sc{id} of the shell.  In a @code{()} subshell, it
expands to the process @sc{id} of the invoking shell, not the subshell.

@item !
Expands to the process @sc{id} of the most recently executed background
(asynchronous) command.

@item 0
Expands to the name of the shell or shell script.  This is set at
shell initialization.  If Bash is invoked with a file of commands
(@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
then @code{$0} is set to the first argument after the string to be
executed, if one is present.  Otherwise, it is set
to the filename used to invoke Bash, as given by argument zero.

@item _
(An underscore.)
At shell startup, set to the absolute pathname used to invoke the
shell or shell script being executed as passed in the environment
or argument list.
Subsequently, expands to the last argument to the previous command,
after expansion.   
Also set to the full pathname used to invoke each command executed
and placed in the environment exported to that command.
When checking mail, this parameter holds the name of the mail file.
@end vtable

@node Shell Expansions
@section Shell Expansions
@cindex expansion

Expansion is performed on the command line after it has been split into
@code{token}s.  There are seven kinds of expansion performed:
@itemize @bullet
@item brace expansion
@item tilde expansion
@item parameter and variable expansion
@item command substitution
@item arithmetic expansion
@item word splitting
@item filename expansion
@end itemize

@menu
* Brace Expansion::		Expansion of expressions within braces.
* Tilde Expansion::		Expansion of the ~ character.
* Shell Parameter Expansion::	How Bash expands variables to their values.
* Command Substitution::	Using the output of a command as an argument.
* Arithmetic Expansion::	How to use arithmetic in shell expansions.
* Process Substitution::	A way to write and read to and from a
				command.
* Word Splitting::	How the results of expansion are split into separate
			arguments.
* Filename Expansion::	A shorthand for specifying filenames matching patterns.
* Quote Removal::	How and when quote characters are removed from
			words.
@end menu

The order of expansions is: brace expansion, tilde expansion,
parameter, variable, and arithmetic expansion and
command substitution
(done in a left-to-right fashion), word splitting, and filename
expansion.

On systems that can support it, there is an additional expansion
available: @var{process substitution}.  This is performed at the
same time as parameter, variable, and arithmetic expansion and
command substitution.

Only brace expansion, word splitting, and filename expansion
can change the number of words of the expansion; other expansions
expand a single word to a single word.
The only exceptions to this are the expansions of
@code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"}
(@pxref{Arrays}).

After all expansions, @code{quote removal} (@pxref{Quote Removal})
is performed.

@node Brace Expansion
@subsection Brace Expansion
@cindex brace expansion
@cindex expansion, brace

Brace expansion is a mechanism by which arbitrary strings may be generated.
This mechanism is similar to
@var{filename expansion} (@pxref{Filename Expansion}),
but the file names generated need not exist.
Patterns to be brace expanded take the form of an optional @var{preamble},
followed by either a series of comma-separated strings or a seqeunce expression
between a pair of braces,
followed by an optional @var{postscript}.
The preamble is prefixed to each string contained within the braces, and
the postscript is then appended to each resulting string, expanding left
to right.

Brace expansions may be nested.
The results of each expanded string are not sorted; left to right order
is preserved.
For example,
@example
bash$ echo a@{d,c,b@}e
ade ace abe
@end example

A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}},
where @var{x} and @var{y} are either integers or single characters,
and @var{incr}, an optional increment, is an integer.
When integers are supplied, the expression expands to each number between
@var{x} and @var{y}, inclusive.
Supplied integers may be prefixed with @samp{0} to force each term to have the
same width.  When either @var{x} or @var{y} begins with a zero, the shell
attempts to force all generated terms to contain the same number of digits,
zero-padding where necessary.
When characters are supplied, the expression expands to each character
lexicographically between @var{x} and @var{y}, inclusive.  Note that
both @var{x} and @var{y} must be of the same type.
When the increment is supplied, it is used as the difference between
each term.  The default increment is 1 or -1 as appropriate.

Brace expansion is performed before any other expansions,
and any characters special to other expansions are preserved
in the result.  It is strictly textual.  Bash
does not apply any syntactic interpretation to the context of the
expansion or the text between the braces.
To avoid conflicts with parameter expansion, the string @samp{$@{}
is not considered eligible for brace expansion.

A correctly-formed brace expansion must contain unquoted opening
and closing braces, and at least one unquoted comma or a valid
sequence expression.
Any incorrectly formed brace expansion is left unchanged.

A @{ or @samp{,} may be quoted with a backslash to prevent its
being considered part of a brace expression.
To avoid conflicts with parameter expansion, the string @samp{$@{}
is not considered eligible for brace expansion.

This construct is typically used as shorthand when the common
prefix of the strings to be generated is longer than in the
above example:
@example
mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
@end example
or
@example
chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
@end example

@node Tilde Expansion
@subsection Tilde Expansion
@cindex tilde expansion
@cindex expansion, tilde

If a word begins with an unquoted tilde character (@samp{~}), all of the
characters up to the first unquoted slash (or all characters,
if there is no unquoted slash) are considered a @var{tilde-prefix}.
If none of the characters in the tilde-prefix are quoted, the
characters in the tilde-prefix following the tilde are treated as a
possible @var{login name}.
If this login name is the null string, the tilde is replaced with the
value of the @env{HOME} shell variable.
If @env{HOME} is unset, the home directory of the user executing the
shell is substituted instead.
Otherwise, the tilde-prefix is replaced with the home directory
associated with the specified login name.

If the tilde-prefix is @samp{~+}, the value of
the shell variable @env{PWD} replaces the tilde-prefix.
If the tilde-prefix is @samp{~-}, the value of the shell variable
@env{OLDPWD}, if it is set, is substituted.

If the characters following the tilde in the tilde-prefix consist of a
number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
the tilde-prefix is replaced with the
corresponding element from the directory stack, as it would be displayed
by the @code{dirs} builtin invoked with the characters following tilde
in the tilde-prefix as an argument (@pxref{The Directory Stack}).
If the tilde-prefix, sans the tilde, consists of a number without a
leading @samp{+} or @samp{-}, @samp{+} is assumed.

If the login name is invalid, or the tilde expansion fails, the word is
left unchanged.

Each variable assignment is checked for unquoted tilde-prefixes immediately
following a @samp{:} or the first @samp{=}.
In these cases, tilde expansion is also performed.
Consequently, one may use file names with tildes in assignments to
@env{PATH}, @env{MAILPATH}, and @env{CDPATH},
and the shell assigns the expanded value.

The following table shows how Bash treats unquoted tilde-prefixes:

@table @code
@item ~
The value of @code{$HOME}
@item ~/foo
@file{$HOME/foo}

@item ~fred/foo
The subdirectory @code{foo} of the home directory of the user
@code{fred}

@item ~+/foo
@file{$PWD/foo}

@item ~-/foo
@file{$@{OLDPWD-'~-'@}/foo}

@item ~@var{N}
The string that would be displayed by @samp{dirs +@var{N}}

@item ~+@var{N}
The string that would be displayed by @samp{dirs +@var{N}}

@item ~-@var{N}
The string that would be displayed by @samp{dirs -@var{N}}

@end table

@node Shell Parameter Expansion
@subsection Shell Parameter Expansion
@cindex parameter expansion
@cindex expansion, parameter

The @samp{$} character introduces parameter expansion,
command substitution, or arithmetic expansion.  The parameter name
or symbol to be expanded may be enclosed in braces, which
are optional but serve to protect the variable to be expanded from
characters immediately following it which could be
interpreted as part of the name.

When braces are used, the matching ending brace is the first @samp{@}}
not escaped by a backslash or within a quoted string, and not within an
embedded arithmetic expansion, command substitution, or parameter
expansion.

The basic form of parameter expansion is $@{@var{parameter}@}.
The value of @var{parameter} is substituted.  The braces are required
when @var{parameter}
is a positional parameter with more than one digit,
or when @var{parameter}
is followed by a character that is not to be
interpreted as part of its name.

If the first character of @var{parameter} is an exclamation point (!),
a level of variable indirection is introduced.
Bash uses the value of the variable formed from the rest of
@var{parameter} as the name of the variable; this variable is then
expanded and that value is used in the rest of the substitution, rather
than the value of @var{parameter} itself.
This is known as @code{indirect expansion}.
The exceptions to this are the expansions of $@{!@var{prefix}@*@}
and $@{!@var{name}[@@]@}
described below.
The exclamation point must immediately follow the left brace in order to
introduce indirection.

In each of the cases below, @var{word} is subject to tilde expansion,
parameter expansion, command substitution, and arithmetic expansion.

When not performing substring expansion, using the form described
below, Bash tests for a parameter that is unset or null.
Omitting the colon results in a test only for a parameter that is unset.
Put another way, if the colon is included,
the operator tests for both @var{parameter}'s existence and that its value
is not null; if the colon is omitted, the operator tests only for existence.

@table @code

@item $@{@var{parameter}:@minus{}@var{word}@}
If @var{parameter} is unset or null, the expansion of
@var{word} is substituted.  Otherwise, the value of
@var{parameter} is substituted.

@item $@{@var{parameter}:=@var{word}@}
If @var{parameter}
is unset or null, the expansion of @var{word}
is assigned to @var{parameter}.
The value of @var{parameter} is then substituted. 
Positional parameters and special parameters may not be assigned to
in this way.

@item $@{@var{parameter}:?@var{word}@}
If @var{parameter}
is null or unset, the expansion of @var{word} (or a message
to that effect if @var{word}
is not present) is written to the standard error and the shell, if it
is not interactive, exits.  Otherwise, the value of @var{parameter} is
substituted.

@item $@{@var{parameter}:+@var{word}@}
If @var{parameter}
is null or unset, nothing is substituted, otherwise the expansion of
@var{word} is substituted.

@item $@{@var{parameter}:@var{offset}@}
@itemx $@{@var{parameter}:@var{offset}:@var{length}@}
Expands to up to @var{length} characters of @var{parameter}
starting at the character specified by @var{offset}.
If @var{length} is omitted, expand