path: root/doc/oldbash.texi

\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename bash.info
@settitle GNU Bourne Again SHell
@setchapternewpage odd
@c %**end of header

@ignore
**EXPLANATION OF COMMENTS IN FILE**
All comments, which start with @c, are by Julie Sussman
(jems@zurich.ai.mit.edu).
If a comment has someone else's name or initials in it, it is still
by me (Julie), but is a note on something that person told me.
@end ignore

@ignore
**TO DO**
Update all nodes
Update all menus for Info.  They don't match current manual.
Fix the cross references -- too many have abbreviated node names.
Fix/redo/complete the indexing.
  Separate index for commands, vars, etc. (separate from concepts)
Use group/end group around examples to prevent bad page breaks.
@end ignore

@ignore
JEFF KELLEM'S MISC. COMMENTS
* add a glossary
* below are some additions/changes that are being considered for final
  1.06 release -- there are probably others; these are off the top of my
  head 
  * check on `-' arg to cd to swap $PWD and $OLDPWD
  * `+' option to `set' to list all var names w/o their values (`set +')
  * `set --' will unset the positional params if no other args are given ?
  * -r option to read
  * -p flag of jobs to list PIDs only (posix.2a)
  * job_spec args to jobs (posix.2a)
  * shell error msgs may now have `bash: ' as a prefix  (will have to chk
    if Brian decided to bless it)
@end ignore

@c DON'T RUN FINALOUT YET UNTIL FINAL STAGES
@ignore
@iftex
@finalout
@end iftex
@end ignore

@ifinfo
This file documents the GNU Bourne Again SHell.

Copyright @copyright{} 1989, 1990 Free Software Foundation, Inc.
@end ifinfo

@titlepage
@sp 10
@center @titlefont{Bourne Again SHell}
@center Unproofed Draft
@sp 10
@center Brian Fox, Diane Barlow Close,
@center Julie Sussman, Chet Ramey,
@center Richard Stallman
@center @today{}

@page
This document describes GNU Bash, a Bourne shell compatible command
language interpreter which executes commands read from standard input
or from a file.

Published by the Free Software Foundation @*
675 Massachusetts Avenue, @*
Cambridge, MA 02139 USA

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.

@vskip 0pt plus 1filll
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
@end titlepage

@node Top, Thanks, (dir), (dir)
@unnumbered Preface

This manual introduces the GNU Bourne Again SHell (BASH) and explains
its role in the operating system.  This manual does not explain the
fundamentals of using operating system commands such as @code{ls},
@code{cd}, and others, nor does it explain how to log into your system.

BASH is a command language interpreter that executes commands read from
the standard input or from a file.  BASH is compatible with the Bourne
shell (@code{sh}), and also incorporates useful features of the Korn
shell (@code{ksh}) and the C shell (@code{csh}).  The intention is that
BASH be a superset of the desirable features found in other shells.

BASH is POSIX compliant.

If you read this manual sequentially, you'll find it leads you through
the concepts of a shell from its simple beginnings to more complex
shell features.  If you are familiar with your machine's operating
system and have some experience with shells, then this manual makes a
handy reference.
@c A nice goal would be to make the above paragraph come true

@menu
* Thanks::           Acknowledgement of those who made it possible.

* License::          GNU licensing information.

* Introduction::     Introduction to shells.

* I/O::              Redirection.  Pipes.

* Line::             Command line syntax.

* File Names::   How the shell interprets your input before
                     it arrives at other commands.  Wildcard 
                     characters.

* Job Control::      Controlling when commands are run.

* Editing::          Editing lines that you type, and how to
                     get at previously typed lines.

* History::          History substitution.

* Aliases::          Substitution of command words.

* Functions::        How to generalize a group of related
                     commands.

* Programming::      An overview of programming using BASH.

* Scripts::          Writing shell programs with BASH.

* Variables::        Shell variables.

* Environment::      Discovering your shell's environment.

* Conditionals::     Programming using conditional statements.

* Looping::          Programming using looping statements.

* Built-in::         Description of commands that are built into
                     the shell.

* Install::          Installing BASH.

* Invoke::           Invoking BASH.  Details on signal control in BASH.
                     Customizing BASH prompts.

* Start-up::         A sample start-up files for BASH.

* Advanced Scripts:: Samples of writing more advanced shell scripts.

* Tools::            Related and useful operating system commands.

* Authors::          Who's responsible for all this.

* Concept Index::    Index of shell concepts.

@end menu

@node Thanks,  , Top, Top
@unnumberedsec Acknowledgements

Many people need to be thanked for their assistance in producing this
manual.  Brian and Diane would like to thank Chet Ramey for his
production of the BASH man page.  It made the job of writing this
manual infinitely easier.

Robert Chassell gave helpful comments on the drafts of this manual. 
Allan Painter contributed beginning-user examples.  Bennett Todd
and Bill Trost contributed very useful samples of shell scripts.  Many
thanks to all those who submitted scripts for consideration.  It
was difficult to choose only two for inclusion in this manual; all were
of very high quality and usefulness.

@node License, Introduction, Top, Top
@unnumbered License

@node Introduction, Typing Commands, License, Top
@chapter Introduction to Shells
@c This chapter needs to be rewritten/replaced
@ignore
Some topics:
 built-in cmds, other cmds, use in examples and doc in manual
@end ignore

The shell is a program that the operating system automatically starts
up when you log in, so that the system can understand your commands. 
@cindex shell, what is a
@cindex BASH, what is
@cindex Bourne Again SHell, what is

Here is a brief listing of some of the things that the Bourne Again SHell
(BASH) provides:

@itemize @bullet
@item
a built-in language for writing shell programs

@item
compatibility with shell programs written for the Bourne shell

@item
Emacs and vi style command editing

@item
process and job control

@item
command aliases

@item
shell @emph{functions}

@item
completion of file names, user names, and variable names
@c  "and other types of completion"  ?? such as what??
@end itemize

@menu
* Interpretation::   The Shell as a Command Interpreter.

* Language::         The Shell as a Programming Language.

@end menu

@node Interpretation, Language, Introduction, Introduction
@section The Shell as a Command Interpreter

When you log on to your system a shell is automatically started for you. 
Think of the shell as a layer of software between you and the operating
system's internal workings, as shown below:
@cindex command interpreter
@cindex shell, as a command interpreter

@example
@var{commands} (@r{typed by you}) <------> @var{shell} <-------> @var{operating system}
@end example

@noindent
The shell interacts with you, the user, to interpret your commands and
tell the operating system to take appropriate action.  The shell stays
with you until you log out.

The input and execution of a simple shell command involves the following
steps:

@enumerate
@item
The shell displays a prompt (@samp{bash$}, unless you have
specified a different prompt) and waits for you to type a command.

@item
You type a command line, ending with a carriage return.

@item
The shell analyzes that command line, and extracts the command name
and arguments.  Here is a template for a simple shell command, with
the optional parts between square brackets, @samp{@r{[}@dots{}@r{]}}:

@example
@var{command} @r{[}@var{arguments}@r{]} @r{[}&@r{]} @key{RET}@refill
@end example

@noindent
A simple command line consists of a sequence of words
separated by blanks (a blank is a space or a tab).  The first word of
the command line specifies the name of the command to be executed, and the
remaining words are passed as arguments to that command.

@item
The shell tries to locate the specified command as a program in the
directories specified in your path.

@item
If the shell can't find the command program you requested, it gives you
an error message and provides a new prompt.

If the shell is successful in locating the requested program, it tells
the operating system to execute that program using the rest of the
command line as arguments for that program.

@item
If you did not end your command line with @samp{&}, the program is run
in the @dfn{foreground}.  When the program is
finished, the operating system returns control to the shell and the
shell gives you another prompt.

If you ended your command line with @samp{&}, the program is run in the
@dfn{background}.While the program is executing the shell waits.
The shell doesn't wait for the operating system to
finish running the program; rather, the shell immediately gives you a prompt so
you can continue typing commands.  (Running a program in the background
is useful if the program takes a long time to execute and doesn't need
supervision.)

@item
At the new prompt you type in the next command line to be processed
and run.  These steps are repeated until you log out.
@end enumerate

@node Language,  , Interpretation, Introduction
@section The Shell as a Programming Language

BASH has its own built-in, interpreted programming language.
@cindex shell, as a programming language
@cindex programming language, features

Some of the programming features available to you are:

@itemize @bullet
@item
storage of values in variables

@item
conditional execution statements

@item
user-defined functions

@item
looping and other ways of executing commands repeatedly
@end itemize

@node Notation
@section Notation

To indicate special keys or key combinations, this documentation
uses the following notations:
@c also explain RET, CTL, DEL, etc.

@table @kbd
@item C-k
The text @kbd{C-k} is read as ``Control-K'' and describes the character
produced when you hold the Control key (@key{CTL}) down and strike the @kbd{k} key.

@item M-k
The text @kbd{M-k} is read as ``Meta-K'' and describes the character
produced in either of two ways:
@itemize @bullet
Either hold the @key{META} key (if you have one) down and strike the @kbd{k} key

or type @key{ESC} @i{first} and then type @kbd{k}.
@end itemize
Either process is known as @dfn{metafying} the @kbd{k} key.

@item M-C-k
The text @kbd{M-C-k} is read as ``Meta-Control-k'' and describes the
character produced by metafying @kbd{C-k} (see @kbd{C-k} and @kbd{M-k}
just above).
@end table

@node  Typing Commands, I/O, Introduction, Top
@chapter Typing Commands

@c !! forgot to cover case sensitivity!

This chapter deals with the mechanics of typing commands.

Normally, to give a command you type a line and end it with a newline
character (usually referred to as @key{RET} in this documentation).

In the following example, BASH displayed its prompt (@samp{bash$ }),
we typed the command @samp{who} (terminated by a @key{RET}, which is
not explictly shown in the example), the output of @code{who} (a listing
of users logged into the system) was displayed, and BASH displayed
another prompt.

@example
bash$ who
glassw   ttyq0   Apr 15 15:09   (worker-8)
glassw   ttyq1   Apr 15 20:50   (worker-7)
cqc      ttyq2   Apr 15 18:15   (worker-9)
zvona    ttyq5   Apr 15 14:13   (nico)
painter  ttyd0   Apr 15 21:00
stf      ttyh4   Apr 15 11:58
sandiway ttyh9   Apr 13 23:05
pwu      ttyhc   Apr 15 15:19
bash$
@end example

The following sections explain more about typing commands, including how
to correct mistakes as you type a command and how to type a command that
is too long to fit on one line.

@node Typeahead
@section Typeahead

Your typing is echoed (displayed on the screen) as you type.
If you start to type a command before the prompt is displayed,
your typeahead, which echoes immediately, appears before the
prompt.  It may even be mixed up with output from the command
that was executing when you typed it.
In order that you can see the actual command you have
typed, BASH redisplays your typeahead after the prompt.
Don't worry -- though some characters appear on your screen twice,
BASH has kept only one copy of them.

The following shows the appearance of my screen when I
typed @samp{date} to find out the current date and time,
then typed @samp{who} to find out who was logged in.
I didn't wait for @code{date}'s output before I started to type,
so the @samp{wh} from @samp{who} appears in that output.
The next prompt is followed by a redisplay of the @samp{wh}
I already typed, followed by the final @samp{o}.

@example
bash$ date
whFri Jan 04 13:47:49 EST 1991
bash$ who
gjs        console      Dec 19 15:53
wisdom     pty/ttyu0    Dec 27 16:11
jems       pty/ttyu1    Jan  4 10:56
bash$
@end example

@node Editing, Continuation, Typing Commands, Typing Commands
@section Editing the Command Line

@cindex editing command lines, basic

To correct an error in the line you are typing, you can type @key{DEL}
repeatedly to delete one character at a time until you are back to the
spot that needs fixing, then continue typing.  Or you can type @kbd{C-u}
to delete the whole current line and start over.

However, it is also possible to move the cursor to the place you want to
change and correct the error without deleting and retyping everything
you've typed after the error.

You can edit the current line as long as you have not typed the
@key{RET} that terminates it.

Using the editing keys described below, you move the cursor to the
place that needs correction and delete or insert the text of the
correction.  Then, when you are satisfied with the line, you simply
press @key{RET}.  The cursor doesn't have to be at the end of the line
when you press @key{RET}; the entire line will be accepted in any case.

As you type text into the line, you'll notice that characters to the
right of the cursor get pushed over to make room for the
characters you are typing.  Likewise, when you delete a character
behind the cursor, characters to the right of the cursor get pulled
back to fill in the blank space created by the removal of those
characters.

The rest of this section describes basic command-line editing.
@xref{Readline Commands}, for a list of all the editing commands.

If you are an Emacs user, you may already be familiar with most of the
editing keys described below: All but @kbd{C-u} are the same ones used
in Emacs.

Note: If you don't like any of the editing keys, you can change them
to be whatever you want (@pxref{Customizing Readline}).

@heading Moving the Cursor

Here are the basic ways to move the cursor within the line you are typing:

@table @kbd
@item C-b
Move cursor back (left) one character.

@item C-f
Move cursor forward (right) one character.

@item M-b
Move cursor backward (left) one word.

@item M-f
Move cursor forward (right) one word.

@item C-a
Move cursor to the start of the line.

@item C-e
Move cursor to the end of the line.
@end table

Notice that @kbd{C-f} moves forward a character, while @kbd{M-f}
moves forward a word.  It is usually the case that Control keystrokes
act on characters, while Meta keystrokes act on words.

@heading Deleting Text

Here are the basic ways to delete text once you have positioned the cursor:

@table @kbd
@item C-d
Delete the character underneath the cursor.

@item @key{DEL}
Delete the character to the left of the cursor.

@item C-k
Kill the text from the current cursor position to the end of the line.

@item C-u
Kill the text from the beginning of the line to the current cursor position.
(Note that if the cursor is at the end of the line, this kills the whole line.)
@end table
@c maybe add M-d, M-DEL (corresponding to C-d, DEL)

@heading Inserting Text

To insert text into the line, just position the cursor and type
the text as you normally do at the end of a line.
No special keystroke is needed to indicate that you want to insert.

@heading Clearing the Display

If the screen is cluttered, you may wish to:

@table @kbd
@item C-l
Clear the screen, reprinting the current line at the top.
@end table

@node Typos
@subsection Failing to Correct a Command Line

If you notice an error while typing a command, it is better to
fix it (or delete the command and start over) than to let the command
execute as is, especially if the command contains any punctuation
characters (many of which have special meaning to the shell).
Although many sorts of errors will result in perfectly harmless
(and sometimes even comprehensible) error messages, other erroneous
commands may do things you didn't intend or give you error messages that only
a shell wizard can understand.
For example, if you accidentally hit @samp{*} while typing a file
name in a command to delete a file, you may end up deleting more
than one file (@pxref{File Names}).

@node History Use
@section Repeating Earlier Commands

You can sometimes save typing by retrieving an earlier command.
You can reexecute the command as is, or you can edit it before
executing it.
This is particularly useful if a command gets an error.
Instead of retyping it with the error corrected, you can
retrieve the command and just fix the erroneous part.

If you are an Emacs user, you may recognize the following commands
as the same ones that move to the previous or next line
or to the beginning or end of an Emacs buffer.
Think of BASH as maintaining an Emacs buffer of your command
lines, in which you can see only one line at a time.
Each time you end a line (by typing @key{RET}), BASH adds
that line to the end of the buffer and positions its cursor
at the start of the next line.

@xref{History List}, for a more complete description of what
commands BASH remembers in its history list.

The rest of this section describes the basic commands for accessing
previous command lines.
@xref{History Commands}, for the complete set of commands.
@c note: the stored line contains the result of history substitutions.
@c If you typed a ! history reference, the resulting cmd is stored.
@c because: history subst is before shell sees input

@c Following edited from readline chapter -- may need to change that to
@c match this.

@table @kbd
@item C-p
Get the previous line from the history list.
(Opposite of @kbd{C-n}.)
The line is displayed after the prompt as if you had just typed it.

@item C-n
Get the next line from the history list.
(Opposite of @kbd{C-p}.)
The line is displayed after the prompt as if you had just typed it.

@item M-<
Get the oldest line in the history list.
(Opposite of @kbd{M->}.)
The line is displayed after the prompt as if you had just typed it.

@item M->
Get the most recent line in the history list.
(Opposite of @kbd{M-<}.)
This is the line you are typing at the current prompt.
Unless you type something after the prompt, this line is blank.
@end table

If you're a BASH novice, it is probably best to start by using
just @kbd{C-p} and @kbd{C-n}.
Type @kbd{C-p} repeatedly to move back as far as you want.
If you overshoot, use @kbd{C-n} to go forward again.

@node Continuation,  , Editing, Typing Commands
@section Continuing a Command on the Next Line

If you don't have room on the line to finish typing your command,
type a backslash, @samp{\}, then @key{RET}.
A @samp{\} at the @emph{end} of a command
line tells the shell that the command hasn't ended, but is to be
continued on the next line.
The shell will give you a secondary prompt (different from the ordinary
prompt, so you can tell that this is a continuation line), and you can
continue typing the rest of the command.
In this way, you can continue a command over any number of lines.
The command is not executed until the final @key{RET} (that is, a @key{RET}
not preceded by a @samp{\}) is typed.
@c But: expansion/substitution take place after each RET -- e.g. !, *, ...
@c rms: ! is during input processing by history library, * is done by shell
@c bfox: ! done on each line
@c   can avoid \ if know what's incomplete
@c   e.g. things in quotes
@c   usually only use \ for shell script, don't need interactively
@c   a) usually type shorter cmds, b) line will wrap
@c consider moving this? or recommending really for scripts and describing
@c the default long-line wraparound (with pointer to inputrc for
@c changing it)
@cindex long commands
@cindex continuing command lines
@cindex command lines, continuing
@cindex commands longer than 1 line

@c lousy example
For example, both of the following commands concatenate the files
@file{file1} through @file{file6} together into a single file
@file{file1to6}.  In the first sequence, the command is split into two
lines by ending the first line with a @samp{\}.  BASH prints a secondary
prompt (@samp{bash>}, unless you have specified a different prompt) to
signal that it awaits further input for the current command.

@example
bash$ cat file1 file2 file3 \@key{RET}
bash>file4 file5 file6 > file1to6@key{RET}
bash$
@end example

@noindent
is equivalent to:

@example
bash$ cat file1 file2 file3 file4 file5 file6 > file1to6@key{RET}
bash$
@end example

Warning:
@itemize @bullet
@item
The @samp{\} must be the last thing on the line that is to be
continued.  If you accidentally type a space after the @samp{\}, your
screen will not look any different, but the command line will be
terminated by the @key{RET} rather than continued.

@item
The multiple command lines are simply concatenated, with no
space inserted.  If a space is needed between the last thing you type
on one line and the first thing you type on the next line, you must
be sure to include the space yourself (either before the @samp{\}
that ends the first line or at the start of the next line).
@end itemize

@heading Editing Earlier Lines

Command-editing (@pxref{Editing}) only works on the current line.
If you notice while typing a continuation line that you need to correct
an earlier line of the command, you will need to abort the command
entry and start over (though you needn't retype everything, if you
follow the instructions below):

@enumerate
@item
To avoid losing the line you are in the midst of typing, end it with
@kbd{\@key{RET}}.

@item
Type @kbd{C-c} to abort command entry and get back to the top level of
BASH.

@item
The lines you typed but never executed were nonetheless stored
in the command history list.  Use @kbd{C-p} (@pxref{History Use})
to retrieve the lines of your multi-line command one at a time.
Type @key{RET} after each correct line, but when you come to the bad
line, edit it before typing @key{RET}.
@end enumerate

@node I/O, File Names, Typing Commands, Top
@chapter Redirecting Input and Output (Basic)

@cindex redirecting input and output
You may want to send a program's output to a printer instead
of to your screen.  Or you may want to use a data file for
input, instead of typing input at your keyboard.

@cindex redirection operators, versus command arguments
Many commands
allow input files and output files to be specified as arguments.
For commands that don't take such arguments (or whose arguments you
don't remember), you can use redirection operators, as
explained in this chapter, to @dfn{redirect} input or output to come
from or go to a file.
You can also redirect input or output to come from or go to another
program, by using @dfn{pipes}.

Redirection is performed by the shell, not by individual command programs.
The action of the command itself is unchanged by redirection; in
general, commands are unaware that their input or output has been redirected.
The command reads its input and writes its output as usual, and that
input and output automatically come from and go to whatever places the shell has set up.
This is accomplished as follows.

@cindex standard input
@cindex standard output
@cindex standard error
Most programs that read from or write to the terminal actually
read their input from an imaginary place called
@dfn{standard input}, write their ordinary output to an imaginary
place called @dfn{standard output}, and write their error messages
to an imaginary place called @dfn{standard error}.
Before the shell runs the program in a command, it hooks up the
standard input, standard output, and standard error to real places,
such as your terminal, a file, or another program's input or output.

The following sections tell you how to specify how these standard
input and outputs should be hooked up.

@c add a diagram showing standard I/O as sockets with things plugged in?

@heading Redirection versus file arguments

@cindex redirection operators, versus command arguments
Consult the documentation of the specific command you wish to use to
see whether you have to use redirection operators in order to make it
use files.
File Names as
arguments are often preferable to redirection operators because they enable
the command to know the name of the file it is reading.  (A command can
know its arguments, but is not aware of redirection.)  Also,
some commands (such as @code{sort})
can read more than one input file when the files are
specified as arguments, whereas redirection can only specify a single input
file.
@c If file args to cmd are preferable, isn't it bad to use such cmds as
@c redirection examples?
@ignore
rms: better examples: cat, compress
compress file
 replaces file with file.Z  and deletes original file
 option to not delete file
 If want to redirect output, must redirect input too.
    compress < f1 > f2
 Because if there's an arg (file name), compress
 opens the arg file itself, so redirection is useless.
 With no arg, it uses streams it's given (by < and >)
@end ignore

For example, here are two ways to sort the file @file{unsorted}
to produce the file @file{sorted-file}.
The first command gives the file names as arguments, with @samp{-o}
flagging the output file name.
The second command uses @samp{<} to redirect the input and @samp{>}
to redirect the output.

@example
bash$ sort -o sorted-file unsorted

bash$ sort < unsorted > sorted-file
@end example

@noindent
However, if you want to combine two input files @file{unsorted-1}
and @file{unsorted-2} into one sorted output file, you'll have
to give the input files as arguments, because only one input file
could be supplied by redirection.  You still have a choice of how to
specify the output file.

@example
bash$ sort -o sorted-file unsorted-1 unsorted-2

bash$ sort unsorted-1 unsorted-2 > sorted-file
@end example

@menu
* Redirection::        How to redirect standard input and standard
                       output.

* Other Redirections:: Redirecting standard input and standard output
                       simultaneously.  Redirecting background
                       processes.  Redirecting standard error.

* Pipes::              Connecting commands together.

@end menu

@node Redirection, Here-documents, I/O, I/O
@section Basic Redirection to Files

@c posix 3.7  n op word
@c  op is:  <  >  >|  >>  <<  <&  >&  <>
@c  special cases for <&-, >&-, <<-

@cindex redirection operators
@cindex standard input, redirecting
@cindex standard output, redirecting
@cindex standard error, redirecting
This section shows the basic method for redirecting the standard input,
standard output, and standard error to files.
@xref{Advanced Redirection}, for more complicated forms of redirection.
@c may want appendix that has 1 unified table of operators

In general, a simple redirection of input or output to a file looks like this:
@c rms: redir op can be among or before args (even before cmd?) [see posix]

@ignore
@c They were each shown with args, but it's probably better to consider
@c those as part of the command.  E.g. it was:
@var{command} @r{[}@var{arguments}@r{]} > @var{file}
@end ignore
@example
@var{command} @var{redirection-operator} @var{file}
@end example
@c show syntax for more than 1 redir op in a cmd??

@noindent
The @var{file} is the file or device you want to use,
@c note: "file" includes "devices" (such as printers).  Explain somewhere?
@c Nice thing in Unix is devices are simply files in directory /dev
and the @var{redirection-operator} is @samp{<} for input; @samp{>}, @samp{>|},
or @samp{>>} for output; or @samp{>&} for output and error.
Spaces surrounding the operator are optional, but it is a good idea
to leave a space before the operator.
(Otherwise you might accidentally specify one of the redirections
with a file descriptor -- @ref{Advanced Redirection}.)
@c Space needed after arg if it is a # and could look like file-descr.
@c rms: spaces optional around the REDIRECTION, but required to avoid ambig.

@ignore
In this section, with no file descriptor before operator (i.e. file
descriptor defaulted) and file name required after each operator, the
operators are as follows:
 >  >|  >>  <	posix
 >&		bash extension (from csh)
		(posix doesn't define >& with file name)
Anything involving a file descriptor or no file name is considered advanced.
@end ignore

@table @code
@item >
@itemx >|
@itemx >>
instruct the shell to send the command's standard
output to the specified @var{file} instead of to your terminal.
@cindex @code{>} operator, redirecting output
@cindex @code{>>} operator, redirecting output

@c copy of following itemize is in advanced chapter
@itemize @bullet
@item
If @var{file} doesn't yet exist, it is created.

@item
If @var{file} already exists:
@itemize @bullet
@item
With @samp{>} and @samp{>|}, @var{file} is erased before the
first output is written to it.  Be careful:
If a file of the same name already exists,
its contents are deleted before your command's output is
written to that file.
If you don't want @samp{>} to erase existing files, set the
shell's @code{noclobber} variable; then
@samp{>} with an existing file will generate an error message and leave
the file alone.  (But note that @samp{>|} will clobber existing files
regardless of the setting of the @code{noclobber} variable.)
@c Note: alternative 'set -o noclobber...' for noclobber var -- where
@c should cover this? which is preferable?

@item
With @samp{>>}, the output is appended to the end of an existing @var{file}.
@end itemize
@end itemize

Note that @samp{>}, @samp{>|} and @samp{>>} redirect only the standard
output; error messages printed by @var{command}, which go to standard
error, still appear on the terminal and not in the file @var{file}.  To
redirect error messages along with other output, see @samp{>&}, below.

Here's an example of output redirection:

@example
bash$ who
glassw   ttyq0   Apr 15 15:09   (worker-8)
glassw   ttyq1   Apr 15 20:50   (worker-7)
cqc      ttyq2   Apr 15 18:15   (worker-9)
zvona    ttyq5   Apr 15 14:13   (nico)
painter  ttyd0   Apr 15 21:00
stf      ttyh4   Apr 15 11:58
sandiway ttyh9   Apr 13 23:05
pwu      ttyhc   Apr 15 15:19
bash$ who > users-file
bash$
@end example

@noindent
The command @code{who} prints onto standard output a list of
the users currently logged into a computer system.
The simple command @samp{who}
prints onto your screen (the default standard output).  The
command @samp{who > users-file} redirects @code{who}'s
standard output to
the file @file{users-file}, so that the output of the @code{who}
command goes into @file{users-file}
instead of appearing on the screen.@refill

The following command sequence creates a file containing the current
date followed by the list of users currently logged onto the system:

@example
bash$ date > date-who-file
bash$ who >> date-who-file
bash$ cat date-who-file
Sat Aug 04 11:27:05 EDT 1990
glassw   ttyq0   Apr 15 15:09   (worker-8)
cqc      ttyq2   Apr 15 18:15   (worker-9)
zvona    ttyq5   Apr 15 14:13   (nico)
painter  ttyd0   Apr 15 21:00
stf      ttyh4   Apr 15 11:58
pwu      ttyhc   Apr 15 15:19
bash$
@end example

@noindent
The command @code{date} prints the system date on standard output.
In this example, the output of @code{date} becomes the first line of the file
@file{date-who-file} created with the @samp{>} redirection operator.
The output of the @code{who} command is @emph{appended} to the file
@file{date-who-file}, because we used the @samp{>>} redirection
operator.  @code{cat} simply shows the file's contents on the terminal.@refill

@item &>
@itemx >&
both instruct the shell to send the command's
standard output @emph{and} standard error to the file @var{file},
instead of to your terminal.  Both ordinary output and any error
messages are written to @var{file}, interspersed, in the order they
are generated.  Of the two forms, the second (@code{>&}) is preferred,
because it conforms to the convention that output redirection operators start
with @samp{>}.
@cindex @code{>&} operator, redirecting output
@cindex @code{&>} operator, redirecting output

As with @samp{>}, @var{file} is erased before the first output is written to
it.  Be careful:
If a file of the same name already exists, its contents are deleted
before your command's output is written to that file.
If you don't want @samp{>&} to erase existing files, set the
shell's @code{noclobber} variable; then
@samp{>&} with an existing file will generate an error message and leave
the file alone.
@c no appending version of >& analogous to >>  --  suggested it to bfox

The example at the end of this section shows how to redirect
standard error and standard output to different places.

@item <
instructs the shell to get the command's standard input from the
specified file @var{file} instead of from your terminal.
@cindex @code{<} operator, redirecting input

Here's an example of this type of redirection:

@example
bash$ wc < date-who-file
     7     39     244
bash$
@end example

@noindent
The command @code{wc} counts the number of lines, words, and
characters it reads from standard input.  Using the standard input
redirection operator, @samp{<}, we made @code{wc} read a file as its
standard input.  In this example, @code{wc} prints the line, word, and
character counts for the file @file{date-who-file} that was created in the
example for @samp{>>} above using the @code{date} and @code{who} commands.

Actually, redirection was not necessary for the above command,
since @code{wc} accepts the name of an input file as an argument:

@example
bash$ wc date-who-file
     7     39     244
bash$
@end example
@end table

@cindex redirection operators, using more than one
More than one redirection operator can appear in a command.
Here's an example that redirects both standard input and standard output:

@example
bash$ sort < users-file > sorted-list
@end example

@noindent
This example reads the input for the command @code{sort} from the file
@file{users-file} and writes the sorted output to the file
@file{sorted-list}.  Any error messages are still written to the
default standard error, which is your terminal screen.

You cannot redirect a single I/O stream to more than one file:
If you specify more than one redirection of the same I/O stream,
only the rightmost takes effect.
(The shell evaluates redirection operators in the order encountered, from
left to right.)  For example, the output of @code{sort} in the following
goes only to @file{out-file}, not to @file{sorted-list}.
@example
bash$ sort < users-file > sorted-list > out-file
@end example

In the next example, the output of @code{sort} goes to @file{out-file}
and the error messages go to @file{error-file}.  The @samp{>&} redirects
both standard output and standard error, then the @samp{>} redirects
standard output to @file{out-file}, overriding the @samp{>&}.
@example
bash$ sort < users-file >& error-file > out-file
@end example


@node Pipes, Pipes, Other Redirections, I/O
@section Pipes -- ``Mix-and-Match'' Commands
@c  pipes are what connect processes, pipeline is whole thing
@c    check terminology throughout

@cindex pipe
@cindex pipeline
@cindex pipes
@cindex @code{|}, use in piping
@cindex intermedate file, using pipe to avoid
@cindex combining commands with pipes
@cindex connecting commands together with pipes

@c a picture of boxes piped together would be nice
One of the shell's most powerful features is the way it lets you ``mix
and match'' commands.  By feeding the output of one command into another
command, you can get a combination of behaviors that no predefined
command provides.

A @dfn{pipe} connects the standard output of one command to the standard
input of another.
This has the same effect as redirecting the standard output of the first
command to a file, then redirecting the standard input of the second
command to come from that file; but the pipe does this with a single
command, and stores no intermediate files on disk.
@c also: separate processes means output produced before 1st cmd finishes

For example, let's say you want to see an alphabetical list of the
users logged into the system.
There is no command that does this, but there is a command
@code{who} that produces a list of the logged-in users and
a command @code{sort} that sorts its input lines.
By piping these commands together
(making the output of @code{who} become the input to @code{sort}),
you can get the desired sorted list:
@c contrast with   who > file; sort < file

@ignore
@c the raw data before sorted
@example
bash$ who

glassw   ttyq0   Apr 15 15:09   (worker-8)
glassw   ttyq1   Apr 15 20:50   (worker-7)
cqc      ttyq2   Apr 15 18:15   (worker-9)
zvona    ttyq5   Apr 15 14:13   (nico)
painter  ttyd0   Apr 15 21:00
stf      ttyh4   Apr 15 11:58
sandiway ttyh9   Apr 13 23:05
pwu      ttyhc   Apr 15 15:19
@end example
@end ignore
@example
bash$ who | sort

cqc      ttyq2   Apr 15 18:15   (worker-9)
glassw   ttyq0   Apr 15 15:09   (worker-8)
glassw   ttyq1   Apr 15 20:50   (worker-7)
painter  ttyd0   Apr 15 21:00
pwu      ttyhc   Apr 15 15:19
sandiway ttyh9   Apr 13 23:05
stf      ttyh4   Apr 15 11:58
zvona    ttyq5   Apr 15 14:13   (nico)
bash$
@end example

@heading Viewing Output by the Screenful 

@cindex @code{more}, with pipes
@cindex pipe, used to view output by the screenful
An extremely important use for pipes is to view the output of a command
one screenful at a time, by piping the command's output into the
@code{more} command.

Let's say you want to see a detailed listing
of a directory that contains a large number of files.  If you just
type @samp{ls -l}, the listing will scroll by faster than you can read it.
But if you use a pipe to attach the standard
output of @samp{ls -l} to the standard input of the @code{more}
command, you can page through the directory listing at your leisure:

@example
bash$ ls -l | more
@end example

@node How to pipe
@subsection How to Pipe Commands

@cindex pipeline, general format
To pipe the output of one command into the input of another, place a
vertical bar, @kbd{|}, between them.  The general format for a
@dfn{pipeline} is:

@example
@var{command} | @var{command2} @r{[}| @dots{} @r{]}
@end example

@noindent
That is, any number of commands are given, separated by vertical bars,
@kbd{|}.
The standard output of @var{command1} is connected to the standard
input of @var{command2}, and so on.

In order for a pipeline to work, the first command in the pipeline
must generate output to the standard output,
the last command must accept input from the standard input, and
any intermediate commands must both read from standard input
and write to standard output.

@c rms: "filter" terminology good to know, standard terminology
@c   for program designed to be used in a pipeline.
@c  Many  unix cmds designed so CAN be used as filter (i.e.they use
@c   standard input and standard output)
Commands used between pipe operators are called @dfn{filters}.  They
accept input from the standard input and generate output to
the standard output.
Examples of commands that can be used as filters
include @code{sort} (which sorts its input lines) and
@code{pr} (which formats text for printing).

@menu
* tee::  Using the @code{tee} command to preserve the
         contents of intermediate files.
@end menu

@node tee, tee, Pipes, Pipes
@subsection Saving Intermediate Pipeline Data with @code{tee}

@cindex pipeline, @code{tee} in
@cindex @code{tee} command for pipelines
@cindex pipeline, saving intermediate data
Normally, any data generated by commands in a pipeline exists only
momentarily within the pipeline, because the output of each command
simply flows into the next command.

The command in the following example outputs the five lines of
the file @file{list-files} that come first alphabetically:

@example
bash$ sort list-files | head -5
@end example

@noindent
This works as follows:
The command @code{sort list-files} sorts the file, sending the sorted
data to the command @code{head -5}, which outputs the first five
lines in its input.  The sorted data is discarded.

If you want to preserve the sorted data, you could first @code{sort} the
original data into a new file, then look at the @code{head} of that file:

@example
bash$ sort list-files > sort-saved
bash$ head -5 < sort-saved
@end example

@c pipe vs. redirection -- any pros or cons?

On some systems,
there is also a way to preserved the sorted data while using a pipeline.
To preserve intermediate pipeline data, such as the sorted data
in the above example, insert the @code{tee} command into your pipeline.
(Note: @code{tee} is not built into BASH.  It comes with GNU, and may
or may not exist on other operating systems.)
@c bfox says: tee doesn't belong here (no non-shell cmds do)
@c   including tee vs. including ps:
@c      ps comes with unix, behavior varies from system to system
@c      not all systems have tee -- though gnu will
@c jems thinks tee should be kept here
The @code{tee} command takes a file name as its argument and does two things:
@itemize @bullet
@item
It copies its standard input to the standard output.

@item
It copies its standard input into the specified file.
If the file doesn't exist, @code{tee} creates it.
If the file already exists, @code{tee} overwrites it,
unless you give @code{tee} the @code{-a} option, in which case
it appends to the file.
@c If tee arg omitted: It's a NOP: no err msg, no tee output
@c bfox: reason is so following will ``work'' even if var has no value
@c    cmd 1 | tee $var | cmd2
@end itemize

@noindent
(The name @code{tee} stands for the T shape of a pipe used in plumbing
to split the flow into two parts.)

Thus @code{tee} can be used to copy the data passing through a pipeline
into a file for later use.  For example, we can insert a @code{tee} into
the pipeline shown above:

@example
bash$ sort list-files | tee sort-saved | head -5
@end example

@noindent
Now the output of @code{sort} is sent to the @code{tee} command, which
stores the sorted data in a file called
@file{sort-saved} and also passes that data on to the next
program in the pipeline, @code{head}
@c diagram of example would be nice
@c  list_files -> sort -> sorted data -> head -> lines on terminal
@c  where sort and wc are in boxes

@node Pipes and redirection
@subsection Redirection in Pipelines

You may redirect the standard input of the first command in a pipeline
and the standard output and standard error of the last command in a pipeline
by using redirection operators (@pxref{Redirection}) in those commands.

The following example sorts the file @code{list-files}
(given to @code{sort} on its standard input by redirection with @code{<}),
gives the sorted output to @code{head}
(by connecting the standard output of @code{sort} to the standard input
of @code{head} with a pipe, @code{|}),
and stores the first five lines of the sorted output in the file @file{5lines}
(by redirecting the standard output of @code{head} to that file with @code{>}):
@example
bash$ sort < list-files | head -5 > 5lines
@end example


@node Pipeline processes
@subsection Processes in a Pipeline

@c new concepts: process, exit status

Each command in a pipeline is run as a separate process.
That is, the commands run simultaneously, in parallel.

The shell waits for all commands in the pipeline to terminate before
returning control to you.

The exit status of the pipeline is the exit status of the last command.

@node File Names, Customization, I/O, Top
@chapter File Names: Shorthands and Special Characters
@c need better title
@c need intro to material in chapter

@c new topic for bash 1.07 will go here:  filename expansion
@c   'foo{a,b}' ==> 'fooa foob'

@node Wildcards
@section Wildcards

@c Wildcards also show up in Case statement patterns
@c rms: right to think of wildcards as being for file names
@c    (case statement is strange additional use)

The shell allows you to specify sets of file names using @dfn{filename
patterns} containing @dfn{wildcard characters}, so that you don't have
to type all of the file names directly.
@cindex file names, wildcards in
@cindex wildcard characters in file names

For example, if you want information about the five files in the
current directory that end with @samp{.c}, you don't have to type
the five file names:

@example
ls -l foo.c bar.c fred.c card.c game2.c
@end example

@noindent
Instead you can type:

@example
ls -l *.c
@end example

@noindent
The shell interprets the filename pattern @samp{*.c} as matching all
existing file names ending in @samp{.c}.  The character @samp{*}, which
can match almost any substring of a file name, is
called a wildcard character.
@xref{Wildcard Constructs}, for an explanation of @samp{*} and the other
wildcard constructs.

A single pattern may contain more than one wildcard.
For example, @samp{*.c*} would match all file names that contain
@samp{.c}.

@c document 'set -o noglob...' for disabling wildcards -- disables all
@c of them?

@node Wildcard Constructs
@subsection Wildcard Constructs

Here are the wildcard constructs and their meanings:

@table @code
@item *
The asterisk matches any sequence of zero or more characters, except
that it does not match a period at the beginning of a file name.
(If you want @samp{*} to include initial periods, set the variable
@code{glob_dot_filenames}.)

For example: @samp{foo*} matches any file name whose first three
characters are @samp{foo}, including the name @file{foo} itself;
@samp{*foo} matches any file name not starting with @samp{.} whose last
three characters are @samp{foo}, including the name @file{foo} itself;
and @samp{.*foo} matches any file name starting with @samp{.} whose last
three characters are @samp{foo}, including the name @file{.foo} itself;
@c Beware! .* can behave unexpectedly
@c  ls .* expands to ls . .. .emacs (and so on)
@c  but ls . and ls .. list those directories!
@c by contrast, *. behaves as expected (* can't match initial .)

@item ?
The question mark matches any single character, except
that it does not match a period at the beginning of a file name.
(If you want @samp{?} to match initial periods, set the variable
@code{glob_dot_filenames}.)

For example, @samp{foo?} matches any four-character file name
whose first three characters are @samp{foo}.  (Note that @samp{foo?}
does not match @samp{foo} because @samp{foo} has only three characters.)

@item [@var{char-set}]
This @dfn{character set} matches any @emph{one} character specified by
the @var{char-set}.
Like a @samp{?}, a character set matches a single character.  Unlike the
@samp{?}, the character set is selective about which characters it will match.

The @var{char-set} consists of a sequence of any number of characters
and/or any number of ranges of characters.
The character set matches any of the single characters listed or any of
the characters included in the specified ranges.

For example, @samp{[123abcdq]} will match any one character from
the set @samp{123abcdq};
@samp{[1-3a-dq]} matches exactly the same characters, but it uses
hyphens to indicate the ranges of characters from @samp{1} to @samp{3}
(inclusive) and from @samp{a} to @samp{d}.

Thus, @samp{foo[12]} matches @samp{foo1} and @samp{foo2} and nothing else;
@samp{foo[a-z]} matches any four-character file name whose
first three characters are @samp{foo} and whose fourth
character is any lower-case letter; and
@samp{foo[a-z12]} matches any four-character file name whose
first three characters are @samp{foo} and whose fourth
character is @samp{1}, @samp{2}, or any lower-case letter.

@c KELLEM added ^ item (as synonym for !)
@item [^@var{char-set}]
This matches any @emph{one} character @emph{not} included in the given
@var{char-set}, where the @var{char-set} is as specified above for
the @code{[@var{char-set}]} case.
For example, @samp{foo[^a-z12]} matches any four-character file name whose
first three characters are @samp{foo} and whose last character is not
@samp{1}, @samp{2}, or a lower-case letter.

@item [!@var{char-set}]
This is the same as @code{[^@var{char-set}]} if history substitution
is disabled.
Otherwise the @samp{!} invokes history substitution (@pxref{History}).
@c 12/90, Bash 1.06.25:  'ls b[!a]*' --> 'a]*: Event not found'
@c   in particular, ! does history subst and [, ]*, are not interpreted here
@c   because ! done before shell sees line
@c  Tried quoting the ! -- ls fo[\!a] -- but it just said fo[!a] not found.
@c    (didn't find my file 'foo')
@c  Works with history disabled
@end table

@node Wildcard implementation
@subsection How Wildcards Work

Each command word that contains a wildcard character is @dfn{expanded},
which means it is replaced by a sequence of words, one for each
file that matches the pattern.
If @samp{*.c} in the command @samp{ls -l *.c} expands to
@samp{foo.c bar.c fred.c card.c game2.c},
the @code{ls} command sees these five file names as its arguments;
it never sees the @samp{*.c}.

Normally, a filename pattern that doesn't match any files is left in the
command as is (it expands to itself).  For example, @samp{*.foo} is left
as is if there are no files ending in @samp{.foo}, so in the following
example the @code{ls} command gets @samp{*.foo} as its argument
and reports that there is no such file (which is what you want to know).

@example
bash$ ls -l *.foo
*.foo not found
bash$
@end example

@noindent
If for some reason you don't like this behavior, you can set the
variable @code{allow_null_glob_expansion}.  When that variable is set, a
pattern that doesn't match anything is removed from the command (expands
to a null file name).  In the above example, the @samp{*.foo} would
disappear, and @code{ls} would get no arguments, so it would report
on all files in the current directory.

Warning: A command word containing a wildcard construct is expanded
to a sequence of file names @emph{whether or not you intended it to be
a file name}.  At the time the expansion takes place, the system does
not know or care whether it makes sense to treat the word as a file name.

@node echo, Quotation, File Names, File Names
@section Using @code{echo} to Preview Wildcard Expansion

If you are going to use wildcards for something dangerous, like deleting
a group of files, it is a good idea to be sure you know what files the
pattern will match.

@cindex @code{echo} command
@cindex command lines, previewing
To find out how wildcard characters will be expanded without actually
executing your command, use the @code{echo} command to preview the
expansion of a filename pattern.  The @code{echo} command
simply displays its arguments fully expanded, with
any pattern that doesn't match anything left as is
(or deleted, if you have set @code{allow_null_glob_expansion} --
@ref{Wildcard implementation}).
@c rms: expand = replacing text with other text (!, *, ...)
@c   interp may be part of expand,
@c    e.g. substituting result of cmd into enclosing cmd
@c  NB: $(...) is new version of `.  Nice because it nests

For example,

@example
bash$ echo rm *.log *.foo
rm bash.log *.foo
bash$
@end example
@noindent
shows that if I ask to delete (with the @code{rm} command) all files
ending in @samp{.log} or @samp{.foo}, I will be deleting only
@file{bash.log}.
The pattern@samp{*.log} was expanded to the single file name that matched, namely
@samp{bash.log}, and @samp{*.foo} was not expanded because it did not
match any existing file names.

@c what is echo for besides wildcards & variable substitution?
@c   rms: in shell scripts to print output
@c   Not so good for ! expansion:
@c I tried 'echo !n' where n is a command #
@c It echoed with the ! expanded, namely it display 'echo ...'
@c Then it went on to execute that last 'echo ...' ???
@c Ah: the 'echoing' of the expansion is just the normal ! expansion,
@c not the execution of the 'echo !n' command.  First the shell displays
@c the expanded command, then it executes it.  So echo is a confusing
@c way to preview ! expansion.

@node Wildcard Quotation
@section File Names Containing Special Characters

@cindex wildcards, quoting
@cindex quoting, special characters in file names

Normally, file names are made up of ``ordinary'' characters --
alphanumeric characters (letters and numbers), periods (@samp{.}), and a
few other characters (such as @samp{_} or @samp{~}) that have no special
meaning to the shell.  For example: the file containing this documentation is
named @file{bash.texinfo}; a backup version of this file saved for me by
Emacs is called @file{bash.texinfo.~1~}; and the file in which BASH
keeps track of commands I have issued (@pxref{History List}) is called
@file{.bash_history}.

If a file name contains a `special'' character -- a character that
has special meaning to BASH, you must @dfn{quote} it to prevent
BASH from giving the character its special interpretation.
In particular, you must quote the following characters if you need
to include them in a file name:

@example
  !  |  &  ;  <  >  (  )  $  `  '  "  \  *  ?  [  ]  #
@end example
@c above is all special chars?  what about : { }  (others?)
@c  rms: colon not special, braces are
@c  bfox: should quote the braces in file ames
@c I tried it 1/31/91:  foo} was not special, foo{ gave message about
@c   missing } but then went on to process foo{
@c bfox: braces recognized as special only if separated from surrounding text
@c   bourne:if not delimited, brace is regular char
@c bfox 2/8/91
@c   New bash feature (stole from csh): foo{a,b} ==> fooa foob
@c   Will fix to not treat { as brace expansion unless see a comma

@xref{Quotation}, for information on how to quote.

@node Tilde
@section Tilde Expansion

You can avoid having to type long directory pathnames by using a
shorthand for your home directory (and even other users' home
directories) and for the directory you were last connected to.
All of these directory abbreviations start with @kbd{~}.

You may also see this home-directory shorthand in program output.
For example, when you ask Emacs to find a file,
it uses @kbd{~} instead of spelling out your home directory
in the default pathname in the file-name prompt.

@cindex expansion, tilde
@cindex tilde expansion
@c  terminology: tilde substitution vs. tilde expansion (title)
@c  bfox: usually =, but sometimes a precedence issue
When a tilde character (@kbd{~}) appears at the beginning of a word
in a command, it is treated as follows:

@table @code
@item ~
@itemx ~/@dots{}
Tilde alone (or followed by a slash) is replaced by the value of the
variable @code{HOME}, or by your home directory if @code{HOME} is unset.

@item ~@var{login-name}
@itemx ~@var{login-name}/@dots{}
Tilde followed by someone's login name is replaced by that person's home
directory.

@item ~+
@itemx ~+/@dots{}
Tilde followed by a plus sign is replaced by the value of the variable
@code{PWD}, which is the directory you are connected to.
(Thus @samp{~+} is the same as @samp{.}.)
@c ? where are ., .. etc covered? Operating system rather than shell?

@item ~-
@itemx ~-/@dots{}
Tilde followed by a minus sign is replaced by the value of the variable
@code{OLDPWD}, which is the directory you were previously connected to.
@end table
@c ? what happens if there is stuff other than / after the ~+ or the ~-

In the following example, I change directories and copy a file
from the first directory to the second:
@example
bash$ cd /top/next/a-subdirectory
bash$ cp ~-/file-to-copy .
bash$
@end example

Note for advanced users:
The above @samp{~} constructs can
also be used in pathnames that are stored in variables.
For example, you can use pathnames
with tildes in the @code{PATH}, @code{MAILPATH}, and @code{CDPATH} variables.
In such variables, any pathname (not just the first) can start with
@samp{~}.  That is, @samp{~} can appear after a @samp{:}, which
separates pathnames.

@node History List
@chapter The Command History List

BASH maintains a list of the commands you have given it most recently,
so that you can reuse earlier commands or just review what you did.

This section explains what is actually remembered and how you can
influence that by changing the values of shell variables.
The following sections explain how to make use of the command history.
@xref{Basic Variable Mechanics}, for general information on shell variables.

@cindex history list, size of
@cindex history list, changing size of
The length of the history list is controlled by the @code{HISTSIZE}
shell variable.  By default, the value of this
variable is 500; that is, the shell saves the last 500 command lines.
You can make the length of the history list bigger or smaller by
changing the value of the @code{HISTSIZE} variable.  A value of zero means
no lines are saved.

In this example, we check the value of @code{HISTSIZE} and find that
it has the default value of 500, then we reduce the value to 128:

@example
bash$ echo $HISTSIZE
500
bash$ HISTSIZE=128
bash$
@end example

The command history does not start out empty whenever you log in.
Rather, commands are saved from session to session.  Old commands
are erased from the list only when the length of the list exceeds
@code{HISTSIZE}.

The way BASH remembers commands between sessions is to store them
in a file.
By default, the file is @file{~/.bash_history} in your login directory.
You can change this file name, if you want, by setting the
@code{HISTFILE} variable.

Normally, all commands are remembered in the history list.
You can stop the recording of command lines beginning with a space
or of consecutive identical command lines by setting the
@code{history_control} variable, which is not set by default.
@table @code
@item history_control=ignorespace
stops lines beginning with a space from being recorded.

@item history_control=ignoredups
stops a line identical to the last one in the history list from being recorded.
@end table
@noindent
(Sorry, but there is to way to stop both kinds of command recording at once.)

To see the history list, use the @code{history} command (@pxref{History}).
You could also look at the file in which BASH saves history,
but that is normally updated only when you exit from BASH, so it
will contain the history as of the end of your last session
rather than the current history.

To reuse earlier commands (or portions of earlier commands),
use Emacs-style keystrokes (@pxref{History Use}) or
history substitution (@pxref{History}).

@node Customization, Job Control, File Names, Top
@chapter Customizing Shell Behavior

@cindex customizing shell behavior
@cindex controlling shell behavior
@cindex changing shell behavior
You can control some aspects of the shell's behavior, by changing
values (such as how often the shell checks whether you have new mail)
or by enabling or disabling features (such as whether
@samp{!} invokes history substitution -- if you don't know what that is,
you should probably disable it).

Many parts of this manual include information on how to customize
the behavior being described.
This chapter covers some basic customizations that don't fit naturally
into other topics or that are especially recommended for BASH novices.
@c what to include here?
@c Decision: Only include customization that doesn't fit in another
@c chapter.  Customization of particular features will be in those
@c chapters -- e.g. history vars with history stuff

To try out a customization command, you can simply type it
and see if you like the changed behavior.
But you should not waste time retyping your favorite customization
commands each time you log in.
Instead, the commands you always want in effect should be put into a
startup file that BASH automatically executes whenever you log in
(@pxref{Login script}).

@node Variables
@section Shell Variables

@cindex variables, controlling shell behavior
@cindex shell variables, to control behavior

One way to affect shell behavior is to set @dfn{variables} used by the
shell.

@xref{Basic Variables}, for documentation of some of the more basic
variables.  Other variables are covered where appropriate throughout
this manual.
@c how should those sections help you manipulate the vars?
@c   repeat the how-to info?  point to {Variable Mechanics}?
@xref{Shell Vars}, for documentation
of all the variables set or used by the shell.

Some of the mechanics of manipulating shell variables are given here
(@pxref{Basic Variable Mechanics}).
@xref{Variable Mechanics}, for more complete information.

@node Basic Variable Mechanics
@subsection Manipulating Shell Variables

To find out the value of a variable, type @samp{echo $@var{name}}, where
@var{name} is the variable of interest.  (Be sure to include the @samp{$}; if
you omit it, @code{echo} just repeats the @var{name} itself.)

To change the value of a variable, type @samp{@var{name}=@var{new-value}},
where @var{name} is the variable you want to change and @var{new-value} is
the new value you want it to have.  Don't leave any blank space around the
@kbd{=}.

@emph{Warning:} Be careful to type variable names exactly as they are shown
here, matching uppercase and lowercase letter exactly.  If you type a name
wrong before an @samp{=}, you will either change the wrong variable or create
a new variable; if you type a name wrong after @samp{echo $}, you will examine
the wrong variable.

In the following example, we ask for the value of the @code{MAILCHECK}
variable, which is 600, then change it to 0 and verify our change.
@example
bash$ echo $MAILCHECK
600
bash$ MAILCHECK=0
bash$ echo $MAILCHECK
0
bash$
@end example


@node Basic Variables
@subsection Basic Shell Variables

This section documents some basic shell variables whose values you might want
to change.  For example, if you use more than one computer, you might want to
change the shell prompt to be the name of the computer you are using instead
of @samp{bash$ }.  @xref{Shell Vars}, for documentation of all the variables
set or used by the shell.

@c include any other vars?
@c recommend (point to) other vars?  noclobber (for safety)

@heading Directories

@table @code
@item HOME
This holds the default argument for the @code{cd} command.  @code{HOME} is set
to your login directory when you log in, so that a simple @samp{cd} command
will return you to your login directory at any time.

For example, I may want to frequently return to the directory where
I work on GNU projects:
@example
bash$ HOME=/usr/jems/gnu
bash$
@end example

@noindent
Now a simple @samp{cd} command will return me to @code{/usr/jems/gnu} instead
of to @code{/usr/jems}.

@item PATH
This is the search path the shell uses when looking for program files
referenced in commands.  It holds a sequence of directory names separated by
colons, to be searched from left to right.

For example:

@example
/usr/gnu/bin:/usr/local/bin:.:/usr/ucb:/bin:/usr/bin/X11:/usr/bin
@end example

@c simplify or explain the PATH example
@c :.: is especially opaque

@end table

@heading Mail

@table @code
@item MAILCHECK
This specifies the amount of time that must pass before the shell will check
whether your mail file (the file named by the @code{MAIL} variable) has
changed.  The default is 60 seconds (1 minute).  An interval of 0 causes the
shell to look for mail before printing each prompt.

For example,

@example
MAILCHECK=600
@end example

@noindent
causes the shell to check for mail before printing a prompt if 600 seconds
have passed since the last check.
@end table

@heading Prompts

@cindex customizing your prompt
@cindex prompt, customizing
When executing interactively, BASH displays the primary prompt (stored in the
variable @code{PS1}) when it is ready to read a command, and the secondary
prompt (stored in the variable @code{PS2}) when it needs more input to
complete a command.

@table @code
@item  PS1
This is the primary prompt string.  By default it is @samp{bash$ }.
(Actually, the value in PS1 is @samp{bash\$ }, which prints as @samp{bash$ }
unless you are a superuser.)

The following example sets the primary prompt string to be your login name,
followed by an @samp{@@} and the name of the computer, followed by a dollar
sign and a space (for example, @samp{jems@@zurich$ }).  The variable value is
enclosed in quotes (either double quotes, as shown here, or single quotes) so
that it can include a space.  The special codes @samp{\u} and @samp{\h} for
the user name and host name, as well as other codes useful in prompts, are
explained below.
@c ? apparently \u etc. must be within double quotes, otherwise they are
@c used literally -- 1.06, 2/22/91

@example
PS1="\u@@\h$ "
@c same as "$(whoami)@@$(hostname)$ "
@c better example would be host & directory?
@c single quotes -- deferred eval of $ things till expanded
@c double quotes: $ things eval'ed when ps1 assigned (bfox)
@c should use single if $ things in prompt should change -- e.g. your pwd
@c  not relevant to \ methods below, since they're special to prompts,
@c  not expanded as more fundamental mechanism
@end example

@item PS2
This is the secondary prompt string, which is printed whenever bash needs more
input to complete a command.
@c what's an example of needing more input?  when does it happen?
@c whenever syntax demands more -- e.g. 'if' statement without
@c the closing 'fi'
@c Also, the secondary prompt is printed after some errors. (which?)

By default it is @samp{bash>}. 
For example, we can change the secondary prompt string to @samp{more>}:

@example
PS2="more>"
@end example

Note that the secondary prompt, unlike the primary prompt, normally doesn't
end in a space.  A space might fool you into thinking the lines of a
multi-line command were automatically separated by a space, whereas they are
actually run together exactly as typed (@pxref{Continuation}).
@end table

The values of @code{PS1} and @code{PS2} can contain special character
sequences beginning with @samp{\} that are decoded as follows.  (That is, the
@samp{\} and the following character are replaced by what they stand for when
the prompt is printed.)

@table @code
@item \t
The time.

@item \d
The date.

@item \n
Carriage return and line feed (@sc{CRLF}).
@c notation/terminology: call it newline?

@item \w
The full pathname of the current working directory (the value of the variable
@code{PWD}).

@itemx \W
The last element of the current working directory (the last directory in the
value of the variable @code{PWD}).

@item \u
Your username.

@item \h
Your machine's hostname.

@item \#
The command number of this command (consecutively numbered since login,
starting with 1).

@item \!
The history number of this command (the position of this command in the
history list -- @ref{History List}).

@item \\
A backslash.  Since @samp{\} in a prompt normally isn't printed, but rather
gives the next character a special meaning, if you want a @samp{\} in your
prompt you must put @samp{\\} in the prompt string.

@c next is too obscure for ordinary user
@item \s
The name of the shell (the basename of the positional parameter @code{$0}).
@c basename = last element of path name  - normally bash
@c $0 is name of prog you're running
@c  if execute shell script foo directly (typing name of executable file),
@c   inside foo, $0 is foo

@c next is too obscure for ordinary user
@item \$
@samp{$} unless you are the superuser, in which case it is @samp{#}.
@c actual criterion is: if the effective user @sc{id} is 0
@c bfox: when log in, get a non-0 uid:  if su to become root, get eff uid=0

@c next is too obscure for ordinary user
@item \@var{nnn}
The character that has the given octal code.
@end table

For example, if for some reason you did
@example
PS1="\d \t\n\u@@\h\n\w \#$ "
@end example
you would have a ridiculously long, multiline prompt, consisting of:
@enumerate
@item
the date and time (separated by a space);

@item
your user name and host name (separated by an @samp{@@});

@item
your working directory, a space, the number of this command
(numbered from 1 since you logged in), a @samp{$}, and a space.
@end enumerate

@example
bash$ PS1="\d \t\n\u@@\h\n\w \#$ "
Sat Feb  9 14:03:58
jems@@zohar
~/gnu 4$ who
jems       pty/ttyu0    Feb  9 11:38
gjs        pty/ttyu1    Feb  8 15:16
Sat Feb  9 14:04:01
jems@@zohar
~/gnu 4$ 
@end example

@c following needs explaining -- is this about what happens
@c   at prompt-printing time after \'s are processed?
@noindent
Note for advanced users:

After the prompt string is decoded, it is expanded via parameter expansion
and command substitution unless the variable @code{NO_PROMPT_VARS} is set, 

@node set
@section The @code{set} Command

You can use the shell's built-in @code{set} command to turn shell options on
and off (@pxref{Built-in}).  Here are some option settings you might want to
use:

@c recommend any other features for beginners?
@c   'set -u' (or set -o nounseft...) to make unset vars different from null vars
@c  2/8/91,bfox: 'set -o' is now for options, not history.
@c    plain 'set -o' gives list of options

@table @code
@c following set is according to bfox -- must try it
@item set -o histexpand off
disables history substitution (@pxref{History}).
If you don't know what history substitution is, it is a good idea to
disable it.

@end table

@c anything else besides set from builtin chapter?  enable?

@node Job Control, Combining commands, Customization, Top
@chapter Background and Foreground Processes

This chapter explains how to run commands in the @dfn{background},
so that you can do more than one thing at a time, and how to
interrupt commands that are running.

First we present a short scenario that illustrates most of
the facilities covered in this chapter.  The rest of the chapter
provides full explanations of these facilities.

@c ideas for following scenario:
@c bfox often does:
@c   start ftp, c-z it, bg, stops when needs tty input, fg, talk to it
@c   find (see other example)
@c **need output lines in following scenario, where marked by **
@example
bash$ monthly-accounting
C-z
bash$ bg
**is job & proc # printed here as for & ?
bash$ make >& log &
[1] 18432
bash$ emacs
@c another good example would be 'mail'
C-z
bash$ jobs
**show both background jobs running & suspended foreground job
bash$ fg
@dots{}
bash$ **a done notice for one of the background jobs
bash$ wait
**done notice for other background job
bash$
@end example
@c bfox: silly to WAIT for 1 job.  Should just FG it, and will get
@c   prompt when it finishes.  Not all systems have job control. (Have
@c   backgrounding, but can't interact with the bg job except to  send
@c   it kill it.)  GNU does.  But Bash could run on a system V machine,
@c   no job control.  Wait useful when no job control
@c bfox: can log out & bg jobs keep going!
@c   downplay wait -- don't expect users to use it
@c users only need fg, bg, %, auto_resume
@c Fix whole chapter to separate out what have with/without job control
@c INTTERUPT IS NOT THE SAME AS STOP

In this example, we gave the command @samp{monthly-accounting}, which started
our @code{monthly-accounting} program (in the foreground).  We didn't want to
sit there waiting for it to finish, so we interrupted it (@kbd{C-z}) and
continued it running (@code{bg}) in the background.
@c Beware: if we didn't have the foresight to redirect output originally
@c it's too late now
We then started a program compilation (@code{make@dots{}}) in the background
(@code{&}).  While those background jobs ran, we started up @code{emacs}.
After a while we wanted to see how the background jobs were coming along, so
we interrupted the foreground job (@kbd{C-z}) and asked about our jobs.  The
@code{jobs} command reported on our two background jobs and also told us about
our suspended @code{emacs} job.  We resumed the @code{emacs} program
(@code{fg}).  When we exited from @code{emacs}, BASH reported that our
@code{make} job had finished.  We decided to wait for the
@code{monthly-accounting} job to finish also (@code{wait}).


@node Start job
@section Starting a Job

@cindex foreground
Commands such as those shown in most of our examples are run in the
@dfn{foreground}.  That is, the command runs and you do not get another BASH
prompt (and the opportunity to run another command) until it finishes.  This
is appropriate for short or interactive tasks.

@cindex background
If a program will be running a long time and does not require supervision or
input from the terminal, it may be best run in the @dfn{background}.  This
leaves your terminal free for other tasks.

@node Background
@subsection Starting a Background Job

@cindex background processes
@cindex background, placing things in the
@cindex background (&)
@cindex command lines, putting in the background

To run a command in the background, place an ampersand, @samp{&}, at the end
of the command line.  For example, the following command runs @code{make}
(which recompiles a program as specified by a data base in the current
directory) in the background (@samp{&}), redirecting @code{make}'s standard
output and error messages to the file @file{log}:

@example
bash$ make >& log &
@end example

@cindex background job's standard input and output
In this example, the command does not read from the standard input, so we had
no reason to redirect standard input.  If a background command uses its
standard input, you should normally redirect it, because the command cannot
read from the terminal (which you are using for other things).  If a
background task needs input from the standard input and you have not
redirected the standard input:
@c new concept: job control -- what is it?  Not defined in this manual
@itemize @bullet
@item
On a system with job control (such as GNU), the background task is suspended
if it needs input from the standard input.  You can then bring the task to the
foreground (@pxref{Resuming}) and type the input.
@c add an xref?

@item
On a system without job control (such as @sc{System V}), the background task
is given a null string if it needs input from the standard input.
@end itemize

You should usually redirect the background command's standard output as well
(as shown in the above example), unless you want the output to be interspersed
with your other work on the terminal.  If your background task sends output to
the standard output and you did not redirect the standard output, this output
appears on your terminal, @emph{even if you are running another program}.

When you run a background command, the shell prints out its job number and the
@sc{pid} of the last process in the pipeline (@pxref{Numbers}).  In the
following example, BASH assigns our background command a job number of 1.  It
assigns a @sc{pid} of 18449 to the last process in the pipeline, @samp{wc >
count-file}.

@example
bash$ ls -l | wc > count-file &
[1] 18449
bash$
@end example

@node notify
@subsection Notification of Background Job Termination

@cindex background, the @code{notify} variable
@cindex @code{notify} variable, for background jobs

When a background job is finished, BASH reports its job number, the word
@samp{Done}, and the command line itself:

@example
[1]+  Done              ls -l | wc >count-file 
@end example

@noindent

@c also reports when a job becomes suspended (by a signal)
Normally the shell reports on jobs only when it issues a prompt, so it doesn't
interrupt what you are doing.  If you wish to be told of changes in job status
immediately (not just when you get the next shell prompt), set the
@code{notify} variable, as follows:

@example
bash$ notify=
@end example
@c create a var = set a var;  how uncreate it if change your mind?  

@node wait
@subsection Waiting for Background Jobs to Terminate

@cindex background, the @code{wait} command
@cindex @code{wait} command
If you want to wait for some or all of your background jobs to finish before
issuing any more commands, you can save yourself the trouble of keeping track
of the termination notices (@pxref{notify}) or repeatedly typing the
@code{jobs} command (@pxref{Jobs command}) by using the @code{wait} command to
wait for the background jobs to finish.

@table @code
@item wait
@itemx wait @var{job_spec}
@c next item added by KELLEM
@itemx wait @var{pid}
The @code{wait} command waits for active background processes to finish.  It
suspends operation of your terminal until the specified background job
(@var{job_spec}) or background process (@var{pid}) is finished.  If no job or
process is specified, @code{wait} waits for all currently active jobs to
finish.
@c presumably wait finishes immediately if the job is suspended

@var{job_spec} is any job specification 
and @var{pid} is a @sc{pid} (@pxref{Numbers}).

Let's assume that you want to start three lengthy jobs running concurrently
and then want to wait for all three jobs to finish before continuing.  Here's
how you'd do it:

@c bfox: searches starting with / for files named core
@c   & prints to standard out  (whole path name)
@example
bash$ find / -name core -print >& core_list &
[1] 2240
bash$ grep "Experience" /home/* >& exper_list &
[2] 2241
bash$ ls -lR / >& dir_list &
[3] 2242
bash$ wait
[1]   Done                find / -name resume -print >& resume_list
[2]-  Done                grep "Experience" /home/* >& exper_list
[3]+  Done                ls -lR / >& dir_list
bash$
@end example

@noindent
In this example, three long jobs are performed simultaneously: each job is
performed in background by the @code{&} operator at the end of the command.
Notice that each job has its standard output and standard error redirected to
a file with the @code{>&} operator so that the jobs do not write output or
error messages to the screen while they are running in the background.  The
@code{wait} command waits for all three commands to finish before allowing
BASH to continue.
@end table

@menu
* Numbers::    Job numbers and process identification
               numbers.

* Stopping::   Stopping and suspending jobs.

* Job Specs::  Stopping, restarting, and otherwise
               modifying the state of a job.

* fg::         Resuming stopped or suspended jobs.

* bg::         Placing stopped jobs in the background.

* kill::       Terminating Processes.

* nice::       Running processes at a low priority
               using the @code{nice} command.

* nohup::      Preventing jobs from stopping using 
               the @code{nohup} command.
@end menu

@node Numbers, Stopping, Job Control, Job Control
@section Jobs, Processes, and their Identifiers

Each pipeline run by the shell is considered a separate @dfn{job}.  (A
pipeline is a set of commands joined by pipes (@pxref{Pipes}), or a command
without pipes -- which can be though of as the simplest possible pipeline,
with only 1 command and 0 pipes.)  Each command in the pipeline is run in its
own process (that is, they run simultaneously).  Hence a job consists of one
or more processes.

There are a number of commands that act on jobs or processes.  (For example,
there are commands to suspend a job or kill a process.)  If you give a command
for a job (for example, killing the job), this applies to all the processes in
the job.  If you give a command for a process, only that process is affected.

To specify the desired job or process in a command, you may need to refer to
it by number.

@itemize @bullet
@item
Every process has an identifying number, called a @dfn{@sc{pid}} (@sc{p}rocess
@sc{id}entifier).  @sc{pid}s, which are assigned by the operating system, are
unique throughout the entire system: No two processes, even belonging to
different users, can have the same @sc{pid} at the same time.

@item
Jobs are identified by small @dfn{job numbers}, which are assigned by BASH.
Unlike @sc{pid}s, these are not unique throughout the system: Any number of
users may have a job 1 at a given time.  However, at any moment, all your jobs
have numbers that are different from each other, which is all you need to
uniquely identify them in commands.
@end itemize

When you run a background command, the shell prints out its job number and the
@sc{pid} of the last process in the pipeline (@pxref{Background}).  In
addition, you can find out these numbers by using the @code{jobs} command or
the @code{ps} command (@pxref{Jobs command}).

To refer to a process in a command, use its @sc{pid}.  To refer to a job in a
command, use a @dfn{job specification} having one of the following forms:

@c Unclear whether to include % as part of job spec.
@c %... can be cmd by self
@c Cmd with job spec as arg may allow omit % if no other arg.
@c (1) job spec starts w %, bt sometimes can leave it out if want to
@c e.g. in fg or bg:  fg 4 = fg %4
@c  or
@c (2) job spec has no %, sometimes precede with %
@c RMS prefers view (1)

@table @code
@item %@var{number}
refers to the job whose number is @var{number}.  For example, @samp{%1} refers
to job number 1.

@c bfox: both %strings require unambiguous match, and look in whole job list
@item %@var{string}
refers to the job whose command line (the command that started the job) starts
with @var{string}.  For example, @samp{%emacs} refers to an @code{emacs} job.
If there is more than one job whose name begins with the string, you'll be
given an error message.

@item %?@var{string}
refers to the job whose command line (the command that started the job)
contains @var{string}.  For example, @samp{%?mac} may refer to an @code{emacs}
job.  If there is more than one job whose name contains the string, you'll be
given an error message.

@item %
@itemx %+
@itemx %%
all refer to the current job (the last job stopped or placed in the
background, @pxref{current job}).

@item %-
refers to the previous job (the second-to-last job stopped or placed in the
background, @pxref{current job}).
@c 1/7/91, 1.06 -- there was only 1 stopped job -- %- got it (same as %+)
@end table

Note that a job specification starts with a @samp{%} character.  In certain
contexts, however, where it is clear that a job is being referred to, it is
possible to omit the @samp{%}.
@c I didn't show any examples where could omit it -- e.g. fg cmd

@node Jobs command
@section Finding Out Out What Jobs and Processes You Have

To find out what stopped (suspended) and background jobs you have, you can use
the @code{jobs} command.  The following example shows that we have three
suspended jobs.

@c must fix following examples so all based on same set of jobs

@example
bash$ jobs
[1]   Stopped    rn
[2]-  Stopped    vi file
[3]+  Stopped    emacs file2
bash$
@end example

Use the @code{-l} flag with @code{jobs} to see the jobs' processes as well:

@example
bash$ jobs -l
[1]+ 18448 Done         ls -l
     18449              | wc >count-file 
bash$ 
@end example

@cindex @code{ps} command
@cindex monitoring active processes
@cindex processes, monitoring
@cindex background, monitoring processes
@c define 'active'?
The @code{ps} command reports more detail about your active processes than
@code{jobs} does, but it treats the processes as individuals and doesn't group
them into jobs.  When typed without options, @code{ps} gives you the following
information. (Note that @code{ps} is not built into BASH, so its output is
different from system to system; however, the basics remain the same.)

@table @code
@item PID
The process identification number.

@item TTY
The terminal from which the process was started.

@item TIME
The amount of computer time the process has used so far.

@item COMMAND
The name of the process.
@end table

Here's an example of the output of @code{ps}:

@example
bash$ jobs
[1]+  Stopped             emacs
bash$ ps
  PID TTY      TIME COMMAND
 2249 ttyp0    0:00 ps
 2184 ttyp0    0:00 emacs
 2170 ttyp0    0:00 bash
bash$
@end example

@noindent
This @code{ps} command shows that we have three processes: the @code{ps}
process itself, an @code{emacs} process (which we presumably suspended
earlier), and the @code{bash} process itself.  (@code{ps}, unlike @code{jobs},
reports on foreground as well as background processes.)  BASH has assigned job
number 1 and process number 2184 to @code{emacs}.

@xref{ps, , @code{ps}, utilities, The GNU Utilities Manual},
for more information.

@node current job
@subsection Current Job and Previous Job

The @samp{+} and @samp{-} in the output of @code{jobs} identify the ``current
job'' and ``previous job'' respectively.  The job most recently stopped
(suspended) or put in the background is called the @dfn{current job}.
@c last sentence unclear
@c In particular, why is a Done job marked + ?  bfox: May fix later
@c  Current job concept is useless for it, since you can't act on it
@c  Remains + until it's reported to you and removed from list
It is marked with a plus sign, @samp{+}, in the jobs listing.  The
second-to-last job stopped or put in the background is called the
@dfn{previous job}.  It is marked with a minus sign, @samp{-}, in the jobs
listing.  When the current job is terminates or is moved to the foreground,
the previous job becomes the new current job.

The concept of ``current job'' is used for defaulting arguments
to the @code{fg} and @code{bg} commands (@pxref{Resuming}).

@c need examples

@node Stopping, Job Specs, Numbers, Job Control
@section Interrupting a Job

@c How kill a stopped job?
@c bfox: kill job-spec (shell continues & signals the process -- you
@c   don't have to continue it yourself)
@c   Shell tells op sys start process, processes can communicate by signals
@c   Kill exists as ordinary disk-file cmd
@c   Shell has separate built-in kill cmd so can do jobs, which are
@c   shell (not op sys) concept.
@c   If program doesn't disable TERM, it will definitely kill you
@c rms: program handles signal if wants, otherwise unix does it
@c   kill -9  (9=SIGKILL) is signal no one can ask to handle, thus kills anything

@c confusion in this section between Job, Process, Program
@c confused terminology: stop, kill, suspend
@c rms: stop=suspend, terminate=kill (gone)

@node Interrupt foreground
@subsection Interrupting the Foreground Job

@cindex stopping jobs
@cindex jobs, stopping
@cindex suspending jobs
@cindex jobs, suspending

You may want to abort the program you are currently running (in the
foreground), or you may want to interrupt it temporarily in order to do
something else.

The following keys stop the foreground job, placing it in a type of
``suspended animation'' so that it can be resumed if desired
(@pxref{Resuming}).

@c none of these interrupts worked while running vi under bash
@c rms: interactive editors turn things off
@table @code
@item @kbd{C-z}
This stops (suspends) the foreground job immediately.
@c but SIGTSTP says programs may ignore C-z? (bfox: can ignore if enabled)

@item @kbd{C-y}
This is similar to @kbd{C-z} except it causes the process to be stopped
(suspended) only when that process attempts to read input from the terminal.
@c KELLEM: note that C-y (by default in readline lib) is bound to `yank'
@c  thus fine when readline not running
@c bfox: normally type C-y ahead of time (if at prompt, you would type C-z)
@c  op sys buffers it & prepares to send signal later
@c same true of C-z (op sys cmd, not bash)
@end table

@noindent
Note for advanced users:
@kbd{C-z} and @kbd{C-y} will not suspend the shell itself.
@c Does this belong here?  There's lots of other stuff it won't suspend, too.
To suspend a shell, such as one started with the @code{su} command,
use the @code{suspend} command (@pxref{Built-in}).

The following keys kill the foreground job.
The job cannot be resumed.

@table @code
@item @kbd{C-c}
This kills the foreground job immediately.

@item @kbd{C-\}
This kills the foreground job immediately and it is much harsher than @kbd{C-c}.
@c  harsher in what way - just core dump? is core dump the purpose of C-\ ?
@c bfox: C-c is SIGINT, which usually kills
@c   but C-\ is SIGKILL, which can't be ignored
This method usually produces a core (memory) dump for later analysis.
@c why 'usually'?    bfox: core dump happens if not disabled with ulimit
@c  by setting core dump size to 0
@c  He normally has dumps disabled, enables to reproduce a bug
@c  rms: if program  handles signal, it may not produce dump -- otherwise produced
@c what is the core dump useful for?  rms: debugging
@end table

All of the above keystrokes can be reassigned to other keys,
by using @code{stty}.
@c need ref for stty
We are just covering the most common keyboard methods of stopping jobs.
Your operating system manual will tell you about other
keyboard interrupts and how to remap your keyboard.

No matter which method you use (except @kbd{C-c}), the shell tells you 
when your program, or job, has been ``Stopped'', and prints another prompt.
@c really does it for C-\ but not C-c ?
@c be clearer what shell tells you

@node kill, nice, bg, Job Control
@subsection Interrupting a Background Job

@cindex stopping jobs
@cindex jobs, stopping
@cindex suspending jobs
@cindex jobs, suspending
@cindex background, stopping jobs
@cindex background, suspending jobs
@cindex background, terminating processes
@cindex processes, terminating
@cindex terminating processes or jobs

You cannot use the keyboard interrupts (@pxref{Interrupt foreground})
to interrupt a background job, since background jobs do not listen to
the terminal.

To suspend or terminate a background job, you can do either of the following:
@itemize @bullet
@item
Use the @code{kill} command (described below).

@item
Move the job to the foreground (@pxref{fg<>bg}) then use one of the
keyboard interrupts for foreground jobs (@pxref{Interrupt foreground}).
@end itemize

@cindex @code{kill} command
@cindex background, the kill command and
@cindex jobs, the kill command and
@cindex signals, for the @code{kill} command

@c new concept: signal
@table @code
@item kill @r{[}-@var{sigspec}@r{]} @var{pid}
@itemx kill @r{[}-@var{sigspec}@r{]} @var{job_spec}
Send the process identified by @var{pid} or all processes in the
job identified by @var{job_spec}
the terminate signal,
@c  SIGTERM
or the signal specified by @var{sigspec}, if given.
@var{pid} is a process identification number and
@var{job_spec} is a job specification (@pxref{Numbers}).
Signals are specified either by number or by name, as explained below.
@c where are the numbers defined? document here? (appendix)

@item kill -l
This lists all the possible signal names (and numbers).
It does not affect any jobs or processes.
@end table

Here's a summary of the most common and useful signals.
In the @code{kill} command, you can use any of the following:
@itemize @bullet
@item
the name shown  -- e.g. @code{SIGKILL}

@item
the part of the name after @samp{SIG} -- e.g. @code{KILL}

@item
the lowercase version of the part of the name after @samp{SIG} -- e.g.
@code{kill}
@end itemize


@c compare to appendix -- don't  want same table in both places
@table @code
@item SIGHUP
This is a gentle signal you can send to processes that you want to
kill when you want to allow them to clean up after themselves (for
example, delete temporary files, kill subprocesses, etc.).  It is a
good practice to try to kill jobs with this signal first, before trying
any of the harsher signals.  Some programs see this signal as a request
for them to re-initialize some internal state or re-read a startup file,
so this signal is not always used strictly for killing a process.

@item SIGINT
This is the signal generated (normally) by @kbd{C-c} on the keyboard.
This signal will kill most processes, although a program may choose to
ignore @code{SIGINT}.  @code{SIGINT} also allows a process to clean up
after itself before dying.
@c how differs from SIGHUP?  rms: SIGHUP means terminal is disconnected.
@c  prog might die from hup but not c-c

@item SIGQUIT
This is the signal generated (normally) by @kbd{C-\} on the keyboard. 
@c normally = if not remapped
@code{SIGQUIT} is identical to @code{SIGINT} except that it requests that the
operating system produce a diagnostics file called a @dfn{core dump},
which is placed into a file named @file{core}.
This can be useful for debugging.

@item SIGTERM
@code{SIGTERM} is similar to @code{SIGINT} except that it is normally produced by a
program and not from the @kbd{C-c} on the keyboard.  Note that
some programs treat @code{SIGTERM} differently from @code{SIGINT}.

@item SIGKILL
@code{SIGKILL} is the harshest ``kill'' signal.  It kills a process
without warning
and without allowing the process to clean up after
itself.
@c rms: i.e. doesn't signal process, just kills it
@code{SIGKILL} should be used as a last resort, if
@code{SIGHUP}, @code{SIGTERM}, @code{SIGINT}, and @code{SIGQUIT} don't
work.

@item SIGTSTP
@code{SIGTSTP} is the signal sent (normally) by the @kbd{C-z} key on the
keyboard.
@c normally = modulo remapping
Some programs may ignore this signal.  This signal does not
kill the process but instead @emph{stops} the process, putting the
program into a suspended state.

@item SIGSTOP
@code{SIGSTOP} is identical to @code{SIGTSTP} except it is not generated from
the keyboard by @kbd{C-z}; it is must be sent with @code{kill} or from within
a program.

@item SIGCONT
@code{SIGCONT} causes a @emph{stopped} process to continue running.  A stopped
process is sent this signal by BASH when the @code{fg} and @code{bg}
commands are used.
@end table

The following example terminates a @code{tip} process that has
been stopped earlier:
@c tip is for: communicate over serial port to log into another machine
@c replace example -- don't use tip or HUP (HUP normally due to hangup, not sent by you)
@c rms: normally do kill, or kill -stop, or kill -kill
@c bfox: either kind of name can be lower case
@c replace example

@example
bash$ jobs -l
[1]+ 29854 Stopped        tip
bash$ kill -HUP 29854
[1]+ Hangup               tip
bash$ jobs
bash$
@end example

@noindent
For a @code{tip} process, it is especially useful to use the @code{-HUP}
signal so that @code{tip} cleans up the @sc{UUCP} lock files that it leaves
around.


@node Stopped jobs
@subsection Logging Out With Stopped Jobs

@cindex logging off, with stopped jobs
@cindex jobs, logging off with stopped
@cindex stopped jobs, logging off with
If you have stopped jobs that you have forgotten about and you try to
log off, you will be given a warning that you have ``Stopped jobs'' and
will not be allowed to log off.  If you continue to try to log off, you
will eventually be successful, but the operating system will kill
(terminate) all your stopped jobs.
@c what if you have running (background) jobs?
@c ? bfox: they just keep silently running ?
@c  csh sends hup to children when logs up, bash currently doesn't
@c  might change it -- if so, add nohup biltin

It is much better to bring the stopped jobs to the foreground
(@pxref{Resuming}) and terminate them properly, so that can clean up
after themselves (save files, etc.).

You can also prevent jobs from being killed
when you log off by using the @code{nohup} command (@pxref{nohup}).

@node Resuming
@section Resuming a Suspended Job

A job that has been suspended (@pxref{Stopping}) can be resumed.
That is, you can make it continue from where it left off.
The resumed job can be run either in the foreground or in the
background, regardless of whether it was foreground or background
when it was interrupted.

The following methods of resuming jobs are described more fully below:
@itemize @bullet
@item
To resume a suspended job in the foreground, use the @code{fg} command
or just type a job specification (@pxref{Numbers}).

@item
If you set the @code{auto_resume} variable, typing a command
may resume a suspended job instead of starting a new one.

@item
To resume a suspended job in the background, use the @code{bg} command
or just type a job specification (@pxref{Numbers}) followed by an
ampersand (@samp{&}).@refill
@end itemize

@table @code
@item fg
@itemx fg @var{job_spec}
@itemx @var{job_spec}
Bring the specified job into the foreground, and resume running it.  If
@var{job_spec} isn't specified, @code{fg} acts on the current job
(@code{%}).

The following example resumes the current job in the foreground:

@example
bash$ fg
@end example

The following example resumes a stopped @code{du} process in the foreground:

@example
bash$ %du
@end example


@item bg
@itemx bg @var{job_spec}
@itemx @var{job_spec} &
Place the specified job in the background, and resume running it as if
it had been started with @samp{&}.  If @var{job_spec} is omitted,
@code{bg} acts on the current job (@code{%}).@refill

@example
bash$ find / -name resume -print >& resume_list 
C-z
[1]+  Stopped   find / -name resume -print >& resume_list
bash$ bg
find / -name resume -print >& resume_list &
bash$
@end example

@noindent
Here we started the @code{find} command in the foreground but then
stopped it (with @kbd{C-z}) and placed it in the background when we got
tired of waiting for the command to finish.

The following example places job 2 in the background:

@example
bash$ jobs
[1]-  Stopped   find / -name resume -print >& resume_list
[2]+  Stopped   ls -R / >& dir_list
bash$ %2 &
ls -R / >& dir_list &
bash$
@end example

@c 12/90, bash 1.06.25: bug: 'exact' has no effect - never need whole name
@item auto_resume=
@itemx auto_resume=exact
If you create the @code{auto_resume} variable (e.g. by typing
@samp{auto_resume=}), then if you type a command that matches
a suspended job's command,
@c match of cmd word
@c bfox: auto_resume is for 1-word commands
@c   must be 'simple word' -- e.g. \emacs is new
@c bfox: to specifically talk about 1st wd of cmd, call it ``command word''
the suspended job is resumed instead of a new job being started.
If the value of @code{auto_resume} is @code{exact}
(you set @samp{auto_resume=exact}), then you must
type the entire job name; if the value is anything else,
then only part of job name is enough to resume it.
@c fix: job name = command word
If there is more than one job
with such a name, the job with the highest number is resumed.

For example, assume that you have a stopped Emacs job:

@example
bash$ jobs
[1]+  Stopped             emacs -f rmail
@end example

@itemize @bullet
@item
If you have not set @code{auto_resume}, then the command

@example
bash$ emacs
@end example

@noindent
will start another Emacs job, and the old job will remain suspended.

@item
If you have set @code{auto_resume}, the above @samp{emacs} command
will resume the stopped Emacs job.

@item
If you have set @code{auto_resume} to anything but @code{exact}, an
abbreviated command (such as @samp{ema}) will also resume the stopped
Emacs job.
@end itemize
@end table

@node fg<>bg
@section Moving a Job Between Foreground and Background

To move the job that is running in the foreground to the background,
suspend the job (@pxref{Stopping})
and then resume it in the background (@pxref{Resuming}).

To make a job that is running in the background be the foreground job,
pretend the job has been suspended (though there is no need to
actually suspend it) and ``resume'' it using any method of resuming jobs
in the foreground (@pxref{Resuming}).

@c BFOX: Flush NICE from manual
@c KELLEM: nice is NOT a builtin -- description below looks like it's from csh
@c  /bin/nice usage is typically: nice [-number] command (both BSD and SysV)
@c  note the `-' before number .. what's GNU nice going to do?
@c rms: may be in posix 2 or 2a
@ignore
@node nice, nohup, kill, Job Control
@section Running Processes at a Low Priority Using @code{nice}

@cindex jobs, the @code{nice} command
@cindex background, the @code{nice} command
@cindex @code{nice} command, for lower priority
@cindex jobs, running at low priority
@cindex background, running processes at a low priority
The @code{nice} command causes a background process to be run at a 
low priority.  The operating system runs any commands specified by
@code{nice} when the machine has nothing else to do (it runs those 
commands less often than normal).  This way, commands that normally 
consume large amounts of system resources, slowing the system
considerably, are run in stages that don't slow the system down quite
as much.  Of course, a program that is run at a lower priority takes
longer to finish, but it doesn't interfere with more important
programs, either.

The format of the @code{nice} command is:

@example
nice @r{[}@var{number}@r{]} @var{command-line}
@end example

@noindent
where @var{command-line} is the command line you want to place at a
lower priority.
If present, the @samp{@var{number}} option causes @code{nice} to
increment the priority by the amount given, up to a limit of 20.  The
higher the value given, the lower the command's scheduled priority. 
The default value for @var{number} is 10.@refill

@c need example: maybe 'nice make -k hairy-program >& log' (rms)

@menu
* exception::  Using @code{nice} to force processes to run
               at a higher priority than normal.
@end menu

@cindex @code{nice} command, using for higher priority
@c what's a super-user? = root
Note for advanced users:
The super-user may give commands a higher priority than normal by using
a negative @var{number}, for example @samp{-5}.
@end ignore

@c comments by KELLEM
@c should `nohup' description be here?  machine specific
@c maybe should just note that way nohup works is machine dependent
@node nohup,  , nice, Job Control
@section Preventing Jobs From Stopping Using @code{nohup}

@c ? stop = be killed = be terminated?
The @code{nohup} command prevents commands from stopping, or being
killed, when you log out.
Normally when you log off your system, any
commands or processes that are running in the background are
terminated.
@c ? aren't suspended processes terminated too?
@c what happens if you suspend a process started with nohup, then resume
@c   it?  is it still nohup?
The @code{nohup} command prevents hangup signals
(@code{SIGHUP}, normally generated when you log off),
interrupt signals (@code{SIGINT}, normally generated by @kbd{C-c}),
and quit signals (@code{SIGQUIT}, normally generated by @kbd{C-\})
from terminating your program.@refill
@c ? any other signals disabled?

@cindex @code{nohup} command
@cindex jobs, the nohup command
@cindex background, the nohup command
@cindex preventing job suspension/stopping when logging out
@cindex logging out, preventing job suspension/stopping
The format of the @code{nohup} command is:

@example
nohup @var{command-line}
@end example

@noindent
where @var{command-line} is the command you don't want interrupted.
Any output the @var{command-line} produces is
put into a file called @file{nohup.out} in your current directory.
@c ? i.e. output to standard output?
(If this file cannot be written to your current directory, @code{nohup}
places it in your home directory.)

@c ?
THIS DESCRIPTION IS MACHINE SPECIFIC, UNLESS WE HAVE A GNU NOHUP (bfox).
@c i.e. nohup may not change priority
@c point of nohup: keep running after hang up

The @code{nohup} command increments the priority by 5.
(@xref{nice}, for an explanation of priority.).  Make sure that you
invoke @code{nohup} from the shell prompt with @samp{&}, so that it
won't respond to interrupt signals, or take input from the next user.
@c format above should thus show with & ?
@c ? if it's not given with &, how can you log out?
@c what next user?
@c  rms: it still has association with tty#, might respond to c-c etc.


@node Combining commands, Editing, Job Control, Top
@chapter Combining Several Commands on One Line

@node Sequential cmds, Parallel cmds, Combining commands, Combining commands
@section Sequential Commands

There are several ways to type several commands in one command line,
such that the commands are executed one after another.
You can either make the sequence execute unconditionally,
as if you had typed the commands one after another at the shell prompt;
or you can make execution of the sequence stop early depending
on the outcome of one of the commands, as if you had typed the commands
one at a time and decided whether to continue as you went along.

To do this, give a command of the form
@example
@var{command} @r{[}@var{separator} @var{command}@r{]}
@end example
That is, give any number of commands with an appropriate separator
between each pair, as defined in the following:

@table @code
@item ;
allows you to put
several commands on the same line, to be executed sequentially.
Separate each command from the next with a semicolon, @samp{;}.
@cindex @code{;}, sequential command sequence

No command in the sequence is executed until you end the line (press
@key{RET}).
Then the commands are executed in order, from left to right,
as if you had typed each separately and waited for it to finish
before typing the next.
@cindex separating commands
@cindex command line, separating commands on a

For example:

@example
bash$ cp test test-old; du > test; ls -l test*
@end example

@item &&
indicates conditional execution of commands in the sequence.
@samp{&&} means @sc{and}; the trailing commands are executed only if the
preceding commands are executed successfully.@refill
@cindex @code{&&}, conditional command sequence
@cindex joining commands
@cindex commands, joining
@cindex pipelines, joining
@cindex pipelines, conditional execution of
@cindex commands, conditional execution of

For example, if there is no file named @file{garbage.test},
then an attempt to list directory information for such a file
(@samp{ls -l@dots{}}) and an attempt to view its contents (@samp{cat@dots{}})
will both fail:

@example
bash$ ls -l garbage.test ;  cat garbage.test
garbage.test not found
cat: cannot open garbage.test
bash$
@end example

But if @samp{&&} instead of @samp{;} joins the two commands,
the second command is performed only if the
first command is successful.  Since the file @file{garbage.test} doesn't exist,
we get the error message associated with @code{ls} and @code{cat} isn't run:

@example
bash$ ls -l garbage.test && cat garbage.test
garbage.test not found
bash$
@end example

@item ||
indicates conditional execution of commands in the sequence.
@samp{||} means @sc{or}; the remaining commands are executed only if the
preceding commands are @emph{not} executed successfully.@refill
@cindex @code{||}, conditional command sequence
@cindex joining commands
@cindex commands, joining
@cindex pipelines, joining
@cindex pipelines, conditional execution of
@cindex commands, conditional execution of

For example:

@example
bash$ cat garbage.test || cat junk.test
cat: cannot open garbage.test
This is the contents of junk.test.
@end example

@noindent
The first @code{cat} failed to find @file{garbage.test}, so the second
@code{cat} was performed.

@end table

@node Parallel cmds, Combination precedence, Sequential cmds, Combining commands
@section Simultaneous Commands

There are two ways to type several commands in one command line,
such that the commands are executed simultaneously, in separate
processes.
You can specify either independent commands or commands whose
inputs and outputs are linked together.

To do this, give a command of the form
@example
@var{command} @r{[}@var{separator} @var{command}@r{]}
@end example
That is, give any number of commands with an appropriate separator
between each pair, as defined in the following:

@table @code
@item |
joins commands together into a pipeline.
The standard output of each command is redirected (connected) to the
standard input of the next command in the sequence.
@xref{Pipes}.

@item &
causes each command to run in the background.
The commands are executed simultaneously in the background,
as if you had typed each one separately, terminated with @kbd{&}.
@xref{Job Control}.

Note: @samp{&} actually terminates commands rather than separating
them.  This is a difference from the other command combiners in
this chapter.  Thus be sure to put a @samp{&} after the last command
as well as between commands, or the last command will @emph{not} run
in the background.

@end table

@node Combination precedence,  , Parallel cmds, Combining commands
@section Mixtures of Sequential and Simultaneous Commands

Any or all of the command separators described in this chapter
(@samp{;}, @samp{&&}, @samp{||}, @samp{|}, @samp{&})
can be used in a single command.

The order of precedence (from highest to lowest) is
@table @code
@item |
pipeline

@item && @r{and} ||
``and'' and ``or'', equal precedence, processed from left to right

@item ; @r{and} &
sequential and background, equal precedence, processed from left to right
@end table

However, if you have a mixture of operators, you should usually group
the subcommands with parentheses or braces (@pxref{Grouping}), rather
than assume you know how the command will be interpreted.
@c rms: for mixtures of operators, tell them to group with ()

@node Editing, History, Combining commands, Top
@chapter Command Line Editing

@menu
* Readline Intro::    An introduction to editing command lines
                      using @code{readline}.

* Syntax::            The basic editing commands.

* Customizing::       Customizing @code{readline} to use other
                      key bindings.  Includes a complete list of
                      all commands used in editing.

* vi mode::     Editing using other modes, including a 
                      @code{vi} editing mode.
@end menu

@cindex @code{readline} library
@cindex command lines, editing
@cindex editing command lines
@cindex Emacs, command lines and
BASH provides powerful facilities for editing the command line
you are currently typing, so as to minimize the amount of typing
needed to fix mistakes.
It also includes facilities to save typing by giving you access to
earlier commands and by completing things (such as file names) that you have
not finished typing.

The command-entry features described here are not specially programmed
into BASH.
Rather, they are provided by the @code{readline} library, which is used by a
number of other GNU programs besides BASH.
This means that you can use the same typing and editing facilities
with a variety of programs.

By default, @code{readline} has Emacs-like key bindings.
That is, most features that Emacs also has (such as moving the cursor
over words or characters) are invoked by the same keystrokes as
in Emacs.
@xref{Customizing Readline}, for how to change any key bindings you
don't like and customize other aspects of @code{readline}'s behavior.

@menu
* Movement::                Moving about the line.
* History Commands::        Using previous lines.
* Text::                    Commands for changing text.
* Buffer::                  Commands for killing and yanking.
* Numeric Arguments::       Specifying numeric arguments and
                            repeat counts.
* Completion::              Getting @code{readline} to do the
                            typing for you.
* Miscellaneous::           Other miscellaneous commands.
@end menu

@node Readline Commands
@section @code{readline} Commands

The following sections list all the functions provided by @code{readline}.
Each entry consists of
@itemize @bullet
@item the function name
You do not need the function name unless you want to change the key
binding (@pxref{Customizing Readline}).

@item the default key binding (in parentheses)
This is the key you press to invoke the function.
If no key binding is shown, then you can't use the function
unless you bind it to a key (@pxref{Customizing Readline}).

@item a short description of what the function does
@end itemize

@cindex command editing, advanced
@cindex editing commands, advanced
@cindex @code{readline} editing commands, advanced

@node Movement, History Commands, Customizing, Customizing
@subsection Moving the Cursor

Here are the @code{readline} cursor movement commands:

@cindex @code{readline} library, cursor movement commands
@cindex cursor movement commands in the @code{readline} library
@table @asis
@item beginning-of-line (@kbd{C-a})
Move to the start of the current line.

@item end-of-line (@kbd{C-e})
Move to the end of the line.

@item forward-char (@kbd{C-f})
Move forward (right) one character.

@item backward-char (@kbd{C-b})
Move backward (left) one character.

@item forward-word (@kbd{M-f})
Move forward (right) one word.

@item backward-word (@kbd{M-b})
Move backward (left) one word.
@end table

@node Text, Buffer, History Commands, Customizing
@subsection Changing the Command Text

@c new term: 'cursor point'
@c numeric &/or negative args mentioned but never explained

@cindex @code{readline} library, commands to change text
@cindex changing text commands in the @code{readline} library
Here are the @code{readline} commands for text manipulation:

@table @asis
@item quoted-insert (@kbd{C-q}, @kbd{C-v})
Add the next character that you type to the line verbatim.  This allows
you to insert a control character, for example,
and not have it act as an editing key.
For example, if you want to search for a @kbd{C-l} in a file,
you can type the @kbd{C-l} argument to the @code{grep} command
by typing @kbd{C-q C-l}.

@item tab-insert (@kbd{M-TAB})
Insert a tab character.
(A @kbd{TAB} character itself normally invokes completion
rather than being inserted into the command line -- @pxref{Completion}.)

@item self-insert (a, b, A, 1, !, ...)
Insert the typed characters verbatim.
All printing characters except @kbd{TAB} and newline
@c ? @kbd{RET}  ?
(i.e., all non-control, non-meta characters)
@c source: bfox
are inserted as typed.

@item transpose-chars (@kbd{C-t})
Interchange the character before the cursor with the character
at the cursor and position the cursor after both characters.  If the
cursor point is at the end of the line, then transpose the two
characters before the cursor point.  Negative arguments are invalid.

@item transpose-words (@kbd{M-t})
Interchange the word before the cursor with the word
at the cursor and position the cursor after both words.

@item upcase-word (@kbd{M-u})
Change the current (or following) word to uppercase and put the cursor
after the word.  When given with a
negative argument, the previous word is changed to uppercase, but the
cursor point is not moved.

@item downcase-word (@kbd{M-l})
Change the current (or following) word to lowercase and put the cursor
after the word.  When given with a
negative argument, the previous word is changed to lowercase, but the
cursor point is not moved.

@item capitalize-word (@kbd{M-c})
Capitalize the current (or following) word and put the cursor 
after the word.  When given with a negative
argument, the previous word is capitalized, but the cursor point is not
moved.
@end table

@node Buffer, Numeric Arguments, Text, Customizing
@subsection Deleting and Restoring Text

@cindex readline library, killing commands
@cindex killing commands in the readline library
@cindex readline library, yanking commands
@cindex yanking commands in the readline library
@cindex readline library, buffer commands
@cindex buffer commands in the readline library
Here are the @code{readline} commands involved in deleting text and
restoring previously deleted text.

In the following table, the term @dfn{kill} means to delete text from a
line, but save that text in a buffer for later retrieval. 
Usually you retrieve killed text by @dfn{yanking} it back into the
line.  The term @dfn{yank} means to retrieve text from a buffer and
insert it at the cursor in the current line.
Text that is @dfn{deleted} rather than killed is not saved and
cannot be yanked back.

@table @asis
@item delete-char (@kbd{C-d})
Delete the character under the cursor.
Note: If the cursor is at the
beginning of the line, there are no characters in the line, and the
last character typed was not @kbd{C-d}, then @kbd{C-d} means
end-of-file return @sc{eof}, and BASH exits.
@c bfox: bash exits (logs you out)!! ignoreeof can protect you from this

@item backward-delete-char (@key{DEL})
Delete the character behind the cursor.  A numeric argument given with
this command causes the characters to be killed instead of deleted.

@item kill-word (@kbd{M-d})
Kill the text from the current cursor position to the end of the
current word or, if between words, to the end of the next word.

@item backward-kill-word (@kbd{M-DEL})
Kill the text from the current cursor position to the start of the
current word or, if between words, to the start of the previous word.
@c bfox: words delimited by
@c  when doing completion  space tab nl " \ ` ' @ $ > < =
@c  in word movement/deletion  non-alphanumeric

@item kill-line (@kbd{C-k})
Kill the text from the current cursor position to the end of the line.

@item backward-kill-line ()
Kill backward to the beginning of the line.  That is, kill the text from
the beginning of the line to the current cursor position.  This is
normally not bound to a key.  (See @code{unix-line-discard}, which is bound to
@kbd{C-u}.)

@item unix-line-discard (@kbd{C-u})
Kill backward to the beginning of the line.
This is identical to backward-kill-line.

@item unix-word-rubout (@kbd{C-w})
Kill the text from the current cursor position to the previous
whitespace.  This is different from @kbd{M-DEL} because the word
boundaries are different.

@item yank (@kbd{C-y})
Restore the most recently killed text back into the line at the cursor.

@item yank-pop (@kbd{M-y})
Restore the next to most recently killed text back into the line at the
cursor.  You can do this only if the prior command was @kbd{C-y} or
@kbd{M-y}.
@end table

@node History Commands, Text, Movement, Customizing
@subsection Manipulating the Command History

@cindex readline library, history commands
@cindex history commands in the readline library
Here are the @code{readline} commands for manipulating the
command history (@pxref{History List}).

@table @asis
@item accept-line (@key{RET}, newline character)
Accept the line regardless of where the cursor is.  If this line is not
empty, add it to the history list.  If this line was a history line,
then restore the history line to its original state.
@c bfox: editing a cmd line retrieved from history
@c   if execute it, becomes new history line
@c   if edit it but move back to new line, old line stays edited, marked
@c     with * in history list -- can undo to restore it

@item previous-history (@kbd{C-p})
Move up through the history list.

@item next-history (@kbd{C-n})
Move down through the history list.

@item beginning-of-history (@kbd{M-<})
Move to the oldest line in the history list.

@item end-of-history (@kbd{M->})
Move to the most recent line in the history list.

@c must explain searches -- how to abort, when it's executed (RET), etc.
@c   How get the found line for editing?
@c  string is inside `', cursor at matching spot, RET executes, or just
@c  start editing it -- it becomes current command
@item reverse-search-history (@kbd{C-r})
Search backward starting at the current line and moving up through the
history as necessary.  This is an incremental search.

@item forward-search-history (@kbd{C-s})
Search forward starting at the current line and moving down through the
the history.  This is an incremental search.
@end table

@node Numeric Arguments, Completion, Buffer, Customizing
@subsection Specifying Numeric Arguments

@cindex readline library, specifying numeric arguments
@cindex numeric arguments, specifying in the readline library
Here is how you specify numeric arguments in @code{readline}:

@c explain what args are for, where can use them

@table @asis
@item digit-argument (@kbd{M-0}, @kbd{M-1}, ... @kbd{M--})
Add this digit to the argument already accumulating, or start a new
argument.  @kbd{M--} (meta-minus) starts a negative argument.

@item universal-argument ()
This lets you type numeric argument digits without metafying.
To start a negative argument use the minus key.
@c use minus when? after the ^U (or whatever bound to)
A minus sign alone, with no other digits following, means @minus{}1.

This is normally not bound to a key.

Assume you have bound @kbd{C-u} to universal-argument.  Then
@kbd{C-u} followed by a character that is neither a digit nor a minus
sign means ``multiply the next argument by 4''.  @kbd{C-u C-u} means
multiply the next argument by 16.
@c possible to reword without mentioning C-u ?
@c  probably not, if unbound commands are inaccessible
@end table

@node Completion, Miscellaneous, Numeric Arguments, Customizing
@subsection Completion:  Letting @code{readline} Type For You

@cindex readline library, completion commands
@cindex readline library, shortcut commands
@cindex completion commands in the readline library
@cindex shortcut commands in the readline library

You can save typing by asking for completion of the word you are in the
midst of typing.  The system can complete partially-typed file names,
command names, variable names, user names, and host names.  You can
either specify the type of completion you would like to perform on the
text before the cursor, or you can let the system guess what kind of
name is being typed and complete it accordingly.

@table @asis
@item complete (@key{TAB})
Try to complete the text before the cursor

In particular,
@c source: bfox
@itemize @bullet
@item variable

If the word before the cursor starts with @samp{$},
try to complete it as a variable name.

@item user

If the word before the cursor starts with @samp{~},
try to complete it as a user name.

@item host

If the word before the cursor starts with @samp{@@},
try to complete it as a host name.

@item command

If the word before the cursor is the first word in
the command line, try to complete it as a command name.
@c e.g. ema<TAB>-->emacs

@item file

If none of the above cases apply,
try to complete the word before the cursor as a file name.
@end itemize

@item possible-completions (@kbd{M-?})
List the possible completions of the text before the cursor.
See above for what kind of completion is assumed.

@c JEMS: tested 1/7/91 -- not all worked (bfox says fixed)
@item complete-variable (@kbd{M-$})
@itemx possible-variable-completions (@kbd{C-x $})
@itemx complete-username (@kbd{M-~})
@itemx possible-username-completions (@kbd{C-x ~})
@itemx complete-hostname (@kbd{M-@@})
@itemx possible-hostname-completions (@kbd{C-x @@})
@itemx complete-command (@kbd{M-!})
@itemx possible-command-completions (@kbd{C-x !})
@itemx complete-filename (@kbd{M-/})
@itemx possible-filename-completions (@kbd{C-x /})
@c rewrite
Each of these specify the type of completion you would like to perform
on the text before the cursor, whether it be filename, username,
hostname, variable name, or hostname completion, respectively.  These
BASH-specific @code{readline} commands do not depend on a prefix
character; though, if one is there, such as the dollar sign, @samp{$},
at the beginning of variable names, the commands will still work.@refill

The @code{possible-@dots{}-completions} commands are similar in
functionality to the @code{possible-completions} command.

Note that the specific completion commands are specific to BASH and are
@emph{not} defined in the @code{readline} library.
@end table

@node Miscellaneous,  , Completion, Customizing
@subsection Some Miscellaneous Commands

@cindex readline library, miscellaneous commands
@cindex miscellaneous commands in the readline library

@table @asis

@item clear-screen (@kbd{C-l})
Clear the screen, leaving the current line at the top of the screen.

@item abort (@kbd{C-g})
Sounds the warning bell and stops whatever was happening when you typed
these keystrokes.
For example, @kbd{C-g} can be used to abort entry of a numeric
argument (@pxref{Numeric Arguments}) or a search through command
history (@pxref{History Commands}).

@item do-uppercase-version (@kbd{M-a}, @kbd{M-b}, ...)
Run the command that is bound to the named, but uppercase, command.
@c bfox: M-a can be bound differently from M-A
@c   normally, M-a looks up & runs M-A
@c  if you rebind it, they're different
@c  **be careful in .inputrc to bind correct case
@c    is current doc of .inputrc wrong??

@item prefix-meta (@kbd{@key{ESC}})
@emph{Metafy} the next character that you type.  This is for
people without a @key{META} key.  @kbd{@key{ESC} f} is equivalent to
@kbd{M-f}.

@c I have no idea what the 'last thing' is.
@c empirically: successive C-- (note: I typed hyphen, not underscore) insert
@c   sucessive deletions or delete a whole contiguous set of insertion (typein)
@c bfox: consecutive insertions up to n is 1 thing
@item undo (@kbd{C-_})
This is the incremental undo.  Undo the last thing that you did.
@c last thing in current cmd?
You can undo all the way back to an empty line.
@c bfox: history has edits saved, so can undo them too

@item revert-line (@kbd{M-r})
Undo all changes made to this line.  This is like typing the ``undo''
command enough times to get back to the beginning of your corrections
for that line.
@end table

@node Customizing Readline, vi mode, Syntax, Editing
@section Customizing @code{readline}

@c ? to define/explain:  home directory, ~/ (= home dir?)

You can customize programs that use @code{readline} by putting commands
in a @code{readline} initialization file,
named @file{.inputrc}, in your home directory.
When a program (such as BASH) that uses the @code{readline} library
starts up, it checks the file @file{~/.inputrc} to set up its key bindings
and other parameters to your liking.
@c KELLEM's comments follow
@c footnote{Currently, both @code{gdb} and @code{bash} use the
@c @code{readline} library.  Future interactive GNU Project programs
@c will also incorporate the @code{readline} library.}

You can also force the initialization file to be reread
(for example, if you modify it and want to use your modifications
in BASH without logging out and logging in again)
by typing @kbd{C-x C-r} (the default key binding for 
@code{readline}'s @samp{re-read-init-file} function.
@c ?? re-read-init-file not documented above
@cindex @file{.inputrc} file, re-reading the
@cindex re-reading the @file{.inputrc} file

Three kinds of lines can appear in this initialization file:
@itemize bullet
@item comment

A line starting with @samp{#} is a comment.

@item key binding

@xref{Readline Key Bindings}.

@item variable setting

@xref{vi mode}.
@xref{Readline Variables}.
@end itemize

@node Readline Key Bindings
@subsection Key Bindings

@cindex readline library, customizing
@cindex editing commands, customizing
@cindex customizing readline library commands
Although the @code{readline} library comes with a set of Emacs-like key
bindings, it is possible that you would like to use different keys.

To bind a @code{readline} function to a key, place a line of the form

@example
@var{key-name}: @var{readline-function}
@end example

@noindent
or

@example
@var{key-name}: @var{readline-function} @var{comment}
@end example

@noindent
in the @file{~/.inputrc} file.  
@xref{Readline Commands}, for the function names and their default key bindings.
Any text after the @var{readline-function} is considered to be a
comment and is ignored.
Key names are explained below.

For example,

@example
C-u:	universal-argument
@end example

@noindent
or

@example
C-u:	universal-argument  used to be unix-line-discard
@end example

@noindent
binds @kbd{C-u} (which is initially bound to @code{unix-line-discard})
to @code{universal-argument} (which is not bound to any key by default).


@heading Key Names 

@c needs rewriting
For the key name, you can use the name of the key combination,
such as @kbd{C-f}.  The various ``words'' you can use to describe keys
are:

@table @key
@item Control-@kbd{k}
@itemx C-@kbd{k}
Holding down the control key and pressing the @kbd{k} key.

@item Meta-@kbd{k}
@itemx M-@kbd{k}
Holding down the meta key and pressing the @kbd{k} key.
@xref{Notation}, for alternative ways of metafying a key.

@item Rubout
@itemx DEL
The delete key.

@item Escape
@item ESC
The escape key, or @kbd{Control-[}.

@itemx RETURN
The enter (or return) key.

@item Space
@itemx SPC
The space bar.

@item LFD
@itemx NEWLINE
The @kbd{Control-j} key.

@item TAB
The tab key.
@end table

@heading Key Sequences

You can also specify an arbitrary key sequence instead of a single key:

@example
@var{key-sequence}: @var{readline-function} @var{comment}
@end example

To do so, surround the sequence in double quotes.
@c example

@c rewrite
If you want to use the @key{C-} or @key{M-}
specifications inside double quotes, you need to precede it with a
backslash (@samp{\}).  You can also specify the escape character with
@samp{\e}.  Note that you cannot use the ``words'' listed above, only:

@example
"\C-k"
"\M-k"
"\e"
@end example

@heading Macros

You can bind a key (or key sequence) to a key sequence instead of
to a named function.
@c rewrite
To do so, instead of a function name,
give the key sequence in double quotes.
Keys in this sequence are named as explained above
under ``Key Sequences''

@c example
@c format, with comment

@node vi mode,  , Customizing, Editing
@subsection @code{vi} mode in @code{readline}

@cindex readline library, VI commands
@cindex VI commands in the readline library
@c KELLEM wants to change @code{vi} to @sc{vi} in this section
The @code{readline} library does not have a full set of @code{vi}
editing functions, but it does contain enough to allow simple editing of
a line.

To switch interactively between Emacs and @code{vi} 
editing modes, use the command @kbd{M-C-j} (toggle-editing-mode).
@c why not listed in fns above? -- add it there
@c bfox: vi: start in insert mode
@c   get into cmd mode by doing ESC; then M-C-j
@c   press ESC till beeps, then M-C-j
@c  beware of accidentally getting into vi mode!
To enter the @code{vi}-like editing mode directly,
without starting in Emacs mode, place the command:

@example
@code{set editing-mode vi}
@end example

@noindent
in your @file{~/.inputrc} file.

@c what about 'set -o vi...' (vs. 'set -o emacs...')

When you enter a line in @code{vi} mode, you are already placed in
``insertion'' mode, as if you had typed an @samp{i}.  Pressing @key{ESC}
switches you into ``edit'' mode, where you can edit the text of the line
with the standard @code{vi} keys.  Since @code{vi} is not an
officially supported Free Software Foundation product, we won't explain
the key bindings here.
@c reference?
@c KELLEM: probably should, at least, give a list of key/function list for vi
@c mode.. maybe as an appendix?


@node Readline Variables
@subsection Other @code{readline} Variables

@c KELLEM supplied most of this section's content

In addition to @code{editing-mode} (@pxref{vi mode}),
there are a number of
other variables that can be set in @file{~/.inputrc} to
affect @code{readline}'s behavior.

To set a variable, put a line of the form

@example
set @var{readline-variable-name} @var{setting}
@end example

@noindent
in the initialization file.

The current @code{readline} variables are:

@table @code
@item editing-mode
specifies the default editing mode for the
@code{readline} library.  You can specify either emacs-style or vi-style
default key bindings.  The default is emacs-style key bindings.
The meaningful settings of @var{editing-mode} are:
@table @code
@item emacs

@item vi
@xref{vi mode}, for more information.
@end table

@item horizontal-scroll-mode
determines how to display lines longer than the width of your display.
The meaningful settings of @var{horizontal-scroll-mode} are:
@table @code
@item Off
If @code{horizontal-scroll-mode} is set to @code{Off}
(actually, any value other than @code{On} is treated as @code{Off}), lines are
``wrapped'' when they extend beyond the width of the display.
Such a line takes more than one line on the screen,
but it still counts as a single line.
(For example, @kbd{C-a} still goes to the very beginning.)

@item On
If @code{horizontal-scroll-mode} is set to @samp{On}, the
line is shifted to the left about a third of the display's width when
the cursor extends beyond the right side of the display.
That is, the input line is scrolled between the two edges of the
screen so that the current part is visible, though other parts may not be.
@c test this
@end table

@noindent
The default value of @code{horizontal-scroll-mode} is @code{Off}.

@item mark-modified-lines
specifies whether or not to ``mark''
modified history lines with an asterisk, @samp{*}.
The meaningful settings of @code{mark-modified-lines} are:
@table @code
@item Off
Modified history lines are not marked.

@item On
Modified history lines are marked.
@end table
The default value of @code{mark-modified-lines} is @code{Off}.

@end table


@c next sec added by KELLEM
@node Inputrc File,  , Other Scripts, Start-up
@subsection A Sample @file{~/.inputrc} file

@cindex inputrc file, customizing readline
@cindex inputrc file
@cindex customizing readline library, sample
@cindex readline library, sample customization file
@cindex editing commands, sample customization file

Here's an example of a simple @code{readline}
customization file, @file{~/.inputrc}:

@example
# -*- text -*-
# File: ~/.inputrc
# This file controls the behaviour of line input editing for
# programs that use the GNU Readline library.  Existing programs
# include Camera, Bash, and Gdb.
#
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
# Set various bindings for emacs_mode.

Meta-Rubout:	backward-kill-word  Stuff after the function name ignored
#Control-u:	universal-argument

# Note that the order of the words doesn't matter.
Meta-Control-r:	revert-line
Control-Meta-u: revert-line
C-Meta-T:	transpose-words
M-C-k:		transpose-chars
"\C-x\C-?":	backward-kill-line

# This line is bad syntax. It should have the M- before the C-.
# But it works.
"\C-\M-f":	forward-word		

# Here is a macro definition.  You can tell because the right-hand
# side is in quotes.
#"\C-xr":	"\C-a\C-kemacs -f rmail\C-j\C-y"

# Bind the arrow keys. (good for sun and vt220, vt100, etc.. )
"\e[A":		previous-history
"\e[B":		next-history
"\e[D":		backward-char
"\e[C":		forward-char

# help key macro
"\e[28~":	"\C-a\C-khelp | less\C-j\C-y"   VT220 help key
"\e[3~":	delete-char			VT220 remove key
# C-r is reverse-search-history
"\e[1~":	"\C-r"				VT220 find key

# Select the mode.
set editing-mode emacs
set horizontal-scroll-mode On
@end example
@ignore
@c alternative for arrow keys
"\M-[A":  previous-history
"\M-[B":  next-history
"\M-[C":  forward-char
"\M-[D":  backward-char
@end ignore


@node History, Line, Editing, Top
@chapter History Substitution

@cindex history library

BASH provides facilities to remember commands and let you reuse them.

The command-history features described here are not specially programmed
into BASH.
Rather, they are provided by the history library, which is used by a
number of other GNU programs besides BASH.
(In general, programs that use @code{readline} also use history.)
This means that you can use the same history facilities
with a variety of programs.

The history library maintains a list of recent command lines, or
@dfn{events}.
@cindex event, in command history
It provides you
with functions for remembering lines on a history list,
searching through the list for a line containing an arbitrary text
string, and referencing any line on the list directly.  In addition, a
history expansion function is available which allows you to easily use
those command lines again as is, or with some modifications, with very
little additional typing.

@cindex history library, using readline library instead
@cindex readline library, using instead of history library
If you find using the history library too difficult, you can use the
readline library instead (@pxref{Editing}).  The readline library
includes history manipulation by default,
@c by default?  is it ever not there?
and has the added advantage of Emacs-style command line editing.
@c any reason to use ! ever?

@menu
* Using History::    Using history substitution.

* Events::           How to specify which history line to use.

* Words::            Selecting words from an event.

* Modifiers::        Modifying previous events.

* History Size::     Changing the number of history lines saved.

* History Shortcuts:: History substitution shortcuts.

* History Protection:: History substitution delimiters.

@end menu


@node Using History, Events, History, History
@section How to Use History Substitution

If you type the command @code{history} on a line by itself, you are
presented with a list of events stored in the history list.  For
example:

@cindex history library, how to use the
@example
bash$ history

     1   cd News
     2   ls
     3   ls -l
     4   more tobob.doc
     5   mail bob
     6   rm tobob.doc
     7   ls
     8   cat memo 
     9   history
@end example

@noindent
The events are numbered from the oldest command typed (in this case,
number 1) to the latest command typed (in this case, number 9).

You can re-execute any event in a history list.  First you have to
determine which line from the previous history to use, then you need to
select portions of that line for inclusion in the current one.

The line selected from the previous history is called the @dfn{event},
and the portions of that line that are acted upon are called
@dfn{words}.  The line is broken into words in the same fashion that
the BASH shell does, so that text surrounded by quotes is considered to
be one word (@pxref{Quotation}).

@node Events, Words, Using History, History
@section Determining Which History Line to Use

@cindex history library, events in
@cindex events, history library and
@cindex history, determining events
@c why called substitution?
By far the most common use of this @dfn{history substitution} is simply
to reuse an entire line.  One way this can be done is to enter a
line which consists of @samp{!} followed immediately by enough
characters to uniquely identify the beginning of the line you want to
reuse.  For example, @samp{!cat} re-runs the last @code{cat}
process (@samp{cat memo}) in the above history list:

@example
bash$ !cat
cat memo
This is a memo.
bash$
@end example

@cindex command lines, reusing
@cindex reusing command lines
@cindex history, reusing command lines
Another way to reuse a line is to follow the @samp{!} with a number,
which specifies which line in the history list to use.  For example, to
reuse @samp{cat memo} we could have typed:

@example
bash$ !8
cat memo
This is a memo.
bash$
@end example

A third way is to type @samp{!?@var{string}}, which says to look
backwards through the history for the first line which contains
@var{string}.  Here's yet another way of re-using @samp{cat memo}:

@example
bash$ !?memo
cat memo
This is a memo.
bash$
@end example

@cindex events, referring to
@cindex history, referring to events
As we have just demonstrated, there are several ways to refer to an
event:  you can use its relative position in the history list,
@c relative position not demonstrated above?
its absolute position in the history list, or any text the event may
contain.  Here is a table summarizing the various ways to refer to an
event:

@table @code
@item !!
refers to the previous command.

@item !@var{n}
refers to an event by its absolute position in the history
list.  It refers to command line number @var{n}, where 
@var{n} is the line number shown by the @code{history} command.

@item !-@var{n}
refers to an event by its relative position in the history
list.  It refers to the command line @var{n} before the current line.

For example:

@example
bash$ echo a
a
bash$ echo b
b
bash$ !-2
echo a
a
bash$
@end example

@noindent
@samp{!-2} may be used to re-run the command prior to the last command
entered.  Successive usage of @samp{!-2} may be used to cycle the last
two commands.  In fact, the last @var{n} commands may be cycled through
repeatedly by using @samp{!-@var{n}}.

@item !@var{string}
refers to the most recent command @emph{beginning} with @var{string}.

@item !?@var{string}
@itemx !?@var{string}?
refers to
the most recent command containing @var{string}.  The closing
@samp{?} is optional, and is necessary only when you need to separate
the event designator from additional text.
@c explain need to separate

Here's an example.  Given the following two commands, entered in this
order:

@example
bash$ cp /etc/motd ~
bash$ rcp /etc/motd unsuspecting:/etc/motd
@end example

@noindent
@samp{!cp} matches the first command, while @samp{!?cp} matches the
second command.

@item !#
@itemx !:#
both refer to the current line so far.  For example:

@example
bash$ echo foo !#
echo foo echo foo
foo echo foo
bash$
@end example
@end table

No matter which way you choose to refer to an event, the shell searches
its history list from the most recent event to the least recent event,
until it finds a match for your request.  If your request is too
ambiguous,
@c what ambiguity is possible?  all are numbers or refer to most recent
or if no such event exists, you are given an error message.

Whenever the shell sees the special character
@samp{!} in a command line, it checks the history list and makes the
appropriate substitution.  There are some exceptions:  if @samp{!} is
followed by a @key{SPC}, @key{TAB}, @key{RET}, @samp{=} or @samp{(}, or
preceded by @samp{<} or @samp{|}, history substitution does not take
place.
@c should samp's in above be kbd's?  should key's be wrapped in kbd's?
@c why are those contexts exceptional?  what DOES happen?
@c why not also preceding b [, for filename patterns?

@node Words, Modifiers, Events, History
@section Words Within Events

@cindex history, words in
@cindex history, selecting words
@cindex words, selecting from history
It is possible to select and use only portions of an event.  You can
select any word, or series of words, from an event.  Several words
surrounded by quotes are considered to be one word.
@c single quotes? double quotes?

The words of an event line are numbered from left to right, with the
first word (the command name) being 0.  For example:

@example
bash$ echo one two three four five
@end example

@noindent
In this example, word 0 is @code{echo}, and word 5 is @code{five}.

To specify a particular word from a previous event, follow the event
specification with a colon, @samp{:}, and a designator for the desired
word, or words, from that event.  The word designators are:
@c must define 'event spec' above

@table @code
@item 0
The number 0 represents the first word, which is almost always the
command name.

@item @var{n}
This matches the @var{n}'th word.

@item ^
This is a special notation representing the first argument (that is,
word 1).

@item $
This is a special notation representing the last argument.

@item %
This represents the word matched by the most recent pattern search,
@code{?@var{string}@r{[}?@r{]}}.

@item @var{x}-@var{y}
This matches a range of words.
@c inclusive

@item -@var{y}
This is equivalent to the range @code{0-@var{y}}.

@item *
This matches all the words after word 0, up to and including the last
word.  This is similar to matching the range @code{^-$}, except
@code{*} can match 0 or more words, while @code{^-$} must match 1 or
more words.

@item @var{x}*
This is equivalent to the range @code{@var{x}-$}.

@item @var{x}-
This is equivalent to the range @code{@var{x}-($-1)}.
@c what's that useful for?  looks bizarre
@end table

The @samp{:} that separates the event specification from the word
designator can be omitted if the word designator begins with a @kbd{^},
@kbd{$}, @kbd{*} or @kbd{%}.
@c but not - ?
When referring to the immediately
preceding command, you can omit the line identifier if you want.
Therefore, @samp{!:2} refers to word 2 in the previous command line.@refill

Note that @samp{!} alone on a line means nothing in terms of history
expansion.  Also, if an event contains more than one command line
separated by semicolons, the semicolons count as words too.

Here are several examples using the various word designators in the
above table:

@example
bash$ mkdir /nfs/cwjcc/fs2/src/Gnu/src/bash/1.06
bash$ mv bash.tar.Z !$
mv /nfs/cwjcc/fs2/src/Gnu/src/bash/1.06
bash$ cd !$
cd /nfs/cwjcc/fs2/src/Gnu/src/bash/1.06
@end example
@c should the mv response include bash.tar.Z ??

@noindent
This example uses the shorthand for the last word on a command line to
avoid typing in a lengthy path name more than once.
@c show equivalent & explain that !=prev cmd, $=last wd

@c need a REAL example
@example
bash$ echo a
a
bash$ !! b
echo a b
a b
bash$ !! c
echo a b c
a b c
bash$ echo !*
echo a b c
a b c
@end example
@c above, shows expanded cmd before does it.
@c not all examples do, but all should

@noindent
This example demonstrates how you can build up a command line
with successive applications of the @samp{!!} notation.  You then use
the @samp{!*} expansion to make use of all arguments accumulated so
far.

@example
bash$ cc -o prog -g a.c b.c c.c
bash$ cmd=!:0 output=!:2 optimize=!:3 files="!:4-$"
@end example
@c what's cc, what's cmd= ?

@noindent
@c explain
This shows one possible use of the history facilities to break up
command lines into individual elements.  After the second command, the
individual portions of the command may be reused, perhaps to print the
source files just compiled with @samp{lpr $files}.

@node Modifiers, History Size History, Words, History
@section Modifying Previous Events

@cindex history, modifying previous events
@cindex events, modifying previous
@cindex modifying previous events
Sometimes you don't want to re-execute an event exactly.
Perhaps you
mis-typed a file name, or want to substitute a new pathname, or a
different argument.  Whatever the reason, you can modify an event, or
any word of an event, by following that event with a colon, @samp{:},
and a modifier.

Here is a list of modifiers and their explanations:

@c terminology to explain: pathname, head, filename extension, basename, tail
@table @code
@item h
This removes the last element of a pathname, leaving the only the @emph{head}.

@item r
This removes a filename extension, or trailing suffix
@samp{.@var{xxx}}, leaving only the @emph{root}.

@item e
This removes all @emph{but} the filename @emph{extension}, or trailing suffix
@samp{.@var{xxx}}.

@item t
This removes all of the leading pathname components, leaving only the
@emph{tail}.

@item s/@var{string1}/@var{string2}
This @emph{substitutes} the value of @var{string2} for @var{string1} the
first time it appears.  If the @code{g} flag is given as well, the
changes take place globally; that is, all occurrences of @var{string1}
are replaced with @var{string2}.

@item p
This @emph{prints} the new command but does not execute it.  This
allows you to preview the effects of modifiers safely.

@c s and gs added by KELLEM
@item s/@var{this}/@var{that}
substitutes the first occurrence of @var{this} with @var{that} on
the specified history line.

@item gs/@var{this}/@var{that}
globally substitutes @var{this} with @var{that} on the specified
history line.
@end table

The modification is applied only to the first applicable word
on the line.  If there are two or more occurrences on that line, the
subsequent occurrences are not changed.  If no word on the line is
applicable, then you get an error message.

Here are some examples of reusing command lines with slight
modification:

@example
bash$ diff -c2 old/shell.c shell.c > shell.diffs
bash$ !!:gs/shell/builtins
diff -c2 old/builtins.c builtins.c > builtins.diffs
@end example

@noindent
This example demonstrates the use of the substitution mechanism to
re-run a command.  This example may be used repeatedly to create
``diffs'' of a number of changed files without retyping the lengthy
command each time.

@example
bash$ echo /a/b/c/d
bash$ head="!:1:h" tail="!:1:t"
bash$ echo $head $tail
/a/b/c d
@end example
@c what's the = ? variable setting?

@noindent
This shows a possible use for the filename splitting facilities.

@example
bash$ edit file.c
bash$ f="!:1:r" ; echo making $@{f@}.o ; make $@{f@}.o ; unset f
@end example

@noindent
This is a rather clumsy way to remake an object file from a
just-modified source file.  While this example shows the use of the
history library, there are easier ways to remake an object file.  For
example you can encapsulate the @code{echo} and @code{make} into a
function, like this:

@c ?
@example
bash$ type make_o
make_o is a function
make_o ()
@{
     echo making $@{1@}.o
     make $@{1@}.o
@}
bash$ edit file.c
bash$ make_o !:1:r
make_o file
@end example

@node History Shortcuts, History Protection, History Size History, History
@section Shortcuts

@cindex command lines, making changes to
@cindex command lines, history library and
A @samp{^} at the beginning of a command line is a special way to
designate that you want to make changes, or corrections, to the
previous command line.  In this case, @samp{^} is equivalent to
@samp{!:s^}, and provides a convenient and special shorthand for making
substitutions to the (immediately) preceding event.  The syntax for
this substitution is:

@example
^@var{old}^@var{new}
@end example

@noindent
The @var{old} characters between the two @samp{^} are replaced by the
@var{new} characters following the second @samp{^}.  For example:

@example
bash$ mroe parse.y
bash: mroe: command not found
bash$ ^mroe^more
@end example

@noindent
The first command contained a spelling error, resulting in an unknown
command.  Using the quick substitution feature, we can rerun the
command with the correct spelling substituted.

@node History Protection,  , History Shortcuts, History
@section Delimiters

You can delimit a history substitution from the characters that follow
it by surrounding that substitution with @samp{@{}and @samp{@}}.  For
example:

@example
bash$ make flags.o
          @r{[} errors compiling flags.c @r{]}
bash$ edit @{!$:r@}.c
@end example
@c explain: !... means last arg basename, namely 'flags'

@noindent
In the above example, we attempt to use the @code{make} command to
create @file{flags.o} from @file{flags.c}.  There are errors in
@file{flags.c}, so history substitution is used to create the name of
the source file so that it can be edited.

@c can't understand next paragraph -- what makes the {} a NOP?
@c also, if braces not needed here, need better example.
While braces are not strictly necessary in this example, note that the
braces are not treated specially by the history substitution mechanism
in any way.  This works because brace expansion is enabled on our
version of BASH.  @emph{If brace expansion is not enabled, enclosing a
history substitution in braces will cause those braces to be retained.}

@node Quotation,  , echo, File Names
@chapter Preventing Shell Interpretation of Special Characters

@c Is quoting for other parts of commands too, or just for wildcards?
@c (Current chapter separated from old wildcard chapter)
@c sounds more general

@cindex command lines, quoting
@cindex quoting
There are times when you want the shell to treat special characters as
regular characters, and not expand or interpret them.
@c what does 'interpreted' mean?  different from 'expanded'?
To do this,
you must @dfn{quote} the special character by preceding the character
with a @samp{\} or by surrounding the character (or part of
the argument containing it) with single or double quotes.
@c justification?  isn't it bad & very rare to have file names with
@c special chars in them?

@table @code
@item \
The backslash, @samp{\},
forces the character that follows it to have its literal
meaning, suppressing any special interpretation in the shell.
Exception: A
backslash followed by a newline character signifies a continuation of
a shell command line onto the following line (@pxref{Continuation}).
@c newline=RET ?
  
Note that the backslash protects a single character, not a string
of characters.

For example, @samp{rm bad*name} deletes all files whose names start with
@samp{bad} and end with @samp{name}, whereas @samp{rm bad\*name} deletes
only the file named @file{bad*name}.  The @samp{\} prevents the shell
from interpreting the @samp{*} as a wildcard.

You can protect the backslash itself from being interpreted by the
shell by preceding it with another backslash.
@c example

@item '@dots{}'
Single quotes turn off the special meanings of @emph{every} character
between them.  All these characters are taken literally.  This allows
you to include blank characters in a string.  For example:
@c huh? why are blanks interesting?  how relate to file names?
@c '...' equivalent to \ in front of every char?

@c what does example have to do with wildcards?
@c what are such strings for?
@example
'This $#?!!# sentence is taken literally.'
@end example
@c example with > 1 wildcard instead?  e.g. rm bad?*name vs.
@c  rm bad'?*'name = rm 'bad?*name'

Note that even the backslash character is treated literally between
single quotes.  Therefore, there is no way to include single quotes
themselves in the string.
@c explain or remove

@item "@dots{}"
Double quotes turn off the special meanings of every character between
them @emph{except} @samp{$}, @samp{'}, and @samp{\}.  The characters
@samp{$} and @samp{'} retain their special meanings within double
quotes.  When surrounded by double quotes, the backslash, @samp{\},
retains its special meaning only when followed by @samp{$}, @samp{`},
@samp{"}, @samp{\}, or the newline character.
@c whole "" section has no clear relation to filename wildcards

For example:

@c example not related to file names
@example
"The value of test is $test."
@end example

You can protect a double quotation mark from being interpreted by the
shell by preceding it with the backslash character, as in @samp{\"}.
A double quote may be quoted within double quotes by preceding it
with a backslash.

Warning: the special parameters @samp{$*} and @samp{$@@} have special
meanings when inside double quotes (@pxref{Predefined}).
@end table

@c following par: need examples of why/when need such chars quoted
You should quote any special character if you
do not want the shell to use that character's special meaning. 
Therefore quote all redirection operators, wildcard characters,
command-line characters, quote characters, and grouping characters if
they are to represent themselves.  In particular, the following
characters should be quoted if they are to represent themselves:
@cindex quote, when to

@example
  !  |  &  ;  <  >  (  )  $  `  '  "  \  *  ?  [  ]  #
@end example
@c above is all special chars?  what about : { }  (others?)

@noindent
In addition, you should always quote the space, tab, and newline
characters if they are not to be interpreted by the shell.  You can
use single or double quotes around an entire argument or word, or
around just part of one.  For example:

@example
make CC="cc -O"
@end example
@noindent
shows how to specify @samp{cc -O} as the compilation command.

@node Advanced Redirection
@chapter Redirecting Input and Output (Advanced)

@node Other Redirections, Pipes, Here-documents, I/O
@section Redirection Using File Descriptors

@cindex redirection operators, with file descriptors
@cindex file descriptors
@cindex standard input, redirecting
@cindex standard output, redirecting
@cindex standard error, redirecting
@cindex redirecting input and output
The basic redirection operations (@pxref{Redirection})
are actually special cases of a more general mechanism for
affecting the input and output files used by programs.

Programs actually do their input and output in terms of @dfn{file
descriptors} (non-negative integers) that are associated with files or
devices.
@c bfox: file descr is index to array of file info
For example, a program might read from file descriptor 3 and
write to file descriptors 6 and 8.
The redirection operators are a means of associating open files with
file descriptors, so that such a program will use the desired files.

In order for the shell to be able to set up command input and output
in simple, general ways -- hooking commands together with pipes
(@pxref{Pipes}) or redirecting input and output to files as shown
earlier (@pxref{Redirection}) -- certain conventions have been
established for file descriptors.  Descriptors 0, 1, and 2
are generally used as follows:

@table @asis
@item 0
is called @dfn{standard input}.
Programs usually read their input from standard input.
@cindex standard input, file descriptor 0

@item 1
is called @dfn{standard output}.
Programs usually write their output to standard output.
@cindex standard output, file descriptor 1

@item 2
is called @dfn{standard error}.
Programs usually write their error messages to standard error.
@cindex standard error, file descriptor 2
@end table

Other file descriptors have no standard meaning.

You can redirect any file descriptors you like, but
not all redirections make sense.  In particular, redirecting a file descriptor
number that the program doesn't use will have no effect.

In general, a redirection using file descriptors looks like this:
@ignore
@c they were each shown with args, but it's probably better to consider
@c those as part of the command.  E.g. it was:
@var{command} @r{[}@var{arguments}@r{]} @r{[}@var{n}@r{]}> @var{m}
@end ignore
@example
@var{command} @r{[}@var{n}@r{]}@var{redirection-operator} @var{m}
@exdent @r{or}
@var{command} @r{[}@var{n}@r{]}@var{redirection-operator} @var{file}
@end example

@noindent
where @var{n} (which is optional) and @var{m} are file descriptors,
@var{file} is a file,
and the @var{redirection-operator} is as described below.

Warning:
If @var{n} is supplied, there must not be any space between it
and the operator.

If the file descriptor @var{n} is omitted and the first character of
the redirection operator is @samp{<}, @var{n} defaults to the
standard input (file descriptor 0).  If @var{n} is
omitted and the first character of the redirection operator is
@samp{>}, the @var{n} defaults to the standard output (file
descriptor 1).

@table @code
@item @var{n}> @var{file}
@itemx @var{n}>| @var{file}
@itemx @var{n}>> @var{file}
open @var{file} for output on file descriptor @var{n}.
@var{n} defaults to 1 (standard output).
Thus the operators @samp{>}, @samp{>|}, and @samp{>>} described earlier,
which redirect standard output, are equivalent to @samp{1>}, @samp{1>|},
and @samp{1>>} respectively.
@cindex @code{>} operator, with file descriptor
@cindex @code{>|} operator, with file descriptor
@cindex @code{>>} operator, with file descriptor

@c following itemize is exact copy from basic chapter
@itemize @bullet
@item
If @var{file} doesn't yet exist, it is created.

@item
If @var{file} already exists:
@itemize @bullet
@item
With @samp{>} and @samp{>|}, @var{file} is erased before the
first output is written to it.  Be careful:
If a file of the same name already exists,
its contents are deleted before your command's output is
written to that file.
If you don't want @samp{>} to erase existing files, set the
shell's @code{noclobber} variable; then
@samp{>} with an existing file will generate an error message and leave
the file alone.  (But note that @samp{>|} will clobber existing files
regardless of the setting of the @code{noclobber} variable.)

@item
With @samp{>>}, the output is appended to the end of an existing @var{file}.
@end itemize
@end itemize

For example:

@example
bash$ find / -name resume -print 2> /dev/null
@end example

@noindent
This command looks for and prints the pathnames of all files
named @file{resume} by traversing all directories under the @file{/}
directory.  When @code{find} encounters permission problems (for
example, directories it does not have permission to read) it prints an
error message on standard error.  The above redirection @samp{2>
/dev/null} forces all these error messages to be written to the special
file @file{/dev/null}, which simply discards these messages so that
only the requested @file{resume} files are printed on standard output. 
This saves you from wading through pages of uninteresting error messages
from @code{find}.
@c rewrite in terms of utility for redirecting just error w/o output

@item @var{n}< @var{file}
opens @var{file} for input on file descriptor @var{n}.
@var{n} defaults to 0 (standard input).
Thus the operator @samp{<} described earlier, which redirects standard
input, is equivalent to @samp{0<}.
@cindex @code{<} operator with file descriptor
@c what if n=1 or 2(output)?
@c I tried 'who 1< foo' . Got err msg if foo not exist, no err msg but
@c    also no output if foo existed (foo left untouched)
@c bfox: probably who wrote to 1, but it was open for read, not write,
@c   but who didn't check for errors on write

@cindex redirection operators, reading and writing
@item @var{n}<> @var{file}
opens @var{file} for both reading and writing on file descriptor @var{n}.
@var{n} defaults to 0 (standard input).
@cindex @code{<>} operator, redirecting input and output

As with @samp{>} (above), an existing @var{file} is erased before the
first output is written to it unless the shell's @code{noclobber}
variable is set (in which case @samp{<>} with an existing file will
generate an error message and leave the file alone.)

@item @var{n}>& @var{m}
makes the file descriptor @var{n} be a copy of the file descriptor @var{m}.
@var{n} defaults to 1 (standard output).
@c  no requirement that n and/or m be output descriptors?
@c  n=0(input)  seems harmless
@c what if m=0(input)?  1>&0 seems to be NOP w no msg
@c   e.g. date 0<foo 1>&0 sends output (1) to tty, not to foo
@cindex @code{>&} operator with file descriptor

Thus the redirection @samp{>&@var{file}} described earlier, which
redirects standard output and standard error to the @var{file},
is equivalent to @samp{>@var{file} 2>&1}.

For example :

@example
bash$ make >make.log 2>&1
@end example

@noindent
@code{make} produces output both on the standard output (as it executes
commands) and on the standard error (in the case that a file didn't
compile correctly, etc.).
The first redirection operator on the line says to send output for
the standard output into a file called @file{make.log}.
The second redirection causes
output to file descriptor 2 (the standard error) to be output wherever
the output from file descriptor 1 is going (the standard output).  
Thus, both the standard error and standard output are written to
@file{make.log}.  (There is a shorthand for
redirecting both the standard output and the standard error to a single file.
@xref{Redirection}, @samp{>&@var{file}}.)

@item @var{n}<& @var{m}
makes the file descriptor @var{n} be a copy of the file descriptor @var{m}.
@var{n} defaults to 0 (standard input).
(Note that @code{@var{n}<& @var{m}} and @code{@var{n}>& @var{m}} behave
identically except when @var{n} is omitted, in which case they have
different defaults.)
@cindex @code{<&} operator with file descriptor

@c note: (bfox) >&- same as <&-, only diff is default value of n
@item @r{[}@var{n}@r{]}>&-
closes the file descriptor @var{n}.
@var{n} defaults to 1 (standard output).
@c bfox: closes file &  removes association of file w. n

@item @r{[}@var{n}@r{]}<&-
closes the file descriptor @var{n}.
@var{n} defaults to 0 (standard input).
(Note that @code{@r{[}@var{n}@r{]}<&-} and @code{@r{[}@var{n}@r{]}>&-}
behave identically except when @var{n} is omitted, in which case they
have different defaults.)

@end table

@heading Multiple Redirections

More than one redirection operator can appear in a command.
@cindex redirection operators, using multiple
@emph{The order in which redirections are specified is important.} The
shell evaluates redirection operators in the order encountered, from
left to right.  A file descriptor specified with an earlier
redirection operator can be used by a subsequent redirection.  For
example:

@c strange example: plain >& does it without file descriptors
@example
ls > error-list 2>&1
@end example

@noindent
redirects first the standard output (@code{>})
and then the standard error (@code{2>&1}) to the
file @file{error-list}, while the command:

@c strange example: plain > does it without file descriptors
@example
ls 2>&1 > error-list
@end example

@noindent
redirects only the standard output to the file @file{error-list}.  The
first redirection operator @code{2>&1}
makes the standard error (2) be a copy of the
standard output (1) @emph{before} the standard output is redirected to
@file{error-list} with @code{>}.

@heading Redirection in Pipelines

Each command in a pipeline may
include redirection operators.  These redirections are performed after
the pipes that link the commands are created.
That is, first the standard input and standard output of each command
in the pipeline are set up as specified by the pipes, then any
redirections specified in the commands are performed.
Thus such a redirection can access the standard input and output set up
by the pipeline.  For example, @samp{2>&1} in the first command in
a pipeline makes that command's standard error be the same as its standard
output, hence sends the command's error messages along with its ordinary
output to the second command in the pipeline.

@node Here-documents, Other Redirections, Redirection, I/O
@section Redirection to Shell Scripts

@c what are << and <<- for? shellscripts?  probably not a good idea at
@c tty, so examples with prompts are poor.
@c  bfox: also good in functions
@c Posix p.172 calls it 'here-document' in 'shell input file'
@c add Intro here to explain it.
@c bfox: say it is traditionally called here-document
In general, such a redirection of input looks like this:

@ignore
@c they were each shown with args, but it's probably better to consider
@c those as part of the command.  E.g. it was:
@var{command} @r{[}@var{arguments}@r{]} << @var{word}
@end ignore
@example
@var{command} @var{redirection-operator} @var{word}
@end example

@noindent
where the @var{redirection-operator} is as follows,
and spaces surrounding it are optional:

@table @code
@item <<
instructs the shell to read input for @var{command}
from the same place as the shell is reading commands from.
The shell reads lines
until a line containing only the given @var{word} (with no trailing blanks) is
seen.  All of the lines read up to that point are considered the input
for the @var{command}.
@cindex @code{<<} operator
For example:

@c example was CAT << foo, but sort seems more interesting.
@c Need a real example.
@example
bash$ sort << foo
hip
hip foo
hooray
and
foo
and
hip
hip foo
hooray
bash$
@end example

@noindent
The four lines after @samp{sort << foo} became the input to the
@code{sort} command.  The fifth line, containing @samp{foo} on a line by
itself, marked the end of the input.  (Note that the @samp{foo} in the
second input line did not end the input because the line contained other
text as well.)  The four lines after the end of the input are
the output of the @code{sort}, namely the input lines in alphabetical order.

@item <<-
@samp{<<-} is like @samp{<<}, except that leading tab characters are
stripped from each line of input as it is read.
@c how justify version that strips tabs - bfox: for formatting?
@cindex @code{<<-} operator
@end table

@c Posix says can have more than one <<, <<- in command.
@c cover that?  True of any other redirection operators?


@node Grouping
@chapter Grouping Commands

@c placeholder for stuff to rewrite completely
@c new concept: subshell, shell environment, [non]interactive shell

@table @code
@item @{ @var{list}; @}

@c what is format of the list?
Curly braces are used to group commands.  The list of commands is
executed in the current shell environment.  The curly braces
must either begin a line, follow a @samp{;}, or be surrounded with
whitespace for the shell to recognize them as grouping commands.  For
example:
@cindex commands, grouping
@cindex grouping commands, using @{ @}

@example
bash$ foo=bar
bash$ @{ ls -l ; echo "Listing finished."; echo $foo @} >listing
@end example

@noindent
lists the files in the current directory, outputs ``Listing finished.'',
and outputs ``bar'', all of which is redirected into the file
@file{listing}.  Unlike the following example, the grouping commands do
not start a subshell, so the current shell's variables are available for
use.

@item (@var{list})
@c what is format of the list?
The list of commands is executed in a subshell.  Variable assignments
and built-in commands that affect the shell's environment do not remain
in effect after the command finishes.
@cindex grouping commands, using ( )
@cindex commands, grouping

The fact that commands within parentheses are executed within a
subshell means that the parent shell is unaffected by shell
side-effects of those commands.  Changes in shell state caused by
commands executed in a @emph{subshell} do not affect the parent shell. 


Let's illustrate:
@c silly example -- the cd in the subshell is useless

@example
bash$ pwd
/home/alan/work
bash$ (cd ..)
bash$ pwd
/home/alan/work
bash$ cd ..
bash$ pwd
/home/alan
bash$ 
@end example

@noindent
In this example, the current working directory is
@file{/home/alan/work} as shown by the output of the @code{pwd}
command.  The command @code{(cd ..)} executes in a @emph{subshell} so
that it does not change the current directory of the parent shell and
the user remains in the original directory, @file{/home/work/alan}.

However, when the command @code{cd ..} is executed in the parent shell
(that is, it is executed without being surrounded by parentheses) the
parent shell's current working directory is changed to
@file{/home/alan}.
@end table


@node Aliases, Functions, Line, Top
@chapter Aliases

@cindex alias
@cindex shorthand, command names
@cindex command name shorthand
Aliases are a way to rename, redefine, or otherwise rearrange commands
to your liking.  An alias is created using the following syntax (note
that there cannot be any spaces before or after the @samp{=} sign):

@example
alias @var{name}=@var{expansion}
@end example

@noindent
The @var{name} is the command-name shorthand you want to enter at the
shell prompt.  The @var{expansion} is the command that
the @var{name} will stand for.  For example:

@example
alias more=less
@end example

@noindent
causes the program @code{less} to be substituted for the operating
system's @code{more} program every time the word @samp{more} is typed. 
@c next sec says: any time typed as command part (1st part) of cmd

@c ? I don't understand this text & example
@c  see kellem's example below
If the last character of the value for the alias,
@var{expansion}, is a blank, then the word following the alias
will also
@c ? also = in addition to the cmd part of the line?
be checked for substitution.  For example:@refill

@example
alias time='time '
@end example

@noindent
allows you to time a command for which you have defined an alias. With
this alias you can time what you would be running if you typed the
expanded version as a command.

For example, let's say you defined an alias @samp{alias more=less}. 
Normally, if you type @samp{time more}, @file{more} is
timed.  However, if the @samp{time} alias has been previously defined,
typing @samp{time more} times @file{less}, which is
what you want.  The alias @code{more} is expanded, and its value
(@code{less}) is substituted as the program to time.

If the value for the alias, @var{expansion}, contains spaces,
tabs, or metacharacters,
@c ? metachar means M-... ?  What's reason to include metas, not C- etc.?
you must enclose that definition in quotes
to avoid misinterpretation by the shell.  For example,
let's say that you use the command-option sequence @samp{ls -la} at
lot.  You can assign this command to the alias @code{la} to
make typing quicker and easier:

@example
alias la='ls -la'
@end example

@noindent
Now you can type @samp{la} instead of @samp{ls -la} when listing files.

@c KELLEM: you can make aliases for arbitrary text,
@c that is all an alias really is (a text substitution).  can be useful for
@c bash$ alias foo=some.host.somewhere
@c bash$ alias rlogin="rlogin "
@c bash$ rlogin foo
@c   is same as `rlogin some.host.somewhere'

@cindex aliases, listing
To get a list of all the currently defined aliases, simply type the
@code{alias} command with no arguments.  A list of aliases in the form
@samp{@var{name}=@var{value}} is displayed on the standard output.  If
you want to know if a specific shorthand name has any aliases, you can
type:@refill

@example
alias @var{name}
@end example

@noindent
This tells you if any aliases exist for that specific @var{name}.

@cindex aliases, the shell and
Aliases are local to the shell in which they were declared.  This means
that aliases can't be used within shell scripts @emph{unless those
aliases were declared in that script}.  This means that the alias
command has to be executed in the shell script before the command which
references that alias is read.  
It also means that aliases disappear when their shell is terminated. 
@emph{BASH aliases cannot be exported to another shell.}  To get BASH
to remember an alias permanently, you have to enter that alias in your
login file (@pxref{Start-up}).

@menu
* Advanced Aliasing::  Creating aliases for complex commands.

* Remove::             Removing aliases.
@end menu

@node Advanced Aliasing, Remove, Aliases, Aliases
@section Creating Aliases For Complex Commands

@cindex aliases, complex
@cindex aliases, string substitution and
@cindex string substitution and aliases
While you can use simple string substitution with aliases, note that
the @code{alias} command is limited to expanding only the first word in
a command.  Using pipes, @samp{|}, semicolons, @samp{;},
@samp{&&} (@sc{and}) and @samp{||} (@sc{or}), it is possible to have more
than one command sequence per command line.
@c ? terminology problem is killing us here -- command meaning either
@c prog to run or simple cmd with args or compound command
In this case, you can have
more than one alias on the command line, but you can still only have
one alias per command.  For example, let's create two more
aliases:@refill

@example
bash$ alias listdir='ls'
bash$ alias linecount='wc -l'
@end example

@noindent
and combine those aliases on one command line:

@example
bash$ listdir | linecount
@end example

@noindent
The @code{alias} command expands @code{listdir} to @code{ls} and
@code{linecount} to @code{wc -l} because @code{listdir} and
@code{linecount} begin @emph{separate} commands.@refill

@cindex aliases, versus functions
@cindex aliases, using functions instead of
@cindex functions, versus aliases
@cindex functions, using instead of aliases
If you need more complicated expansion in a command line, use a shell
function (@pxref{Functions}).  In particular, there is no mechanism in
BASH for using arguments in the replacement text of aliases.  If
arguments are needed, a shell function should be used instead of an alias.

@cindex aliases, multiple commands and
@cindex multiple commands, aliases and
You can also make aliases that represent multiple commands.  For
example, you can create an alias that goes to a directory of your
choice (@code{cd}), lists what is in that directory in long form
(@code{ls}), and shows you the
total disk space used by that directory (@code{du}):

@c KELLEM: dashes are not allowed in POSIX.2 draft 10 in aliases (not a valid
@c shell identifier), I believe.  'course, the dashes are fine with me. :-)
@example
alias m-use='cd /usr/spool/mail; ls -la; du'
@end example

@noindent
To use this alias, just type @code{m-use}.

@c ref for keywords?  Is there a list of keywords somewhere?
Lastly, you can alias keywords.  For example, if you would rather end
the @code{do} part of a loop command (@pxref{Conditionals and Loops})
with @code{od} than with the normal @code{done}, you can

@example
bash$ alias od=done
bash$ for i in 1 2 3
> do
> echo $i
> od
1
2
3
@end example

@node Remove,  , Advanced Aliasing, Aliases
@section Removing Aliases

@cindex aliases, removing
@cindex removing aliases
@cindex @code{unalias} command
@cindex aliases, the @code{unalias} command
To get rid of aliases, use the @code{unalias} command.  This command
looks like this:

@example
unalias @var{name1} @var{name2} @dots{} @var{nameN}@refill
@end example

@noindent
The @code{unalias} command removes all the named aliases from the list
of defined aliases.  For example:

@example
unalias m-use
@end example

@noindent
removes the @code{m-use} alias, if present.

@node Variables, Environment, Scripts, Top
@chapter Shell Variables

@c need new introduction

@c bfox: home etc.: bash tries to get from env, if not there, creates
@c  * etc. are really predefined
@c 5 kinds of vars: 
@c  inherit or create (e.g. home)
@c  predefined (*, @, ...)
@c  magic vars -- auto_resume, noclobber -- control shell's internal operation
@c  user vars
@c  dynamic vars -- seconds, etc.

@c to coordinate -- what is explained here vs. customization chapter re
@c  how to set/unset a var, see its value, etc.

@cindex variables, what are
@cindex shell variables
@cindex shell variables, types of

@node Variable Mechanics
@section Mechanics of Named Variables

Shell behavior that depends on a variable may depend on:

@itemize
@item
the value of the variable

@item
whether the variable exists (is set), independent of what value it has
@end itemize

Thus, in order to configure a shell variable to get the effect you want,
you may need to know:

@itemize
@item
how to tell whether a variable exists (is set)

@item
how to create (set) a variable

@item
how to unset a variable (make it cease to exist)

@item
how to find out the value of a variable

@item
how to change the value of a variable
@end itemize

To find out the value of a variable, type
@samp{echo $@var{name}}, where @var{name} is the variable of interest.
(Be sure to include the @samp{$}:  If you omit it, @code{echo} just
repeats the @var{name} itself.)
@itemize
@item
If something is printed, that is the value of the variable.

@item
If nothing is printed, then either the variable exists and has a null
(invisible) value, or the variable does not exist.
@end itemize

@noindent
More generally, to get the value stored in a variable, precede the variable's
name by a dollar sign, @samp{$}.
@c explain what 'more generally' is

To set a variable (create a new variable or change the value of
an existing variable), type
@samp{@var{name}=@var{new-value}},
where @var{name} is the variable you want to set and
@var{new-value} is the value you want it to have.
Don't leave any blank space around the @kbd{=}.
If you just want to create the variable, and don't need to give it any
particular value, you can simply omit the @var{new-value}
and type @samp{@var{name}=}.

The name of a shell variable must start with a letter or an underscore
and it can contain only letters, digits, and underscores.
Uppercase and lowercase letters are not equivalent in names.
Be careful to type variable names correctly:
If you type a name wrong before an @samp{=}, you will either change
the wrong variable or create a new variable.

To include whitespace (spaces, tabs, or newline characters) in a
variable's value, either quote the value with @code{"@dots{}"} or
@code{'@dots{}'}, or precede each whitespace character with a backslash,
@samp{\} (@pxref{Quotation}).

@c bfox: this stuff is done at assignment time
@c Value undergoes tilde expansion, parameter and variable expansion,
@c command substitution and quote removal.

To get rid of a variable, type @samp{unset @var{name}},
where @var{name} is the variable of interest.

To find out whether a variable exists, you can do any of the following:
@itemize
@item
Type @samp{set} to get a listing of all your shell variables in
alphabetical order, and see if the variable is in the list.

@item
Type @samp{set | grep @var{name}=}.
If the variable @var{name} exists, its name (and value, if non-null) will be given;
otherwise there will be no output.

@item
Type @samp{set -u}
@c substitute new equivalent: something like
@c  set -o nounset
to tell the shell to make @code{echo} of an unset
(nonexistent) variable give an error message.
From then on, @samp{echo $@var{name}} will be different for nonexistent
variables than for variables with null values.
@end itemize

Warning: @code{set} and @samp{unset} are not inverse commands:
Although @code{unset} unsets shell variables, @code{set} does not set
them.

@node Variable Examples, Positional, Variables, Variables
@subsection Examples with Named Variables

@c need more examples
@c may integrate with parent section (mechanics)

Here are some examples of user-defined variables:

@example
bash$ test=This\ is\ a\ test
bash$ test_2="This is also a test"
bash$ test_3='Yet another test'
bash$ echo $test
This is a test
bash$ echo $test_3
Yet another test
@end example

To prevent @samp{$} from meaning ``evaluate the following variable,''
precede the @samp{$} with a backslash, @samp{\}, or enclose @samp{$} and
the reference in single quotes.
@c note: not double quotes
@c explain diff between single & double quotes
For example:

@example
bash$ echo \$test
$test
bash$ echo '$test'
$test
bash$ echo $test
This is a test
@end example

@node Positional, Predefined, User-definable, Variables
@section Positional Parameters

@cindex positional parameters
A program, shell function, or shell script needs a way to refer to
arguments passed to it on the command line that invoked it.  The shell
provides for this by means of special variables called @dfn{positional
parameters}.

The name of a positional parameter is a positive integer.

The value of a positional parameter is whatever the shell assigns
it from a command line, or whatever you assign it with
@code{set} or @code{shift} (described below).

To evaluate a positional parameter, precede its
name by a dollar sign, @samp{$}, just as you would a named variable.
But if the parameter name is longer than a single digit, you must
enclose it in braces.  For example, you'd type
@kbd{$@{10@}} to refer to the value of parameter @samp{10}.

When you give a command, the arguments are put into consecutive
positional parameters starting with @code{1}.

For example, assume we have a script named @code{args}
that simply echoes its first two arguments to the standard output.
That is, the script contains just the command
@samp{echo $1 $2}.  Then @code{args} behaves as follows:

@example
bash$ args 1 3
1 3
bash$ args hi there
hi there
bash$ args hi there everybody
hi there
bash$ 
@end example

@xref{Predefined}, for information about the parameter @code{0},
which holds the name of the current command,
the parameters @code{*} and @code{@@}, which refer to all
the positional parameters at once, and the parameter @samp{#},
which holds the number of positional parameters (the current
number of arguments).

The @code{set} command can be used to assign new values to positional
parameters.  The command

@example
set @var{values}
@end example

@noindent
assigns the given @var{values} to consecutive positional parameters 
starting with @code{1}.  For example, if we augment the above
@code{args} script to be

@example
echo $1 $2
set new message
echo $1 $2
@end example

@noindent
then it will modify its positional parameters, replacing the
command-line arguments with @code{new} and @code{message}, and will behave
as follows:

@example
bash$ args hi there everybody
hi there
new message
bash$
@end example


The @code{shift} command moves each positional parameter's value
into the parameter to its left.
The value of @code{2} is moved into @code{1}, the value of @code{3}
is moved into @code{2}, and so on.
The last parameter becomes null.

@c bfox: used to determine whether any args left on line -- example?
This is useful, for example, in a recursive shell function,
to ``cdr down'' the list of arguments.

@code{shift} can also take a numeric argument:
@example
shift @var{n}
@end example

@noindent
This causes the positional parameters to be shifted left
@var{n} positions instead of just 1 position.
The value of parameter @var{n+1} is moved into @code{1}, and so on.

For example, if we modify the above @code{args} script to be

@example
echo $1 $2
shift 2
echo $1 $2
@end example

@noindent
then it will behave as follows:

@example
bash$ args hi there everybody else
hi there
everybody else
bash$
@end example

BASH itself also has positional parameters, which you can @code{set},
@code{shift}, and examine.
The positional parameters seen by a command are distinct from
those of the invoking shell.
In this example, we set the shell's first three positional parameters
and see that they are unaffected by execution of the @code{args}
command defined above, which uses @samp{echo $1 $2} to echo its first two arguments.

@example
bash$ set one two three
bash$ echo $1 $2
one two
bash$ args hi you
hi you
bash$ echo $1 $2
one two
bash$ 
@end example

The @code{set} command is the easiest way to break a multi-word string
into elements that can be referenced individually.  This can be useful
in conjunction with command substitution (@pxref{Command Subs}).  For
example, we can set the positional parameters to the words in the output
of the @code{date} command as follows:

@example
bash$ set $(date)
bash$ echo $1 $2 $3 $4 $5 $6
Fri Feb 22 18:13:14 EST 1991
@end example

@node Predefined, Command Subs, Positional, Variables
@section Predefined Shell Variables
@c 'predefined shell vars' sound to me like ordinary vars that are defined
@c by the shell (e.g. HOME)
@c bfox: not standard terminology -- can change

@cindex shell variables, predefined
@cindex variables, predefined shell
The predefined shell variables are set by the shell.
You cannot assign them values, but
you can reference their values by prefacing their names by @samp{$}. 
The predefined shell variables are:

@table @code
@item ?
contains the exit status returned by the command that was last run in
the foreground.

@item !
contains the process identification number of the last background
command.

@item $
contains the process identification number of the current shell.

@item #
contains the current number of positional parameters (@pxref{Positional}).

@item -
contains shell options.
@c bfox: echo $- gives the options you invoked bash with (as modified by
@c set) [some subset of options -- due to new -o option]

@item 0
(zero) contains the name of the command being executed.

@item *
@itemx @@
contain a list of the positional parameters.

@c bfox:
@code{*} and @code{@@} are equivalent unless they appear
inside double quotes.
@samp{$*} @samp{$@@} are both equivalent to @samp{$1 $2 ... $@var{n}},
where @var{n} is the last positional parameter.
But @code{"$*"} is equivalent to @samp{"$1 $2 $3 @dots{}"}
and @code{"$@@"} is equivalent to @code{"$1" "$2" "$3" @dots{}}.
In other words, @code{"$*"} expands to a single word, whereas
@code{"$@@"} expands to separate words.

@c replace example
@c bfox will suppply example with FOR command
@example
bash$ cat a
this is a file named a
bash$ cat b
this is a file named b
bash$ cat c1
/bin/cat "$*"
bash$ cat c2
/bin/cat "$@@"
bash$ c1 a b
a b: No such file or directory
bash$ c2 a b
this is a file named a
this is a file named b
@end example

@noindent
This example shows the use of two scripts: @code{c1}, which tries to execute
@file{/bin/cat} on the expansion of @samp{$*}, and @code{c2}, which executes
@file{/bin/cat} on the expansion of @samp{$@@}.  When invoked with more
than one argument, @code{c1} attempts to run @code{cat} on the file whose name
is the concatenation all its arguments -- not what you would expect.  
On the other hand, @code{c2} uses @samp{$@@} and behaves correctly.
@end table

The following example sets the positional parameters to
the output of the @code{date} command and shows that that output
consists of 6 words:

@example
bash$ echo $#
0
bash$ set $(date)
bash$ echo $#
6
bash$ echo $*
Sat Aug 4 22:19:05 EDT 1990
@end example

Here's an obscure script using predefined parameters:

@example
#
# 2, 3, 4, 5 -- print in the number of columns defined by the
# name of the script.  Adapted from Kernighan and Pike.
#
/bin/pr -$(basename $0) -t -l1 "$@@"
@end example

@noindent
This file prints its input in as many columns as specified by its
name -- if invoked as "2", it prints its input in two columns.

@node Parameter Subs, Arithmetic Evaluation, Command Subs, Variables
@section Variable Substitution

@c Posix has excellent description of this, with table comparing the
@c different substitutions.  Plagiarize it.

The simplest case of @dfn{variable substitution} is the simple
@code{$@var{name}} construct, in which the value of the variable
@var{name} is substituted for @code{$@var{name}}.
More complicated constructs let you specify what should happen
if the named variable is unset or if its value is null.

@cindex parameter substitution
@cindex substitution, of parameter values
BASH's parameter substitution facility lets you test and conditionally set the
value of parameters and shell variables.
@c what's param vs. shell var 
Braces allow a variable to be
tested to see if it is defined and is not the null string.  This is
important as sometimes the value of an expression depends on whether or
not a variable has been defined.  If the colon in the following 
expansions is omitted, BASH only tests that the parameter is
unset; it does not test to see that it's unset or null.

The substitutions allowed are:

@c fix up items below to make differences clear by using a single
@c example throughout
@table @code
@item $@{@var{variable}@}
The value of @var{variable} is substituted.  The braces are required
when @var{variable} is a positional parameter with more than one digit,
or when @var{variable} is followed by a character that isn't part of
its name.
@c e.g. ${v}e -- why should that happen?

@item $@{@var{variable}:-@var{string}@}
If the named @var{variable} exists, then the expression has
the value of the variable, otherwise it has the value @var{string}. 
For example:

@example
echo $@{timenow-$(date)@}
@end example

@noindent
This echoes the current time, as stored in the variable @code{timenow}. 
If @code{timenow} isn't set, the @code{date} command is run to generate
it.
@c clarify -- date generates time, doesn't set timenow var

@item $@{@var{variable}:=@var{string}@}
If the named @var{variable} exists, then the expression has
the value of the variable, otherwise it has the value of @var{string}
@emph{and} @var{string} is assigned to @var{variable}.  For example:

@example
bash$ echo $A

bash$ echo $@{A=123@}
123
bash$ echo $A
123
@end example

@noindent
The first line of this example shows that @samp{A} is unset.
@c actually, nset or null
The second line assigns the value of 123 to @samp{A}.  Then the value of
@samp{$A} is substituted, so @samp{A} retains the value 123.
@c last sentence unclear

This form does not work with positional parameters (@pxref{Positional})
or special parameters (@pxref{Predefined}).
@c what doesn't work?  just this := case? unlikely

@item $@{@var{variable}:+@var{string}@}
If the named @var{variable} exists, then it has
@c has --> gets?
the value of @var{string}, otherwise it has no value.
@c ? otherwise not created?
For example:

@example
if [ "$@{var+set@}" = "set" ] ; then
     echo '$var' is set
fi
@end example

@noindent
This example shows a simple method to test whether or not a shell
variable is set.  If @code{var} has a value, then the expansion has the
value @code{set}, and you can test on that fact.
@c expansion?  test?

@item $@{@var{variable}:?@var{text}@}
If the named @var{variable} exists, then the expression has
the value of the variable, otherwise the message @var{text} is printed. 
For example:

@example
: $@{REQUIRED?"REQUIRED must be set"@}
@end example
@c example messed up?  colon in wrong place?

@noindent
This statement echoes @samp{REQUIRED must be set} if @code{REQUIRED} is not set. 
This can be used to inform the user that further execution of the
current script is not possible.  If you don't make this part of an
interactive script, the shell exits after printing the
message.
@c ???
If there is no @var{text} following the @samp{?}, BASH prints a standard
message.

@item $@{#@var{variable}@}
The length in characters of the value of @var{variable} is substituted. 
@c next sentence ???
If @var{variable} is @samp{*} or @samp{@@}, the length substituted is
the length of @samp{*} expanded within double quotes.

@item $@{@var{variable}#@var{string}@}
@itemx $@{@var{variable}##@var{string}@}
@c ???
The @var{string} is expanded to produce a pattern just like pathname
expansion.  If the pattern matches the beginning of the value of
@var{variable}, then the expansion is the value of @var{variable} with
the shortest matching pattern deleted (the @samp{#} case) or the
longest matching pattern deleted (the @samp{##} case).

@item $@{@var{variable}%@var{string}@}
@itemx $@{@var{variable}%%@var{string}@}
@c ???
The @var{string} is expanded to produce a pattern like pathname
expansion.@c ???
If the pattern matches
@c matches ???
a trailing portion of the value of
@var{variable}, then the expansion is the value of @var{variable} with
the shortest matching pattern deleted (the @samp{%} case) or the longest
matching pattern deleted (the @samp{%%} case).
@end table


@node Functions, Programming, Aliases, Top
@chapter Shell Functions

@cindex functions
@c need to say what functions are for
A shell function stores a series of commands for execution at a later
time, similar to a shell script.  Functions are executed in
the current shell; no new process is created to interpret them.

@node Function Definition
@section Defining a Function

@c fix: fn def is a cmd, can go anywhere
Function definitions can be entered from the command line or declared in
your login file (@pxref{Start-up}).
The shell doesn't save functions when you log off.  To make
function definitions ``permanent'' you must enter them in your login file
(@pxref{Start-up}).
To declare a function use either of the following equivalent forms:
@cindex functions, format of

@c ? what's the format of the list?  what's a legal name? same as var
@c names except fn name can contain dash in addition to what var name can have

@example
function @var{fname} () @{ @var{commands} @}

@r{or}

@var{fname} () @{ @var{commands} @}
@end example

@noindent
It makes no difference which form you use.  Both create a simple
command invoked by @var{fname} which executes the given @var{commands}.

@cindex functions, recursive
@cindex recursive functions
A function can be recursive; that is, it can call itself.  No limit is
imposed on the number of recursive calls that can be made.  However,
make sure you put in checks to avoid infinite recursion, as you would
in any programming language.

@node Function Arguments
@subsection Function Arguments

@cindex functions, positional parameters and
@cindex positional parameters, functions and
Arguments present on the command line along with @var{fname} are passed
to the function as positional parameters during its execution
(@pxref{Positional}).  The special parameter @code{#} is updated to
reflect the change.  Positional parameter @code{0} is unchanged.  When the
function finishes, the values of the positional parameters and the
special parameter @code{#} are restored to the values they had before
the function was executed.

Here's an example of a function, using the first syntax:

@c ? how about a simpler, more basic example?
@example
function xtitle()
@{
   if [ "$DISPLAY" ] ; then
   echo -n -e "\033]2;$*\007";
   echo -n -e "\033]1;$*\007";
   fi
@}
@end example

@noindent
@c ?
If BASH is executing in an xterm window,
@c what's an xterm window?
this function makes its arguments
@c whose args? the fn?
be the string displayed in an xterm title bar.

@c use same example both times (above & here)
Here's an example of a function, using the second syntax:

@c ? another mysterious example
@example
cd()
@{
     builtin cd "$@@" &&
     xtitle $HOST: $PWD
@}
@end example

@noindent
This redefines the @code{cd} built-in command to allow setting the
title of an xterm window to the host name and current directory.

@cindex functions, the shell and
@cindex functions, execution of a
@cindex functions, making permanent
@c ? call vs. execute vs. interpret (call is defined in next section)
Shell functions can be executed only in the same shell that
is used to call that function.  The shell does not fork a copy of
itself
@c ? fork a copy?? and isn't subshell for a script optional?
to interpret the function, like it would with a script.

@menu
* Listing::   Listing available functions.
* Calling::   Calling functions.
* Export::    Exporting functions.
* Local::     Local variables within functions.
* Return::    Returning from function calls.
@end menu

@node Local, Return, Export, Functions
@subsection Local Variables

@cindex local variables, functions and
@cindex @code{local} command
@cindex functions, local variables and
@cindex functions, @code{local} command and
Bash supports the use of local variables within a function. 
A local variable shadows the value of a previously defined variable
(local or not) with the same name.

Local variables differ from other variables in only one way: when the
function that defined the variable exits, the local variable goes away,
and any previously defined variable with the same name becomes visible
again.  

There is no way to have changes made to a local variable affect the
value of any previous variable with the same name.  Local variables
have to be exported to be available to programs invoked by that
function, and to their children, too.
@c children not explained

Local variables are created with the @code{declare} or @code{local}
commands (@pxref{Built-in}):

@table @code
@c KELLEM added i (frxi)
@item declare @r{[}-+frxi@r{]} @r{[}@var{name}@r{[}=@var{value}@r{]}@r{]}
This command declares variables and gives them attributes.  If no
@var{name} is given, then a listing of the values of variables is
displayed, instead.  

The @samp{-f} option causes @code{declare} to use function names only. 
@c ? only as opposed to what?
The @samp{-r} option causes @code{declare} to make @var{name} readonly. 
@c ? what's readonly?
The @samp{-x} option causes @code{declare} to make @var{name} export
only.
@c ? what's export only?
@samp{+} and @samp{-} turn on and off, respectively, the options.
@c ? on/off unclear

When @code{declare} is used in a function, it makes @var{name} local,
the same as the @code{local} command.

@example
bash$ type z
z is a function
z ()
@{
    declare a=2;
    echo in z, a = $a;
@}
bash$ a=3
bash$ z
in z, a = 2
bash$ echo $a
3
@end example

@noindent
The instance of the variable @code{a} in the function @code{z} is
private to @code{z}; the value of @code{a} in the shell
(set by @samp{a=3)} does not
affect it and is not affected by it (as shown by the final @samp{echo $a}).

@item local @var{name}@r{[}=@var{value}@r{]}
This creates a local variable called @var{name}, and gives it a value
of @var{value}.  The @code{local} command can be used only within a
function; it causes the variable @var{name} to be restricted to that
function and its children.
@c ? what children?

@example
bash$ type z
z is a function
z ()
@{
    local pid=$$;
@c ? what's $$
    echo This function is executed in shell $pid;
@}
bash$ echo $pid

bash$ z
This function is executed in shell 252
bash$ echo $pid

bash$
@end example

@noindent
The variable @code{pid} is private to function @code{z}; the calling
shell has no such variable.
@c echo above doesn't tell us there's no such var, just that either
@c there's no such var or there's such a var with a null value

@end table

Here is the declaration of a function that uses a local version of the
@code{PATH} variable, and executes all of its arguments using a
@code{PATH} which contains only @file{/bin}:

@example
using_bin () @{
  local PATH=/bin
  eval $*
@}
@end example

@noindent
A useful call to this function might look like:

@example
using_bin "rm *.texinfo; cp ../*.texinfo ."
@end example
@c ? what are the quotes for?  to have just 1 arg?  why not do w 2 args?

@node Return,  , Local, Functions
@subsection Returning From Functions

@cindex functions, return status
@cindex @code{return} command
@cindex functions, @code{return} command and
A function exits if an error occurs, if a @code{return} statement is
executed, or after executing the last command.

Here is the syntax of the return command:

@example
return @r{[}@var{n}@r{]}
@end example

@noindent
@c ? return status (= return value ?) not defined -- = exit status?
This causes a function to exit with the return value specified by
@var{n}, if present.  If @var{n} is omitted, the return status is that
of the last command.

Here's an example:

@example
true()
@{
    return 0
@}
false()
@{
    return 1
@}
@end example

@noindent
These are replacements for the commands of the same name, and will
execute much faster. 
@c ? what true/false cmds?  documented?  what are they for? Why is this faster?

@node Calling, Export, Listing, Functions
@section Calling Functions

@cindex functions, calling
To use a function you must @dfn{call} it.  This works the same way as
calling (and using) any program.  Here is the syntax used to call a
function:

@example
@var{fname} @r{[} @var{args} @r{]}
@end example

@noindent
This calls the function named @var{fname}, and provides it with
optional command-line arguments, @var{args}.  Here's an example:

@example
bash$ f /usr/spool/mail/close
@end example

@noindent
This calls the function @code{f} with the name of a system mailbox as
its argument.  In the body of the function, @samp{$1} is replaced with
@file{/usr/spool/mail/close}.

@cindex functions, operating system commands and
@cindex operating system commands and functions
@cindex functions, the @code{command} command and
@cindex @code{command} command
If you have a function with the same name as an operating system
command, you can do one of two things to be able to run that operating
system command instead of your function.  You can call the command using its full pathname, or
you can use the @code{command} command (@pxref{Built-in}):

@example
command @r{[}@var{command} @r{[}@var{args}@r{]}@r{]}
@end example

@noindent
This causes the shell to run the command named in @var{command} with
the arguments specified by @var{args}, ignoring shell
functions.  For example, if you have a shell function called @code{ls},
and you want to run the operating system's @code{ls} command instead,
you'd have to say @samp{command ls}.

@node Listing, Calling, Functions, Functions
@section Listing Available Functions

@cindex functions, listing
You can get a list of all the currently defined functions using the
@samp{-f} option of the @code{declare} command (@pxref{Built-in}).  The
text of the functions, as well as the function names, is included in
the listing.  For example:

@example
bash$ declare -f
declare -f f ()
@{
    grep "^From:" $@{1-$MAIL@};
@}
declare -f popd ()
@{
    builtin popd "$@@";
    xtitle $HOST: $PWD;
@}
declare -f pushd ()
@{
    builtin pushd "$@@";
    xtitle $HOST: $PWD;
@}
declare -f cd ()
@{
    builtin cd "$@@";
    xtitle $HOST: $PWD;
@}
declare -f xtitle ()
@{
    echo -n -e "\033]2;$*\007";
    echo -n -e "\033]1;$*\007";
@}
@end example

@noindent
This lists the names of the functions together with their definitions.



@node Environment, Conditionals, Variables, Top
@chapter The Shell Environment
@c should precede or merge with shell var chapter?

@c ? documentation of export and declare is very inconsistent, over the
@c parts of this chapter and the built-in command appendix.
@c  What are they supposed to do?  In particular, is it supposed to be
@c  the case that:
@c  export   =   declare (or maybe declare -x)
@c  export -f =  declare -f (or maybe declare -fx)
@c Is export intended to replace declare ?

@c cover 'set -o allexport...' somewhere in this chapter

@cindex environment
@cindex shell environment
@c ? program environment vs. shell environment
When a program is invoked it is given an array of strings called the
@dfn{environment}.  The shell @dfn{environment} is the set of all
shared and exported
@c ? shared = exported?
shell variables and functions.  By typing
@code{declare -x}, or the @code{export} command by itself, you can see
a list of all exported variables.  This is a list of name-value pairs,
of the form @samp{@var{name}=@var{value}}:

@example
bash$ export
declare -x HOME=/usr/chet
declare -x SHELL=/bin/bash
declare -x TERM=xterm
declare -x USER=chet
declare -x PATH=/usr/local/bin/gnu:/usr/local/bin:/usr/ucb:/bin:/usr/bin
declare -x HOSTTYPE=IBMRT
declare -x MAILCHECK=60
declare -x BASH=/bin/bash
declare -x HISTFILE=/usr/chet/.history
declare -x HISTSIZE=500
declare -x LOGNAME=chet
declare -x TZ=EST5EDT
declare -x MAIL=/usr/chet/mbox
declare -x HOST=arrakis
declare -x EDITOR=/usr/local/bin/ce
declare -x VISUAL=/usr/local/bin/ce
declare -x PAGER=/usr/local/bin/more
declare -x DISPLAY=unix:0.0
@end example

A process can access and use any environment variables and functions
that exist in that process's environment.
@c ? access AND use?
C programs have a @code{getenv()} function available for this purpose.
@c sudden switch from 'commands' (scripts, etc.) to C progs

The shell allows you to manipulate the environment in several ways.  On
invocation,
@c clarify 'invocation' -- maybe ``when it starts up, the shell scans...''
the shell scans its own environment and creates a parameter
@c ? parameter?
for each name found, automatically marking it for export to child
processes.
@c ? marking paramater? marking name?

Generally, this ``basic'' environment consists of (at least) the
@code{HOME}, @code{PATH} and @code{TERM} variables.  These tell the
shell what your home directory is, the search paths you use most often,
and what terminal you want to emulate, respectively.  Other variables
are used to customize your environment to make it more
useful to you.

Executed commands inherit this environment.
@c ? what environment?
@c ? explain inherit.  different from share? use?
If the value of a parameter
@c ? parameter
in the environment is modified,
@c ? modified by the command that's executed?
the new value becomes part of the environment, replacing the old.
@c ? doesn't subshell  have COPY of env?

@c ???
Therefore, the environment inherited by any executed command consists
of the shell's initial environment, whose values may be modified in the
shell, less any values removed by the @code{unset} command, plus any
additions via the @code{export} and @code{declare} commands.

@c ??? child processs?  subshells?
Remember that exported variables can only be exported to child
processes.  If you want to make a variable accessible to all subshells,
be sure to define and export it in your login shell.

The environment for any simple command or function can be augmented
temporarily by prefixing the command with parameter assignments.
@c ? parameter = shell variable ?
These assignment statements affect only the environment seen by that command.

@example
bash$ foo=bar printenv foo
bar
bash$ printenv foo
bash$
@end example

@c ???
If @samp{set -k}
@c substitute new 'set -o ...' version of above
is used (@pxref{Built-in}), then all parameter
assignments are placed in the environment for a command, not just those
that precede the command name.

@node Shared Variables,  , Arithmetic Evaluation, Variables
@section Shared Variables
@c ? shared = exported?

@cindex shared variables
@cindex local variables
@cindex variables, local
@cindex variable, shared
@cindex shell variables, local
@cindex shell variables, shared
Normally shell variables are @dfn{local} variables.  That is, these
variables are known only to the shell that created them.  When you
start a new shell (@pxref{Install}), the new shell doesn't know about
any of the old shell's variables.  Each shell's variables are known
only (are local) to itself.

Sometimes, however, we want a new shell to recognize the old
shell's variables.  You can accomplish this using the @code{export}
command (@pxref{Built-in}):

@table @code
@item export @var{names}
exports the value of named variables @var{names} to a subshell.
@c what subshell?
Exported variables can only be exported
to child processes and @emph{not} back to parent processes.
@c to every child created from now on?
@c explain child & parent somehwere

@item export -n @var{names}
removes the export property from the named variables, @var{names}.
@c i.e. no longer exported?

@item export
lists the variables that are already exported.
@c ? relationship to declare -x ?
@end table

The @code{export} command actually gives only a @emph{copy} of the
original variable to the new subshell.  When the subshell dies, so does
the value of the variable @emph{copy}; the original variable value
remains untouched.
@c key is probably that changes to var in subshell don't affect value
@c seen by parent shell ?

@node Export, Local, Calling, Functions
@section Exporting Functions

@cindex functions, exporting
@cindex @code{declare} command
@cindex functions, @code{declare} command and
@cindex @code{export} command
@cindex functions, @code{export} command and
Normally, functions are unset
@c ? unset?
when the shell executes a shell script. 
You can get around this problem by exporting your functions to the
environment (@pxref{Environment}).  Exported functions are available to
any invocation of the shell, including any shell scripts.  There are
two ways you can export functions:  use the @samp{-f} option of the
@code{export} command or use the @samp{-xf} option of the
@code{declare} command (@pxref{Built-in}).  Here's how they work:@refill
@c ? why synonymous commands?
@c  confusing:  export -f fn = declare -xf fn, export -f = declare ??

@table @code
@item export -f @var{fname}
exports the function named @var{fname} to the environment.  More
than one function name can be listed for export.
@item export -f
lists the currently exported functions.

@noindent
For example:

@c ? what is 'type'
@example
bash$ type fn
fn is a function
fn ()
@{
    grep "^From:" $@{1-$MAIL@};
@}
bash$ export -f fn
bash$ export -f
declare -xf fn ()
@{
    grep "^From:" $@{1-$MAIL@};
@}
@end example

@item declare -xf @var{fname}
exports the function named @var{fname} to the environment.  More
than one function name can be listed for export.
@item declare -xf
lists the currently exported functions.
@c ? is it declare -xf or declare -x?  example below confused

@noindent
For example:

@example
bash$ type fn
fn is a function
fn ()
@{
    grep "^From:" $@{1-$MAIL@};
@}
bash$ declare -x fn
bash$ declare -xf
declare -xf fn ()
@{
    grep "^From:" $@{1-$MAIL@};
@}
@end example

@noindent
The first @code{declare} statement marks the function @code{fn} for
export to the environment.
@c ? marks for export = exports (above) ?
The second statement lists all exported
functions; in this case @code{fn} is the only one.@refill

@end table

@node Substitution
@chapter Command Substitution and Arithmetic Evaluation

@node Command Subs, Parameter Subs, Predefined, Variables
@section Command Substitution

@cindex command substitution
@cindex substitution, of command values
A command enclosed in backquotes,
@samp{`@var{command}`}, is replaced by the output it
produces.  This is called @dfn{command substitution}.

For example:

@example
bash$ echo I am logged in as `whoami`
I am logged in as jems
bash$
@end example

@noindent
Inside single quotes, a backslash retains its literal meaning, except when followed by
a @samp{$}, @samp{`}, or a @samp{\}.
@c ? what happens in those cases?  why just those cases?


@c preferred syntax should be first, other mentioned as historical
You can also perform command substitution using the
@samp{$(@var{command})} syntax.
This is the preferred syntax for command substitution.
When this form of command substitution
is used, none of the characters between the parentheses are treated
specially; all characters are considered to make up the command. 
Here's an example:@refill

@c candidate for world's worst example?
@example
kill -1 $(cat /etc/named.pid)
@end example

@noindent
This sends a hangup signal (@code{SIGHUP}) to the process whose process
@sc{id} is in the file @file{/etc/named.pid}.

Note that the command substitution operation replaces any linefeed
characters in the command's output with space characters.
@c ? linefeed = newline?
The shell also deletes trailing newlines.
@c what's word splitting?  path name expansion?
Note, also, that word
splitting and path name expansion are not performed on the resulting
command if the substitution appears within double quotes.
@c ??? what substitutiont? what resulting command?

Command substitutions may be nested.  (When nesting using the
@samp{`@var{command}`} form, protect the inner backquotes with
backslashes to prevent shell misinterpretation.)

Command substitution is useful in assigning variables.  Use it when you
want the output of a command to be the value of a variable.  For
example:

@example
x=$(pwd)
@end example

@noindent
This assigns @code{x} the value of your current working directory.  This
example isn't really useful because shell has built-in command
(@code{cd}) for performing this action.
@c ? huh?  cd doesn't assign x
Here's a more useful example:

@example
i=$(expr $i + 1)
@end example
@c ? what's expr?

@noindent
This increments a number if @var{i} is a number.  This is useful in
shell scripts for creating loops.

Here's another example:

@example
name=$(basename $i)
@end example

@noindent
This removes all the path information from @var{$i} and gives you a
pure file name.

A common use of command substitution's linefeed-to-spaces translation
is keeping lists of items on separate lines of a file, and then using
@code{cat} inside of back-quotes to produce word lists for the
@code{for} command (@pxref{for}).
In the following example, the @code{cat} command is used to write the
contents of file @file{namelist} to the output:@refill

@example
bash$ cat namelist
joe
sam
mary
ezekiel
bash$ echo `cat namelist`
joe sam mary ezekiel
@end example

Here's an example using the file
@file{namelist} from above:@refill

@example
bash$ for i in `cat namelist`
bash> do
bash> echo "Hi there, $i."
bash> done
Hi there, joe.
Hi there, sam.
Hi there, mary.
Hi there, ezekiel.
@end example

@c KELLEM added this skeletal section
@c this section assumes that $[..] arithmetic evaluation is included in
@c 1.06 -- it's from posix and should be included
@node Arithmetic Evaluation, Shared Variables, Parameter Subs, Variables
@section Arithmetic Evaluation

@c this section should probably be reworded a little, but it's a start
@cindex arithmetic evaluation
@cindex arithmetic expressions
@cindex expressions, arithmetic
@cindex evaluating arithmetic expressions
@cindex math expressions
You can evaluate arithmetic expressions in BASH.  The syntax for
arithmetic evaluation is @samp{$[@var{expression}]}.  The
@var{expression} is treated as if it were within double quotes, but a
double quote inside the brackets is not treated specially.  All tokens
in the @var{expression} undergo parameter expansion, command
substitution, and quote removal.  Arithmetic evaluations may be
nested.@refill

The evaluation of expressions is done in long integers with no check for
overflow, though division by 0 is trapped and flagged as an error.  The
following list of operators is grouped into levels of equal precedence
operators.  The levels are listed in order of decreasing precedence.

@table @code
@item -
unary minus
@item !
logical @sc{not}
@item * / %
multiplication, division, remainder (modulus)
@item + -
addition, substraction
@item <= >= < >
comparison operators
@item == !=
equality, inequality
@item =
assignment
@end table

Shell variables are allowed as operands; parameter expansion is
performed before the expression is evaluated.  The value of a parameter
is coerced to a long integer within an expression.  Operators are
evaluated in order of precedence.  Subexpressions in parentheses are
evaluated first and may override the precedence rules above.  Operators
of equal precedence are evaluated from left to right.

You may also specify arithmetic evaluation with the @code{let} builtin
command.  @xref{Built-in, let, Builtin Commands}, for more
information.@refill

@node Scripts, Variables, Programming, Top
@chapter Shell Scripts

@cindex shell scripts
@cindex scripts
A shell script is a collection of operating system commands,
comments, and shell programming-language constructs grouped together in
a file.

Shell scripts can be composed of fixed commands requiring no arguments,
and run without interruption.  Scripts can also be composed of commands
that require user input.  If this is the case, the script can obtain
that input either by prompting or by arguments included on the command
line used to invoke the script.  Scripts can also use pipes and
redirection both internally and externally.
@c ? what does last sentence mean?
@c  guess: internal = redir ops in cmds in script, external = i/o of
@c  script redirected by command invoking script

@cindex script, how to execute a
You can run shell scripts in a number of ways.  You can type the
@code{bash} command followed by the script file name, or you can turn the
script into an actual command using the @code{chmod} command
(@pxref{chmod, , @code{chmod}, utilities, The GNU Utilities Manual}),
and execute that new command by typing the script's file name.  Both of
the ways of executing a script create a new shell process.
@c ? last sentence false?  surely bash foo runs foo in a fresh bash,
@c   (actually, I don't see it doc'ed like this)
@c   but foo creates a foo (non-shell) process
@c must explain shell process above, & current/new process below

To execute a program without creating a new process you can use the
@code{.} command or the @code{source} command (@pxref{Built-in}).  These
execute a shell script as part of the current process.  Each line in the
script is acted upon as if you had typed it, excepting that the shell's
notion of interactiveness is turned off.

The @code{exec} command
(@pxref{exec, , @code{exec}, utilities, The GNU Utilities Manual}),
also executes programs in
place of the current process, but @code{exec} never returns control to
the original program.

@cindex script, steps in writing a
To summarize, here's one of the easiest ways of writing and executing a
shell script:
@c it's not a summary, it's new info
@c  (above, needed exec, ., or source -- chmod case wasn't clear

@enumerate
@item
Create a file that contains the commands you want to execute.  For
example, a series of commands that you execute frequently and are tired
of repeatedly typing.

@item
Change the file access mode so the file can be run like a program
rather than be treated like a data file.  For example, @code{chmod +rx
@var{file}}, where @var{file} represents the name of your script.  The
@samp{+rx} option allows all users to read and execute this file.
@c ? why do all users?  for just me, do +x ?

@item 
Type the name of the file to execute the commands in the shell script.
@end enumerate

@cindex script, sample of
Here's an example of a simple shell script:

@example
#Display the date, time, username and current directory.
echo "The current date and time is:"
date
echo " "
echo "You are `whoami` \n"     #print username.
echo "Your current directory is `pwd`."  #print current directory.
@end example

@noindent
This script prints the current date, time, username and working
directory for the user who invokes it.  The first line of this script
is a comment, identified by the pound sign @samp{#} that begins it.
Comment statements don't get executed; use them to
document your shell script.
Notice that comments don't have to be placed on a line by themselves. 
When a word begins with a @samp{#} sign, it causes the rest of that
line to be interpreted as a comment, and not executed.
Note: @samp{#} works only in a noninteractive shell.
@c new concept: [non]interactive shell
@cindex command lines, comments in
@cindex comments
@cindex scripts, comments in
@cindex non-interactive shells, comments in

The backquotes around the @code{whoami} and @code{pwd} commands shows
the use of command substitution (@pxref{Command Subs}).  Basically
@c ? basically
the shell replaces the command (including the backquotes) with the
output of that command.  The @samp{\n} tells @code{echo} to add an extra
carriage return to the end of the line.

@xref{Advanced Scripts}, for more advanced examples of writing scripts.


@node Conditionals and Loops, Built-in, Environment, Top
@chapter Conditionals and Loops

@c Intro not related to rest of chapter.
@c Rest of chapter isn't about shell use of exit status.

@cindex conditional statements
BASH has some built-in decision-making and looping statements.  Most of these
statements base their decisions on the @dfn{exit}, or @dfn{return},
status of specified processes.  An exit status is simply a flag that
indicates the success or failure of an executed command.
@c what's a flag?  a value?
Exit status flags are returned to the parent process when a child
process stops executing (for any reason).

For example, suppose we wish to look at the contents of a file using
the @code{cat} command.  If the specified file cannot be found, it
certainly can't be looked at and the attempt to execute @code{cat} is
looked upon as unsuccessful by the shell.  Therefore the exit status is
returned as ``unsuccessful''.
 
This status can be tested by the shell and used to make decisions about
what actions to take next.  An exit status of zero means that the
command was executed successfully.  An exit status of non-zero means
that the command was unsuccessful.

@menu
* if::       The @code{if} statement.

* case::     The @code{case} statement.

* for::      The @code{for} statement.

* while::    The @code{while} statement.

* until::    The @code{until} statement.

* break & continue::   The @code{break} statement and the
                       @code{continue} statement.
@end menu

@node if, case, Conditionals, Conditionals
@section The @code{if} Statement

The syntax of the @code{if} statement is:

@example
if @var{condition}
then 
    @var{commands}
@r{[}elif @var{condition}
then 
    @var{commands}@r{]}
@dots{}
@r{[}else 
    @var{commands}@r{]}
fi
@end example
@noindent
where the brackets and the dots indicate that the @code{else} part is optional
and that there can be any number (including none) of @code{elif} parts.

If the commands contained in the first @var{condition} are successfully
executed, then the commands contained in the first @var{commands} are
executed.
The optional @code{elif} parts allow you to specify
conditions to test (and corresponding commands to execute if
successful) if previous conditions were not successful.
The optional @code{else} part allows you to specify
commands to execute if none of the @var{condition}s are successful.
After the appropriate @var{condition}s are tested
and any appropriate @var{commands} are
executed, control goes to the statement following the @code{fi}.

Here's an example:
@c replace system example by user example

@example
# check to see that we've got sufficient files to bring the
# system up multi-user
for i in /bin/login /etc/getty /etc/passwd ; do
@c what's the next obscure line???
    if [ ! -s $@{i@} ]; then
     echo "$@{i@}: not present @dots{} Can't come up to multi-user mode."
>/dev/console
     /bin/kill 1
    fi
done
@end example

@noindent
This is code to execute at the end of the system startup script.  It
checks that the necessary files are present to bring the system up to a
multiuser state, and shuts the system down if the files are not
present.

Here's another example:

@example
if [ -f /etc/license ] ; then
    PATH=~/bin.vax-ultrix:$PATH
elif [ -f /hp-ux ] ; then
    PATH=~/bin.hp-ux:$PATH
elif [ -x /bin/arch ] ; then
    if [ $(/bin/arch) = "sun3" ] ; then
        PATH=~/bin.sun3:$PATH
    else
        PATH=~/bin.sparc:$PATH
    fi
else
    PATH=~/bin.ibm032:$PATH
fi
@end example

@noindent
This code tacks a machine-specific binary directory onto the
front of the @code{PATH} variable.  Only one of the @code{then} bodies is executed,
depending upon the machine being used.@refill

If you don't want to put the parts of an @code{if} statement
on separate lines as shown in the syntax, you don't have to.
But if you move one of the keywords (@code{then}, @code{elif},
@code{else}, or @code{fi}) onto the same line as the preceding
@var{condition} or @var{commands}, you must put
a semicolon before it.
In other words, each
@var{condition} or @var{commands} must be followed by a newline
or a @samp{;}.
@c is it allowable to always end with ;, even if newline next?

For example:

@c what is the [...] ?
@c The condition here, with =, is not a case of 'successful execution'
@c as discussed above.  Rather, it's a comparison.  Confusion of
@c concepts: exit status used as t/f for tests
@example
if [ "X$PS1" = "X" ]; then exit ; else echo "interactive shell" ;
fi@refill
@end example

@noindent
This echoes ``interactive shell'' if BASH is executing interactively. 
The variable @code{PS1} is set only if the shell is interactive.


@node case, for, if, Conditionals
@section The @code{case} Statement

The syntax of the @code{case} statement is:

@example
case @var{string} in
     @var{pattern_1a} | @var{pattern_1b} | @var{pattern_1c})
            @var{commands1}
            ;;
     @var{pattern_2})
            @var{commands2}
            ;;
     @dots{}
esac
@end example

This statement tries to match a string, @var{string}, to various
@var{patterns}.  If it finds a match, it
executes the corresponding pattern's commands.  When execution is
complete, control is transferred to the statement following the
@code{esac}.
 
Each pattern in a list is separated
from the next by @samp{|}.  Patterns can contain the
file-matching wildcards @samp{*}, @samp{?}, or @samp{[ @dots{} ]}
(@pxref{File Names}).  A pattern list is ended with a closing
parenthesis (note that there is no matching open parenthesis).@refill
@c so in this case wildcards aren't just for files

You don't have to separate all the parts of the @code{case} statement
on separate lines as shown above.
Any of the newlines can be omitted.

@c put an example case statement here instead of a template
@example
case @var{string} in @var{pattern1a} @r{[}| @var{pattern1b} @dots{}@r{]}) @var{commands} @r{[};; @dots{}@r{]};; esac @refill
@end example

Here's an example:

@c example redefines builtin cd, while also using it?
@c example is teco-like gibberish -- replace &/or explain
@c Want simpler example here -- use this example in customization
@c section for people to copy if they like the behavior.
@example
cd()
@{
     builtin cd "$@@" &&
     case "$1" in
     '')
          PS1='$ '
          ;;
     ..|*/..)
          PS1="$@{PWD##*/@}$ "
          ;;
     */*)
          PS1=$@{$1##*/@}$ "
          ;;
     *)
          PS1="$1$ "
          ;;
     esac
