LDP/LDP/inprogress/Bash-Scripting-Introduction-HOWTO.xml

<?xml version="1.0" encoding="iso-8859-1"?>

<!--
I'm still trying to figure out why xsltproc works with this DTD URI:

	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

but generates an error with this DTD URI:

	"http://docbook.org/xml/4.2/docbookx.dtd"
-->

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://docbook.org/xml/4.2/docbookx.dtd"
[
    <!ENTITY ldp "Linux Documentation Project">
    <!ENTITY ldpurl "http://www.tldp.org/">
    <!ENTITY thisurl "&ldpurl;HOWTO/Intro-Bash-Scripting-HOWTO.html">
    <!ENTITY gfdlurl "http://www.gnu.org/copyleft/fdl.html">
    <!ENTITY bashref "http://www.gnu.org/software/bash/manual/bashref.html">
    <!ENTITY shebang "<emphasis>shebang</emphasis>">
]>

<!--
************************************************************************
Bash Scripting Introduction HOWTO
Maintainers: Francis Litterio <franl@world.std.com>,
             Rohit Patil <rvpatil@gmail.com>
************************************************************************
-->

<article>
  <articleinfo>
    <title>Bash Scripting Introduction HOWTO</title>

    <author>
      <firstname>Francis</firstname><surname>Litterio</surname>
      <affiliation>
	<address><email>franl@world.std.com</email></address>
      </affiliation>
    </author>

    <author>
      <firstname>Rohit</firstname><surname>Patil</surname>
      <affiliation>
	<address><email>rvpatil@gmail.com</email></address>
      </affiliation>
    </author>

    <!-- Copyright (c) 2004 Francis P. Litterio, Jr. -->

    <copyright>
      <year>2004</year>
      <holder>Francis P. Litterio, Jr.</holder>
    </copyright>

    <legalnotice>
      <para>
	Permission is granted to copy, distribute and/or modify this document
	under the terms of the <ulink url="&gfdlurl;">GNU Free Documentation
	License</ulink>, Version 1.1 or any later version published by the Free
	Software Foundation A copy of the license is included in the section
	entitled "GNU Free Documentation License" (<xref
	linkend="sect-copyleft"/>).
      </para>
    </legalnotice>

    <pubdate>2004-XX-XX</pubdate>

    <!-- Most recent revision goes at the top; list in descending order -->
    <!-- All dates specified in ISO "YYYY-MM-DD" format -->
    <revhistory>
      <!-- Add more <revision></revision> elements here. -->
      <revision>
	<revnumber>1.0</revnumber>
	<date>2006-XX-XX</date>
	<authorinitials>FL</authorinitials>
	<authorinitials>RP</authorinitials>
	<revremark>
	  First release in Docbook format.  Based on an earlier version in Linuxdoc
	  format by Mike G.
	</revremark>
      </revision>
    </revhistory>

    <abstract>
      <para>
	This HOWTO helps you write basic Bash shell scripts.  This HOWTO assumes
	that you know nothing about shell scripting, but it assumes you have
	used Bash or the Bourne shell interactively.  You do not have to be a
	programmer to benefit from this HOWTO.  This is not an advanced shell
	scripting HOWTO.  If you want to read an advanced document on this
	topic, see <emphasis>The Advanced Bash-Scripting Guide</emphasis> at the
	&ldp; (<ulink url="&ldpurl;">&ldpurl;</ulink>).
      </para>
    </abstract>
  </articleinfo>

  <sect1 id="sect-intro">
    <title>Introduction</title>

    <sect2 id="sect-finding-this-howto">
      <title>Where to Find This HOWTO</title>

      <para>
	You can always find the latest version of this HOWTO at the <ulink
	url="&ldpurl;">Linux Documentation Project</ulink> at this location:
      </para>

      <blockquote>
	<para><ulink url="&thisurl;">&thisurl;</ulink>.</para>
      </blockquote>
    </sect2>

    <sect2 id="sect-overview">
      <title>Overview</title>

      <para>
	The Bourne Again Shell (Bash) is the primary shell of the GNU system.  It
	is compatible with the Bourne shell, which is one of the oldest UNIX
	shells, but it has many enhancements that make it superior to the Bourne
	shell.  A Bash <firstterm>script</firstterm> is a human-readable file
	containing commands that are executed by Bash.  This HOWTO is an
	introduction to writing Bash scripts.
      </para>

      <para>
	This HOWTO is written for anyone who wants to begin writing Bash scripts
	but who has no prior scripting experience.  You do not have to be a
	programmer to benefit from this HOWTO, but you need to have some
	experience using Linux (or any UNIX system) from an interactive shell,
	preferably Bash or the Bourne shell.  If you are a C shell user who has
	never used a Bourne-like shell, some of the Bash commands may appear
	strange, but this HOWTO should still be valuable to you.
      </para>
    </sect2>

    <sect2 id="sect-disclaimer">
      <title>Disclaimer</title>

      <para>
	No liability for the contents of this document can be accepted.  Use the
	concepts, examples and information at your own risk.  There may be
	errors and inaccuracies in this document that could lead to damage to
	your system.  Proceed with caution, and although damage to your system
	is highly unlikely, the author(s) do not take any responsibility for
	damage or loss caused by errors in this document.  All copyrights are
	held by their by their respective owners, unless specifically noted
	otherwise.  Use of a term in this document should not be regarded as
	affecting the validity of any trademark or service mark.  Naming of
	particular products or brands should not be seen as endorsements.
      </para>
    </sect2>

    <sect2 id="sect-credits">
      <title>Credits and Contributors</title>

      <para>
	This document is based on an earlier version written by Mike G.  The
	following people contributed to this document in one form or another:
      </para>

      <!-- Please scramble addresses; help prevent spam/email harvesting -->
      <simplelist type="inline">
	<member>Nathan Hurst</member>
	<member>Jon Abbott</member>
	<member>Felix Hudson</member>
	<member>Kees van den Broek</member>
	<member>Andreas Beck</member>
      </simplelist>
    </sect2>

    <sect2 id="sect-feedback">
      <title>Feedback</title>

      <para>
	Feedback is welcome. Send your comments to the author.
      </para>
    </sect2>

    <sect2 id="sect-translations">
      <title>Translations</title>

      <para>
	There are currently no translations of this document into other
	languages. If you would like to provide one, please contact the
	author.
      </para>

      <!--
      <itemizedlist>
        <listitem>
          <para>
	    <ulink url="http://tldp.org/">French Translation</ulink> provided by
	    INDIVIDUAL <email>someone (at) somewhere.fr</email>.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    <ulink url="http://tlpd.org/">German Translation</ulink>
	    provided by INDIVIDUAL <email>someone (at) somewhere.de</email>.
	  </para>
	</listitem>
      </itemizedlist>
      -->
    </sect2>
  </sect1>

  <sect1 id="sect-getting-started">
    <title>Getting Started</title>

    <sect2 id="sect-what-you-should-know">
      <title>What You Should Already Know</title>

      <para>
	This HOWTO assumes you know the following things about using Bash
	interactively.
      </para>

      <itemizedlist>
	<listitem>
	  <para>
	    You understand the purpose of the Bash startup files
	    <filename>.bash_profile</filename> and <filename>.bashrc</filename>
	    in your home directory, even if you have not edited them yourself.
	    For more information on Bash startup files refer to the man page for
	    Bash on your system, which is usually found by running the command
	    "<command>man&nbsp;bash</command>" or
	    "<command>man&nbsp;bash&nbsp;|&nbsp;less</command>" for a more
	    navigable man page on Solaris.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    You understand the purpose of the environment variables
	    <envar>HOME</envar> and <envar>PATH</envar>.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    You understand the purpose of basic shell metacharacters, such as
	    "<computeroutput>*</computeroutput>",
	    "<computeroutput>?</computeroutput>", and
	    "<computeroutput>~</computeroutput>".
	  </para>
	</listitem>

	<listitem>
	  <para>
	    You understand how to run commands in the background by appending a
	    "<command>&amp;</command>" to the end of a command.
	  </para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="sect-what-is-bash">
      <title>What and Where is Bash?</title>

      <para>
	Bash is a <firstterm>shell</firstterm>, which is a program that reads
	commands and executes them.  Sometimes, the commands that Bash reads
	come directly from the keyboard as you type them.  When this happens, we
	say that Bash is an <firstterm>interactive</firstterm> shell.  If you've
	ever logged into a UNIX system, then you've used an interactive shell.
	Bash is the default interactive shell of the GNU/Linux system (and you
	might also find it installed on commercial UNIX systems).  Sometimes,
	the commands that Bash reads come from a file called a <firstterm>shell
	script</firstterm>.  When this happens, we say that Bash is a
	<firstterm>non-interactive</firstterm> shell.  In this case, Bash reads
	each line of the script file from top to bottom, executing each command
	as if it had been typed on the keyboard.
      </para>

      <para>
	Where is the Bash shell?  On GNU/Linux systems, you'll always find
	Bash in <filename>/bin/bash</filename>.  On commerical UNIX systems, such
	as Solaris or HP-UX, you might find it in the same place, or it might be
	in <filename>/usr/local/bin/bash</filename>.  You rarely need to run Bash
	directly, but you need to know where Bash is located on your system so
	that you can write the very first line of your Bash scripts correctly.
      </para>

      <para>
	Often, you can find where Bash is located on a UNIX system by typing
	"<command>which&nbsp;bash</command>" or
	"<command>type&nbsp;bash</command>" to your interactive shell.  If that
	doesn't work, try this <command>find</command> command (but beware that
	it may take a while to complete):
      </para>

      <blockquote>
        <para>
	  <computeroutput>find / -type f -name bash 2&gt;/dev/null</computeroutput>
	</para>
      </blockquote>

      <para>
	If you are running the C shell (csh), you might find Bash by typing
	"<command>whereis&nbsp;bash</command>".
      </para>

      <para>
	If that doesn't work, ask your system administrator or local guru for
	help.  It's possible that you do not have Bash installed on your system.
	If this is the case, you'll have to download the source code for Bash,
	build it, and install it.  If you've never done those things, ask your
	system administrator or local guru for help.  It's not hard to do.
      </para>
    </sect2>

    <sect2 id="sect-simple-scripts">
      <title>Writing a Simple Bash Script</title>

      <para>
	Let's start with a simple Bash script and work up to more complex ones
	later.  Just about the simplest program you can write in any programming
	language is a <emphasis>Hello World</emphasis> program, which is a
	program that simply outputs the text "Hello world".  <xref
	linkend="ex-hello-script"/> shows a Bash script to do that.
      </para>

      <para>
	<blockquote>
	  <example id="ex-hello-script">
	    <title>A Simple <emphasis>Hello World</emphasis> Script</title>
	    <programlisting>
