back to the table of contents, | There exists a May 20, 2019 version at www.gnu.org/software/bash/manual/bashref.html.gz |
|
#
causes remaining characters on that line to be ignored
Metacharacters | & ; ( ) < >
[space] and [tab]
seperate words of a command.
\
) or
enclosed within apostrophes† ( '
)
their special meaning is supressed as is parameter expansion."
) their special treatment is disabled,
prevents reserved words
( which include the [ ] ! { }
) from being recognized,
\
the shell would interpret the ;
as the end of the command.
A \
at the end of a line †
signals a continuation onto the next line and prompts with $PS2
(\
and new-line are ignored )
.
A circumflex (
A
^
) indicates a non-printable character, example:
To causes a page eject in a print stream, insert a formFeed
(^L
is produced by holding down the CONTROL key then pressing the letter L )
> echo \^L
apostrophe†
An apostrophe may not occur between apostrophes, even when preceded by a
> grep '(@)' filename
# locate lines containing the three characters (@)†
[ ] !
{ }†
) from being recognized,
> echo Process Aborted '! ! '
$var
).
> echo '$?' is $? #display the status
$? is 0
\
, use quotes instead.
> grep 'don\'t' dafile.txt #
will wait for closing apost. Double Quotes†
Enclosing characters in "
Beware of copying/pasting “ ” which are a pretty left/right quotes but not for bash!.
$
, `
, and \
.
$
STILL indicates parameter expansion
`
STILL indicates command substitution
\$
, \`
, \"
, \\
, and \newline
are treated specially but other occurances of backslash are not.
Backslashes preceding characters without a special meaning are left unmodified.
*
and @
Specify special parameter expansion within quotes."
may be preserved within "
s by preceding it with a backslash.
Example: have grep
locate lines containing use "TITLE" with
> grep "use \"TITLE\" with" HTML-Notes.html
ANSI-C Quoting
A word of the form $'string'
expands to string
,
with backslash-escaped characters replaced with
\n | newline | x0A \cJ †
(i.e. ctrl-J )
| 
\\ backslash | x5C | aka solidus
| \' apostrophe | x27 | Refered to as "single quote".
| \a alert (bell) | x07 |
| \b backspace | x08 | ␈
| \r carriage return | x0D | ␍
| \t horizontal tab | x09 | ␉
| \f form feed | x0C | ␌
| \v vertical tab | x0B | ␋
| \e ESCape character | x1B | ␛
used as "lead-in" for terminal specific function (not ANSI C)
| \ooo
the eight-bit character whose value is the octal value ooo
| \xXX
the eight-bit character whose value is the hexadecimal value | XX
\cc a control- | c character
|
The result is single-quoted, as if the dollar sign had not been present.
Example:
echo $'\a12\bAB' 1AB
Beep is sounded, 12
is displayed, a backspace positions at the 2
then the A
is placed over the 2
, obscuring the 2, then a B
is displayed,
resulting in 1AB
.
To prevent the shell from processing the \
escape it with a leading \
( i.e. echo \\a12\\bAB
).
To sound the alert tone:
echo $'\a'To bold part of a message it is necessary to use the ANSI terminal control sequence :
echo ++++ The message $'\e[1m' mds[]: "(/)(Warning)" $'\e[0m' does not belong in alert
++++ The message mds[]: (/)(Warning) does not belong in alert.log
See ANSI terminal codes for additional renditions.
It may be helpful to create a file containing only the ESCape character by:
echo -n $'\e' > ESC
`
character encloses a command and is not a quoting character.> export startedAt=`date +%s` # (seconds since epoch usable to calculate elapsed seconds at completion or in .bash_logout
.
> echo $startedAT
1358799415/pre>
$
will
cause the string to be translated according to the current locale, C
or POSIX
, the dollar sign is ignored. example: echo $LOCALE QQ(_) eh wot?
space
s, terminated by a control operator
† which returns a status.
The first word generally specifies a command to be executed followed by arguments (options, files, etc).
For example to list the files in the current directory in long format:
ls -l total 88 -rwxr-xr-x 1 realger1 realger1 11747 Nov 14 19:47 a.out -rw-r--r-- 1 realger1 realger1 211 Nov 14 19:24 buff.c -rw-r--r-- 1 realger1 realger1 591 Nov 14 19:52 buff.s -rw-r--r-- 1 realger1 realger1 0 Oct 11 17:49 lx drwx------ 2 realger1 realger1 4096 Oct 30 01:42 logs -rw-r--r-- 1 realger1 realger1 0 Oct 13 15:49 lynx.cfg
Multiple commands may be on a single line seperated by ;
or on seperate lines.
;
;
are executed sequentially;
the shell waits for each command to terminate. newline
.
When a command ends with &
&
, the shell executes the command asynchronously in a subshell,
i.e. the shell does not wait for the command to finish. A command prompt is issued immediately.
Known as executing the command in the background. The status is
The standard input for asynchronous commands is /dev/null
by default.
$!
contains the pid of that background process and can be assigned with back_PID=$!
,
then wait back_PID
will wait until the background process completes.
Pipelines
A sequence of simple commands separated by |
† .
The STDOUT
of each command is sent to the STDIN
of the next command.
For example to cut
off the type, mod bit display, links, owner and ls -l
(i.e. the first 34 characters ) use:
ls -l | cut -c35- 11747 Nov 14 19:47 a.out 211 Nov 14 19:24 buff.c 4096 Oct 30 01:42 logs |
The shell waits for each of the commands in the pipeline to complete, unless the pipeline is to be executed asynchronously † .
Each command is executed in its own subshell †.
The status is that of the last command or its negation if !
|.
The next command may be on a subsequent line, this permits comments after the pipe for example:
ls -l | #list the files
cut -c35-
A list is a sequence of one or more pipelines separated by one of the operators
&&
||
;
&
terminated by ;
&
or a newline
.
&&
and ||
have equal precedence, followed by
;
and &
which have equal precedence.
command1 &&
command2
command1
returns a status of 0̸; then command2
is executed.&&
do_more_stuff_since_it_is_going_well
command1 || command2
command1
returns a non-zero status; then command2
is executed.||
( rc=$?; clean_up_mess_from_failured_stuff; echo failed ; exit $rc)
The status is that of the last command executed.
(list)
list
is executed in a subshell environment.list
.
{ list;
}
list
is executed in the current shell environment.{}
see
Brace expansion and
Parameter Expansion list
.
((arithmetic_expression))
arithmetic_expression
is evaluated according to the
arithmetic evaluation rules .
If the value of the expression is zero. the result is 1 (aka TRUE)
|
If the value of the expression is non-zero;the result is 0̸ (aka FALSE).
|
Example:
(( $rc )) ||†
echo success; logger -p local2.warning " Monthly sort failed."
[[
conditional expressions
]]
[[ $str == '' † ]]; echo $str
conditional_expression
.
==
and !=
are used, the
string to the right of the operator is a pattern and matched
according to the rules described in Pattern Matching
( * , ? , [..], [a-z] , …
). nocasematch
is enabled, the match is performed without regard to the case of alphabetic characters.
For ==
if the string matches the value is
For !=
if the string does not match the value is
Any part of pattern
may be quoted to force it to be matched as a string.
=~
the string to the right of the operator is an extended regular expression
and matched as in regex.
If nocasematch
is enabled, the match is performed without regard to the case of alphabetic characters.
Substrings matched by parenthesized, subexpressions within the regular expression are saved in the array variable BASH_REMATCH
.
The element BASH_REMATCH[0]
is the portion of the string matching the entire regular expression.
The BASH_REMATCH[n]
is the portion of the string matching the nth parenthesized subexpression.
==
, !=
and =~
have the same precedence.
( exprn ) | returns the value of exprn. Used to override the normal precedence of operators or for clarifcation.
| ||||
!† exprn
|
&&
and ||
do not execute exprn2
if the value of exprn1
is sufficient to determine the return value of the entire conditional expression.
Conditional operators which test a files status, such as -f
†,
must be unquoted to be recognized as primaries.
break
as target of an if
to terminate a loop prematurely.
for
for name
[ in words
] ; do command-list ; done
If words
is expanded, generating a list of items.
name
is set to each element of this list in
turn, and command-list
is executed for each.
in words
is omitted, for
executes command-list
once for each positional parameter that is set.
The status is that of the last command that executes.
If the expansion of words
is an empty list, no commands are executed, and the status is 0̸!
for ODDNUM in 1 3 5 7 ; do echo $ODDNUM ;done
alternate format:
for (( expr-init ; expr-test ; expr-incr )) ; do command-list ; done
expr-init
is evaluated as per arithmetic evaluation.
expr-test
is evaluated " "
results not 0 | results 0 | |||
---|---|---|---|---|
command-list is executed | command-list is NOT executed
expr-incr is evaluated and processing continues with the expr-test
processing continues with | the command after the done .
|
A 1 is used if an expr
is ommited.
The return value is the status of the last command in list that is executed, or false if any of the expressions is invalid.
until while | until test-commands; do commands; done while test-commands do commands … done As long as | test-commands has an status which is
not zero | zero
|
execute | commands
|
The status is the status of the last command executed in commands;
Execute the case
case $var in
pattern1 [|
patternn] ) command-list ;;
[patternm ) command-list ;;]
…
esaccommand-list
corresponding to the first pattern
that matches $VAR
.
A pattern list is delimited by |
and terminated by )
.
A pattern list and associated command-list is known as a clause
.
Each clause must be terminated with ;;
.
$var
undergoes itilde expansion, parameter expansion, command substitution, arithmetic expansion,
and quote removal before matching is attempted.
pattern
undergoes tilde expansion, parameter expansion, command substitution, and arithmetic expansion.
Example:
The code: | |
echo "Enter the name of an animal:" read ANIMAL echo "The $ANIMAL has " case $ANIMAL in man | kangaroo ) echo two ;; esac echo "legs."
running code
| Enter the name of an animal: cat The cat has four legs. |
pattern
is matched. command-list
executed. (Which might be zero!)
if test ; then true command-list; fi
test
(aka conditional expressions) is evaluated or
commands aare executed.
A true or success result returns
0̸ and causes the true-command-list
to be executed.
(Some languages use 0̸ for false.
Using 0̸ for success proivides for multiple failure return codes.)
if test
then
true-commands
more-true-commands
fi
When test and action are short this can be written on a single line:
if test; then
true-commands;
more-true-commands; fi
rm xxyyww; rc=$? # save return code for later display and use with exit.
if [ $rc ]; then echo " failed \$RC=$rc"; exit $rc; fi
else … if
else false-commands;
]
if tests; then
elif more-tests; then
[else false-commands;]
elif
list is executed in turn, more-true-commands
is executed
If "else false-commands
" is present, and the final command in the final if
or elif
clause has a non-zero status,
then false-commands
is executed.
The status is the status of the last command executed, or 0̸ if no condition tested true.
if
needs space before [
[ x comparison y ]
needs spaces around comparison
./myscript.sh
RS=$?
if [ $RS -ne 0 ]; then echo myscript failed status= $RS ; fi
./yourscript.sh
if [ $? -eq 0 ]; then echo yourscript worked, no cleanup needed; exit; fi
if [ $anyDefinedVarilable ]; then echo true ; fi ( including $? )
if [ -z "$PS1" ]; then
echo This shell is not interactive
else
echo This shell is interactive
fi
-bash: [: -eq: unary operator expected Attempting to compare an unset $variable
| -bash: [: 0: unary operator expected |
The very simple if first command works, execute second command
./setup.sh && ./process.sh
If first command fails, execute second command
./checkIt || rc=$?; echo "checkIt failed" ; exit $rc;
(see Lists of Commands )
select name [in words … ]; do commands; done
in words
is omitted, the positional parameters are output, as if in "$@"
had been specifed.
PS3
prompt is then displayed and a line is read from the standard input.
null
.
EOF
is read, the select
command completes.
The line read is saved in the variable
REPLY
.
commands
are executed after each selection until a break
or return
command is executed, at which point the select
command completes.
select fname in 0.sh birdloger* *.sed ; do echo you picked $fname \($REPLY\); break; done 1) 0.sh 3) birdloger.pl 5) log-summ.sed 2) birdloger.html 4) birdlogmail2content.sed 6) lslrClean.sed #? 3 you picked birdloger.pl (3)
function funcname (){
command-list;
return [rc];
}
The command-list
is executed when funcname
is used as a command.
Functions can be defined within a script or in a file but must be defined before they are invoked.
To include a file containing functions use source fileWithFuncs
or
. fileWithFuncs
.
A function is invoked as if it were a commmand, for example:
When a function is entered, the positional parameters are the arguments of the caller> pwd > funcname arg1 arg2 …
# no ()s are used.> date $1
$#
) is the number of arguments. $
The status of a function is the status of the last command executed in the command-list or
the value supplied by return n
.
When the function completes,
$#
are restored Variables local to the function may be declared with the local
builtin making them accessible only to the function and the commands it invokes.
Functions may be recursive. No limit is placed on the number of recursive calls.
Example:
> echo $0 -bash > cat resetfile.fun resetfile(){ echo $0 echo $1 if [ -e $1 ]; then rm $1;fi touch $1 chmod 755 $1 } > . resetfile.fun > resetFile output1 -bash notice that 0̸ reflects the caller of the script not the function output1 >ls -l output1 -rwxr-xr-x 1 me mygroup0 Oct 7 13:210
$
and
can be a name ($HOME
, $LOGNAME
, $PATH
), a number ($1
), or
one of several
A variable is a parameter denoted by a name.
A variable may be assigned by a statement of the form
name=[value]
If value
is not given, the variable is assigned the null string.
All value
s undergo tilde expansion, parameter expansion, and variable expansion,
command substitution, arithmetic expansion, and quote removal .
integer
attribute set (see declare
),
value
is subject to arithmetic expansion even if the $((…
expansion is not used (see Arithmetic Expansion).
$@
Once a variable is 'set', it may be 'unset' only by using the unset
builtin.
A positional parameter
is a parameter denoted by $
and one or more digits
assigned from the shell's arguments when a script or function is invoked.
They may be reassigned using set
, but not with assignment statements.
Positional parameter $N
may be referenced as ${N}
.
They are temporarily replaced when a function is executed .
A positional parameter consisting of more than a one digit must be enclosed in braces.
To test if the first positional parameter was provided and is an existing file use:if [ ! -e ${1:? What file\?} ]; then echo \ \-\- $1 does not exist; exit 2; fi
shift
causes the 1st parameter to be assigned to $0
,
the 2nd assigned to $1
…
$ |
stdin
aka file descriptor stdout
(descriptor 1).
and control/diagnostic &helip; output to
stderr
)(descriptor 2)
The shell uses the |
† between to filters
to indicate that the stdout from the previous filter is sent directly to the next filter (i.e. no file is created). ls | grep middlechars
<
(input) and >
(output).
Redirection opens and closes files before the command is executed and a failure causes the command to be skipped.
For example sudo
will not execute if the output is redirected to a file that is not writable to the invoking user.
Processed from left to right they may precede, appear within or follow a command and
are commonly placed after a command where the appearance is consistant with the dataflow.
For example:
sort < infile > outfileThe
filename
following the redirection operator is subjected to
{ brace,
~ tilde,
${ parameter,
$(( arithmetic and
filename* expansion,
` command substitution and
' "
quote removal.
If it expands to more than one word, Bash reports the error: "ambiguous redirect" and the command is not executed.
n
]<filename
filename
to be opened for reading.n
) is 0, standard input.tr '[:upper:]' '[:lower:]' < cedar2.txt
Redirecting Output
n
]>[|
]filename
If filename
does not exist it is created.
If filename
exists it is truncated to zero size,
use [n
]>>filename
to append to an exisiting file.
if filename
exists as a regular file and noclobber
is set, the command is not executed,
Use >|
to overwrite filename
regardless of noclobber
.
If the directory for filename
does not exist; the command is not executed and the error No such file or directory
is output .
Default output file descriptor n
is 1
standard output. Use 2
for standard errror.
To redirect stdout to stderr use 1>&2
†.
Although any file descriptor number can be used by a program I've never seen anything else.(ed)
Programs that output 2 reports or read multiple input file streams usually with arguments like:
invoices --transin bank.in --checkin checking.in --summary summ.txt --details details.txt
Example: ls -l > filelist 2>>err.log # redirects STDOUT to filelist and STDERR to err.log
NB: It's the shell (not the program) that (attempts to) delete and open the destination file. This is especially important for sudoers since if your current user id cannot create/write to the redirected file, the command fails.
if current directory is
ls -l > t will (as you should expect) fail unless you have write access to sudo -l > t will also fail (although you might not expect that)
sudo touch t will sucessfully create an empty file, next
|
Redirecting stderr while leaving stdout as redirected in command line:
The function:
sedlist(){ sed "s/xy/as/" <$1 ls -l $1 }Invoked with sedlist infile > outfile causes sed to operate on infile and errors go to the console.
command &>filename
ls -l &> /tmp/stdout+stderr
Redirecting to /dev/null
should be avoided. Instead use, for example:
monthlyProcessing > monthly.rpt 2> monthly.err
if [ $? >
This displays the STDERR
output if the return code was not
[n]<&fdes
If n
is not specified, the STDIN
(file descriptor 0) is used.
If fdes
expands to one or more digits, the file descriptor (n
) becomes
a copy of that file descriptor.
If the digits in fdes
do not specify
a file descriptor open for input, a redirection error occurs.
If fdes
evaluates to -
, file descriptor n
is closed.
Duplicate output file descriptors: [n]>&fdes
If n
is not specified, the standard output (file descriptor 1) is used.
If the digits in fdes
do not specify a file descriptor open for output, a redirection
error occurs. As a special case, if n
is omitted, and
fdes
does not expand to one or more digits, STDOUT
and STDERR
are redirected .
d
to file descriptor n
, or the standard input
if n
is not specified: [n]<&d-
d
is closed after being duplicated to n
.
[n]<>file
file
to be opened
for both reading and writing on file descriptor n
, or on file
descriptor 0 if n
is not specified.delimiterWord
. <<[-]‡delimiterWord
lines of input
…
delimiterWord
No trailing spaces are permitted on the line with delimiterWord
No parameter expansion, command substitution, filename expansion, or
arithmetic expansion is performed on delimiterWord
.
If any characters in delimiterWord
are quoted, the delimiterWord
is the result of quote
removal on delimiterWord
, and the lines in the here-document are not expanded.
If delimiterWord
is unquoted, all lines of the here-document are subjected to parameter expansion, command substitution, and arithmetic expansion.
The pair \newline
is ignored, and \
must be used to escape \
, $
, and
`
.
<<-
leading tab characters are stripped from input and the line containing
delimiter.
This allows here-documents within shell scripts to be indented.
> cat << ++++ > newfile here is an input line and another These come from the script $0 with args $* Current \$PATH is $PATH ++++ > cat newfile here is an input line and another These come from the script -bash with args editing-mode vi Current $PATH is usr/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
When a simple command is executed, the shell performs the following operations from left to right.
=
in each variable assignment undergoes
tilde expansion, parameter expansion,
command substitution, arithmetic
expansion, and quote removal before being assigned to the variable.
variable=`ls ~/*.sh`
/Users/me > echo $variable
/Users/me/LibraryClean.sh /Users/me/net.sh /Users/me/pocketForCordury.sh
If no command name results, the variable assignments affect the current shell environment.
Otherwise, the variables are added to the environment of the
executed command and do not affect the current shell environment.
If no command name results, redirections are performed, but do not affect the current shell environment.
If there is a command name left after expansion, execution proceeds as described below. Otherwise, the command exits.
If one of the expansions contained a command substitution, the status of the command is the status of the last command substitution performed. If there were no command substitutions, the command exits with a status of 0̸.
After a command has been split into words, if it results in a simple command and an optional list of arguments, the following actions are taken.
If the command name contains no slashes, the shell attempts to locate it checking for a:
$PATH
for a directory containing an executable file. PATH
searches (see the description of hash
in section Bourne Shell Builtins, this may be a problem if the file is created during the shell execution.
A full search of the directories in $PATH
is performed only if the command is not found in the hash table. )&
The status of a simple command is its exit status or 128+n if the command was terminated by signal??(_) n.
exec
builtin
cd
, pushd
, or popd
, or inherited by the shell at invocation
umask
or inherited from the shell's parent
trap
set
or inherited from the shell's parent in the environment
set
shopt
alias
es
$$
, and the value of $PPID
When a simple command other than a builtin or shell function is to be executed,(among other things ) it is invoked in a separate execution environment that consists of:
A command invoked in this separate environment cannot affect the calling shell's execution environment.
Command substitution and asynchronous commands are invoked in a subshell environment that is a duplicate of the shell environment, except that traps caught by the shell are reset to the values that the shell inherited from its parent at invocation.
Builtin commands that are invoked as part of a pipeline are also executed in a subshell environment.
Changes made to the subshell environment cannot affect the shell's execution environment.
NAME=value
pairs) and environment
is made available.
On invocation, the shell marks each parameter export to child processes.
Executed commands inherit the environment.
unset
,
export
and
declare
add/delete parameters and functions to/from the environment.
The environment for any simple command or function may be augmented
temporarily by prefixing it with parameter assignments, as described in Shell Parameters.
These assignment statements affect only the environment seen by that command.
With -k
aka -o keyword
(a set builtin), parameter assignments are placed in the environment for a command, not just those that precede the command name.
When Bash invokes an external command, $_
is set to the full path name of the command.
A non-zero status indicates failure.
This seemingly counter-intuitive† scheme is used so there is
n
command failed with a return code of n
ls -l
).The status is used by the Conditional Constructs and some of the list constructs .
A negative value used in an exit returns 256-value example exit -9
returns 247
default keystrokes | see stty
> stty -a … cchars: discard=^O; dsusp=^Y; eof=^D; eol=intr=^C; quit=^\; killcharacters typedAhead=^U; eof=^D; eol=<undef> eol2= SIG | QUIT ^\ |
If BASH receives a signal, for which a trap has been set, while waiting for a command to complete, will not be executed until the command completes.
If wait
ing for an asynchronus command a status greater than 128 is set, then trap is executed.
Commands started by Bash have signal handlers set to the values inherited by the shell from its parent.
Additional signals , passed to process
-c
nor -s
is supplied (see Invoking Bash).
The parameter $0
is set to the name of the file (rather than the name of the shell),
and positional parameters are set to the remaining arguments, i.e. $1, $2
….
When a file in the $PATH
for a command, it spawns a subshell to execute it. In other words, executing
file arguments
†
is equivalent to executing
bash file arguments
†
chmod
regarding setting permissions to allow a file to be executable as a script.
This subshell initializes itself, so that the effect is as if a new shell had been invoked to interpret the script,
with the exception that the locations of commands
remembered by the parent (see hash
Builtins) are retained by the child.
If the first line of a script begins with #!
,
the remainder of the line specifies an interpreter for the the script, followed by the arguments.
For example:
#!/bin/bash#!/usr/bin/perl -w