@}
@end example

@noindent
This sets your prompt to contain the name of the current directory,
with all path information stripped.
@c example to explain above sentence
This can be used as a
way to reset your primary prompt when you change directories.  If you 
are in your home directory, via a @code{cd} with no arguments,
@code{PS1} will contain no directory information at all.
@c need example of behavior after doing it:
@c  bash$ cd me
@c  me$


@node for, while, case, Conditionals
@section The @code{for} Statement

The @code{for} statement executes a sequence of commands once for each
value in a list of items.

The format of the @code{for} statement is:

@example
for @var{name} @r{[}in @var{list}@r{]}
do
    @var{commands}
done
@end example

For each element in @var{list}, @var{name} is set to that
element and the @var{commands} are executed. 
When you omit the optional @samp{in @var{list}}, it
defaults to @samp{in "$@@"}, so that the loop is executed once for
each of the command line parameters.

Here's an example:

@example
for host
do
     echo $host:
     rsh $host w
done
@end example

@noindent
This defines a script that runs the @code{w} command remotely on each
host named as an argument.
@c need example of using the script

Here's an example using the @samp{in @var{list}} option:

@example
for file in $(echo *.c)
do
     touch $file
done
@end example

@noindent
This updates the timestamp of each file ending in @samp{.c} in the
current directory.  This is useful for preparing for a rebuild of a
software system.