#!/bin/bash
echo Hello world
	    </programlisting>
	  </example>
	</blockquote>
      </para>

      <para>
	<xref linkend="ex-hello-script"/> shows a very simple two-line Bash script.
	Create this script by typing those two lines into a file using your
	favorite text editor.  The name of the file can be anything you choose,
	but you should <emphasis>not</emphasis> name the file
	<filename>test</filename>, because there is a built-in
	<command>test</command> command in almost
	every shell, and it's too easy to accidentally run the built-in
	<command>test</command> command instead
	of your own script.  I suggest that you name this script
	<filename>hello</filename>.
      </para>

      <para>
	Be careful to type the script exactly as you see it in <xref
	linkend="ex-hello-script"/>.  If you misspell a word or mistype the
	first line, the script may not work.  One common mistake is to put a
	space somewhere on the first line.  There should be no spaces anywhere
	on the first line.  Another common mistake is to put one or more blank
	lines above the line containing
	"<computeroutput>#!/bin/bash</computeroutput>".  That line
	<emphasis>must</emphasis> be the very first line of the script.
      </para>
    </sect2>

    <sect2 id="sect-running-hello">
      <title>Running the <emphasis>Hello World</emphasis> Script</title>

      <para>
	Once you've created your <emphasis>Hello World</emphasis> script, you can
	execute it in a variety of ways.  Let's assume that you named the script
	<filename>hello</filename>, and it exists in your current working
	directory.  <xref linkend="ex-running-hello"/> shows how to execute the
	script.  In this example, the interactive shell's prompt is shown as
	"<computeroutput>bash$</computeroutput>".  Your shell's prompt might look
	different, but that's OK.
      </para>

      <para>
	<blockquote>
	  <example id="ex-running-hello">
	    <title>How to Run a Bash Script</title>
	    <screen>
bash$ <command>bash hello</command>
Hello world
	    </screen>
	  </example>
	</blockquote>
      </para>

      <para>
	When you type "<computeroutput>bash hello</computeroutput>" as shown in
	<xref linkend="ex-running-hello"/>, if you get an error message that says
	"<computeroutput>command not found</computeroutput>" (or something
	similar) then either you don't have Bash installed on your system or it is
	installed in a directory that is not listed in the value of your
	<envar>PATH</envar> environment variable.  If you get an error message
	that says "<computeroutput>No such file or directory</computeroutput>",
	then your current working directory is probably not the one containing the
	script you just created.
      </para>

      <para>
	The command "<command>bash&nbsp;hello</command>" starts a
	non-interactive Bash shell and passes it one argument: the name of the
	file containing the script to execute.  While the script is running,
	there are actually <emphasis>two</emphasis> shells running!  One is the
	interactive Bash shell which displays the
	"<computeroutput>bash$</computeroutput>" prompt and executes the command
	"<command>bash&nbsp;hello</command>".  The other is the non-interactive
	Bash shell that you manually started to execute the script.  The
	interactive shell isn't doing anything while the script is running
	&mdash; it's merely waiting for the non-interactive shell to terminate.
	In <xref linkend="ex-running-hello"/>, the interactive shell is Bash,
	but you don't have to use Bash as your interactive shell to run a Bash
	script.  The command shown in <xref linkend="ex-running-hello"/> will
	work no matter which interactive shell you use.
      </para>

      <para>
	It's a bit of a hassle to run Bash scripts this way.  It would be
	simpler if you could just type the name of your script without the
	leading "<computeroutput>bash</computeroutput>" to make the operating
	system automatically start a new Bash shell to execute your script.
	That way, the script can be run just like any other program.  To allow
	your script to be run without having to type the leading
	"<computeroutput>bash</computeroutput>", you must do two things:
      </para>

      <orderedlist>
	<listitem>
	  <para>
	    Change the permissions on the script to allow you to execute it.
	    This can be done with the command
	    "<command>chmod&nbsp;u+x&nbsp;hello</command>".  You don't have to
	    grant execute permission just to yourself.  The command
	    "<command>chmod&nbsp;ugo+x&nbsp;hello</command>" allows everyone to
	    execute your script.  See the man page for the
	    <command>chmod</command> command for more information.
	  </para>
	</listitem>

	<listitem id="item-dir-path">
	  <para>
	    Make sure that the directory containing the script is one of the
	    directories listed in the value of your <envar>PATH</envar>
	    environment variable.
	  </para>
	</listitem>
      </orderedlist>

      <para>
	A good way to satisfy the requirement in item #<xref
	linkend="item-dir-path"/> above is to do this:
      </para>

      <orderedlist>
	<listitem>
	  <para>
	  Create a directory named "<filename>bin</filename>" under your home
	  directory.  You can do this with the command
	  "<command>mkdir&nbsp;$HOME/bin</command>".
	  </para>
	</listitem>

	<listitem>
	  <para>
	    Move the script to that directory.  You can do this with the command
	    "<command>mv&nbsp;hello&nbsp;$HOME/bin</command>".
	  </para>
	</listitem>

	<listitem>
	  <para>
	    List the full pathname of that directory in the value of your
	    <envar>PATH</envar> environment variable (We cover variables in more
	    detail in <xref linkend="sect-variables"/>).  You can do this by
	    putting the following line into your interactive Bash startup script
	    (which is the file <filename>.bashrc</filename> in your home
	    directory):

	    <blockquote>
	      <para>
		<computeroutput>PATH="$HOME/bin:$PATH"</computeroutput>
	      </para>
	    </blockquote>
	  </para>
	</listitem>

	<listitem>
	  <para>
	    Terminate your shell, and start a new one.  You have to do this
	    because the changes to your <filename>.bashrc</filename> file only
	    take effect in shells started after you save the changes.
	  </para>
	</listitem>
      </orderedlist>

      <para>
	Lastly, if you don't want to permanently alter your <envar>PATH</envar>
	environment variable (as shown above), you can run a Bash script in your
	current working directory by typing "<command>./scriptname</command>".
	If you want to run your scripts in this fashion, you still have to make
	the script executable using the <command>chmod</command> command shown
	above.  <xref linkend="ex-running-hello2"/> shows how you can run your
	<filename>hello</filename> script if you have made the script
	executable.
      </para>

      <para>
        <blockquote>
	  <example id="ex-running-hello2">
	    <title>Other Ways to Run a Bash Script</title>
	    <screen>
