@subsubsection ANSI-C Quoting
@cindex quoting, ANSI
-Character sequences of the form $'@var{string}' are treated as a special
-kind of single quotes.
+Character sequences of the form @code{$'@var{string}'} are treated as
+a special kind of single quotes.
The sequence expands to @var{string}, with backslash-escaped characters
in @var{string} replaced as specified by the ANSI C standard.
Backslash escape sequences, if present, are decoded as follows:
When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), @code{time}
may be followed by a newline. In this case, the shell displays the
total user and system time consumed by the shell and its children.
-The @env{TIMEFORMAT} variable may be used to specify the format of
-the time information.
+The @env{TIMEFORMAT} variable specifies the format of the time information.
If the pipeline is not executed asynchronously (@pxref{Lists}), the
shell waits for all commands in the pipeline to complete.
After these expansions are performed, quote characters present in the
original word are removed unless they have been quoted themselves
-(@dfn{quote removal}).
+(@dfn{quote removal}). @xref{Quote Removal} for more details.
Only brace expansion, word splitting, and filename expansion
can increase the number of words of the expansion; other expansions
@code{"$@{@var{name}[@@]@}"} 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
$ v=123
$ echo $@{v-unset@}
123
+$ echo $@{v:-unset-or-null@}
+123
+$ unset v
+$ echo $@{v-unset@}
+unset
+$ v=
+$ echo $@{v:-unset-or-null@}
+unset-or-null
@end example
@item $@{@var{parameter}:=@var{word}@}
Command substitution allows the output of a command to replace
the command itself.
-Command substitution occurs when a command is enclosed as follows:
+The standard form of command substitution occurs when a command is
+enclosed as follows:
@example
$(@var{command})
@end example
@noindent
-or
+or (deprecated)
@example
-`@var{command}`
+`@var{command}`.
@end example
@noindent
-Bash performs the expansion by executing @var{command} in a subshell environment
-and replacing the command substitution with the standard output of the
-command, with any trailing newlines deleted.
+Bash performs command substitution by executing @var{command} in a subshell
+environment and replacing the command substitution with the standard
+output of the command, with any trailing newlines deleted.
Embedded newlines are not deleted, but they may be removed during
word splitting.
The command substitution @code{$(cat @var{file})} can be
replaced by the equivalent but faster @code{$(< @var{file})}.
-When the old-style backquote form of substitution is used,
+With the old-style backquote form of substitution,
backslash retains its literal meaning except when followed by
@samp{$}, @samp{`}, or @samp{\}.
The first backquote not preceded by a backslash terminates the
When using the @code{$(@var{command})} form, all characters between
the parentheses make up the command; none are treated specially.
+There is an alternate form of command substitution:
+
+@example
+$@{@var{c} @var{command}; @}
+@end example
+
+@noindent
+which executes @var{command} in the current execution environment
+and captures its output, again with trailing newlines removed.
+
+The character @var{c} following the open brace must be a space, tab,
+newline, or @samp{|}, and the close brace must be in a position
+where a reserved word may appear (i.e., preceded by a command terminator
+such as semicolon).
+Bash allows the close brace to be joined to the remaining characters in
+the word without being followed by a shell metacharacter as a reserved
+word would usually require.
+
+Any side effects of @var{command} take effect immediately
+in the current execution environment and persist in the current
+environment after the command completes (e.g., the @code{exit} builtin
+will exit the shell).
+
+This type of command substitution superficially resembles executing an
+unnamed shell function: local variables are created as when a shell
+function is executing, and the @code{return} builtin forces
+@var{command} to complete;
+however, the rest of the execution environment,
+including the positional parameters, is shared with the caller.
+
+If the first character following the open brace
+is a @samp{|}, the construct expands to the
+value of the @code{REPLY} shell variable after @var{command} executes,
+without removing any trailing newlines,
+and the standard output of @var{command} remains the same as in the
+calling shell.
+Bash creates @code{REPLY} as an initially-unset local variable when
+@var{command} executes, and restores @code{REPLY} to the value it had
+before the command substitution after @var{command} completes,
+as with any local variable.
+
+For example, this construct expands to @samp{12345}, and leaves the
+shell variable @code{X} unchanged in the current execution environment:
+
+@example
+
+$@{ local X=12345 ; echo $X; @}
+@end example
+
+@noindent
+(not declaring @code{X} as local would modify its value in the current
+environment, as with normal shell function execution),
+while this construct does not require any output to expand to
+@samp{12345}:
+
+@example
+$@{| REPLY=12345; @}
+@end example
+
+@noindent
+and restores @code{REPLY} to the value it had before the command substitution.
+
Command substitutions may be nested. To nest when using the backquoted
form, escape the inner backquotes with backslashes.
-If the substitution appears within double quotes, word splitting and
-filename expansion are not performed on the results.
+If the substitution appears within double quotes, Bash does not perform
+word splitting and filename expansion on the results.
@node Arithmetic Expansion
@subsection Arithmetic Expansion
the names is not a valid shell variable name, or @option{-f} is supplied
with a name that is not a shell function.
+@item false
+@btindex false
+@example
+false
+@end example
+
+Does nothing, returns a non-zero status.
+
@item getopts
@btindex getopts
@example
hash [-r] [-p @var{filename}] [-dt] [@var{name}]
@end example
-Each time @code{hash} is invoked, it remembers the full pathnames of the
+Each time @code{hash} is invoked, it remembers the full filenames of the
commands specified as @var{name} arguments,
so they need not be searched for on subsequent invocations.
The commands are found by searching through the directories listed in
@env{$PATH}.
-Any previously-remembered pathname is discarded.
+Any previously-remembered filename is discarded.
The @option{-p} option inhibits the path search, and @var{filename} is
used as the location of @var{name}.
The @option{-r} option causes the shell to forget all remembered locations.
+Assigning to the @env{PATH} variable also clears all hashed filenames.
The @option{-d} option causes the shell to forget the remembered location
of each @var{name}.
If the @option{-t} option is supplied, the full pathname to which each
using the rules listed above.
@end table
-When used with @code{test} or @samp{[}, the @samp{<} and @samp{>}
+If the shell is not in @sc{posix} mode,
+when used with @code{test} or @samp{[}, the @samp{<} and @samp{>}
operators sort lexicographically using ASCII ordering.
+If the shell is in @sc{posix} mode, these operators use the current locale.
+
+The historical operator-precedence parsing with 4 or more arguments can
+lead to ambiguities when it encounters strings that look like primaries.
+The @sc{posix} standard has deprecated the @option{-a} and @option{-o}
+primaries and enclosing expressions within parentheses.
+Scripts should no longer use them.
+It's much more reliable to restrict test invocations to a single primary,
+and to replace uses of @option{-a} and @option{-o} with the shell's
+@code{&&} and @code{||} list operators. For example, use
+
+@example
+test -n string1 && test -n string2
+@end example
+
+@noindent
+instead of
+
+@example
+test -n string1 -a -n string2
+@end example
@item times
@btindex times
The return status is zero unless a @var{sigspec} does not specify a
valid signal.
+@item true
+@btindex true
+@example
+true
+@end example
+
+Does nothing, returns a 0 status.
+
@item umask
@btindex umask
@example
@example
set [-abefhkmnptuvxBCEHPT] [-o @var{option-name}] [--] [-] [@var{argument} @dots{}]
set [+abefhkmnptuvxBCEHPT] [+o @var{option-name}] [--] [-] [@var{argument} @dots{}]
+set -o
+set +o
@end example
If no options or arguments are supplied, @code{set} displays the names
@item -o @var{option-name}
-Set the option corresponding to @var{option-name}:
+Set the option corresponding to @var{option-name}.
+If @option{-o} is supplied with no @var{option-name},
+@code{set} prints the current shell options settings.
+If @option{+o} is supplied with no @var{option-name},
+@code{set} prints a series of
+@code{set}
+commands to recreate the current option settings
+on the standard output.
+Valid option names are:
@table @code
@item allexport
The list of @code{shopt} options is:
@table @code
-@item assoc_expand_once
-If set, the shell suppresses multiple evaluation of associative array
-subscripts during arithmetic expression evaluation, while executing
+@item array_expand_once
+If set, the shell suppresses multiple evaluation of
+associative and indexed array subscripts
+during arithmetic expression evaluation, while executing
builtins that can perform variable assignments,
and while executing builtins that perform array dereferencing.
+@item assoc_expand_once
+Deprecated; a synonym for @code{array_expand_once}.
+
@item autocd
If set, a command name that is the name of a directory is executed as if
it were the argument to the @code{cd} command.
Setting @code{extdebug} after the shell has started to execute a script,
or referencing this variable when @code{extdebug} is not set,
may result in inconsistent values.
+Assignments to @env{BASH_ARGC} have no effect, and it may not be unset.
@item BASH_ARGV
An array variable containing all of the parameters in the current Bash
Setting @code{extdebug} after the shell has started to execute a script,
or referencing this variable when @code{extdebug} is not set,
may result in inconsistent values.
+Assignments to @env{BASH_ARGV} have no effect, and it may not be unset.
@item BASH_ARGV0
When referenced, this variable expands to the name of the shell or shell
@code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if
referenced within another shell function).
Use @code{LINENO} to obtain the current line number.
+Assignments to @env{BASH_LINENO} have no effect, and it may not be unset.
@item BASH_LOADABLES_PATH
A colon-separated list of directories in which the shell looks for
dynamically loadable builtins specified by the
@code{enable} command.
+@item BASH_MONOSECONDS
+Each time this variable is referenced, it expands to the value returned
+by the system's monotonic clock, if one is available.
+If there is no monotonic clock, this is equivalent to @env{EPOCHSECONDS}.
+If @env{BASH_MONOSECONDS}
+is unset, it loses its special properties, even if it is
+subsequently reset.
+
@item BASH_REMATCH
An array variable whose members are assigned by the @samp{=~} binary
operator to the @code{[[} conditional command
variable are defined.
The shell function @code{$@{FUNCNAME[$i]@}} is defined in the file
@code{$@{BASH_SOURCE[$i]@}} and called from @code{$@{BASH_SOURCE[$i+1]@}}
+Assignments to @env{BASH_SOURCE} have no effect, and it may not be unset.
@item BASH_SUBSHELL
Incremented by one within each subshell or subshell environment when
is unset, it loses its special properties, even if it is
subsequently reset.
+@item BASH_TRAPSIG
+Set to the signal number corresponding to the trap action being executed
+during its execution.
+See the description of @code{trap}
+(@pxref{Bourne Shell Builtins})
+for information about signal numbers and trap execution.
+
@item BASH_VERSINFO
A readonly array variable (@pxref{Arrays})
whose members hold version information for this instance of Bash.
For example, a value of @code{-mtime} sorts the results in descending
order by modification time (newest first).
+A sort specifier of @samp{nosort} disables sorting completely; the results
+are returned in the order they are read from the file system,.
+
If the sort specifier is missing, it defaults to @var{name},
so a value of @samp{+} is equivalent to the null string,
and a value of @samp{-} sorts by name in descending order.
The optional @var{p} is a digit specifying the precision, the number of
fractional digits after a decimal point.
A value of 0 causes no decimal point or fraction to be output.
-At most three places after the decimal point may be specified; values
-of @var{p} greater than 3 are changed to 3.
+At most six places after the decimal point may be specified;
+values of @var{p} greater than 6 are changed to 6.
If @var{p} is not specified, the value 3 is used.
The optional @code{l} specifies a longer format, including minutes, of
That means, for example, that a backslash preceding a double quote
character will escape it and the backslash will be removed.
+@item
+The @code{test} builtin compares strings using the current locale when
+processing the @samp{<} and @samp{>} binary operators.
+
+@item
+The @code{test} builtin's @option{-t} unary primary requires an argument.
+Historical versions of @code{test} made the argument optional in certain
+cases, and bash attempts to accommodate those for backwards compatibility.
+
@item
Command substitutions don't set the @samp{?} special parameter. The exit
status of a simple command without a command word is still the exit status
has no special effect
@end itemize
-@item compat32
-@itemize @bullet
-@item
-interrupting a command list such as "a ; b ; c" causes the execution
-of the next command in the list (in bash-4.0 and later versions,
-the shell acts as if it received the interrupt, so
-interrupting one command in a list aborts the execution of the
-entire list)
-@end itemize
-
@item compat40
@itemize @bullet
@item
projects / thirdparty / bash.git / blobdiff