The @code{do} and @code{done} mark the beginning and the
end, respectively, of the loop.  When the @var{list} is
used up, control is passed to the statement following the @code{done}.

If you don't want to put the parts of a @code{for} statement
on separate lines as shown in the syntax, you don't have to.
But if you move one of the keywords (@code{do} or @code{done})
onto the same line as the preceding
@var{name}, @var{list}, or @var{commands}, you must put
a semicolon before it.
@c is it allowable to always end with ;, even if newline next?

@node while, until, for, Conditionals
@section @code{while} and @code{until} Loops

The format of a @code{while} or @code{until} loop is:

@example
while @var{condition}
@r{[}do
      @var{commands}@r{]}
done
@end example
@noindent
or
@example
until @var{condition}
@r{[}do
      @var{commands}@r{]}
done
@end example

In a @code{while} loop, the @var{commands} are
repeatedly executed as long as the @var{condition} executes
successfully (returns an exit status of zero).
Before each pass through the loop, @var{condition} is executed.  If
@var{condition} returns zero, @var{commands} is executed.  Usually
@var{commands} affects the @var{condition} execution in some way so
that it will eventually return non-zero.  Otherwise you end up with an
infinite loop.
When the @var{condition} is unsuccessful in executing, control
jumps to the statement following the @code{done}.

