Bash Reference Manual Reference Documentation for Bash

Chapter 3: Basic Shell Features
16
For a complete description, refer to the GNU Parallel documentation. A few examples
should provide a brief introduction to its use.
For example, it is easy to replace xargs to gzip all html files in the current directory
and its subdirectories:
find . -type f -name ’*.html’ -print | parallel gzip
If you need to protect special characters such as newlines in file names, use find’s -print0
option and parallel’s -0 option.
You can use Parallel to move files from the current directory when the number of files
is too large to process with one mv invocation:
ls | parallel mv {} destdir
As you can see, the {} is replaced with each line read from standard input. While using
ls will work in most instances, it is not sufficient to deal with all filenames. If you need to
accommodate special characters in filenames, you can use
find . -depth 1 \! -name ’.*’ -print0 | parallel -0 mv {} destdir
as alluded to above.
This will run as many mv commands as there are files in the current directory. You can
emulate a parallel xargs by adding the -X option:
find . -depth 1 \! -name ’.*’ -print0 | parallel -0 -X mv {} destdir
GNU Parallel can replace certain common idioms that operate on lines read from a file
(in this case, filenames listed one per line):
while IFS= read -r x; do
do-something1 "$x" "config-$x"
do-something2 < "$x"
done < file | process-output
with a more compact syntax reminiscent of lambdas:
cat list | parallel "do-something1 {} config-{} ; do-something2 < {}" | process-output
Parallel provides a built-in mechanism to remove filename extensions, which lends itself
to batch file transformations or renaming:
ls *.gz | parallel -j+0 "zcat {} | bzip2 >{.}.bz2 && rm {}"
This will recompress all files in the current directory with names ending in .gz using bzip2,
running one job per CPU (-j+0) in parallel. (We use ls for brevity here; using find as
above is more robust in the face of filenames containing unexpected characters.) Parallel
can take arguments from the command line; the above can also be written as
parallel "zcat {} | bzip2 >{.}.bz2 && rm {}" ::: *.gz
If a command generates output, you may want to preserve the input order in the output.
For instance, the following command
{ echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel traceroute
will display as output the traceroute invocation that finishes first. Adding the -k option
{ echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel -k traceroute
will ensure that the output of traceroute foss.org.my is displayed first.
Finally, Parallel can be used to run a sequence of shell commands in parallel, similar to
‘cat file | bash’. It is not uncommon to take a list of filenames, create a series of shell

---

Chapter 3: Basic Shell Features
17
commands to operate on them, and feed that list of commnds to a shell. Parallel can speed
this up. Assuming that file contains a list of shell commands, one per line,
parallel -j 10 < file
will evaluate the commands using the shell (since no explicit command is supplied as an
argument), in blocks of ten shell jobs at a time.
3.3 Shell Functions
Shell functions are a way to group commands for later execution using a single name for
the group. They are executed just like a "regular" command. When the name of a shell
function is used as a simple command name, the list of commands associated with that
function name is executed. Shell functions are executed in the current shell context; no new
process is created to interpret them.
Functions are declared using this syntax:
name () compound-command [ redirections ]
or
function name [()] compound-command [ redirections ]
This defines a shell function named name. The reserved word function is optional. If
the function reserved word is supplied, the parentheses are optional. The body of the
function is the compound command compound-command (see Section 3.2.4 [Compound
Commands], page 9). That command is usually a list enclosed between { and }, but may
be any compound command listed above, with one exception: If the function reserved
word is used, but the parentheses are not supplied, the braces are required. compound-
command is executed whenever name is specified as the name of a command. When the
shell is in posix mode (see Section 6.11 [Bash POSIX Mode], page 96), name may not be
the same as one of the special builtins (see Section 4.4 [Special Builtins], page 70). Any
redirections (see Section 3.6 [Redirections], page 32) associated with the shell function are
performed when the function is executed.
A function definition may be deleted using the -f option to the unset builtin (see
Section 4.1 [Bourne Shell Builtins], page 42).
The exit status of a function definition is zero unless a syntax error occurs or a readonly
function with the same name already exists. When executed, the exit status of a function
is the exit status of the last command executed in the body.
Note that for historical reasons, in the most common usage the curly braces that surround
the body of the function must be separated from the body by blanks or newlines. This
is because the braces are reserved words and are only recognized as such when they are
separated from the command list by whitespace or another shell metacharacter. Also, when
using the braces, the list must be terminated by a semicolon, a ‘&’, or a newline.
When a function is executed, the arguments to the function become the positional pa-
rameters during its execution (see Section 3.4.1 [Positional Parameters], page 19). The
special parameter ‘#’ that expands to the number of positional parameters is updated to
reflect the change. Special parameter 0 is unchanged. The first element of the FUNCNAME
variable is set to the name of the function while the function is executing.
All other aspects of the shell execution environment are identical between a function and
its caller with these exceptions: the DEBUG and RETURN traps are not inherited unless the

---