bash$ <command>chmod u+x hello</command>
bash$ <command>./hello</command>
Hello world
bash$ <command>mkdir $HOME/bin</command>
bash$ <command>mv hello $HOME/bin</command>
bash$ <command>PATH="$HOME/bin:$PATH"</command>
bash$ <command>hello</command>
Hello world
	    </screen>
	  </example>
	</blockquote>
      </para>

      <para>
	<xref linkend="ex-running-hello2"/> shows both the
	"<command>./hello</command>" form of the command and the
	"<command>hello</command>" form of the command.  The latter only works
	if <filename>hello</filename> is located in a directory that is listed
	in the value of your <envar>PATH</envar> environment variable.  In the
	above example, the value of <envar>PATH</envar> is changed interactively
	so that it contains the pathname of the <filename>bin</filename>
	directory under your home directory, but to make that change permanent,
	you should edit your <filename>.bashrc</filename> as described above and
	restart your shell.
      </para>
    </sect2>

    <sect2 id="sect-understanding-hello">
      <title>Understanding the <emphasis>Hello World</emphasis> Script</title>

      <para>
	Let's understand how the script shown in <xref linkend="ex-hello-script"/>
	works.  It's just two lines long, but both lines are significant.  Neither
	line can be left out.  The first line
	(<computeroutput>#!/bin/bash</computeroutput>) tells the operating system
	which shell to spawn to execute this script.  Unlike programs written in
	compiled languages, such as C, Pascal, or C++, a Bash script is
	<firstterm>interpreted</firstterm>, which means that some other program
	(the <firstterm>interpreter</firstterm>) must read the script and execute
	the commands in the script.  Bash is the interpreter for a Bash script.  A
	good analogy is to think of a chef cooking a meal by reading a recipe.  In
	this case, your script is the recipe, and Bash is the chef.
      </para>

      <para>
	The first line of your script must specify the full pathname of the Bash
	shell immediately after the characters
	"<computeroutput>#!</computeroutput>".  If your Bash shell is installed
	somewhere other than <filename>/bin/bash</filename>, then you must know
	where it is installed and write the first line of your script accordingly.
	If you are using Linux, then Bash is always installed in
	<filename>/bin/bash</filename>.  The first line in a shell script is
	sometimes called the <firstterm>shebang</firstterm> line.  This term is
	derived from the use of the word "bang" to refer to an exclaimation mark
	and the fact that the first line of a shell script names a shell.
      </para>

      <para>
	The second line of the script in <xref linkend="ex-hello-script"/> is an
	<command>echo</command> command.  You typically use this command in an
	interactive shell to view the value of variables (we'll cover variables
	in <xref linkend="sect-variables"/>).  In a Bash script, the
	<command>echo</command> command is the general purpose mechanism for
	producing output.  It simply outputs its arguments to the terminal on
	which the script is running.  A single space is output betwen each
	argument, and a newline character is appended.
      </para>

      <para>
	In general, Bash executes the commands in a script from top to bottom,
	executing each command as if it had been typed into an interactive
	shell.  You can put any command in a Bash script that you would normally
	type to an interactive shell, and it will work the same way (see <xref
	linkend="sect-interactive-vs-noninteractive"/> for a short list of
	exceptions to this rule).  But what about that &shebang; line
	(<computeroutput>#!/bin/bash</computeroutput>)?  What happens when Bash
	reads and executes that line?
      </para>

      <para>
	The answer is: nothing.  The text between a
	"<computeroutput>#</computeroutput>" character and the end of the same
	line is a <firstterm>comment</firstterm>.  A comment is completely ignored
	by Bash.  You should use comments to make your script more readable
	by including information that helps the reader understand your script.
	We cover comments in more detail in <xref linkend="sect-comments"/>.
      </para>

      <para>
	Since the "<computeroutput>#!/bin/bash</computeroutput>" line is ignored
	by Bash, why can't you leave it out?  Although it is ignored by Bash, it
	is not ignored by the operating system, which uses the first line of the
	script to determine which shell to spawn to interpret the script.  Thus,
	the first line of the Bash script shown in <xref
	linkend="ex-hello-script"/> cannot be omitted, even though it is
	ignored by Bash.
      </para>

      <para>
	After Bash has executed the command on the last line of the script, Bash
	terminates, thus terminating your script.  Later, we'll see how you can
	control when and how your script terminates.
      </para>
    
      <para>
	There is one situation where the &shebang; line isn't needed.  If you
	run your script by explicitly invoking Bash, as shown in <xref
	linkend="ex-running-hello"/>, then a &shebang; line isn't needed.
	However, you should always include a &shebang; line in your scripts,
	because you never know when you'll want to invoke the script like a
	regular command.  Additionally, the &shebang; line acts to document the
	kind of script for human readers.
      </para>
    
    </sect2>

    <sect2 id="sect-interactive-vs-noninteractive">
      <title>Interactive vs. Non-Interactive Shells</title>

      <para>
	Before we move on to a more advanced Bash script, we should cover the few
	situations where the commands that you type into a Bash script work
	differently than the same commands typed into an interactive Bash shell.
	This is not a long list, but it is important to remember the
	following differences.
      </para>

      <orderedlist>
	<listitem>
	  <para>
	    If you have aliases defined in your personal
	    <filename>.bashrc</filename> startup file, you cannot use those
	    aliases in a Bash script.  This is a good thing.  Imagine that you
	    could use your own personal aliases within a script.  If you give that
	    script to someone else, then it will malfunction, because the other
	    user doesn't necessarily have the same aliases defined as you.  That
	    is why aliases are ignored by Bash when it executes a script.  Aliases
	    only work in interactive shells.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    In a Bash script, job control commands are not available.
	    Specifically, after launching a background job by appending
	    "<command>&amp;</command>" to a command, you cannot use the
	    <command>bg</command>, <command>fg</command>, and
	    <command>jobs</command> commands to examine and manipulate the
	    background job.  You also cannot use the
	    "<command>kill&nbsp;%JOBID</command>" form of the
	    <command>kill</command> command to kill background jobs.  This is
	    not a great loss, since the job control commands were designed for
	    interactive use, and they don't make much sense in a script.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    In a Bash script, if the <command>exec</command> command fails for
	    any reason, Bash immediately terminates.  This doesn't happen in an
	    interactive shell so that you can try the <command>exec</command>
	    command again.
	  </para>
	</listitem>

	<listitem>
	  <para>
	    In a Bash script, you cannot use the history expansion character
	    ("<computeroutput>!</computeroutput>") to execute previously
	    executed commands.  In fact, all command history functionality is
	    disabled in a script (e.g., the <command>history</command> command
	    is ignored).
	  </para>
	</listitem>
      </orderedlist>
    </sect2>

    <sect2 id="sect-comments">
      <title>Comments</title>

      <para>
	A comment is any text following a "<computeroutput>#</computeroutput>"
	character on the same line, but the "<computeroutput>#</computeroutput>"
	character must be the first character in a word.  Comments are ignored by
	Bash, but they help the person who reads the script to understand it.
	<xref linkend="ex-comments"/> shows a script containing some comments.
	This is also the first script we've seen that contains blank lines.  Bash
	ignores blank lines, so you can use them to make your script more
	readable.
      </para>

      <para>
        <blockquote>
	  <example id="ex-comments">
	    <title>Using Comments</title>
	    <programlisting>
#!/bin/bash
# This script is an example of using comments.
echo Hello world    # This comment shares a line with a command!

# The next line does _not_ contain a comment!
echo Hello#world

  # This is also a comment.  The "#" doesn't have to be
  # in the leftmost column.  Compare the next echo
  # command with the previous echo command.  One little
  # space can make a big difference!
echo Hello #world
	    </programlisting>
	  </example>
	</blockquote>
      </para>

      <para>
	The first line in the script shown in <xref linkend="ex-comments"/> is the
	classic shebang line, described in <xref
	linkend="sect-understanding-hello"/>.  The comments should be fairly easy
	to see.  The line that reads
	"<computeroutput>echo Hello#world</computeroutput>" contains a
	"<computeroutput>#</computeroutput>" character, but there is
	<emphasis>no</emphasis> comment on that line, because the
	"<computeroutput>#</computeroutput>" does not occur at the beginning of a
	word.  The line that reads
	"<computeroutput>echo Hello #world</computeroutput>" contains a
	comment, because the "<computeroutput>#</computeroutput>" character occurs
	at the beginning of a word.  As you can see from the output of this
	script, that line outputs only the text
	"<computeroutput>Hello</computeroutput>".  When the above script executes,
	it produces this output:
      </para>

      <para>
        <blockquote>
	  <screen>
Hello world
Hello#world
Hello
	  </screen>
	</blockquote>
      </para>

      <para>
	Some people think that writing comments in a script is a waste of time.
	Professional software engineers know this is not true.  Software is hard
	to understand if you are not the author.  Even if you are the author, it
	can be hard to understand long afterwards, when it isn't fresh in your
	mind.  20% to 50% of the lines in your scripts should be comments.
      </para>
    </sect2>
  </sect1>

  <sect1 id="sect-quotes">
    <title>Using Quotes</title>

    <para>
      It is virtually impossible to write a Bash script without using quotes of
      one form or another.  In a Bash script, the quote characters are:
    </para>

    <itemizedlist>
      <listitem>
	<para>
	  <computeroutput>"</computeroutput>    (double quote)
	</para>
      </listitem>
      <listitem>
	<para>
	  <computeroutput>'</computeroutput>    (single quote)
	</para>
      </listitem>
      <listitem>
	<para>
	  <computeroutput>`</computeroutput>    (backquote)
	</para>
      </listitem>
      <listitem>
	<para>
	  <computeroutput>\</computeroutput>    (backslash)
	</para>
      </listitem>
    </itemizedlist>

    <para>
      Let's look at each one in turn.
    </para>

    <sect2 id="sect-double-quote">
      <title>Double Quotes</title>

      <para>
	The double quote (<computeroutput>"</computeroutput>) character is the
	simplest of the quoting characters.  It is most commonly used to group
	space-separated words together so that Bash treats them as if they were
	one word.  For instance, if you need to refer to a file that has spaces in
	its name, you can use double quotes, as follows:
      </para>

      <para>
        <blockquote>
	  <programlisting>
cat "meeting agenda.txt"
	  </programlisting>
	</blockquote>
      </para>

      <para>
	In the above command, the <command>cat</command> program will be passed
	a single filename, <computeroutput>meeting agenda.txt</computeroutput>.
	Had the double quotes been omitted, the <command>cat</command> command
	would have been passed two filenames, <filename>meeting</filename> and
	<filename>agenda.txt</filename>.  It's important to understand that the
	<command>cat</command> program receives this single argument:
      </para>

      <blockquote>
        <para>
	  <computeroutput>
meeting agenda.txt
	  </computeroutput>
	</para>
      </blockquote>

      <para>
	Notice that there are no double quotes in the argument that
	<command>cat</command> receives, but there are double quotes in the
	command.  Quote characters are <firstterm>metacharacters</firstterm>,
	which means they are removed by Bash before the command is executed.
	Even though metacharacters are removed, they are not ignored by Bash.
	In the above <command>cat</command> command, the double quotes change
	how Bash passes the arguments to the program, even though the
	<command>cat</command> program never sees the double quotes!
      </para>

      <para>
	Double quotes (and their cousins, single quotes and backquotes) must occur
	in pairs within a command.  Unfortunately, if you accidentally use an odd
	number of double quotes in a command, Bash will not report an error.  This
	happens because you can use double quotes to group words that span a
	newline character.  Try this command in your interactive shell:
      </para>

      <para>
        <blockquote>
	  <programlisting>
echo "This output occupies
two lines"
	  </programlisting>
	</blockquote>
      </para>

      <para>
	When you press the <keysym>ENTER</keysym> key after typing the first line
	of that command, your interactive shell doesn't execute the command.
	Instead, it notices that you have not typed a closing double quote, and
	prompts you to continue entering the command.  Only when a complete
	command &mdash; with a balanced set of double quotes &mdash; has been
	entered, will pressing the <keysym>ENTER</keysym> key execute the command.
	You can write the above command in a shell script too, and it will behave
	the same way.
      </para>

      <para>
	When writing a script, one common mistake is to leave out a closing quote.
	As a result, you end up quoting the remainder of the script --
	perhaps dozens or hundreds of lines of code!  Bash detects the error only
	when it reaches the end of the script and fails to find the matching
	quote.  The error message will look like this:
      </para>

      <para>
        <blockquote>
	  <screen>
scriptname: line 3: unexpected EOF while looking for matching `"'
	  </screen>
	</blockquote>
      </para>

      <para>
	The line number indicates the line on which the opening quote appears, so
	you won't have much trouble locating your mistake.
      </para>

      <para>
	Double quotes are also used to prevent Bash from giving special meaning to
	certain metacharacters.  If you want your script to output an asterisk,
	you might attempt to do it with this command:
      </para>

      <para>
        <blockquote>
	  <programlisting>
echo *
	  </programlisting>
	</blockquote>
      </para>

      <para>
	But the above command outputs the names of all files and directories in
	the script's current working directory, which is not what you intended.
	This happens because the asterisk is a Bash wildcard metacharacter, and
	Bash replaces each word containing an asterisk with a list of matching file
	and directory names before executing the command.  You want Bash to treat
	the asterisk as if it were just an ordinary character &mdash; not a
	metacharacter.  To do this, you use double quotes to
	<firstterm>escape</firstterm> (or <firstterm>quote</firstterm>) the
	asterisk as follows:
      </para>

      <para>
	<blockquote>
	  <programlisting>
echo "*"
	  </programlisting>
	</blockquote>
      </para>

      <para>
	From now on, we'll use the more technical term
	<firstterm>escape</firstterm> instead of <firstterm>quote</firstterm> to
	mean using one metacharacter to remove the special meaning of another
	metacharacter.  Let's be clear exactly which metacharacters double quotes
	escape.  Double quotes escape the following Bash metacharacters.
      </para>

      <itemizedlist>
	<listitem>
	  <para>
	    Wildcard characters: <computeroutput>*</computeroutput>,
	    <computeroutput>?</computeroutput>,
	    <computeroutput>[</computeroutput>...<computeroutput>]</computeroutput>
	  </para>
	</listitem>

	<listitem>
	  <para>
	    The home directory character: <computeroutput>~</computeroutput>
	  </para>
	</listitem>

	<listitem>
	  <para>
	    Single quotes: <computeroutput>'</computeroutput>...<computeroutput>'</computeroutput>
	  </para>
	</listitem>

	<listitem>
	  <para>
	    The background job creation character: <computeroutput>&amp;</computeroutput>
	  </para>
	</listitem>

	<listitem>
	  <para>
	     I/O Redirection characters: <computeroutput>&gt;</computeroutput>,
	     <computeroutput>&lt;</computeroutput>,
	     <computeroutput>&gt;&gt;</computeroutput>,
	     <computeroutput>&lt;&lt;</computeroutput>,
	     <computeroutput>&lt;&lt;&lt;</computeroutput>,
	     <computeroutput>&gt;&amp;</computeroutput>, and
	     <computeroutput>|</computeroutput>
	  </para>
	</listitem>
      </itemizedlist>

      <para>
	From this list, you can see that the double quote metacharacter does not
	escape itself.  What if you want to output some text surrounded by double
	quotes from a Bash script?  In other words, how would you write a script so
	that the output of the script includes double quote characters?  A command
	of this form doesn't work:
      </para>

      <para>
	<blockquote>
	  <programlisting>
echo Now type "start-backup".
	  </programlisting>
	</blockquote>
      </para>

      <para>
	Try the above command in an interactive Bash shell.  The double quotes
	do not appear, because Bash removes them before executing the
	<command>echo</command> command.  Instead, you must escape the double
	quotes.  That is, you must make Bash treat the double quote characters
	as if they are ordinary characters and not metacharacters.  You cannot
	use double quotes to escape the double quotes, like this:
      </para>

      <para>
        <blockquote>
	  <programlisting>
echo Now type ""start-backup"".
	  </programlisting>
	</blockquote>
      </para>

      <para>
	The double quotes in the above command are paired with each other in the
	order they appear.  The two pairs of double quotes each quote an empty
	string.  They are removed by Bash before the <command>echo</command>
	command executes.  Instead, we need a different quote metacharacter.  We
	need to use single quotes.
      </para>
    </sect2>

    <sect2 id="sect-single-quotes">
      <title>Single Quotes</title>

      <para>
	Single quotes are similar to double quotes, but they have a greater power
	to escape other metacharacters.  Other than that one difference, single
	quotes are used just like double quotes.  An advantage to having two
	different quote characters is that you can use one kind of quote character
	to escape the other, as <xref linkend="ex-mixing-quotes"/> shows.
      </para>

      <para>
	<blockquote>
	  <example id="ex-mixing-quotes">
	    <title>Mixing Single and Double Quotes</title>

	    <programlisting>
#!/bin/bash
# This script shows how you can mix single and double
# quotes, using one kind to escape the other kind.

echo "'This text is surrounded by single quotes.'"
echo '"This text is surrounded by double quotes."'
echo "Welcome to Frodo's Place."
	    </programlisting>
	  </example>
	</blockquote>
      </para>

      <para>
	The output of the above script is:
      </para>

      <blockquote>
	<para>
	  <screen>
'This text is surrounded by single quotes.'
"This text is surrounded by double quotes."
Welcome to Frodo's Place.
	  </screen>
	</para>
      </blockquote>

      <para>
	The above example shows that you need two different quote characters so
	that they can be used to quote each other, but there's another important
	difference between double and single quotes.  Single quotes escape more
	metacharacters than double quotes do.  In fact, single quotes escape
	absolutely every metacharacter, except themselves.  <xref
	linkend="ex-quote-differences"/> shows how double quotes and single quotes
	escape metacharacters differently.
      </para>

      <para>
        <blockquote>
          <example id="ex-quote-differences">
            <title>Differences Between Single and Double Quotes</title>
            <programlisting>
#!/bin/bash
echo "My home directory is $HOME"
echo 'My home directory is $HOME'
echo "*"
echo '*'
	    </programlisting>
          </example>
        </blockquote>
      </para>

      <para>
	The output of the above script is:
      </para>

      <para>
        <blockquote>
	  <screen>
My home directory is /home/franl
My home directory is $HOME
*
*
	  </screen>
        </blockquote>
      </para>

      <para>
	As you can see, both single and double quotes escape the
	"<computeroutput>*</computeroutput>" metacharacter, but only single quotes
	are powerful enough to escape the "<computeroutput>$</computeroutput>"
	metacharacter (which is used to expand variables &mdash; we'll cover
	variables in <xref linkend="sect-variables"/>).
      </para>

      <para>
	Which metacharacters do single quotes escape?  The answer is: all of
	them except for single-quotes.  If you try to use a single quote in the
	middle of a single-quoted string, you end up with an odd number of
	single quotes, which is not valid Bash syntax.
      </para>
    </sect2>

    <sect2 id="sect-backquotes">
      <title>Backquotes</title>

      <para>
	The fourth kind of quotes are backquotes:
	<computeroutput>`...`</computeroutput>.  Backquotes have the same quoting
	properties as double quotes, but with one very big difference.  The text
	between a pair of backquotes is <emphasis>executed by your
	shell</emphasis> and is then <emphasis>replaced by the output of that
	execution</emphasis>!  <xref linkend="ex-backquotes"/> shows backquotes
	in action.
      </para>

      <para>
	<blockquote>
	  <example id="ex-backquotes">
	    <title>Using Backquotes</title>
	    <programlisting>
#!/bin/bash
echo The current working directory is: `pwd`
echo The current date and time is: `date`</programlisting>
	  </example>
	</blockquote>
      </para>

      <para>
	The output of the above script is:
      </para>

      <para>
	<blockquote>
	  <screen>
The current working directory is: /home/franl/examples
The current date and time is: Thu Jan 30 20:43:42 EST 2003
	  </screen>
	</blockquote>
      </para>

      <para>
	You can put any valid Bash command inside backquotes.  You can even put
	multiple commands separates by ';' characters inside backquotes.  If you
	find you are writing a long sequence of commands within backquotes, you
	probably should create a separate shell script to contain those commands
	(or you might want to create a shell function, which is an advanced Bash
	scripting topic not covered by this HOWTO).
      </para>
    </sect2>

    <sect2 id="sect-backslash">
      <title>Backslash</title>

      <para>
	The third kind of quoting character is the backslash: <computeroutput>\</computeroutput>.
	The backslash is unlike the other kinds of quoting characters in that it
	does not occur in pairs.  A backslash behaves exactly like the single
	quote, but it only escapes the <emphasis>character immediately following
	the backslash</emphasis>.  <xref linkend="ex-backslash"/> shows an
	example of how to use backslashes:
      </para>

      <para>
	<blockquote>
	  <example id="ex-backslash">
	    <title>Using Backslashes</title>
	    <programlisting>
#!/bin/bash
echo The price of the item is \$15.79
echo Welcome to Frodo\'s Place!
	    </programlisting>
	  </example>
	</blockquote>
      </para>

      <para>
	The output of the above script is:
      </para>

      <para>
	<blockquote>
	  <screen>
The price of the item is $15.79
Welcome to Frodo's Place!
	  </screen>
	</blockquote>
      </para>
    </sect2>
  </sect1>

  <sect1 id="sect-variables">
    <title>Variables</title>

    <para>
      A variable is a name for a place in memory where a shell script can store
      a string of characters.  Those characters can be anything, including
      letters, digits, punctuation, spaces and tabs.  In the following sections,
      we discuss how to assign values to variables and how to access those
      values after they've been assigned.
    </para>

    <sect2 id="sect-using">
      <title>Using Variables</title>

      <para>
	<xref linkend="ex-variable-assignment0"/> shows how to assign a string of
	characters to a variable.
      </para>

      <para>
        <blockquote>
          <example id="ex-variable-assignment0">
            <title>Assigning a String to a Variable</title>
            <programlisting>
CARMODEL=Porsche
            </programlisting>
          </example>
        </blockquote>
      </para>

      <para>
	In the above example, the name of the variable is
	<varname>CARMODEL</varname>, and the string that is stored in the
	variable is <computeroutput>Porsche</computeroutput>.  There must not be
	any spaces around the '<computeroutput>=</computeroutput>' character,
	and the string must be a single word.  If the string contains any
	whitespace (i.e., spaces, TABs, or newlines), then it must quoted, as
	shown in <xref linkend="ex-variable-assignment1"/>.
      </para>

      <para>
	<blockquote>
	  <example id="ex-variable-assignment1">
	    <title>Assigning a String with Whitespace to a Variable</title>
	    <programlisting>
CARMODEL="Mini Cooper"
            </programlisting>
          </example>
	</blockquote>
      </para>

      <para>
	As discussed in previous sections, the quotes cause the string inside
	the quotes to be taken as a single word (as well as escaping various
	shell metacharacters).  If there were no spaces (and no metacharacters
	that needed to be escaped) in the string, we wouldn't have needed the
	quotes, but it's good style to always use quotes when assigning a value
	to a variable.
      </para>

      <para>
	A variable's name must start with a letter or an underscore.  The
	following characters can be letters, digits, or underscores.  It is
	convention to write variable names in all uppercase characters, but
	that's not required.  Here are some valid variable names:
	<computeroutput>FIRST_NAME</computeroutput>,
	<computeroutput>LINE1</computeroutput>, and
	<computeroutput>_FILENAME</computeroutput>.  Here are some invalid
	variable names: <computeroutput>3rd_PARTY</computeroutput>,
	<computeroutput>MY-VAR</computeroutput>, and
	<computeroutput>INTEREST%</computeroutput>.
      </para>

      <para>
	After you assign a string to a variable, you can access that string by
	writing the variable name prefixed with a
	'<computeroutput>$</computeroutput>', as shown in
	<xref linkend="ex-variable-assignment2"/>.  This is called <firstterm>variable
	expansion</firstterm>.
      </para>

      <para>
        <blockquote>
          <example id="ex-variable-assignment2">
            <title>Referencing a Variable's Value</title>
            <programlisting>
echo "The model of the vehicle is: $CARMODEL"
OLDMODEL="$CARMODEL"
            </programlisting>
          </example>
        </blockquote>
      </para>

      <para>
	Notice that double quotes do not escape the meaning of the
	'<computeroutput>$</computeroutput>' metacharacter (but single quote
	will).  If you want the variable expansion to be adjacent to other
	letters or digits, you need to use braces to mark the start and end of
	the variable name, as follows:
      </para>

      <para>
        <blockquote>
	  <programlisting>
echo "There are 5 ${CARMODEL}s for sale."
CARPLURAL="${CARMODEL}s"
	  </programlisting>
	</blockquote>
      </para>

      <para>
	If there had been no braces around the above variable name, the shell
	would have looked for a variable named <varname>CARMODELs</varname>
	instead of <varname>CARMODEL</varname>, and the script would have
	malfunctioned, because there is no variable named
	<varname>CARMODELs</varname>.
      </para>

      <para>
	A common task is to append (or prepend) a string to the current value of
	a variable.  <xref linkend="ex-variable-append"/> shows how to do each.
      </para>

      <para>
        <blockquote>
          <example id="ex-variable-append">
            <title>Appending and Prepending Text to a Variable's Value</title>
            <programlisting>
CUSTOMER_NAME="Fred"
CUSTOMER_NAME="$CUSTOMER_NAME Smith"  # Appends a string.
CUSTOMER_NAME="Mr. $CUSTOMER_NAME"    # Prepends a string.
echo "$CUSTOMER_NAME"                 # Output is: Mr. Fred Smith
            </programlisting>
          </example>
        </blockquote>
      </para>
    </sect2>

    <sect2 id="sect-kinds-of-variables">
      <title>Kinds of Variables</title>

      <para>
	There are two kinds of variables: <firstterm>shell variables</firstterm>
	and <firstterm>environment variables</firstterm>.  Shell variables are
	not inherited by child processes, and environment variables are
	inherited by child processes.  Other than that one difference, they
	behave exactly the same.  Why would you want a variable to be inherited
	by a child process?  It's a convenient way to communicate information to
	a child process.  Additionally, there are several common environment
	variables that many systems define for every user, such as
	<varname>HOME</varname> and <varname>PATH</varname>.  Since those
	are environment variables in the initial login shell, every process
	descended from that shell inherits those variables.
      </para>
    </sect2>

    <sect2 id="sect-builtin-variables">
      <title>Built-in Variables</title>

      <para>
	Bash automatically defines several built-in variables that contain
	useful information.  Whether or not you can assign new values to
	built-in variables depends on the variable.  The Bash manual (<ulink
	url="&bashref;">&bashref;</ulink>) lists them all, but here are a few:
      </para>

      <variablelist>
	<varlistentry>
	  <term><varname>BASH_VERSION</varname></term>
	  <listitem>
	    <para>
	      This variable expands to the current version of the Bash shell.
	      You cannot assign a value to this variable.  This is a shell
	      variable.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>HOSTNAME</varname></term>
	  <listitem>
	    <para>
	      This variable expands to the hostname of the computer on which the
	      Bash shell is executing.  You cannot assign a value to this
	      variable.  This is an environment variable.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>PWD</varname></term>
	  <listitem>
	    <para>
	      This variable expands to the current working directory of the Bash
	      shell (as it was last set by the <command>cd</command> command).
	      You cannot assign a value to this variable.  This is an
	      environment variable.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>HOME</varname></term>
	  <listitem>
	    <para>
	      This variable expands to the pathname of the home directory of the
	      user who is running the shell.  You can assign to this variable to
	      change it temporarilly during a single shell session, but the next
	      time you login, it will be set to its original value.  This is an
	      environment variable.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>
	There are many more built-in variables.  See the Bash man page or the
	Bash Manual (<ulink url="&bashref;">&bashref;</ulink>) for details.
      </para>
    </sect2>
  </sect1>

  <sect1 id="sect-io-redirection">
    <title>Input/Output (I/O) Redirection</title>

    <para>
      It's almost impossible to write a non-trivial Bash script without using
      <firstterm>I/O redirection</firstterm>.  Every UNIX shell, Bash included,
      provides I/O redirection, but the syntax differs between various shells.
      Naturally, we'll cover the Bash syntax.
    </para>

    <sect2 id="sect-stdio-streams">
      <title>The Standard I/O Streams</title>

      <para>
	A running program is called a <firstterm>process</firstterm>.  For
	example, your interactive shell is a process.  When Bash reads a command
	(either from the keyboard or from a script), Bash spawns a new process
	to execute the command.  Suppose Bash reads and executes the command
	"<command>ls</command>".  The new process exists only for the time it
	takes the "<command>ls</command>" program to execute, and then the
	process terminates.  When Bash starts a process to execute a command,
	the process is connected to several <firstterm>I/O streams</firstterm>.
	An I/O stream is like a hose that has one end connected to the process
	and the other end connected to a terminal.  Data flows through an I/O
	stream like water flows through a hose.  The data flows either from the
	process to the terminal (this is how the process produces output) or
	from the terminal to the process (this is how the process reads input
	from the keyboard).
      </para>

      <para>
	When a process first starts, there are always three <firstterm>standard I/O
	streams</firstterm> connected to the process:
      </para>

      <itemizedlist>
	<listitem><para>Standard input (stdin)</para></listitem>
	<listitem><para>Standard output (stdout)</para></listitem>
	<listitem><para>Standard error (stderr)</para></listitem>
      </itemizedlist>

      <para>
	<firstterm>Standard input</firstterm> is the name of the I/O stream through
	which a process reads input from its terminal.  <firstterm>Standard
	output</firstterm> is the name of the I/O stream through which a process
	writes output to its terminal.  <firstterm>Standard error</firstterm> is the
	name of the I/O stream through which a process writes error messages to
	its terminal.  These standard I/O streams are sometimes referred to using
	their shorthand names: <firstterm>stdin</firstterm>,
	<firstterm>stdout</firstterm>, and <firstterm>stderr</firstterm>.
      </para>
    </sect2>

    <sect2>
      <title>Inheritance of I/O Streams</title>

      <para>
	When your Bash script is running, it is a process just like any other,
	so it also has these three standard I/O streams.  The
	<command>echo</command> command writes its output to standard output.
	Standard output is usually connected to the terminal on which the script
	is running, so the output of the <command>echo</command> command
	typically appears on that terminal.  It is possible to
	<firstterm>redirect</firstterm> an I/O stream so that it is not
	connected to the terminal but to a file.  <xref
	linkend="ex-redirect-stdout"/> shows show you can change the
	<filename>hello</filename> script to redirect the standard output of the
	echo command to a file named <filename>xyz</filename>.
      </para>

      <para>
        <blockquote>
	  <example id="ex-redirect-stdout">
	    <title>Redirecting Standard Output</title>

	    <programlisting>
#!/bin/bash
echo Hello world &gt; xyz
	    </programlisting>
	  </example>
	</blockquote>
      </para>

      <para>
	In this example, the "<computeroutput>&gt;</computeroutput>" is a
	metacharacter.  The "<computeroutput>&gt;</computeroutput>" tells Bash
	to temporarilly redirect standard output of the current command from its
	current destination (the terminal) to the specified file for the
	duration of the command.  You can specify any relative or absolute
	pathname after the "<computeroutput>&gt;</computeroutput>".  In this
	example, the output of the
	"<command>echo&nbsp;Hello&nbsp;world</command>" command is redirected to
	the file <filename>xyz</filename> in the current working directory.
      </para>

      <warning>
	<title>Warning!</title>

	<para>
	  If you redirect standard output to a file that already exists, the file
	  is overwritten, destroying the previous contents of the file!  Always be
	  sure that you don't have any valuable data in the file that is going to
	  be overwritten by redirection.
	</para>
      </warning>
    </sect2>
  </sect1>

  <sect1 id="sect-conditionals">
    <title>Conditionals</title>

    <para>
      Like all programming languages, Bash scripts can make decisions based on
      the values of variables and many other aspects of their system
      environment.  A <firstterm>conditional</firstterm> is a statement that
      makes a decision.  A conditional statement causes one or more other
      statements to execute or not depending on the answer to a question.
    </para>

    <sect2 id="sect-exit-status">
      <title>Exit Status</title>

      <para>
	Every command executed by the shell has an <firstterm>exit
	status</firstterm> that is a number between 0 and 255.  The exit status
	indicates the success or failure of the command.  If a command's exit
	status is 0, it was successful, otherwise the non-zero exit status
	indicates which of many different errors occurred.  The exit status of
	the last command that executed is stored in the built-in shell variable
	<varname>$?</varname>.  <xref linkend="ex-exit-status"/> shows some
	examples.
      </para>

      <para>
        <blockquote>
          <example id="ex-exit-status">
            <title>Examining the Exit Status of Commands</title>
            <screen>
bash$ touch newfile
bash$ echo $?
0
bash$ rm newfile   # This command succeeds.
bash$ echo $?
0
bash$ rm newfile   # This command fails: the file doesn't exist anymore.
rm: cannot remove `newfile': No such file or directory
bash$ echo $?
1
bash$ echo $?      # Can you explain this output?
0
            </screen>
          </example>
        </blockquote>
      </para>

      <para>
	Notice the odd behavior of the last <command>echo&nbsp;$?</command>.
	Why does it output "<computeroutput>1</computeroutput>" the first time
	and "<computeroutput>0</computeroutput>" the second time?  The reason is
        that the value of <varname>$?</varname> is always the exit status of the
	<emphasis>last</emphasis> command that executed.  In <xref
        linkend="ex-exit-status"/> (above), the second
	<command>echo&nbsp;$?</command> command outputs a
	<computeroutput>0</computeroutput> because the first
	<command>echo&nbsp;$?</command> command was successful.  It's important
	to remember that <emphasis>any</emphasis> command alters the value of
	<varname>$?</varname>, so you only have one chance to access the value
	stored in <varname>$?</varname>.  A common scripting practice is to
	store the value of <varname>$?</varname> in a shell variable so it can
	be accessed later, as shown in <xref linkend="ex-saving-exit-status"/>.
      </para>

      <para>
        <blockquote>
          <example id="ex-saving-exit-status">
            <title>Saving the Exit Status for Later Use</title>
            <programlisting>
first_command
STATUS=$?
second_command
echo "The first command exitted with status $STATUS."
            </programlisting>
          </example>
        </blockquote>
      </para>
    </sect2>

    <sect2 id="sect-test-command">
      <title>The <command>test</command> Command</title>

      <para>*** UNDER CONSTRUCTION ***</para>
    </sect2>

    <sect2 id="sect-if-statements">
      <title>If Statements</title>

      <para>*** UNDER CONSTRUCTION ***</para>
    </sect2>

    <sect2 id="sect-andand">
      <title>The <computeroutput>&amp;&amp;</computeroutput> Operator</title>

      <para>*** UNDER CONSTRUCTION ***</para>
    </sect2>

    <sect2 id="sect-oror">
      <title>The <computeroutput>||</computeroutput> Operator</title>

      <para>*** UNDER CONSTRUCTION ***</para>
    </sect2>
  </sect1>

  <sect1 id="sect-loops">
    <title>Loops</title>

    <para>*** UNDER CONSTRUCTION ***</para>

    <sect2 id="sect-while-loops">
      <title>While and Until Loops</title>

      <para>*** UNDER CONSTRUCTION ***</para>
    </sect2>

    <sect2 id="sect-for-loops">
      <title>For Loops</title>

      <para>*** UNDER CONSTRUCTION ***</para>
    </sect2>
  </sect1>

  <sect1 id="sect-more-info">
    <title>Where to Get More Information</title>

    <para>*** UNDER CONSTRUCTION ***</para>

    <!--
    o Refer to the man page.
    o Refer to bug/help/announce/developer mailing list (bug-bash@gnu.org).
    o Refer to the #bash channel on the freenode IRC network.
    o Refer to the Advanced Bash Programming Guide.
    -->
  </sect1>

  <sect1 id="sect-copyleft">
    <title>Copyright and License</title>

    <!-- The LDP recommends, but doesn't require, the GFDL. -->
    <para>
    This document, <emphasis>Introduction to Bash Scripting HOWTO</emphasis>,
    is copyrighted (C) 2002 by Francis Litterio.  Permission is granted to copy,
    distribute and/or modify this document under the terms of the GNU Free
    Documentation License, Version 1.1 or any later version published by the
    Free Software Foundation; with no Invariant Sections, with no Front-Cover
    Texts, and with no Back-Cover Texts.  A copy of the license is included in
    the section entitled "GNU Free Documentation License".
    </para>

    <sect2>
      <title>GNU Free Documentation License</title>

      <para>Version 1.1, March 2000</para>

      <blockquote>
	<para>
	Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite
	330, Boston, MA 02111-1307 USA.  Everyone is permitted to copy and
	distribute verbatim copies of this license document, but changing it is
	not allowed.
	</para>
      </blockquote>

      <sect3>
	<title>PREAMBLE</title>

	<para>The purpose of this License is to make a manual, textbook,
	or other written document "free" in the sense of freedom: to assure
	everyone the effective freedom to copy and redistribute it, with or
	without modifying it, either commercially or noncommercially.
	Secondarily, this License preserves for the author and publisher a way
	to get credit for their work, while not being considered responsible for
	modifications made by others.</para>

	<para>This License is a kind of "copyleft", which means that
	  derivative works of the document must themselves be free in the same
	  sense.  It complements the GNU General Public License, which is a
	  copyleft license designed for free software.</para>

	<para>We have designed this License in order to use it for manuals
	  for free software, because free software needs free documentation: a
	  free program should come with manuals providing the same freedoms that
	  the software does.  But this License is not limited to software manuals;
	  it can be used for any textual work, regardless of subject matter or
	  whether it is published as a printed book.  We recommend this License
	  principally for works whose purpose is instruction or reference.</para>
      </sect3>

      <sect3>
	<title>APPLICABILITY AND DEFINITIONS</title>

	<para>This License applies to any manual or other work that
	  contains a notice placed by the copyright holder saying it can be
	  distributed under the terms of this License.  The "Document", below,
	  refers to any such manual or work.  Any member of the public is a
	  licensee, and is addressed as "you".</para>

	<para>A "Modified Version" of the Document means any work
	  containing the Document or a portion of it, either copied verbatim, or
	  with modifications and/or translated into another language.</para>

	<para>A "Secondary Section" is a named appendix or a front-matter
	  section of the Document that deals exclusively with the
	  relationship of the publishers or authors of the Document to the
	  Document's overall subject (or to related matters) and contains
	  nothing that could fall directly within that overall subject.
	  (For example, if the Document is in part a textbook of
	  mathematics, a Secondary Section may not explain any mathematics.)
	  The relationship could be a matter of historical connection with
	  the subject or with related matters, or of legal, commercial,
	  philosophical, ethical or political position regarding
	  them.</para>

	<para>The "Invariant Sections" are certain Secondary Sections
	  whose titles are designated, as being those of Invariant Sections,
	  in the notice that says that the Document is released under this
	  License.</para>

	<para>The "Cover Texts" are certain short passages of text that
	  are listed, as Front-Cover Texts or Back-Cover Texts, in the
	  notice that says that the Document is released under this
	  License.</para>

	<para>A "Transparent" copy of the Document means a
	  machine-readable copy, represented in a format whose specification
	  is available to the general public, whose contents can be viewed
	  and edited directly and straightforwardly with generic text
	  editors or (for images composed of pixels) generic paint programs
	  or (for drawings) some widely available drawing editor, and that
	  is suitable for input to text formatters or for automatic
	  translation to a variety of formats suitable for input to text
	  formatters.  A copy made in an otherwise Transparent file format
	  whose markup has been designed to thwart or discourage subsequent
	  modification by readers is not Transparent.  A copy that is not
	  "Transparent" is called "Opaque".</para>

	<para>Examples of suitable formats for Transparent copies include
	  plain ASCII without markup, Texinfo input format, LaTeX input
	  format, SGML or XML using a publicly available DTD, and
	  standard-conforming simple HTML designed for human modification.
	  Opaque formats include PostScript, PDF, proprietary formats that
	  can be read and edited only by proprietary word processors, SGML
	  or XML for which the DTD and/or processing tools are not generally
	  available, and the machine-generated HTML produced by some word
	  processors for output purposes only.</para>

	<para>The "Title Page" means, for a printed book, the title page
	  itself, plus such following pages as are needed to hold, legibly,
	  the material this License requires to appear in the title page.
	  For works in formats which do not have any title page as such,
	  "Title Page" means the text near the most prominent appearance of
	  the work's title, preceding the beginning of the body of the
	  text.</para>
      </sect3>

      <sect3>
	<title>VERBATIM COPYING</title>

	<para>You may copy and distribute the Document in any medium,
	  either commercially or noncommercially, provided that this
	  License, the copyright notices, and the license notice saying this
	  License applies to the Document are reproduced in all copies, and
	  that you add no other conditions whatsoever to those of this
	  License.  You may not use technical measures to obstruct or
	  control the reading or further copying of the copies you make or
	  distribute.  However, you may accept compensation in exchange for
	  copies.  If you distribute a large enough number of copies you
	  must also follow the conditions in section 3.</para>

	<para>You may also lend copies, under the same conditions stated
	  above, and you may publicly display copies.</para>
      </sect3>

      <sect3>
	<title>COPYING IN QUANTITY</title>

	<para>If you publish printed copies of the Document numbering more
	than 100, and the Document's license notice requires Cover Texts,
	you must enclose the copies in covers that carry, clearly and
	legibly, all these Cover Texts: Front-Cover Texts on the front
	cover, and Back-Cover Texts on the back cover.  Both covers must
	also clearly and legibly identify you as the publisher of these
	copies.  The front cover must present the full title with all
	words of the title equally prominent and visible.  You may add
	other material on the covers in addition.  Copying with changes
	limited to the covers, as long as they preserve the title of the
	Document and satisfy these conditions, can be treated as verbatim
	copying in other respects.</para>

	<para>If the required texts for either cover are too voluminous to
	fit legibly, you should put the first ones listed (as many as fit
	reasonably) on the actual cover, and continue the rest onto
	adjacent pages.</para>

	<para>If you publish or distribute Opaque copies of the Document
	numbering more than 100, you must either include a
	machine-readable Transparent copy along with each Opaque copy, or
	state in or with each Opaque copy a publicly-accessible
	computer-network location containing a complete Transparent copy
	of the Document, free of added material, which the general
	network-using public has access to download anonymously at no
	charge using public-standard network protocols.  If you use the
	latter option, you must take reasonably prudent steps, when you
	begin distribution of Opaque copies in quantity, to ensure that
	this Transparent copy will remain thus accessible at the stated
	location until at least one year after the last time you
	distribute an Opaque copy (directly or through your agents or
	retailers) of that edition to the public.</para>

	<para>It is requested, but not required, that you contact the
	authors of the Document well before redistributing any large
	number of copies, to give them a chance to provide you with an
	updated version of the Document.</para>
      </sect3>

      <sect3>
	<title>MODIFICATIONS</title>

	<para>You may copy and distribute a Modified Version of the
	Document under the conditions of sections 2 and 3 above, provided
	that you release the Modified Version under precisely this
	License, with the Modified Version filling the role of the
	Document, thus licensing distribution and modification of the
	Modified Version to whoever possesses a copy of it.  In addition,
	you must do these things in the Modified Version:</para>

	<orderedlist numeration="upperalpha">
	  <listitem><para>Use in the Title Page
	  (and on the covers, if any) a title distinct from that of the
	  Document, and from those of previous versions (which should, if
	  there were any, be listed in the History section of the
	  Document).  You may use the same title as a previous version if
	  the original publisher of that version gives permission.</para>
	  </listitem>

	  <listitem><para>List on the Title Page,
	  as authors, one or more persons or entities responsible for
	  authorship of the modifications in the Modified Version,
	  together with at least five of the principal authors of the
	  Document (all of its principal authors, if it has less than
	  five).</para>
	  </listitem>

	  <listitem><para>State on the Title page
	  the name of the publisher of the Modified Version, as the
	  publisher.</para>
	  </listitem>

	  <listitem><para>Preserve all the
	  copyright notices of the Document.</para>
	  </listitem>

	  <listitem><para>Add an appropriate
	  copyright notice for your modifications adjacent to the other
	  copyright notices.</para>
	  </listitem>

	  <listitem><para>Include, immediately
	  after the copyright notices, a license notice giving the public
	  permission to use the Modified Version under the terms of this
	  License, in the form shown in the Addendum below.</para>
	  </listitem>

	  <listitem><para>Preserve in that license
	  notice the full lists of Invariant Sections and required Cover
	  Texts given in the Document's license notice.</para>
	  </listitem>

	  <listitem><para>Include an unaltered
	  copy of this License.</para>
	  </listitem>

	  <listitem><para>Preserve the section
	  entitled "History", and its title, and add to it an item stating
	  at least the title, year, new authors, and publisher of the
	  Modified Version as given on the Title Page.  If there is no
	  section entitled "History" in the Document, create one stating
	  the title, year, authors, and publisher of the Document as given
	  on its Title Page, then add an item describing the Modified
	  Version as stated in the previous sentence.</para>
	  </listitem>

	  <listitem><para>Preserve the network
	  location, if any, given in the Document for public access to a
	  Transparent copy of the Document, and likewise the network
	  locations given in the Document for previous versions it was
	  based on.  These may be placed in the "History" section.  You
	  may omit a network location for a work that was published at
	  least four years before the Document itself, or if the original
	  publisher of the version it refers to gives permission.</para>
	  </listitem>

	  <listitem><para>In any section entitled
	  "Acknowledgements" or "Dedications", preserve the section's
	  title, and preserve in the section all the substance and tone of
	  each of the contributor acknowledgements and/or dedications
	  given therein.</para>
	  </listitem>

	  <listitem><para>Preserve all the
	  Invariant Sections of the Document, unaltered in their text and
	  in their titles.  Section numbers or the equivalent are not
	  considered part of the section titles.</para>
	  </listitem>

	  <listitem><para>Delete any section
	  entitled "Endorsements".  Such a section may not be included in
	  the Modified Version.</para>
	  </listitem>

	  <listitem><para>Do not retitle any
	  existing section as "Endorsements" or to conflict in title with
	  any Invariant Section.</para>
	  </listitem>
	</orderedlist>
	<para>If the Modified Version includes new front-matter sections
	or appendices that qualify as Secondary Sections and contain no
	material copied from the Document, you may at your option
	designate some or all of these sections as invariant.  To do this,
	add their titles to the list of Invariant Sections in the Modified
	Version's license notice.  These titles must be distinct from any
	other section titles.</para>

	<para>You may add a section entitled "Endorsements", provided it
	contains nothing but endorsements of your Modified Version by
	various parties--for example, statements of peer review or that
	the text has been approved by an organization as the authoritative
	definition of a standard.</para>

	<para>You may add a passage of up to five words as a Front-Cover
	Text, and a passage of up to 25 words as a Back-Cover Text, to the
	end of the list of Cover Texts in the Modified Version.  Only one
	passage of Front-Cover Text and one of Back-Cover Text may be
	added by (or through arrangements made by) any one entity.  If the
	Document already includes a cover text for the same cover,
	previously added by you or by arrangement made by the same entity
	you are acting on behalf of, you may not add another; but you may
	replace the old one, on explicit permission from the previous
	publisher that added the old one.</para>

	<para>The author(s) and publisher(s) of the Document do not by
	this License give permission to use their names for publicity for
	or to assert or imply endorsement of any Modified Version.</para>
      </sect3>

      <sect3>
	<title>COMBINING DOCUMENTS</title>

	<para>You may combine the Document with other documents released
	under this License, under the terms defined in section 4 above for
	modified versions, provided that you include in the combination
	all of the Invariant Sections of all of the original documents,
	unmodified, and list them all as Invariant Sections of your
	combined work in its license notice.</para>

	<para>The combined work need only contain one copy of this
	License, and multiple identical Invariant Sections may be replaced
	with a single copy.  If there are multiple Invariant Sections with
	the same name but different contents, make the title of each such
	section unique by adding at the end of it, in parentheses, the
	name of the original author or publisher of that section if known,
	or else a unique number.  Make the same adjustment to the section
	titles in the list of Invariant Sections in the license notice of
	the combined work.</para>

	<para>In the combination, you must combine any sections entitled
	"History" in the various original documents, forming one section
	entitled "History"; likewise combine any sections entitled
	"Acknowledgements", and any sections entitled "Dedications".  You
	must delete all sections entitled "Endorsements."</para>
      </sect3>

      <sect3>
	<title>COLLECTIONS OF DOCUMENTS</title>

	<para>You may make a collection consisting of the Document and
	other documents released under this License, and replace the
	individual copies of this License in the various documents with a
	single copy that is included in the collection, provided that you
	follow the rules of this License for verbatim copying of each of
	the documents in all other respects.</para>

	<para>You may extract a single document from such a collection,
	and distribute it individually under this License, provided you
	insert a copy of this License into the extracted document, and
	follow this License in all other respects regarding verbatim
	copying of that document.</para>
      </sect3>

      <sect3>
	<title>AGGREGATION WITH INDEPENDENT WORKS</title>
	<para>A compilation of the Document or its derivatives with other
	separate and independent documents or works, in or on a volume of
	a storage or distribution medium, does not as a whole count as a
	Modified Version of the Document, provided no compilation
	copyright is claimed for the compilation.  Such a compilation is
	called an "aggregate", and this License does not apply to the
	other self-contained works thus compiled with the Document, on
	account of their being thus compiled, if they are not themselves
	derivative works of the Document.</para>

	<para>If the Cover Text requirement of section 3 is applicable to
	these copies of the Document, then if the Document is less than
	one quarter of the entire aggregate, the Document's Cover Texts
	may be placed on covers that surround only the Document within the
	aggregate.  Otherwise they must appear on covers around the whole
	aggregate.</para>
      </sect3>

      <sect3>
	<title>TRANSLATION</title>

	<para>Translation is considered a kind of modification, so you may
	distribute translations of the Document under the terms of section
	4.  Replacing Invariant Sections with translations requires
	special permission from their copyright holders, but you may
	include translations of some or all Invariant Sections in addition
	to the original versions of these Invariant Sections.  You may
	include a translation of this License provided that you also
	include the original English version of this License.  In case of
	a disagreement between the translation and the original English
	version of this License, the original English version will
	prevail.</para>
      </sect3>

      <sect3>
	<title>TERMINATION</title>
	<para>You may not copy, modify, sublicense, or distribute the
	Document except as expressly provided for under this License.  Any
	other attempt to copy, modify, sublicense or distribute the
	Document is void, and will automatically terminate your rights
	under this License.  However, parties who have received copies, or
	rights, from you under this License will not have their licenses
	terminated so long as such parties remain in full
	compliance.</para>
      </sect3>

      <sect3>
	<title>FUTURE REVISIONS OF THIS LICENSE</title>

	<para>The Free Software Foundation may publish new, revised
	versions of the GNU Free Documentation License from time to time.
	Such new versions will be similar in spirit to the present
	version, but may differ in detail to address new problems or
	concerns.  See <ulink
	url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para>

	<para>Each version of the License is given a distinguishing
	version number.  If the Document specifies that a particular
	numbered version of this License "or any later version" applies to
	it, you have the option of following the terms and conditions
	either of that specified version or of any later version that has
	been published (not as a draft) by the Free Software Foundation.
	If the Document does not specify a version number of this License,
	you may choose any version ever published (not as a draft) by the
	Free Software Foundation.</para>
      </sect3>

      <sect3>
	<title>How to use this License for your documents</title>

	<para>To use this License in a document you have written, include
	a copy of the License in the document and put the following
	copyright and license notices just after the title page:</para>

	<blockquote>
	  <para>
	  Copyright (c)  COPYRIGHT-YEAR  YOUR-NAME
	  Permission is granted to copy, distribute and/or modify this document
	  under the terms of the GNU Free Documentation License, Version 1.1
	  or any later version published by the Free Software Foundation;
	  with the Invariant Sections being LIST THEIR TITLES, with the
	  Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
	  A copy of the license is included in the section entitled "GNU
	  Free Documentation License".
	  </para>
	</blockquote>

	<para>If you have no Invariant Sections, write "with no Invariant
	Sections" instead of saying which ones are invariant.  If you have
	no Front-Cover Texts, write "no Front-Cover Texts" instead of
	"Front-Cover Texts being LIST"; likewise for Back-Cover
	Texts.</para>

	<para>If your document contains nontrivial examples of program
	code, we recommend releasing these examples in parallel under your
	choice of free software license, such as the GNU General Public
	License, to permit their use in free software.</para>
      </sect3>
    </sect2>
  </sect1>
</article>

<!-- Local Variables: -->
<!-- mode: docbook-xml -->
<!-- End: -->