In an @code{until} loop, the @var{commands} are
repeatedly executed as long as the @var{condition} fails
execution (returns an exit status of non-zero).
Before each pass through the loop, @var{condition} is executed.
If @var{condition} returns non-zero, @var{commands} is executed. 
Usually @var{commands} affects the @var{condition} execution in some
way so that it will eventually return zero.  Otherwise you end up with
an infinite loop.
When the @var{condition} is successful in executing, control is
returned to the statement following the @code{done}.

The following example tests the output of the @code{who} command once
each minute until it finds that a user named @samp{chet} has logged in.
@c explain example -- what are who, grep, sleep

@example
until who | grep chet
do
     sleep 60
done
@end example

If you don't want to put the parts of a @code{while} or @code{until} statement
on separate lines as shown in the syntax, you don't have to.
But if you move one of the keywords (@code{do}
or @code{done}) onto the same line as the preceding
@var{condition} or @var{commands}, you must put
a semicolon before it.
In other words, the
@var{condition} and @var{commands} must each be followed by a newline
or a @samp{;}.
@c is it allowable to always end with ;, even if newline next?

The @samp{do @var{commands}} is optional.  Sometimes just
testing the @var{condition} is enough.  For example, here's an
inefficient way of reading the last line of a file:
@c what do you mean by reading?  who sees it? where does it go?
@c if it's inefficient, isn't it a bad example?

@c explain: what's exec?  what's read?
@example
exec < file
while read variable ; done
@end example

@noindent
The return status of @code{read} is 0 (successful) unless the
end-of-file (@sc{eof}) is
encountered.  When the @sc{eof} is encountered, the condition is met and the
usefulness of the statement is finished.  No @samp{do @var{commands}} section is needed.

@node break & continue,  , until, Conditionals
@section The @code{break} and @code{continue} Statements

@cindex loops, interrupting
@cindex interrupting loops
You can interrupt a @code{for}, @code{while}, or @code{until} loop
using a @code{break} or a @code{continue} statement:

@table @code
@item break @r{[}@var{n}@r{]}

The @code{break} statement stops the execution of the loop and passes
control to the statement following the @code{done} that marks the end of
the loop.
If @var{n} is specified, it tells the shell to break at the @var{n}th
level of the enclosing loop.
@c explain nth level -- nested loops?

Here's an example:

@c what is the : in the while?
@c what are echo, read, [], lpr
@example
while :
do
     echo -n "Enter name of file to print [q to quit]: "
     read fn
     if [ "$fn" = "q" ] ; then
          break
     fi
     lpr $fn
done
@end example

@noindent
This prompts for names of files and prints them, until a @samp{q} is
encountered.

@item continue @r{[}@var{n}@r{]}

The @code{continue} statement transfers control to the loop's
@code{done} statement, which continues execution of the loop.  If
@var{n} is specified, it tells the shell to resume computation at the
@var{n}th enclosing loop.
@c explain nth level -- nested loops?

Here's an example:

@c what's [], -d
@example
for dir in $(cat dirlist)
do
     if [ -d $dir ] ; then
          continue
     fi
     mkdir $dir
done
@end example
@c weird example.  Why wouldn't you write it as
@c  'if NOT exists then @c mkdir'
@c  without a Continue?


@noindent
This reads a file containing the names of a list of directories to
create, and creates each one if it does not already exist.
@end table

@node Built-in, Shell Vars, Conditionals, Top
@appendix Built-in Shell Commands

@cindex built-in commands, list of
Some of the commands you may want to run are already part of the shell. 
Because of this, no new processes are started in order to run these
built-in commands.  Therefore, these built-in commands use less time
than those that aren't built-in.

The following is a list of the built-in commands.  Some of these
commands are explained in more detail earlier in this manual.
@c shouldn't all of these be in the manual?
@c This is then just alphabetical summary
You are directed to read the appropriate chapter if you need more information
than is provided here:
@c be sure all descriptions here match those earlier

@table @code
@item :
This command can only expand arguments and perform redirections
and nothing else.  It is the shell's ``do nothing'' command.  It is
not, however, a useless command.  Since the shell is able to scan and
parse the line that follows the colon, this command can be adapted for
many uses.

It can be used as a valid option for a program's conditional statement,
or it can be used to create an infinite (until interrupted) loop. 
Here's an example:

@example
# wait for a file to be created, chewing up lots of CPU time
# usage: waitfor filename
#
while [ ! -f "$1" ] ; do
      :
done
@end example

You can also use the colon to create comment lines, instead of using
the @samp{#} character (@pxref{Scripts}, for more information).
@c other part of doc said # is for noninteractive shell, : for interactive
@ignore
The @samp{:} command can be adapted to create comment lines in an
interactive shell (@pxref{Built-in}).
@cindex command lines, comments in
@cindex comments
@cindex interactive shells, comments in
@cindex colon (@code{:}) command
@iftex
@cindex : command
@end iftex
@c Can't do @cindex : (: is not valid in index/menu in Info mode)
@c from Bob Chassell:  A colon cannot be part of an index
@c entry because a colon is used by Info as the marker between the item
@c name and the node name in the index.
@end ignore
For example:

@example
bash$ echo A bad example > junk
bash$ cat junk
A bad example
bash$ : this is a comment about > junk
bash$ cat junk
bash$
@end example

@noindent
First we create the file called @file{junk}, entering a simple message
into that file.  Then we create a comment about our file using the
@samp{:} statement and insert a redirection operator into the sentence. 
Normally we'd expect the shell to ignore anything that follows a
comment character.  However, the shell is able to parse and interpret
the contents of the line following a colon.
Therefore, the above @samp{:} statement, when scanned by the shell,
causes the file @file{junk} to be opened for output, which removes its
prior contents (@pxref{Redirection}).
@c what happens to rest of : line?

So be careful when using the @samp{:} statement.  It can be useful when
used properly; but it can also be dangerous in careless hands.
@c ??? what's an example of proper, useful use?
Don't insert any characters that can be expanded by the shell into a
@samp{:} comment line.
@c ??? what's this expansion stuff above?
It's safest to protect the comment following @samp{:} with single quotes
so that it won't be interpreted by the shell.
@c ??? single quotes are new concept
Make sure that there's a space between the colon and the opening single
quote, though, or the shell could mistake what follows for a command:
@c space/command stuff not explained

@example
bash$ : 'This is a good way to make a comment.'
bash$ :'This is bad.'
:This is bad.:  command not found.
@end example
@c why not just use # ?? because not valid in interactive shell?

@item . @var{file}
@itemx source @var{file}
Both commands are used to execute shell programs, without creating a
separate child process.  The named file is read and executed in the
current shell environment and control is returned to the current shell. 
Since these commands do not create a subshell they can be used to
change the value of a shell variable in the current shell.

@var{file} must have a fully qualified path name in order to be
executed.  The @code{PATH} variable is searched for the location of the
named file, otherwise the current directory is searched if no file is
found in @code{PATH}.

Redirection of input and output and other command line arguments are
not permitted when using these commands.

@item alias @r{[}@var{name}@r{[}=@var{value}@r{]} @dots{}@r{]}
An alias is defined for each @var{name} whose @var{value} is given. 
@xref{Aliases}, for more information.  A trailing space in @var{value}
causes the next word to be checked for alias substitution.  If a
@var{name} (without the @samp{=@var{value}} part) is given for which no alias has been defined an error
message is printed.

The @code{alias} command, with no arguments, prints the 
list of aliases in the form @samp{@var{name}=@var{value}} 
on the standard output.

@item bg @r{[}@var{job_spec}@r{]}
This causes the shell to place the specified job, @var{job_spec}, in
the background, as if it had been started with @samp{&}.  @xref{Resuming},
for more information.  If @var{job_spec} is not present, the shell's
notion of the current job is used.

@item break @r{[}@var{n}@r{]}
This command exits from an existing @code{for}, @code{while}, or
@code{until} loop.  If @var{n} is specified, it tells the shell to
break at the @var{n}th level of the enclosing loop.  @var{n}
must be greater than or equal to 1.  If @var{n} is greater than the
number of the enclosing loops, all enclosing loops are exited.

@item builtin @r{[}@var{shell-builtin} @r{[}@var{arguments}@r{]}@r{]}
This is used to execute a built-in shell command, passing it
@var{arguments}.  This is useful when you wish to rename a
built-in shell command to be a function, but need the functionality of
the built-in command within the function itself.  (The built-in @code{cd} 
command is commonly redefined this way.)

@item cd @r{[}@var{dir}@r{]}
This command tells the shell to change the current directory to the one
specified by @var{dir}.  The variable @code{HOME} contains the default
value of @var{dir}.

The variable @code{CDPATH} defines the search path for the directory
containing @var{dir}.  @xref{Predefined}, for more information. 
Alternative directory names are separated by a colon, @samp{:}.

A null directory name is considered to be the same as the current
directory.  If @var{dir} begins with a forward slash, @samp{/},
then the search path contained in @code{CDPATH} is not used.

@item command @r{[}@var{command} @r{[}@var{arguments}@r{]}@r{]}
This causes the shell to run the [external] command named in @var{command} with
the arguments specified by @var{arguments}, ignoring all
other shell functions.@refill

For example, if you have a shell function called @code{ls}, and you
want to call the command @code{ls} as well, you can say @samp{command ls}.

@item continue @r{[}@var{n}@r{]}
This command tells the shell to resume the next iteration of the
enclosing @code{for}, @code{while}, or @code{until} loop at the
@var{n}th enclosing loop (if @var{n} is specified).  @var{n}
must be greater than or equal to 1.  If @var{n} is greater than the
number of enclosing loops, the last enclosing loop (the ``top-level''
loop) is resumed.

@c KELLEM added i (frxi)
@item declare @r{[}-+frxi@r{]} @r{[}@var{name}@r{[}=@var{value}@r{]}@r{]}
This command declares variables and gives them attributes.  If no
@var{name} is given, then a listing of the values of variables is
displayed instead.

@table @code
@item -f
Use function names only.

@item -r
Make @var{name} readonly.  These names cannot be assigned
values by subsequent assignment statements.

@item -x
Make @var{name} export to subsequent commands via the environment.

@c KELLEM added -i:
@c the -i is here if $[..] arithmetic evaluation is put into 1.06
@c it's a posix thing
@item -i
Treat @var{name} as an integer; arithmetic evaluation
(@pxref{Arithmetic Evaluation}) will be performed when the variable is
assigned a value.
@end table

Using @samp{+} instead of @samp{-} turns off the attribute.  

When @code{declare} is used in a function, it makes @var{name} local,
the same as the @code{local} command (@pxref{Functions}).

@item dirs
This displays the list of currently remembered directories. 
Directories are added to the list with the @code{pushd} command; you
can get back up through the list with the @code{popd} command.

@item echo @r{[}-ne@r{]} @r{[}arguments@r{]}
This displays a prompt or a message on the standard output.  It outputs
the @var{arguments}, if supplied, separated by spaces.  If the
@samp{-n} option is specified, the trailing newline character is suppressed.@refill

If the @samp{-e} option is given, interpretation of the following
backslash-escaped characters is turned on:

@table @code
@c KELLEM added \a:
@c   \a is a ksh-88 thing and should be included in 1.06 as far as I know
@item \a
Alert/bell.
 
@item \b
Backspace.

@item \c
Suppress trailing newline.

@item \f
Form feed.

@item \n
New line.

@item \r
Carriage return.

@item \t
Horizontal tab.

@item \v
Vertical tab.

@item \@var{NNN}
The character whose @sc{ascii} code is @var{NNN} (octal).

@item \\
Backslash.
@end table

@item enable @r{[}-n@r{]} @r{[}@var{names}@r{]}
This command enables and disables built-in shell commands.  This allows
you to use an operating system command which has the same name as a
built-in shell command.

If the @samp{-n} option is used, the named commands, @var{names},
become disabled.  Otherwise the named commands are enabled.

For example, to use the @code{test} command found in your path instead
of the built-in shell version, you type @samp{enable -n test}.

@item eval @r{[}@var{arguments}@r{]}
The @var{arguments} are read and concatenated together into a single
command.  This ``new'' command is then read and executed by the shell.

@item exec @r{[}@r{[}-@r{]}@var{command} @r{[}@var{arguments}@r{]} @r{]}
If @var{command} is specified, it is executed, replacing this shell,
without creating a new process.  The @var{arguments} become arguments
to @var{command}.

If the first argument is @samp{-}, the shell places a dash in the
zeroth argument passed to @var{command} (exactly what a login does).

If the @var{command} can't be executed the shell exits, unless the
shell variable @code{no_exit_on_failed_exec} exists.

If @var{command} is not specified, any redirections present
take effect in the current shell.

@item exit @r{[}@var{n}@r{]}
@itemx bye @r{[}@var{n}@r{]}
This causes the shell to exit with the status specified by @var{n}.  If
@var{n} is omitted, the exit status is that of the last command
executed.  A trap on the shell variable @code{EXIT} is executed before
the shell terminates.

@item export @r{[}-nf@r{]} @r{[}@var{name}@r{[}=@var{word}@r{]}@r{]}
The @code{export} command exports the value of named variables (or
functions if the @samp{-f} option is specified), @var{name}, to a
subshell.

If no variable names are given, @code{export} displays a list of all
the variables that are already exported.  The @samp{-n} option causes
the shell to remove the export property from the named variables.

@item fg @r{[}@var{job_spec}@r{]}
This places the specified job, @var{job_spec}, in the foreground, and
makes it the current job.  @xref{Resuming}, for more information.  If
@var{job_spec} is not present, the shell's notion of the current job is
used.

@item function @var{name} () @r{[} @var{commands} ; @r{]}
@itemx @var{name} () @r{[} @var{commands} ; @r{]}
This creates a simple command invoked by @var{name} which executes the
named @var{commands} (@pxref{Functions}).  Arguments on the
command line along with @var{name} are passed to the function as
@samp{$0 @dots{} $@var{n}} (@pxref{Positional}).

@item hash @r{[}-r@r{]} @r{[}@var{name}@r{]}
For each variable name, @var{name}, the full pathname of the command is
determined and remembered.  The @samp{-r} option causes the shell to
forget all remembered locations.  With no arguments, @code{hash}
presents information about remembered commands.

@c The 'help' sources should be used to augment/check this doc and vice versa
@c I suspect this doc may have come from those sources
@item help @r{[}@var{pattern}@r{]}
This command displays helpful information about built-in commands.  If
a pattern is specified,
@c ? same pattern wildcards as for filenames?
@code{help} gives detailed help on all commands
matching @var{pattern}, otherwise a list of the built-ins is printed.
If @var{pattern} contains only alphanumeric characters (no wildcard
characters, such as @samp{?} and @samp{*}), then a pattern of
@samp{pattern*} if assumed.  Therefore, the command @samp{help pw} will
produce help on the @code{pwd} command.
@c note: must enclose pattern in quotes if contains wildcards, else
@c  expanded to filenames before help sees it

@item history @r{[}@var{n}@r{]}
@itemx history -rw @r{[}@var{file}@r{]}
@itemx history -s @var{arguments}
The first command displays the history list with line numbers.  Lines listed
with a @samp{*} have been modified.  If a number @var{n} is specified, only
the last @var{n} lines of the history list are displayed.  

The @samp{-w} option means causes the current history file to be
written out.  The @samp{-r} option causes the current history file to
be read, instead.  If a file name, @var{file}, is given, then that file
is used as a history list.  If no file name is given, BASH checks to see
if the variable @code{HISTFILE} is set.  The file @file{~/.bash_history} 
is used as the history file if the variable @code{HISTFILE} is not set.
@xref{History}, for more information.

The @samp{-s} option performs history substitution on the named
arguments.

@item jobs @r{[}-l@r{]}
This lists the active jobs.  The @samp{-l} option causes the list of
process identification numbers to be listed in addition to the normal
information.  @xref{Job Control}, for more information.

@item kill @r{[}-@var{sigspec}@r{]} @var{pid}
@itemx kill @r{[}-@var{sigspec}@r{]} @var{job_spec}
@itemx kill -l
This sends the processes named by @var{pid} or @var{job_spec} the
terminate signal, or the signal specified by @var{sigspec}, if
present.  Signals are specified either by number or by name. 
@c where are the numbers defined? documented?

The @samp{-l} option lists the signal names that can be sent.  Typing
@code{kill} alone does nothing.  @xref{kill}, for more information.

@c KELLEM added next item (let)
@c `let' is for arith. eval. -- from posix, check if really in final
@c release version of 1.06
@item let @var{expression} @r{[}@var{expression} @dots{}@r{]}
Each @var{expression} is an arithmetic expression to be evaluated
(@pxref{Arithmetic Evaluation}).  If the last @var{expression} evaluates
to 0, @code{let} returns 1; otherwise 0 is returned.@refill

@item local @var{name}@r{[}=@var{value}@r{]}
This creates a local variable called @var{name}, and gives it a value
of @var{value}.

When the @code{local} command is used within a function it causes the
variable @var{name} to be restricted to that function and its children. 
Otherwise it is equivalent to creating normal variables, as if the
@code{local} command had been omitted.

When used without options, @code{local} gives a list of local variables
on the standard output.

@item logout
This exits a login shell.

@item popd @r{[}+-@var{n}@r{]}
This removes entries from the directory stack.  With no arguments, it
removes the top directory from the stack, and changes directories
(@code{cd}) to the new top directory.

The @samp{+@var{n}} option removes the @var{n}th entry (counting from
the left of the list shown by the @code{dirs} command), starting with
zero.  For example:  @code{popd +0} removes the first directory, while
@code{popd +1} removes the second.

The @samp{-@var{n}} option removes the @var{n}th entry (counting from the
right of the list shown by the @code{dirs} command), starting with
zero.  For example:  @code{popd -0} removes the last directory, while
@code{popd -1} removes the next to last.

You can see the directory stack with the @code{dirs} command.

If the variable @var{pushd_silent} is not set, and the @code{popd}
command	was successful, a @code{dirs} will be performed too.

@item pushd @r{[}@var{dir}@r{]}
@itemx pushd @r{[}+-@var{n}@r{]}
This adds a directory to the top of the directory stack, or rotates the
stack, making the new top of the stack the current working directory. 
With no arguments, it exchanges the top two directories.

The @samp{+@var{n}} option rotates the stack so that the @var{n}th
directory (counting from the left of the list shown by the @code{dirs}
command) is at the top.

The @samp{-@var{n}} option rotates the stack so that the @var{n}th
directory (counting from the right of the list shown by the @code{dirs}
command) is at the top.

The @samp{@var{dir}} option adds the directory named by @var{dir} to
the directory stack at the top, making it the new current working
directory.

You can see the directory stack using the @code{dirs} command.

If the variable @var{pushd_silent} is not set, and the @code{pushd}
command was successful, a @code{dirs} will be performed too.

@item read @r{[}@var{names}@r{]}
This reads values from the standard input into various shell
variables.  One line is read from the standard input, and the first
word is assigned to the first named variable in @var{names}, the second
word to the second named variable, and so on, with leftover words
assigned to the last named variable.

Only the characters in @code{IFS} are recognized as word delimiters
(@pxref{Predefined}).

@item readonly @r{[}-f@r{]}@r{[}@var{names}@r{]}
The given @var{names} are marked readonly and the values of these
various @var{names} may not be changed by subsequent assignments.  
If the @samp{-f} option is given, the functions corresponding to the
@var{names} are marked instead.  If no arguments are given, a list of
all read-only names is printed.

@item return @r{[}@var{n}@r{]}
This causes a function to exit with the return value specified by
@var{n}.  If @var{n} is omitted, the return status is that of the last
command executed in the function body.

@c ? what about set with no args -- prints list of vars
@item set @r{[}-aefhkntuvxldo@r{]} @r{[}@var{arguments}@r{]}
The @code{set} command sets options for the shell:

@table @code
@item a
This marks variables which are modified or created for export.

@item e
This tells a non-interactive shell to exit immediately if a command
exits with a non-zero status.

@item f
This disables path name expansion.

@item h
This tells the shell to locate and remember function commands as those
functions are defined.  Normally, function commands are looked up when
the function is executed.

@item k
This tells the shell to place all keyword arguments in the
command's environment.  Normally only those that precede the command
name are placed in the environment for a command.

@item n
This tells the shell to read commands but not execute them.  This
may be used to check a shell script for syntax errors, for example. 
This option is ignored in interactive shells.

@item t
This tells the shell to exit after reading and executing one command.

@item u
This tells the shell to treat unset variables as an error when
performing substitutions.  If a substitution is attempted on an unset
variable, the shell prints an error message.  If the shell is
non-interactive, it then exits with a non-zero status.

@item v
This prints shell input lines as they are read.

@item x
This prints the value of @code{PS4} followed by commands and their
arguments as they are executed.

@item l
This saves and restores the bindings of the @var{name} in a @code{for}
command (@pxref{for}).

@item d
This disables the hashing of commands that are looked up for execution. 
Normally, commands are remembered in a hash table and, once found, do
not have to be looked up again.

@c `o' option changed
@c writeup supplied by KELLEM for new o and for `H', replacing the old `o' option.
@c ? really true that H is here?  that both h and H exist and are different?!?
@c that not all the one-letter options have -o named equivalents?
@item H
This enables the @samp{!} style history substitution (@pxref{History}).
This option is on by default.@refill

@item o @r{[}@var{option-name}@r{]}
The @var{option-name} can be one of the following:
@table @code
@item allexport
Same as @samp{-a}.
@item braceexpand
The shell will enable curly brace expansion (SEE BRACE EXPANSION).  This
is on by default.
@item emacs
Use an emacs-style command line editing interface
@item errexit
Same as @samp{-e}.
@item histexpand
Same as @samp{-H}.
@item ignoreeof
The effect is as if the shell command @samp{ignoreeof=10} had been
executed (@pxref{Shell Vars, ignoreeof, Shell Variables}).
@item monitor
Same as @samp{-m}.
@c ? no -m doc'ed above
@item noclobber
The effect is as if the shell command @samp{noclobber=} had been
executed (@pxref{Shell Vars, noclobber, Shell Variables}).
@item noexec
Same as @samp{-n}.
@item noglob
Same as @samp{-f}.
@item nohash
Same as @samp{-d}.
@item notify
The effect is as if the shell command @samp{notify=} had been executed
(@pxref{Shell Vars, notify, Shell Variables}).
@item nounset
Same as @samp{-u}.
@item verbose
Same as @samp{-v}.
@item vi
Use a @sc{vi}-style command line editing interface.
@item xtrace
Same as @samp{-x}.
@end table

If no @var{option-name} is supplied, the values of the current options
are printed.
@end table

@c KELLEM interchanged - and + below (so that - is on)
You can turn these options on and off by preceding the option letter
with @samp{-} for on, and @samp{+} for off.  You can also set these
options on the command line that invokes the shell.  For example:

@example
bash$ bash -v
@end example

@noindent
The special shell variable, @samp{$-} lists the currently defined shell
options.

You can also use the @code{set} command to assign values to positional
parameters (@pxref{Parameter Subs}):

@example
set test junk
@end example

@noindent
sets the positional parameter @samp{$1} to test and @samp{$2} to junk. 
The @var{arguments} are passed as positional parameters @samp{$1} to
@samp{$N}.

If you type the @code{set} command alone, with no arguments, you get a
list of all the currently defined shell variables (@pxref{Variables}).  

@item shift @r{[}@var{n}@r{]}
This causes the positional parameters from @samp{$@var{n}+1} on up to
be renamed to @samp{$1}, @samp{$2}, and so on.  If
@var{n} is not given, it is assumed to be 1.

@item suspend @r{[}-f@r{]}
This suspends the execution of this shell until it receives a
``resume'' (@code{SIGCONT}) signal.  The @samp{-f} option, if specified,
prevents messages about this being a login shell (if it is) and causes
the shell to be suspended quietly anyway.

@item test @r{[}@var{expr}@r{]}
@itemx [@var{expr}]
These test for various conditions named in @var{expr}.  They return a
status of of 0 (true) or 1 (false) depending on the evaluation of
@var{expr}.

Expressions can be unary or binary.  Unary expressions are often used
to examine the status of a file.  You can have string operators and
numeric comparison operators too.

File operators:

@table @code
@item -b @var{file}
This tests that the file @var{file} exists and is a block special file.

@item -c @var{file}
This tests that the file @var{file} exists and is a character special
file.

@item -d @var{file}
This tests that the file @var{file} exists and is a directory.

@item -f @var{file}
This tests that the file @var{file} exists and is not a directory
(tests that it is a plain file).

@item -g @var{file}
This tests that the file @var{file} exists and has the set-group-ID bit
set.

@item -k @var{file}
This tests that the file @var{file} exists and has its ``sticky'' bit
set.

@item -L @var{file}
This tests that the file @var{file} exists and is a symbolic link.

@item -p @var{file}
This tests that the file @var{file} exists and is a named pipe.

@item -r @var{file}
This tests that the file @var{file} is readable by you.

@item -s @var{file}
This tests that the file @var{file} exists and is not empty (has a
non-zero size).

@item -S @var{file}
This tests that the file @var{file} exists and is a socket.

@item -t @r{[}@var{FD}@r{]}
This tests to see if file descriptor @var{FD} is opened on a terminal.
If @var{FD} is omitted, it defaults to 1 (the standard output).@refill

@item -u @var{file}
This tests that the file @var{file} exists and has the set-user-ID bit
set.

@item -w @var{file}
This tests that the file @var{file} exists and is writable by you.

@item -x @var{file}
This test that the file @var{file} exists and is executable by you.

@item -O @var{file}
This tests that the file @var{file} exists and is, effectively, owned
by you.

@item -G @var{file}
This tests that the file @var{file} exists and is owned by the
effective group @sc{id}.

@item @var{file1} -nt @var{file2}
This tests that the files @var{file1} and @var{file2} exist and that
@var{file1} is newer than @var{file2} (according to modification date).

@item @var{file1} -ot @var{file2}
This tests that the files @var{file1} and @var{file2} exist and that
@var{file1} is older than @var{file2} (according to modification date).

@item @var{file1} -ef @var{file2}
This tests that the files @var{file} and @var{file2} exist and that
they have the same device and inode numbers.
@end table

String operators:
@c what strings?  variables? variable values?

@table @code
@item -z @var{string}
This tests that @var{string} exists and is empty (of zero length).

@item -l @var{string}
When this is used as an operand to any of the binary arithmetic 
operators it returns the length of @var{string}.

@item -n @var{string}
@itemx @var{string}
This tests that @var{string} exists and is not empty (has a non-zero
size).

@item @var{string1} = @var{string2}
This tests that @var{string1} and @var{string2} exist and are equal.

@item @var{string1} != @var{string2}
This tests that @var{string1} and @var{string2} exist are not equal.
@end table

Other operators:

@table @code
@item ! @var{expr}
This tests that @var{expr} exists and is false.

@item @var{expr1} -a @var{expr2}
This tests that @var{expr1} and @var{expr2} exist and are both true.

@item @var{expr1} -o @var{expr2}
This tests that @var{expr1} and @var{expr2} exist and that at least
one of them is true.

@item @var{argument1} @var{op} @var{argument2}
@var{op} represents one of the arithmetic binary operators @code{-eq}
(equals), @code{-ne} (not equals), @code{-lt} (less than), @code{-le}
(less than or equal to), @code{-gt} (greater than), or @code{-ge}
(greater than or equal to).

This tests to see if @var{argument1} and @var{argument2} exist and
also tests if @var{argument1} is equal, not equal, less than, less
than or equal to, greater than, or greater than or equal to
@var{argument2}, depending upon the operator used.
@end table

@item times
This prints the accumulated user and system times for the shell and 
for processes started from the shell.

@item trap @r{[}-l@r{]} @r{[}@var{arguments}@r{]} @r{[}@var{sigspec}@r{]}
The command named by @var{arguments} is to be read and executed when
the shell receives the signal(s) specified by @var{sigspec}.  
@var{sigspec} is either a signal name in <signal.h>, or a signal
number.  The @code{trap} command with no arguments prints the list of
commands associated with each signal number.  The @samp{-l} option
causes the shell to print a list of signal names and their
corresponding numbers.

If @var{arguments} is absent, all specified signals are reset to
their original values.  If @var{arguments} is the null string, the
signal is ignored by the shell and by the commands it invokes.  

If @var{sigspec} is @code{EXIT} (0), the command @var{arguments} is
executed upon exit from the shell.

@item type @r{[}-all@r{]} @r{[}-type | -path@r{]} @r{[}@var{names}@r{]}
@c KELLEM: might also allow `-a',`-t', & `-p' as synonyms in 1.06
@c if so, should document here
This allows you to test to see how each named item, @var{name}, would
be interpreted if used as a command name.
@c this item really screwy.  command has ``names'',  description has ``name''

If the @samp{-type} option is used, it returns a single word, either
@samp{alias}, @samp{function}, @samp{builtin}, or @samp{file}, if
@var{name} is an alias, shell function, shell builtin, or disk file,
respectively.  If the name is not found, nothing is printed.

If the @samp{-path} option is used, @code{type} returns either the name
of the disk file that would be executed, or nothing if @samp{-type}
doesn't return a value of @samp{file}.

If the @samp{-all} option is used, it displays all of the
interpretations of @var{names}.  This includes aliases and functions, if
and only if the @samp{-path} option is not also used.@refill

@item ulimit @r{[}-cdfmst @r{[}@var{limit}@r{]}@r{]}
@code{ulimit} provides control over the resources available to processes
started by the shell, on systems that allow such control.  If an
option is given, it is interpreted as follows:

@table @code
@item -c
refers to the maximum size of core (memory dump) files created.

@item -d
refers to the maximum size of a process's data segment.

@item -f
refers to the maximum size of files created by the shell.

@item -m
refers to the maximum resident set size.

@item -s
refers to the maximum stack size.

@item -t
refers to the maximum amount of cpu time, in seconds.
@end table

If @var{limit} is given, it represents the new value of the specified
resource.  Otherwise, the current value of the specified resource is
printed.

If no options are given, the @samp{-f} is assumed to be active.  Values
are in 1k increments, except for @samp{-t}, which is in seconds.

@item umask @r{[}@var{nnn}@r{]}
This sets the user file-creation mask to the octal number @var{nnn}. 
If @var{nnn} is omitted, the current value of the mask is printed.

@item unalias @r{[}@var{names}@r{]}
This removes the named alias(es), @var{names}, from the list of defined
aliases.

@item unset @r{[}-f@r{]} @r{[}@var{names}@r{]}
This removes the corresponding variable or function specified by
@var{names}.  If the @samp{-f} option is given, then functions are
removed.

The predefined variables @code{PATH}, @code{IFS}, @code{PPID}, 
@code{PS1}, @code{PS2}, @code{UID}, and @code{EUID} cannot
be unset (@pxref{Shell Vars}).

@item wait @r{[}n@r{]}
This asks the shell to wait for the specified process, @var{n}, and
report its termination status.  @var{n} can be a process @sc{id} or a
job specification.  If a job specification is given, all processes
in that job's pipeline are waited for.

If @var{n} is not given, all currently active child processes are
waited for, and the return code is zero.  @xref{wait}, for more
information.
@end table

@node Shell Vars, Install, Built-in, Top
@appendix Variables Set or Used by the Shell

@c be clearer for each var, who sets it, who uses it

@cindex variables, set or used by the shell
@cindex shell variables, set or used by the shell
The following variables are set by the shell.
@xref{Variable Mechanics}, for information on shell variables.

@c terminology needing defs or refs:
@c  parent, working directory, user ID, effective user ID, full
@c  pathname, instance of BASH, search path, internal field separators,
@c  shell script, password file, system spool directory, primary prompt
@c  string, secondary prompt string, execution trace, decoded prompt
@c  string, exapnsion, end-of-file characters, exit, pathname
@c  expansion, history expansion, tokenization, symbolic links, logical
@c  chain of directories, complete a hostname, directory stack

@c what is difference between IS and EXPANDS TO?
@c ? I think almost every 'expands to' here should be 'is'
@table @code
@item PPID
This is the @sc{pid} (process id) of the shell's parent.

@item PWD
This is the current working directory.
(It's called @code{PWD} because it is the directory name the @code{pwd}
command would report.)
It is updated when you change directories with the @code{cd} command.

@item OLDPWD
This is the previous working directory.
When you change directories with the @code{cd} command,
the directory you move to goes into @code{PWD} and the directory
you move from goes into @code{OLDPWD}.

@item REPLY
This is set by the @code{read} built-in command (@pxref{Built-in}) when
no arguments are supplied.

@item UID
This expands to the user @sc{id} of the current user.

@item EUID
This expands to the effective user @sc{id} of the current user.

@item BASH
This expands to the full pathname used to invoke this instance of BASH.

@item BASH_VERSION
This expands to the version number of this instance of BASH.

@item SHLVL
This is incremented by one each time an instance of BASH is started.

@c KELLEM: the following variables are from posix.2 and should be in bash
@c these include RANDOM, SECONDS, and LINENO [not in 1.06.25]
@item RANDOM
Each time this variable is referenced, a random integer is generated.
The sequence of random numbers may be initialized by assigning a value
to @code{RANDOM}.  If @code{RANDOM} is unset, it will lose its special
properties, even if it is subsequently reset.@refill

@item SECONDS
Each time this variable is referenced, the number of seconds since shell
invocation is returned.  If a value is assigned to @code{SECONDS}, the
value returned upon subsequent references is the number of seconds since
the assignment plus the value assigned.  If @code{SECONDS} is unset, it
will lose its special properties, even if it is subsequently reset.

@item LINENO
Each time this variable is referenced, the shell substitutes a decimal
number representing the current sequential line number (starting with 1)
within a script or function.  When not in a script or function, the
value substituted is not guaranteed to be meaningful.  When in a
function, the value is not the number of the source line that the
command appears on (that information has been lost by the time the
function is executed), but is an approximation of the number of commands
executed in the current function.  If @code{LINENO} is unset, it will
lose its special properties, even if it is subsequently reset.
@end table

The following variables are used by the shell.  In some cases, as noted
below, BASH assigns these variables default values:

@table @code
@item HOME
This represents the default argument for the @code{cd} command.  (That
is, the command @samp{cd} with no arguments will connect to this
directory.)  It is usually your login directory.  For example:

@example
HOME=/usr/home/close
@end example

@noindent
@code{HOME} is automatically set to your login directory when you log in.

@item PATH
This is the search path to use when the shell looks for program files
referenced in commands.  Separate directory names using colons.  Here's
an example:
@c explain

@example
/usr/gnu/bin:/usr/local/bin:.:/usr/ucb:/bin:/usr/bin/X11:/usr/bin
@end example

@item CDPATH
This is the search path for the @code{cd} command.  Separate directory
names using colons.  Here's an example:

@example
CDPATH=.:~:/usr/src
@end example

@item IFS
This defines the internal field separators.   These are the characters
that separate words.
@c what words? where?
It has a default value of space, tab, and newline characters.  Here's an
example:

@example
IFS=':'
@end example

@noindent
This allows you to read the password file as separate fields.

@item ENV
If this parameter is set when BASH is executing a shell script, its
value is interpreted as a file name containing commands to initialize
the shell (like @file{.bashrc} for interactive shells).

@item MAIL
This is the file name to use as your mailbox.  If this file is non-zero
in length and has been modified since the last time the shell checked
the file, the shell displays the message ``@code{you have mail}''.  You
control how often the shell checks this file by setting the @code{MAILCHECK}
variable.

Here's an example using the @code{MAIL} variable:

@example
MAIL=/usr/homes/close/mbox
@end example

@noindent
This causes the shell to check for mail in @file{/usr/homes/close/mbox}
rather than the system spool directory.

@item MAILCHECK
This specifies the amount of time that must pass before the shell will
check the file named by the @code{MAIL} variable to see if it has changed.  The
default is 60 seconds (1 minute).  An interval of 0 causes the shell
to look for mail before printing each prompt.

For example,

@example
MAILCHECK=600
@end example

@noindent
causes the shell to check for mail before printing a prompt if 600
seconds have passed since the last check.

@item MAILPATH
@c how relates to MAIL variable? what if both set?
This specifies multiple mailboxes for the shell to check.  It is the
path the shell uses to check the named files for modifications (receipt
of mail).  To distinguish which file has received mail, you can follow
each file name with a @samp{%} and some unique text which is printed
when mail is received.  Separate file names with colons.  Here's an
example:

@example
MAILPATH='/usr/homes/close/mbox?"You have mail":~/shell-mail?"$_ has
mail!"'
@end example

@noindent
This causes the shell to print ``You have mail'' whenever it detects a
change in the modification time of the file
@file{/usr/homes/close/mbox}.  Additionally, the file
@file{/usr/homes/close/shell-mail} is also checked, and the message
``/usr/homes/close/shell-mail has mail!'' is printed whenever a change
is detected in its modification time.@refill

@c KELLEM added MAIL_WARNING
@item MAIL_WARNING
If this variable is set and one of the specified mail boxes has been
accessed since the last time BASH checked, then the message ``The mail
in <mailfile> has been read!'' is printed.@refill

@item  PS1
This is the primary prompt string.  By default it is @samp{bash\$ }.
Here's an example:

@example
PS1="$(whoami)@@$(hostname)$ "
@end example

@noindent
This sets the primary prompt string to be the login name of the current
user, followed by the name of the computer, followed by a dollar sign.

@item PS2
This is the secondary prompt string.  By default it is @samp{bash>}. 
For example,

@example
PS2='more> '
@end example

@noindent
sets the secondary prompt string to @samp{more> }.  This is printed
whenever bash needs more input to complete a command.
@c elaborate on when needs more input?

@item PS4
This is the prompt string printed before each command BASH displays
during an execution trace.  By default, it is @samp{+}.

@item NO_PROMPT_VARS
If this is set, the decoded prompt string does not undergo further
expansion.

@item HISTSIZE
This is the number of commands to remember in the command history list
(@pxref{History}).  Its default value is 500.

@item HISTFILE
This is the name of the file in which the command history list is saved
(@pxref{History}).
@c apparently: saved over sessions; history of current session not
@c  there yet if you look (e.g. with emacs or cat)

@item PROMPT_COMMAND
If this is set, the value is executed as a command prior to issuing
each primary prompt.

@c bfox: if a shell is running disconnected from tty, every read from
@c   tty gives it eof -- this way it goes away after n tries
@item IGNOREEOF
@itemx ignoreeof
This controls the action of the shell on receipt of an end-of-file
character as the sole input.  If set, the value is the number of
consecutive end-of-file characters typed before bash will exit.

If the variable exists but does not have a numeric value, or has no
value, the default value is 10.  If it does not exist, an end-of-file
signifies the end of input to the shell.  This is only in effect for
interactive shells.

@item HOSTTYPE
This is automatically set to a string that uniquely describes the type
of machine on which BASH is executing.  The default is
system-dependent.
@c example...

@c KELLEM, adding TMOUT: TMOUT is from posix.2a, I believe
@item TMOUT
If this is set to a value greater than zero, the value is interpreted as
the number of seconds to wait for input after issuing the primary
prompt.  BASH will terminate after waiting for the number of seconds.

@item notify
If this is set, BASH will report terminated background jobs
immediately, rather than waiting until printing the next primary prompt
(@pxref{notify}).

@item history_control
@c tested 12/26, ok
If this is set to a value of @code{ignorespace}, lines that begin with a
space won't be entered in the history list.

If this is set to a value of @code{ignoredups}, lines that match the last
line entered in the history list won't be recorded.

If this is unset, or set to any other value than those above, all
lines read by the shell are saved in the history list.

@item glob_dot_filenames
If this is set, BASH includes file names beginning with a @samp{.} in
the results of pathname expansion.

@item allow_null_glob_expansion
Normally, a filename pattern that doesn't match any files is left in the
command as is (expands to itself) .  For example, @samp{*.foo} is left
as is if there are no files ending in @samp{.foo}.
If @code{allow_null_glob_expansion} is set, however, a pattern that doesn't
match anything is removed from the command (expands to a null file name).
@c example?

@c must doc in appropriate parts of manual
@item histchars
This represents the two characters which control history expansion and
tokenization.  The first character is the history expansion character;
that is, the character which signals the start of a history expansion
(normally @samp{!}).

The second character is the character which signifies that the
remainder of the line is a comment, when found as the first character
of a word.
@c ? default histchars was empty in 1.06, 2/13/91
@c I tried setting it, and ! stopped being special but the new chars
@c didn't seem to do anything.

@item nolinks
If this is set, the shell doesn't follow symbolic links when doing
commands that change the current working directory.  By default, BASH
follows the logical chain of directories when performing commands such
as @code{cd}.

@item hostname_completion_file
This contains the name of a file, in the same format as
@file{/etc/hosts}, that should be read when the shell needs to
complete a hostname.  You can change the file name interactively; the
next time you want to complete a hostname BASH adds the contents of the
new file to the already existing database.@refill
@c really telling user to modify a public file?!?

@item noclobber
If this is set, BASH will not overwrite an existing file with the
@samp{>}, @samp{>&}, and @samp{<>} redirection operators.
@c KELLEM: <> opens a file descriptor for reading and writing. from posix
Such an attempt to overwrite a file will generate an error message.
You can override this via the @samp{>|} redirection operator.  The @samp{>>}
(append) redirection operator will still work on existing files because
it only appends to the file and doesn't erase the file's current contents.
  
@item auto_resume
This variable determines whether a command may restart a suspended job
rather than starting a new one.
@xref{Resuming}, for more information.

@item no_exit_on_failed_exec
If this variable exists, the shell doesn't exit if it can't execute the
file specified in an @code{exec} command (@pxref{Built-in}).

@item cdable_vars
If this is set, an argument to the @code{cd} built-in command that is
not a directory is assumed to be the name of a variable whose value
represents the directory to which you would like to @code{cd}.

@item pushd_silent
If this is set, the @code{pushd} and @code{popd} built-in commands will
not print the current directory stack after successful execution.
@end table

@node Install, Invoke, Shell Vars, Top
@appendix Installing BASH

This appendix tells how to install BASH on a machine.
If BASH is already on your machine, or you are not the person installing
it, ignore this appendix.

@cindex installing BASH
@cindex BASH, installation
To install BASH you simply type @kbd{make}. @c really?
The BASH @file{Makefile} @c really a file name?
tries to dynamically figure out what kind of machine and operating
system you are using.  It makes an educated guess based on the
information it finds.

During the @code{make} process, a message is displayed describing what
machine and operating system has been chosen for you.  This information
is also saved in the file @file{.machine} so you can look at it later.

Therefore, for most machines, simply follow this simple checklist to
install BASH:

@enumerate
@item
Type @kbd{make}.

@item
Wait for the compilation to finish.

@item 
Type @kbd{./bash} to see if the compile worked.
@c how can you tell if it worked?

@item
Type @kbd{cp ./bash /usr/gnu/bin/bash} (or wherever you keep GNU
binaries) to copy BASH to your binaries directory.
@end enumerate

@menu
* Problems::  What to do if BASH doesn't install quite so easily.

* Files::     Files used in the @code{make} process.

* Porting::   Porting BASH to a new machine.

* Bugs::      What to do if you Discover Bugs in BASH.

@end menu

@node Problems, Files, Install, Install
@appendixsec What if it Doesn't Install so Easily?

@cindex installation, problems with
@cindex BASH, installation problems
Sometimes BASH gets confused and will make the wrong assumptions about
your machine or operating system.  If the displayed information (also
found in @file{.machine}) is incorrect, you will have to edit the file
@file{machines.h} and provide the appropriate information so that BASH
can be installed correctly.  The complete instructions for doing this
are located in the @file{machines.h} file.

@c what font should UNKNOWN_MACHINE be?
However, if BASH says that your machine type is an @sc{UNKNOWN_MACHINE},
or BASH thought it knew something about your machine but was wrong,
then reading the next few sections could be of use to you
@xref{Files}, and @ref{Porting}, for more information).

@node Files, Porting, Problems, Install
@appendixsec Files Used in the @code{make} Process.

@cindex installation, files used in
@cindex BASH, files used in installation of
The following files are used during the installation of BASH, in the
@code{make} process:

@table @code
@item Makefile
This is responsible for making the actual @file{Makefile} that is used
to create Bash.  It runs the C preprocessor (usually located in
@file{/lib/cpp}) on the file @file{cpp-Makefile}, producing the output
file @file{bash-Makefile}.

@item cpp-Makefile
This is a file of C comments and text.  It contains
@code{ifdefs} that control what files get compiled and which flags
are passed to the various C files comprising BASH.  It includes a file
called @file{machines.h}.

@item machines.h
This file contains the basic compilation parameters for all of the
machines to which BASH has been ported.  This file consists of a series
of conditional blocks, one per machine type.

These conditional blocks are depend upon the unique identifier that
@file{cpp} has predefined for this machine.  In some cases, additional
information can be passed from @file{Makefile}.  It is possible to pass
information such as whether or not a particular file is available on
this system, and so on.

@item bash-Makefile
This is the output from the initial stage of @code{make}.  It is a
stripped down version of @file{cpp-Makefile} which is tailor-made for
your machine and operating system.  All subsequent @code{makes} use
this file.
@end table

@node Porting, Bugs, Files, Install
@appendixsec What if You Have to Port to a New Machine?

@cindex installation, porting to a new machine
@cindex BASH, porting to a new machine
@cindex porting BASH to a new machine
To port BASH to a previously unsupported
machine, you need to create a block in @file{machines.h}
that is conditional based on a unique identifier present in your
version of the C preprocessor.

If you don't know what that symbol is, you might try the following
simple test:

@example
bash$ echo "main () @{ @}" > foo.c
bash$ cc -v foo.c
@end example

@noindent
The first command puts a small C program into the file @file{foo.c},
and the second program compiles that program.
The @code{-v} option ???. @c what does it do?

@noindent
Look for something of the form @code{-D}@var{machine} in the output of
@code{cc}, where @var{machine} is an identifier for your machine.  If
your machine's C preprocessor doesn't have a unique identifier, you will
have to define the identifier in @file{Makefile} manually.

Let's say you have a machine from Yoyodyne Industries, called the YoYo. 
It runs a version of @sc{bsd}, so it is reasonably compatible.
@c compatible with what?
However, the
@file{cpp} file on this YoYo machine doesn't define any unique identifiers. 
You should change the @file{Makefile} line for @code{CPPFLAGS} to:

@example
CPPFLAGS = -P -DYoYo
@end example

@noindent
Then, in @file{machines.h}, make a copy of the block for
@code{UNKNOWN_MACHINE}, and change the conditional to:@refill

@example
#if defined (YoYo)
@end example

@noindent
Inside the YoYo block, define @samp{M_MACHINE="YoYo"} and
@samp{M_OS=BSD}.  You also modify the existing defines to match your
machine's software.

If BASH still won't compile, perhaps because of missing code that is
required for your YoYo machine, you will have to write that code and
place it within a conditional block based on YoYo.

Most machines aren't that difficult; simply redefining a few of the
default values is sufficient.  If you do run across a difficult machine,
please send all fixes and changes to bash-maintainers@@ai.mit.edu in the
form of context diffs:

@example
diff -c orig-machines.h machines.h >machines.diffs
@end example

@noindent
Please include information about which version of the shell you have.

@node Bugs,  , Porting, Install
@appendixsec Reporting Bugs

@cindex BASH, reporting bugs
If you find a bug in BASH, you should report it.  But first you should
make sure that it really is a bug and that it appears in the latest
version of BASH that is available.
@c how can you find out if it is the latest BASH?

Once you have ascertained that a bug really exists, you are welcome to
mail in a bug report.  If you have a fix, please mail that too!

Suggestions and ``philosophical'' bug reports should be mailed to
bug-bash@@ai.mit.edu.  Genuine bug reports should be mailed to the same
place, or to bash-maintainers@@ai.mit.edu.

@emph{All} bug reports should include:

@itemize @bullet
@item
The version number of BASH.
@c how find it out?

@item
The hardware and operating system used.

@item
The compiler used to compile BASH.

@item
A description of the bug's behavior.

@item
A short script or ``recipe'' which demonstrates the bug.
@end itemize

Without this information, it is generally not possible to successfully
debug BASH.  Usually, without this information, the bug won't manifest
itself!

Discussion and questions about BASH in general (including questions
about this documentation) can be sent to bug-maintainers@@ai.mit.edu. 

@node Invoke, Start-up, Install, Top
@appendix Invoking BASH
@c bad title -- more is covered

@cindex invoking BASH
@cindex BASH, invoking
@c intro material might be useful elsewhere
The operating system starts a shell for you when you log in. 

This shell operates interactively; that is, it prompts you for commands
and processes those commands.  Logging off the system ends this login
shell.

@cindex shell, interactive
@cindex shell, login
@cindex shell, non-interactive
A login shell is one that's been started with the @samp{-login} flag,
or one whose first character of argument 0 is a @samp{-}.
@c I don't understand the last sntence
An
interactive shell is one that has been started with the
@samp{-i} flag, or one whose standard input and standard output are
both connected to terminals.

A shell doesn't always have to be interactive.  For example, if you use
a sequence of commands frequently, you can save time typing by storing
those commands in a file
@c ? is that the def of a shell script?
and direct the shell to execute this command
file when you need it.  When this command file is executed a new
non-interactive shell
is started to read and execute the commands in that file.
@c not necessarily new shell

You can tell if a shell is interactive or not by examining the contents
of the variable @code{PS1}.  It is unset in non-interactive shells, and set in
interactive ones.
@c Why/when do you want to tell? If you're typing at the shell, you
@c already know it is interactive.  If you're writing a file to be
@c executed by a noninteractive shell, that file knows it's noninteractive.

@menu
* Invoke Order::     What files are invokes upon login, logout
                     and starting non-interactive and non-login
                     shells.

* Invoke Options::   Options that modify the shell invocation
                     process.

* Signals::          How BASH handles signals as an interactive
                     shell.

* Tilde::            How BASH handles tilde expansion.

* Splitting::        How BASH handles word splitting and pathname
                     expansion.
@end menu

@node Invoke Order, Invoke Options, Invoke, Invoke
@appendixsec Automatic Script Execution

@cindex invoking BASH, file order when
@cindex shell, login file order
@cindex shell, logout file order
Upon starting a login shell, the system
@c ? the system? or bash?
looks for a file containing
system-wide start-up instructions for BASH and reads and executes it. 
Usually these instructions are in a file called @file{/etc/profile}.

Next the system looks for start-up instructions for your account and
reads and executes it.   These instructions are found in one of the
following files; the system searches for the following files, in order,
and reads and executes the first one it finds:

@table @file
@item ~/.bash_profile

@item ~/.bash_login

@item ~/.profile
@end table

@noindent
Since the chosen file contains start-up instructions for @emph{your}
account, you can modify and ``personalize'' this file if you want. 
@xref{Start-up}, for an example of this type of file
(@file{~/.bash_profile}).  If BASH can't find any of these files,
BASH starts with a default environment; no error message is given.

When exiting a login shell, BASH reads and executes the file
@file{~/.bash_logout}, if it exists.
@c bash IS the login shell that is exiting
@xref{Start-up}, for an example of this type of file.

@cindex shell, interactive file order
@c what causes non-login interacive shell to start up?
Upon starting a non-login, interactive shell, BASH
@c bash IS that shell
reads and executes the
file @file{~/.bashrc} if it exists.
@c ? mnemonic for 'rc'
@xref{Start-up}, for an example of this type of file.

@cindex shell, non-interactive file order
@c what causes non-interacive shell to start up?
Upon starting a non-interactive shell, BASH
@c bash IS that shell
checks to see if the
environment variable
@c ? env var = shell var ?
@code{ENV} is non-null, and reads and executes the
file named by that variable.

@node Invoke Options, Signals, Invoke Order, Invoke
@appendixsec Options That Modify the Shell Invocation Process

To invoke BASH you can type:
@c why? you have one already

@c text below says options come before -...
@example
bash @r{[}-acefhiknstuvx@r{]} @r{[}@var{options}@r{]}
@end example

@noindent
where @var{options} represents one of the multi-character options
described a bit later in this section.  BASH interprets the following
single-character options when it is invoked:

@cindex invoking BASH, options
@cindex shell, invocation options
@c compare to 'set' options. maybe combine doc
@c listed here as
@table @code
@item a
Automatically mark variables which are modified or created for export.

@c how does string combine with other single-char options?
@item c @var{string}
Commands are read from @var{string}.

@item e
Exit immediately if a command exits with a nonzero status.

@item f
Disable pathname generation.

@item h
Locate and remember function commands as functions are defined.

@item i
This makes the shell interactive.

@item k
Place all keyword arguments for a command in the environment for that
command (not just those arguments that precede the command name).

@item n
Read commands but don't execute them.

@item s
If this option is present, or if no arguments remain after option
processing, commands are read from the standard input.  (This option
allows the positional parameters to be set when invoking an interactive
shell.)

@item t
Exit after reading and executing one command.

@item u
Treat unset variables as an error when performing parameter expansion.

@item v
Print shell input lines as they are read.

@item x
After expanding each command, display the value of @code{PS4} followed
by the command and its expanded arguments.
@end table

BASH also interprets a number of multi-character options.  These
options must appear on the command line @emph{before} the single-character
options in order to be recognized.  These options are:@refill

@table @code

@item -norc
Do not load the personal initialization file @file{~/.bashrc}.  This is
the default if the shell name is @code{sh}.
@c ???

@item -noprofile
Do not read either @file{/etc/profile} or @file{~/.bash_profile}, if
this is a login shell.
@c what about the other profiles?  ~/.bash_login, ~/.profile

@item -rcfile @var{file}
Execute commands from @var{file} instead of from the standard personal
initialization file @file{~/.bashrc}.

@item -version
Show the version number of this instance of BASH when starting.
@c this instance = the bash starting up?

@item -quiet
Do not be verbose when starting up (do not show the shell version or
any other information).

@item -login
Make BASH act as if it had been invoked by @code{login}.

@item -nobraceexpansion
Do not perform curly brace expansion (@pxref{Grouping}).

@item -nolineediting
Do not use the readline library to read command lines if this shell is
interactive.
@end table

If arguments remain after option processing,
@c no args shown in syntax above
and neither the
@samp{-c} nor the @samp{-s} option has been supplied,
@c s not explained well -- didn't show use of an arg
then the first
argument is assumed to be the name of a file containing shell commands. 
If BASH is invoked in this fashion, the variable @code{0} is set to the name of the
file, and the positional parameters are set to the remaining arguments. 
BASH reads and executes commands from this file, then exits.

@node Signals, Prompt, Invoke Options, Invoke
@appendixsec How BASH Handles Signals

@cindex BASH, signal handling in
@cindex signals, how BASH handles
@cindex signal handling
@c how relates to signals in process chapter?

@c below:explain job control, synchronous job, inherited, command
@c substitution, kernel, process group id

When BASH is interactive, it ignores @code{SIGTERM}.  This means that
@samp{kill 0} will not kill an interactive shell.  Also, @code{SIGINT}
is caught and ignored, so that @code{wait} is interruptible.

In all cases, BASH ignores @code{SIGQUIT}.

If job control is in effect, bash ignores @code{SIGTTIN},
@code{SIGTTOU}, and @code{SIGTSTP}.  Synchronous jobs started by BASH
have signals set to the values inherited by the shell from its parent. 
Background jobs (jobs started with @samp{&}) ignore @code{SIGINT} and
@code{SIGQUIT}.

Commands run as a result of command substitution ignore the
keyboard-generated job control signals @code{SIGTTIN}, @code{SIGTTOU},
and @code{SIGTSTP}.

Here's a description of the signals listed above:

@table @code
@item SIGINT
This is the signal generated (normally) by @kbd{C-c} on the keyboard. 
This signal will kill most processes, although a program may choose to
ignore @code{SIGINT}.  @code{SIGINT} also allows a process to clean up after itself
before dying.

@item SIGQUIT
This is the signal generated (normally) by @kbd{C-\} on the keyboard. 
@code{SIGQUIT} is identical to @code{SIGINT} except that it requests that the
operating system produce a diagnostics file (called a @dfn{core dump}
which is placed into a file named @file{core}).

@item SIGTERM
@code{SIGTERM} is similar to @code{SIGINT} except that it is normally produced by a
software program and not from the @kbd{C-c} on the keyboard.  Note that
some programs treat @code{SIGTERM} differently from @code{SIGINT}.

@item SIGTSTP
@code{SIGTSTP} is the signal sent (normally) by the @kbd{C-z} key on the
keyboard.  Some programs may ignore this signal.  This signal does not
kill the process but instead @emph{stops} the process, putting the
program into a suspended state.

@item SIGTTIN
The kernel sends the signal @code{SIGTTIN} to a job/process group that is not
in the foreground (that is, the process group's process group @sc{id} is not
equal to the terminal's foreground process group @sc{id}) and attempts to
read from the terminal.

@item SIGTTOU
The kernel sends the signal @code{SIGTTOU} to a job/process group that is not
in the foreground and attempts to write to the terminal if, and only
if, the terminal has the @sc{tostop} bit set in its local flags word (you
can set this bit with @samp{stty tostop}).
@c tostop: code or sc?
@c what's tostop?  local flags word?
@end table

@c what is this topic really?  sections removed from another appendix
@node Command Processing
@appendix Command Processing

@node Splitting,  , Tilde, Invoke
@appendixsec Word Splitting and Pathname Expansion

@c purpose of section -- what is effect of splitting? why do we care?

@cindex word splitting
@cindex splitting, words
@c ???
The shell scans the results of parameter expansion and command
substitution that did not occur within double quotes for word
splitting.

The shell treats each character of the variable @code{IFS} as a delimiter, and
splits the results of the other expansions
@c other than what?
into words on these
characters.  The default value of @code{IFS} is exactly
@samp{<space><TAB><newline>}.
@c SPCTAB ... how notate?
  @xref{Shell Vars}, for more information
on how to change the value of @code{IFS}.

If @code{IFS} is unset or null, no splitting is done.  Otherwise, each occurrence
of an @code{IFS} character is treated as a delimiter.

Explicit null arguments (@samp{""} or @samp{''} -- i.e., single or
double quotes with nothing between them) are retained. 
Implicit null arguments, resulting from the expansion of parameters
that have no values,
@c no value -- unset?  null value?
are removed.  If no expansion occurs, then no splitting is performed.

@cindex expansion, pathname
@cindex pathname expansion
After word splitting, BASH scans each word for the special characters
@samp{*}, @samp{?}, and @samp{[@dots{}]}, unless the @samp{-f} option is
present.  If one of these characters appears, then the word is regarded
as a pattern, and replaced with an alphabetically sorted list of
pathnames matching the pattern.  @xref{File Names}, for more
information on these special characters.

If no matching pathnames are found, and the shell variable
@code{allow_null_glob_expansion} is unset, the word is left unchanged
(@pxref{Shell Vars}).  If the variable is set, the word is removed if
no matches are found.

@c paragraph unclear
When a pattern is used for pathname generation, the character @samp{.}
(at the start of a name or immediately following a slash) must be
matched explicitly, unless the shell variable @code{glob_dot_filenames}
is set (@pxref{Shell Vars}).  The slash character must always be
matched explicitly.  In other cases, the @samp{.} character is not
treated specially.

@node Start-up, Advanced Scripts, Invoke, Top
@appendix Sample Script Files

@c some redundancy between invocation appendix and this one re login files
When you first log in, a shell process is started that establishes the
environment for your session (@pxref{Invoke Order}).  A system-wide
login script assigns default values to environment variables creating a
basic, default environment (@pxref{Environment}). 
(A login script is simply a file that contains commands that customize
the environment.)

@cindex start-up files, sample
@cindex login file samples
This default environment can be quite restrictive.  BASH uses various
local login scripts to allow you to change and ``personalize'' the
default environment (@pxref{Invoke Order}).  If a local login scripts
exists, it is executed by the shell before you get a shell prompt,
customizing your environment for you.

@menu
* Login Script::   Sample of a login script.

* Logout Script::  Sample of a logout script.

* Other Scripts::  Sample of a non-login, interactive shell
                   script.

@end menu

@node Login Script, Logout Script, Start-up, Start-up
@appendixsec Login Scripts
@c some redundancy between invocation appendix and this one re login files
@cindex login script
A local login script allows you to change the default environment to
fit your needs.  If you have one it resides in your home directory. 
Note that names for this script begin with a dot (@samp{.}), so the
file remains hidden when performing a standard directory listing
(@code{ls}).  You have to type @code{ls -a} to see if you have any
local login scripts.  If you do, it will be called one of the following
names:

@c if you don't have one, can create one -- how know what put in it?
@c Be clear it's done after system file, so needn't duplicate what's there
@table @file
@item ~/.bash_profile

@item ~/.bash_login

@item ~/.profile
@end table

Since this file contains start-up instructions for @emph{your} account,
you can modify this file to create an environment
specific to your needs.  Here is an example of a BASH start-up file for
login shells, @file{~/.bash_profile}:
@c need to explain sample scripts

@cindex login script, sample of
@cindex script, sample of a login
@example
# File: /usr/gnu/lib/Bash_profile

# Startup file for bash login shells.
#
default_dir=/usr/gnu/lib/

@c how can your login shell be noninteractive?
# Test to see if this is an interactive shell.
if [ "$PS1" ]; then
  PS1='\u@@\h(\#)\$ '@c KELLEM added \ before $
  ignoreeof=3
fi

LOGIN_SHELL=true

# If the user has her own init file, then use that one, else use
# the canonical one.
@c why in separate rc file instead of right here?
if [ -f ~/.bashrc ]; then
  source ~/.bashrc
else if [ -f $@{default_dir@}Bashrc ]; then
  source $@{default_dir@}Bashrc;
  fi
fi
@end example

@node Logout Script, Other Scripts, Login Script, Start-up
@appendixsec Logout Scripts

A logout script allows you to automate a variety of tasks like starting
background processes with a @code{nohup} option, running file clean-up
routines, or simply displaying a logout message when you log out.  If a
@file{.bash_logout} file exits in your home directory, it is executed
automatically when you log out.
@c nohup not illustrated in sample script

The logout script can contain any commands that you might type at the
shell prompt.  However, a logout script is most useful when used to
display information about the session just ending and to run background
commands after you log out. 

Here's an example of a simple BASH logout file, @file{~/.bash_logout}:

@cindex logout script
@cindex logout script, sample of
@cindex script, sample of a logout
@example
# File: /usr/close/.bash_logout
# BASH log off file

# First clear the screen.
clear

# Clean up my files.
echo "cleaning things up now"
rm *.o

# Print a logout message.
echo `whoami` "logged out on" `date`

# Then say goodbye.
echo "Au revoir"
@end example

@node Other Scripts, Inputrc File, Logout Script, Start-up
@appendixsec Non-login, Interactive Scripts
@c what about noninteracive scripts?

All login scripts are run when you first log in.
@c all ??
In addition, login
scripts that end in @samp{rc} are executed each time your current shell
creates a subshell.
@c ? what are the possible rc script names?
@c ?when does it run a subshell?
Here's an example of a BASH start-up file for
non-login, interactive shells, @file{~/.bashrc}:
@cindex interactive non-login script
@cindex interactive non-login script, sample of
@cindex script, sample of an interactive non-login

@example
# File: /usr/gnu/lib/Bashrc
# Bourne Again SHell init file.
#
# Files you make look like rw-rw-r
umask 002

# Don't make useless coredump files.  If you want a coredump,
# say "ulimit -c unlimited" and then cause a segmentation fault.
ulimit -c 0

# Sometimes, there are lots of places that one can find tex
# inputs.
export TEXINPUTS=.:$HOME/bin:/usr/lib/tex/inputs:/usr/local/lib/tex/inputs

# Where's the Gnu stuff at?
GNU=/usr/gnu/bin
X11=/usr/bin/X11

UTIL_PATH=$GNU:$X11
STANDARD_PATH=/usr/local/bin:/usr/ucb:/bin:/usr/bin:/usr/etc:/etc:/usr/games
if [ "$HOSTTYPE" = "sony" ]; then STANDARD_PATH=$STANDARD_PATH:/usr/sony/bin; fi

if [ -d $HOME/bin/$HOSTTYPE ]; then
  MY_PATH=$HOME/bin/$HOSTTYPE
fi

if [ -d $HOME/bin ]; then
  MY_PATH=$MY_PATH:$HOME/bin
fi

PATH=.:$MY_PATH:$UTIL_PATH:$STANDARD_PATH

@c section claims to be about interactive script -- why need to test?
# If running interactively, then:
if [ "$PS1" ]; then

  # Here are a couple of functions to make csh user's lives easier.
  setenv () @{
    export $1="$2"
  @}

  unsetenv () @{
    unset $*
  @}

  # Here are a couple of functions that make *my* life easier.
  showme () @{
    local files=$(type -all -path $1)
    if [ "$files" ]; then ls -l $files; else echo "No such file."; fi
  @}

  # Set ignoreeof if you don't want EOF as the sole input to the shell to
  # immediately signal a quit condition.  This only happens at the start
  # of a line if the line is empty, and you haven't just deleted a character
  # with C-d.  I turn this on in ~/.bash_profile so that only login shells
  # have the right to be obnoxious.
  # ignoreeof=

  # Set auto_resume if you want TWENEX style behavior for command names.
  auto_resume=

  # Set notify if you want to be asynchronously notified about background
  # job completion.
  notify=

  # Make it so that failed `exec' commands don't flush this shell.
  no_exit_on_failed_exec=

@c section claims to be about non-login script
  if [ ! "$LOGIN_SHELL" ]; then
    PS1="\u@@\h\$ "
  fi

  HISTSIZE=256
  MAILCHECK=60

  # A couple of default aliases.
  alias j='jobs -l'
  alias po=popd
  alias pu=pushd
  alias ls='ls -F'

HOST=$(hostname | sed -e 's/\.*//')

xtitle () @{ echo -n -e "\033]l$*\033" @}

  if [ -f ~/.bash_aliases ]; then
    source ~/.bash_aliases
  fi
fi
@end example


@node Advanced Scripts, Tools, Start-up, Top
@appendix Writing and Debugging Scripts

@cindex debugging shell scripts
@cindex scripts, debugging
@cindex shell scripts, debugging
When writing scripts, it's always possible that mistypings and other
errors can occur.  In complicated scripts
errors may be difficult to track down and fix.

The shell can make things simpler though, with its debugging options,
like @samp{-v} and @samp{-x}.  All can be invoked by command arguments
to BASH or through the @code{set} command (@pxref{Built-in}).  For
example, @code{bash -v} or @code{set -v}.
@c substitute new 'set -o ...' version of above

The @samp{-v} option sets the shell to verbose mode.  This causes
command lines to be displayed as they are read.
@c read in general? or just from a script (file)?
This is useful for
finding syntax errors.  You can use this option in conjunction with
the @samp{-n} option,
@c substitute new 'set -o ...' version of above
which prevents the execution of commands. 
However, note that saying @code{set -n} makes a terminal useless until
an end-of-file is typed.
@c ? how do you type eof?

The @samp{-x} option displays each command as it is executed, following
all substitutions.
@c substitutions such as ...
This lets you see what is going on as the shell
program runs.
@c ? program = script?
It shows you what the shell did to your command line as
a result of all the substitutions that took place.  This is useful to
see if your command lines do what you wanted them to do.

In long shell scripts you can get lots of unwanted and unnecessary
debugging information from the shell when the 
@samp{-x} option is used.  You can reduce the amount of output by
turning this option on (@code{set -x})
@c substitute new 'set -o ...' version of above
where you need it and turning it off (@code{set +x}) when you don't.@refill
@c you mean put 'set '  in the script itslf?

Adding @code{echo} statements to the shell script also helps when
debugging.  It's like having @code{print} statments in a program.

You can even check for unset shell variables with the @samp{-u} option. 
When you use this option, attempts to substitute variables that have not
been set causes an error message and execution is stopped.

@c KELLEM: the next sentence sounds incorrect, will have to verify
@c All options can be turned off by saying @code{set -}.
The current setting of the shell options is available as @samp{$-}.

@menu
* More Scripts::   Advanced sample scripts.
@end menu

@node More Scripts,  , Advanced Scripts, Advanced Scripts
@appendixsec More Examples of Shell Scripts

@cindex shell scripts, advanced examples of
@cindex scripts, advanced examples of
Here's an example of a more advanced shell script.
@c more advanced than what?
This script tells you which file will be executed when you
use the command you give it as an argument.  It uses @code{sed} to
split your path, inserting dots in place of null strings to preserve
the shell semantics.  It tests each directory on your path for an
executable file whose name is the same as the argument you gave to the
script.  If it finds one, it tells you what it is and exits with a
successful status.  If no executable files are found, the script exits
with a failure status.

@example
#
# which -- find out which command in $PATH is executed
#
# adapted from Kernighan and Pike
#
opath=$PATH
PATH=/usr/ucb:/bin:/usr/bin

case $# in
    0)
     echo "usage: $0 command" 1>&2
     exit 1
     ;;
    *)
     ;;
esac

@c !!! my god!!!!  teco**(teco**2)
for i in $(echo $opath | sed 's/^:/.:/
                     s/::/:.:/g
                     s/$:/:./
                     s/:/ /g')
do
     if [ -x $i/$1 ] ; then
          echo $i/$1
          exit 0
     fi
done
exit 1
@end example


Here's another example, submitted by Bennett Todd
(bet@@orion.mc.duke.edu).  It forces the commands run as the arguments
to the script to die after some timeout. This is handy for debugging
full-screen programs (like Emacs) that, if they get hung, wedge the
terminal fatally.

@example
#!/bin/sh
# Launch a sleeping killer-offer

progname=`basename $0`
timeout=10
signal=TERM

while test $# -gt 2 -a `expr "x$1" : "x-."` -gt 0
do
     case "x$1"
     in
          x-t) shift; timeout=$1; shift;;
          x-s) shift;  signal=$1; shift;;
     esac
done

if test $# -lt 1
then
     echo "syntax: $0 [-t timeout] [-s signal] command" 1>&2
     exit 1
fi

(sleep $timeout; kill -$signal $$) &
exec "$@@"
@end example

Finally, here's one more example of a shell script, submitted by Bill
Trost (trost@@reed.bitnet).  It creates an extended version of the
shell's @code{pushd} & @code{popd} commands.  It's slower than the
built-ins, but also adds a couple of features to @code{pushd}: negative
numeric arguments (given a dirstack of size 3, @code{pushd +2} is
equivalent to @code{pushd -1}), and named references.  With a named
reference, a command of the form @code{pushd +xterm} will rotate the
directory stack to the first directory whose final component is
@file{xterm}.  It uses the @samp{#} variable construct, and lots of
@code{sets} and @code{shifts}.

@example
# A shell-level version of pushd and popd.  A bit slower, a bit
# cleverer.  I added a feature, which is best described by
# example.
# Suppose you have the directory stack consisting of /tmp,
# /local/src/X11r4/mit/clients/xterm, and ~/prj/term (/tmp at the
# top).  If you type "pushd +xterm", you'll end up in the first
# directory whose name end with "xterm".

# This is a complete rewrite of a similar function posted to
# gnu.bash.bug by Martin Tomes <mt00@@eurotherm.co.uk>.  I've done
# a little benchmarking, and this version's pushd appears to be 
# gobs faster; this is probably due to my use of the case 
# construct instead of if/elif/fi.  The if construct (at least in
# Bourne shell) has historically been very slow.  Then again,
# popd was just as fast...?
# The alternative explanation is that his frequent use of the
# "cut" and "expr" commands slowed things down.

# This program expects the "seq" command to give a sequence of
# numbers from $1 to $2.  I have a "seq" function which is
# usually very fast.

dirs () @{ echo $PWD $DIRS @}

pushd () @{
  case "$1" in
    "")
        # Swap first two.
        local here=$PWD
        set $DIRS
        cd "$1"
        shift
        DIRS="$here $*"
        ;;
    +[0-9]*)
        local save i=$@{1#+@}
        set $PWD $DIRS
        for i in `seq 1 $i`; do
          [ "$1" = "" ] && @{ set $PWD $DIRS ; save= @}
          save="$save $1"
          shift
        done
        [ "$1" = "" ] || @{
          cd $1
          shift
          DIRS="$* $save"
        @}
        ;;
    [-][0-9]*)
        local dest=$@{1#-@}
        set $PWD $DIRS
        pushd +`expr $# -  \\( $dest % $# \\)`
        ;;
    +?*)
        # Feature: pushd +foo will push to directory whose
        # basename is "foo".
        local wrap i goal=$@{1#+@} found=false
        set $PWD $DIRS
        for i; do
          [ $@{i##*/@} = "$goal" ] && @{
            cd $i
            shift
            DIRS="$* $wrap"
            found=true
            break
          @}
          wrap="$wrap $i"
          shift
        done
        $found || @{
          echo $@{goal@}: Directory not on stack. 1>&2
          return 1
        @}
        ;;
    *)
        [ ! -d $1 ] && @{
          echo "$1": No such file or directory 1>&2
          return 1
        @}
        DIRS="$PWD $DIRS"
        cd $1
        ;;
  esac
  true $@{pushd_silent:-`dirs`@}
@}

popd () @{
  [ -z "$DIRS" ] && @{
    echo popd: Directory stack empty 1>&2
    return 1
  @}
  case "$1" in
    "")
        set $DIRS
        cd $1
        shift
        DIRS="$*"
        ;;
    +*)
        count=$1
        set $DIRS
        # Hack until builtin test works correctly with unary +
        /bin/[ $count -gt $# ] && @{
          echo popd: Directory stack not that deep 1>&2
          return 1
        @}
        DIRS="`echo $DIRS | awk '@{ $'$count' = \"\"; print @}'`"
        ;;
    *)
        echo 'popd: usage: popd [ +n ]' 1>&2
        return 1
        ;;
  esac
  true $@{pushd_silent:-`dirs`@}
@}
@end example


@node Tools, Authors, Advanced Scripts, Top
@appendix Useful Operating System Programs

This is the section that will include useful and related operating
system commands (NOT built-ins) to use with the shell and shell
procedures.

If you think that various utilities and commands used to support shell
programming belong in the shell programming manual, then go ahead and
add them yourself.  Personally, I feel that there is no good determiner
of whether a utility belongs in the shell programming manual or whether
it belongs in the GNU operating system manual.

@c following note by JEMS
@c maybe should include  those used in examples
@c (e.g. ls, rm cat, who, sort, date, more, wc, ...)

@node Authors, Concept Index, Tools, Top
@appendix Who and Where to Write

@c main topic is acknowledgments, not who to write

@cindex authors
This manual is a combined effort of a number of people.  Diane Barlow
Close (close@@lunch.wpd.sgi.com) wrote the original draft.  Julie
Sussman (jems@@altdorf.lcs.mit.edu) did the majority of reorganization
and the second draft.  Without her help, this manual would probably
still be waiting to be written.  Brian Fox (bfox@@ai.mit.edu) produced
the third draft, and provided technical advice for Diane and Julie.

Chet Ramey (chet@@cwns1.ins.cwru.edu) provided many examples for this
manual and wrote the BASH man page.

Richard Stallman (rms@@ai.mit.edu) provided editing and polishing of
the finished product.

Others who provided assistance of varying degrees are mentioned in the
acknowledgement section (@pxref{Thanks}).

Errors concerning this documentation should be sent to
bug-bash-manual@@ai.mit.edu.  @xref{Bugs}, for information on where to
send bug reports for BASH itself.@refill

@node Concept Index,  , Authors, Top
@unnumbered Concept Index

@printindex cp

@summarycontents
@contents
@bye