@c $Id: the-shell.texinfo,v 1.29 2001/06/04 15:29:18 m Exp m $
@node Shell, X, Basics, Getting Started
@comment  node-name,  next,  previous,  up
@chapter The Shell
@cindex the shell
@cindex shells
@cindex Bourne, Steve
@cindex shell prompt
@pindex adduser
@pindex bash
@pindex sh

@noindent
The subject of this chapter is the @dfn{shell}, the program that reads
your command input and runs the specified commands. The shell
environment is the most fundamental way to interact with the
system---you are said to be ``in'' a shell from the very moment you've
successfully logged in to the system.

The @samp{$} character preceding the cursor is called the @dfn{shell
prompt}; it tells you that the system is ready and waiting for input. On
Debian systems, the default shell prompt also includes the name of the
current directory (@pxref{Files and Directories, , Files and
Directories}). A tilde character (@samp{~}) denotes your home directory,
which is where you'll find yourself when you log in.

For example, a typical user's shell prompt might look like this:

@example
@cartouche
~ $ _
@end cartouche
@end example

If your shell prompt shows a number sign (@samp{#}) instead of a
@samp{$}, this means that you're logged in with the superuser, or
@code{root}, account. Beware: the @code{root} account has complete
control over the system; one wrong keystroke and you might accidentally
break it something awful. You need to have a different user account for
yourself, and use that account for your regular use (@pxref{Making
Accounts, , Making a User Account}).

Every Linux system has at least one shell program, and most have
several. We'll cover @code{bash}, which is the standard shell on most
Linux systems. (Its name stands for ``Bourne again shell''---a pun on
the name of Steve Bourne, who was author of the traditional Unix shell,
the Bourne shell.)

@sp .25
@noindent
@strong{NOTE:} @inforef{Top, The GNU Bash Reference Manual,
bashref.info}, for more information on using @code{bash}.

@menu
* Input Line::                  Using the command line.
* Redirection::                 How to redirect input and output.
* Managing Jobs::               Managing your jobs.
* Command History::             Using the command history.
* Typescripts::                 Making a typescript of a shell session.
* Shell Customizing::           Popular ways to customize your shells.
@end menu


@node Input Line, Redirection, Shell, Shell
@comment  node-name,  next,  previous,  up
@section Keys for Command Line Editing
@cindex keys for command line editing
@cindex command line editing, keys for
@cindex shell prompt
@cindex input line
@cindex command line
@cindex Emacs
@cindex Vi
@pindex hostname

@noindent
In @ref{Commands, , Running a Command}, you learned how to run commands
by typing them in at the shell prompt. The text you type at a shell
prompt is called the @dfn{command line} (it's also called the @dfn{input
line}).

The following table describes the keystrokes used for typing command
lines.

@multitable @columnfractions .30 .70
@item @sc{Keystrokes}
@tab @sc{Description}
@item @var{text}
@tab Insert @var{text} at the point where the cursor is at; if there is
text to the right of the cursor, it is shifted over to the right.

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

@item @key{DEL}
@tab Delete the character the cursor is underneath.

@item @key{RET}
@tab Send the command line to @code{bash} for execution (in other words,
it runs the command typed at the shell prompt). You don't have to be at
the far right end of the command line to type @key{RET}; you can type it
when the cursor is anywhere on the command line. 

@item @code{C-a}
@tab Move the cursor to the beginning of the input line.

@item @code{C-d}
@tab Same as @key{DEL} (this is the Emacs equivalent).

@item @code{C-e}
@tab Move the cursor to the end of the input line.

@item @code{C-k}
@tab Kill, or ``cut,'' all text on the input line, from the character
the cursor is underneath to the end of the line.

@item @code{C-l}
@tab Clear the terminal screen.

@item @code{C-u}
@tab Kill the entire input line.

@item @code{C-y}
@tab Yank, or ``paste,'' the text that was last killed. Text is inserted
at the point where the cursor is.

@item @code{C-_}
@tab Undo the last thing typed on this command line.

@item @key{@math{@leftarrow}}
@tab Move the cursor to the left one character.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the <- arrow key.]
@end ifinfo

@item @key{@math{@rightarrow}}
@tab Move the cursor to the right one character.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the -> arrow key.]
@end ifinfo

@item @key{@math{@uparrow}} @var{and} @key{@math{@downarrow}}
@tab Cycle through the command history (@pxref{Command History, ,
Command History}).
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the up and down arrow keys.]
@end ifinfo
@end multitable

@sp .25
@noindent
@strong{NOTE:} These keyboard commands are the same as those used by the
Emacs editor (@pxref{Emacs, , Emacs}). Many other Emacs keyboard
commands also work on the command line (@pxref{Emacs Editing, , Basic
Emacs Editing Keys}). And, for Vi aficionados, it is possible to
configure @code{bash} to recognize Vi-style bindings instead.

The following sections describe some important features of command line
editing, such as quoting special characters and strings, letting the
shell complete your typing, re-running commands, and running multiple
commands. @inforef{Command Line Editing, The GNU Bash Reference Manual,
bashref.info} for more information on @code{bash}'s command line editing
features.

@menu
* Quoting::                     Quoting special characters and strings.
* Completion::                  Let bash complete what you type.
* Repeating Commands::          Running a command more than once.
* Multiple Commands::           Running more than one command at a time.
@end menu


@node Quoting, Completion, Input Line, Input Line
@comment  node-name,  next,  previous,  up
@subsection Passing Special Characters to Commands
@cindex passing special characters to commands
@cindex special characters, passing to commands
@cindex quoting characters
@cindex characters, quoting
@cindex pilcrow sign
@pindex figlet

@noindent
Some characters are @emph{reserved} and have special meaning to the
shell on their own. Before you can pass one of these characters to a
command, you must @dfn{quote} it by enclosing the entire argument in
single quotes (@samp{'}).

For example, here's how to pass @samp{Please Stop!} to a command:

@example
'Please Stop!'
@end example

When the argument you want to pass has one or more single quote
characters in it, enclose it in double quotes, like so:

@example
"Please Don't Stop!"
@end example

To pass special characters as a string, give them as:

@example
@kbd{$'@var{string}'}
@end example

@noindent
where @var{string} is the string of characters to be passed. Special
backslash escape sequences for certain characters are commonly included
in a string, as listed in the following table.

@need 1000

@multitable @columnfractions .30 .70
@item @sc{Escape Sequence}
@tab @sc{Description}
@item @code{\a}
@tab Alert (rings the system bell).

@item @code{\b}
@tab Backspace.

@item @code{\e}
@tab Escape.

@item @code{\f}
@tab Form feed.

@item @code{\n}
@tab Newline.

@item @code{\r}
@tab Carriage return.

@item @code{\t}
@tab Horizontal tab.

@item @code{\v}
@tab Vertical tab.

@item @code{\\}
@tab Backslash.

@item @code{\@var{NNN}}
@tab Character whose ASCII code is @var{NNN} in octal (base 8).
@end multitable

To demonstrate the passing of special character sequences to tool, the
following examples will use the @code{figlet} tool, which displays the
text you give as an argument in a ``font'' made up of text characters
(@pxref{Figlet, , Horizontal Text Fonts}).

@itemize @bullet
@item
To pass a backslash character as an argument to @code{figlet}, type:

@example
$ @kbd{figlet $'\\' @key{RET}}
@end example

@item 
To pass a form feed character followed by a pilcrow sign character
(octal character code 266) to @code{figlet}, type:

@example
$ @kbd{echo $'\f\266' @key{RET}}
@end example
@end itemize


@node Completion, Repeating Commands, Quoting, Input Line
@comment  node-name,  next,  previous,  up
@subsection Letting the Shell Complete What You Type
@cindex letting the shell complete what you type
@cindex tab completion
@cindex completion, tab

@noindent
@dfn{Completion} is where @code{bash} does its best to finish your
typing. To use it, press @key{TAB} on the input line and the shell will
@emph{complete} the word to the left of the cursor to the best of its
ability. Completion is one of those things that, once you begin to use
it, you will wonder how you ever managed to get by without.

Completion works on both file names and command names, depending on the
context of the cursor when you type @key{TAB}.

For example, suppose you want to specify, as an argument to the
@code{ls} command, the @file{/usr/lib/emacs/20.4/i386-debian-linux-gnu/}
directory---that's a lot to type. So instead of typing out the whole
directory name, you can type @key{TAB} to complete it for you. Notice
how our first attempt, typing only the letter @samp{e} in @samp{/e},
brings up a series of files---while the second attempt, typing
@samp{em}, further refines our search:

@example
$ @kbd{ls /usr/lib/e@key{TAB}}
elm-me+    emacs      emacsen-common  entity-map    expect5.30
$ @kbd{ls /usr/lib/em@key{TAB}}
@end example

At this point, the system beeps@footnote{The Unix way of saying it is
that the command ``rings the system bell.''} and the shell completes the
word @samp{emacs}, since all options in this directory beginning with
the letters @samp{em} complete to at least that word. Press
@kbd{/@key{TAB}} to access this word and go on, and the shell completes
the subdirectory @file{20.4} since that is the only file or directory in
the @file{emacs} subdirectory:

@example
$ ls /usr/lib/emacs@kbd{/@key{TAB}@var{20.4/}}
@end example

Press @key{TAB} again to have the shell complete the only subdirectory in
@file{20.4}:

@example
$ ls /usr/lib/emacs/20.4/@kbd{@key{TAB}@var{i386-debian-linux-gnu/}}
@end example

@sp .25
@noindent
@strong{NOTE:} Many applications also support command and/or file name
completion; the most famous example of this is the Emacs text editor
(@pxref{Emacs, , Emacs}).


@node Repeating Commands, Multiple Commands, Completion, Input Line
@comment  node-name,  next,  previous,  up
@subsection Repeating the Last Command You Typed
@cindex repeating the last command you typed
@cindex command, repeating the last 
@cindex reverse incremental search
@cindex history

@noindent
Type @key{@math{@uparrow}} to put the last command you typed back on the
input line. You can then type @key{RET} to run the command again, or you
can edit the command first.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo

@itemize @bullet
@item
To repeat the last command entered, type:

@example
$ @kbd{@key{@math{@uparrow}} @key{RET}}
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo
@end example
@end itemize

The @key{@math{@uparrow}} key moves the last command you typed back to
the input line, and @key{RET} executes it.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo

By typing @key{@math{@uparrow}} more than once, you can go back to
earlier commands you've typed; this is a function of your command
@emph{history}, which is explained in full in @ref{Command History, ,
Command History}.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo

Additionally, you can use the @code{bash} reverse-incremental search
feature, @kbd{C-r}, to @emph{search}, in reverse, through your command
history. You'll find this useful if you remember typing a command line
with @samp{foo} in it recently, and you wish to repeat the command
without having to retype it. Type @kbd{C-r} followed by the text
@kbd{foo}, and the last command you typed containing @samp{foo} appears
on the input line.

Like the Emacs command of the same name (@pxref{Emacs Incremental
Search, , Searching Incrementally in Emacs}), this is called an
@emph{incremental} search because it builds the search string in
character increments as you type. Typing the string @samp{cat} will
first search for (and display) the last input line containing a
@samp{c}, then @samp{ca}, and finally @samp{cat}, as you type the
individual characters of the search string. Typing @kbd{C-r} again
retrieves the next previous command line that has a match for the search
string.

@itemize @bullet
@item
To put the last command you entered containing the string @samp{grep}
back on the input line, type:

@example
$ @kbd{C-r}
(reverse-i-search)`': @kbd{grep}
@end example

@item
To put the third-to-the-last command you entered containing the string
@code{grep} back on the input line, type:

@example
$ @kbd{C-r}
(reverse-i-search)`': @kbd{grep} 
@kbd{C-r C-r}
@end example
@end itemize

When a command is displayed on the input line, type @key{RET} to
run it. You can also edit the command line as usual.


@node Multiple Commands, , Repeating Commands, Input Line
@comment  node-name,  next,  previous,  up
@subsection Running a List of Commands
@cindex running a list of commands
@cindex commands, running a list of
@pindex clear
@pindex hostname
@pindex logout

@noindent
To run more than one command on the input line, type each command in the
order you want them to run, separating each command from the next with a
semicolon (@samp{;}). You'll sometimes find this useful when you want to
run several non-interactive commands in sequence.

@itemize @bullet
@item
To clear the screen and then log out of the system, type:

@example
$ @kbd{clear; logout @key{RET}}
@end example

@item
To run the @code{hostname} command three times, type:

@example
@cartouche
$ @kbd{hostname; hostname; hostname @key{RET}}
figaro
figaro
figaro
$
@end cartouche
@end example
@end itemize


@node Redirection, Managing Jobs, Input Line, Shell
@comment  node-name,  next,  previous,  up
@section Redirecting Input and Output
@cindex redirecting input and output
@cindex shell redirection
@cindex standard input
@cindex standard output
@cindex standard error
@cindex streams

@noindent
The shell moves text in designated ``streams.'' The @dfn{standard
output} is where the shell streams the text output of commands---the
screen on your terminal, by default. The @dfn{standard input}, typically
the keyboard, is where you input data for commands. When a command reads
the standard input, it usually keeps reading text until you type
@kbd{C-d} on a new line by itself.

When a command runs and exits with an error, the error message is
usually output to your screen, but as a separate stream called the
@dfn{standard error}.

You redirect these streams---to a file, or even another command---with
@dfn{redirection}. The following sections describe the shell redirection
operators that you can use to redirect standard input and output.

@menu
* Standard Input::              Redirecting standard input.
* Standard Output::             Redirecting standard output.
* Standard Error::              Redirecting standard error.
* Pipelines::                   Building pipelines.
@end menu


@node Standard Input, Standard Output, Redirection, Redirection
@comment  node-name,  next,  previous,  up
@subsection Redirecting Input to a File
@cindex redirecting input to a file
@cindex file, redirecting input to a
@cindex input, redirecting
@cindex standard input
@pindex apropos

@noindent
To redirect standard input to a file, use the @samp{<} operator. To do
so, follow a command with @kbd{<} and the name of the file it should
take input from. For example, instead of giving a list of keywords as
arguments to @code{apropos} (@pxref{Apropos, , Finding the Right Tool
for the Job}), you can redirect standard input to a file containing a
list of keywords to use.

@itemize @bullet
@item
To redirect standard input for @code{apropos} to file @file{keywords},
type:

@example
$ @kbd{apropos < keywords @key{RET}}
@end example
@end itemize


@node Standard Output, Standard Error, Standard Input, Redirection
@comment  node-name,  next,  previous,  up
@subsection Redirecting Output to a File
@cindex redirecting output to a file
@cindex file, redirecting output to a
@cindex output, redirecting
@cindex standard output
@pindex apropos

@noindent
Use the @samp{>} operator to redirect standard output to a file. To use
it, follow a command with @kbd{>} and the name of the file the output
should be written to.

@itemize @bullet
@item
To redirect standard output of the command @kbd{apropos shell bash} to
the file @file{commands}, type:

@example
$ @kbd{apropos shell bash > commands @key{RET}}
@end example
@end itemize

If you redirect standard output to an existing file, it will overwrite
the file, unless you use the @samp{>>} operator to @emph{append} the
standard output to the contents of the existing file.

@itemize @bullet
@item
To append the standard output of @kbd{apropos shells} to an existing
file @file{commands}, type:

@example
$ @kbd{apropos shells >> commands @key{RET}}
@end example
@end itemize


@node Standard Error, Pipelines, Standard Output, Redirection
@comment  node-name,  next,  previous,  up
@subsection Redirecting Error Messages to a File
@cindex redirecting error messages to a file
@cindex file, redirecting error messages to a 
@cindex error messages, redirecting to a file

@noindent
To redirect the standard error stream to a file, use the @samp{>}
operator preceded by a @samp{2}. Follow a command with @kbd{2>} and the
name of the file the error stream should be written to.

@itemize @bullet
@item
To redirect the standard error of @kbd{apropos shell bash} to the file
@file{command.error}, type: 

@example
$ @kbd{apropos shell bash 2> command.error @key{RET}}
@end example
@end itemize

As with the standard output, use the @samp{>>} operator instead of
@samp{>} to @emph{append} the standard error to the contents of an
existing file. 

@itemize @bullet
@item
To append the standard error of @kbd{apropos shells} to an existing file
@file{command.error}, type:

@example
$ @kbd{apropos shells 2>> command.error @key{RET}}
@end example
@end itemize

To redirect @emph{both} standard output and standard error to the same
file, use @samp{&>} instead.

@itemize @bullet
@item
To redirect the standard output @emph{and} the standard error of
@kbd{apropos shells} to the file @file{commands}, type: 

@example
$ @kbd{apropos shells &> commands @key{RET}}
@end example
@end itemize


@node Pipelines, , Standard Error, Redirection
@comment  node-name,  next,  previous,  up
@subsection Redirecting Output to Another Command's Input
@cindex redirecting output to another command's input
@cindex input, redirecting output to another command's 
@cindex pipe
@cindex pipeline
@cindex commands, piping
@pindex apropos
@pindex less

@noindent
@dfn{Piping} is when you connect the standard output of one command to
the standard input of another. You do this by specifying the two
commands in order, separated by a vertical bar character, @samp{|}
(sometimes called a ``pipe''). Commands built in this fashion are called
@dfn{pipelines}.

For example, it's often useful to pipe commands that display a lot of
text output to @code{less}, a tool for perusing text (@pxref{Perusing
Text, , Perusing Text}).

@itemize @bullet
@item
To pipe the output of @kbd{apropos bash shell shells} to @code{less},
type:

@example
$ @kbd{apropos bash shell shells | less @key{RET}}
@end example
@end itemize

This redirects the standard output of the command @kbd{apropos bash
shell shells} to the standard input of the command @kbd{less}, which
displays it on the screen.


@node Managing Jobs, Command History, Redirection, Shell
@comment  node-name,  next,  previous,  up
@section Managing Jobs
@cindex managing jobs
@cindex jobs, managing
@cindex background jobs
@cindex foreground jobs
@cindex job number
@cindex processes

@noindent
The processes you have running in a particular shell are called your
@dfn{jobs}. You can have more than one job running from a shell at once,
but only one job can be active at the terminal, reading standard input
and writing standard output. This job is the @dfn{foreground} job, while
any other jobs are said to be running in the @dfn{background}.

The shell assigns each job a unique @dfn{job number}. Use the job
number as an argument to specify the job to commands. Do this by giving
the job number preceded by a @samp{%} character.

To find the job number of a job you have running, list your jobs
(@pxref{Listing Jobs, , Listing Your Jobs}).

The following sections describe the various commands for managing jobs.

@menu
* Suspending Jobs::             Suspending a job to do something else.
* Background Jobs::             Having jobs work in the background.
* Foreground Jobs::             Putting jobs in the foreground.
* Listing Jobs::                Listing your jobs.
* Stopping Jobs::               Stopping jobs before they're finished.
@end menu


@node Suspending Jobs, Background Jobs, Managing Jobs, Managing Jobs
@comment  node-name,  next,  previous,  up
@subsection Suspending a Job
@cindex suspending a job
@cindex jobs, suspending

@noindent
Type @kbd{C-z} to suspend or stop the foreground job---useful for when
you want to do something else in the shell and return to the current job
later. The job stops until you either bring it back to the foreground or
make it run in the background (@pxref{Foreground Jobs, , Putting a Job
in the Foreground} and @pxref{Background Jobs, , Putting a Job in the
Background}).

For example, if you are reading a document in @code{info}, typing
@kbd{C-z} will suspend the @code{info} program and return you to a shell
prompt where you can do something else (@pxref{Info, , Using the GNU
Info System}). The shell outputs a line giving the job number (in
brackets) of the suspended job, the text @samp{Stopped} to indicate that
the job has stopped, and the command line itself, as shown here:

@example
[1]+  Stopped                 info -f cookbook.info
@end example

In this example, the job number is 1 and the command that has stopped is
@samp{info -f cookbook.info}. The @samp{+} character next to the job
number indicates that this is the most recent job.

If you have any stopped jobs when you log out, the shell will tell you
this instead of logging you out:

@example
@cartouche
$ @kbd{logout @key{RET}}
There are stopped jobs.
$
@end cartouche
@end example

At this point you can list your jobs (@pxref{Listing Jobs, , Listing
Your Jobs}), stop any jobs you have running (@pxref{Stopping Jobs, ,
Stopping a Job}), and then log out.


@node Background Jobs, Foreground Jobs, Suspending Jobs, Managing Jobs
@comment  node-name,  next,  previous,  up
@subsection Putting a Job in the Background
@cindex putting a job in the background
@cindex background, putting a job in the
@cindex jobs, background
@pindex apropos

@noindent
New jobs run in the foreground unless you specify otherwise. To run a
job in the background, end the input line with an ampersand (@samp{&}).
This is useful for running non-interactive programs that perform a lot
of calculations.

@itemize @bullet
@item
To run the command @kbd{apropos shell > shell-commands} as a background
job, type:

@example
@cartouche
$ @kbd{apropos shell > shell-commands & @key{RET}}
[1] 6575
$ 
@end cartouche
@end example
@end itemize

The shell outputs the job number (in this case, 1) and process ID (in
this case, 6575), and then returns to a shell prompt. When the
background job finishes, the shell will list the job number, the
command, and the text @samp{Done}, indicating that the job has completed
successfully:

@example
[1]+  Done                    apropos shell >shell-commands
@end example

To move a job from the foreground to the background, first suspend it
(@pxref{Suspending Jobs, , Suspending a Job}) and then type @kbd{bg}
(for ``background'').

@itemize @bullet
@item
For example, to start the command @kbd{apropos shell > shell-commands}
in the foreground, suspend it, and then specify that it finish in the
background, you would type:

@example
@cartouche
$ @kbd{apropos shell > shell-commands @key{RET}}
@kbd{C-z}

[1]+  Stopped                 apropos shell >shell-commands
$ @kbd{bg @key{RET}}
[1]+ apropos shell &
$
@end cartouche
@end example
@end itemize

If you have suspended multiple jobs, specify the job to be put in the
background by giving its job number as an argument.

@itemize @bullet
@item
To run job 4 in the background, type:

@example
$ @kbd{bg %4 @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} Running a job in the background is sometimes called
``backgrounding'' or ``amping off'' a job.


@node Foreground Jobs, Listing Jobs, Background Jobs, Managing Jobs
@comment  node-name,  next,  previous,  up
@subsection Putting a Job in the Foreground
@cindex putting a job in the foreground
@cindex foreground, putting a job in the 
@cindex jobs, foreground
@pindex fg

@noindent
Type @kbd{fg} to move a background job to the foreground. By default,
@code{fg} works on the most recent background job.

@itemize @bullet
@item
To bring the most recent background job to the foreground, type:

@example
$ @kbd{fg @key{RET}}
@end example
@end itemize

To move a specific job to the foreground when you have multiple jobs
in the background, specify the job number as an option to @code{fg}. 

@itemize @bullet
@item
To bring job 3 to the foreground, type:

@example
$ @kbd{fg %3 @key{RET}}
@end example
@end itemize


@node Listing Jobs, Stopping Jobs, Foreground Jobs, Managing Jobs
@comment  node-name,  next,  previous,  up
@subsection Listing Your Jobs
@cindex listing your jobs
@cindex jobs, listing your
@pindex jobs
@pindex ps

@noindent
To list the jobs running in the current shell, type @kbd{jobs}.

@itemize @bullet
@item
To list your jobs, type:

@example
@cartouche
$ @kbd{jobs @key{RET}}
[1]-  Stopped                 apropos shell >shell-commands
[2]+  Stopped                 apropos bash >bash-commands
$
@end cartouche
@end example
@end itemize

This example shows two jobs---@kbd{apropos shell > shell-commands} and
@kbd{apropos bash > bash-commands}. The @samp{+} character next to a job
number indicates that it's the most recent job, and the @samp{-}
character indicates that it's the job @emph{previous} to the most recent
job. If you have no current jobs, @code{jobs} returns nothing.

To list all of the @emph{processes} you have running on the system, use
@code{ps} instead of @code{jobs}---see @ref{Processes, , Listing System
Activity}.


@node Stopping Jobs, , Listing Jobs, Managing Jobs
@comment  node-name,  next,  previous,  up
@subsection Stopping a Job
@cindex stopping a job
@cindex jobs, killing
@pindex kill

@noindent
Typing @kbd{C-c} interrupts the foreground job before it completes,
exiting the program. 

@itemize @bullet
@item
To interrupt @kbd{cat}, a job running in the foreground, type:

@example
@cartouche
$ @kbd{cat @key{RET}}
@kbd{C-c @key{RET}}
$
@end cartouche
@end example
@end itemize

Use @code{kill} to interrupt (``kill'') a background job, specifying the
job number as an argument.

@itemize @bullet
@item
To kill job number 2, type:

@example
$ @kbd{kill %2 @key{RET}}
@end example
@end itemize


@node Command History, Typescripts, Managing Jobs, Shell
@comment  node-name,  next,  previous,  up
@section Command History
@cindex command history
@cindex history, command
@cindex event, history

@noindent
Your command @dfn{history} is the sequential list of commands you have
typed, in the current or previous shell sessions. The commands in this
history list are called @dfn{events}.

By default, @code{bash} remembers the last 500 events, but this number
is configurable (@pxref{Bash Login, , Customizing Future Shells}).

Your command history is stored in a text file in your home directory
called @file{.bash_history}; you can view this file or edit it like you
would any other text file.

Two very useful things that having a command history lets you do is to
repeat the last command you typed, and (as explained earlier in this
chapter) to do an incremental backwards search through your history.

The following sections explain how to view your history and specify
events from it on the command line. @inforef{Bash History Facilities,
The GNU Bash Reference Manual, bashref.info}, for more information on
command history.

@menu
* Viewing History::             Viewing the history of what you typed.
* Substituting History::        Substituting a command from your history.
@end menu


@node Viewing History, Substituting History, Command History, Command History
@comment  node-name,  next,  previous,  up
@subsection Viewing Your Command History
@cindex viewing your command history
@cindex history, viewing
@cindex event number
@pindex history
@pindex grep

@noindent
Use @code{history} to view your command history.

@itemize @bullet
@item
To view your command history, type:

@example
@cartouche
$ @kbd{history @key{RET}}
1 who
2 apropos shell >shell-commands
3 apropos bash >bash-commands
4 history
$
@end cartouche
@end example
@end itemize

This command shows the contents of your command history file, listing
one command per line prefaced by its @dfn{event number}. Use an event
number to specify that event in your history (@pxref{Substituting
History, , Specifying a Command from Your History}).

If your history is a long one, this list will scroll off the screen, in
which case you may want to pipe the output to @code{less} in order to
peruse it. It's also common to search for a past command by piping the
output to @code{grep} (@pxref{Pipelines, , Redirecting Output to Another
Command's Input} and @ref{Word Search, , Searching for a Word or
Phrase}).

@itemize @bullet
@item
To search your history for the text @samp{apropos}, type:

@example
@cartouche
$ @kbd{history | grep apropos @key{RET}}
2 apropos shell >shell-commands
3 apropos bash >bash-commands
5 history | grep apropos
$
@end cartouche
@end example
@end itemize

This command will show the events from your history containing the text
@samp{apropos}. (The last line of output is the command you just typed.)


@node Substituting History, , Viewing History, Command History
@comment  node-name,  next,  previous,  up
@subsection Specifying a Command from Your History
@cindex specifying a command from your history
@cindex history, specifying a command from your 
@cindex commands, specifying from your history
@cindex bang

@noindent
You can specify a past event from your history on the input line, in
order to run it again.

The simplest way to specify a history event is to use the up and down
arrow keys at the shell prompt to browse your history. The up arrow key
(@key{@math{@uparrow}}) takes you back through past events, and the down
arrow key (@key{@math{@downarrow}}) moves you forward into recent
history. When a history event is on the input line, you can edit it as
normal, and type @key{RET} to run it as a command; it will then become
the newest event in your history.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo

@itemize @bullet
@item
To specify the second-to-the-last command in your history, type:

@example
$ @kbd{@key{@math{@uparrow}} @key{@math{@uparrow}}}
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo
@end example
@end itemize

To run a history event by its event number, enter an exclamation point
(@samp{!}, sometimes called ``bang'') followed by the event number. (Get
the event number by viewing your history; @pxref{Viewing History, ,
Viewing Your Command History}).

@itemize @bullet
@item
To run history event number 1, type:

@example
$ @kbd{!1 @key{RET}}
@end example
@end itemize


@node Typescripts, Shell Customizing, Command History, Shell
@comment  node-name,  next,  previous,  up
@section Recording a Shell Session
@cindex recording a shell session
@cindex typescripts
@cindex capture logs
@cindex shell session, recording 
@cindex session, recording a
@pindex script

@noindent
Use @code{script} to create a typescript, or ``capture log,'' of a shell
session---it writes a verbatim copy of your session to a file, including
commands you type and their output. The first and last lines of the file
show the beginning and ending time and date of the capture session. To
stop recording the typescript, type @kbd{exit} at a shell prompt. By
default, typescripts are saved to a file called @file{typescript} in the
current directory; specify the file name to use as an argument.

@itemize @bullet
@item
To create a typescript of a shell session and save it to the file
@file{log.19990817}, type:

@example
@cartouche
$ @kbd{script log.19990817 @key{RET}}
Script started, output file is log.19990817
$ @kbd{hostname @key{RET}}
erie
$ @kbd{apropos bash > bash.commands @key{RET}}
$ @kbd{exit @key{RET}}
exit
Script done, output file is log.19990817
$
@end cartouche
@end example
@end itemize

In this example, the typescript records a shell session consisting
of two commands (@code{hostname} and @code{apropos}) to a file
called @file{log.19990817}. The typescript looks like this:

@example
Script started on Tue May 25 14:21:52 1999
$ hostname
erie
$ apropos bash > bash.commands
$ exit
exit

Script done on Tue May 25 14:22:30 1999
@end example

@sp .25
@noindent
@strong{NOTE:} It's possible, but usually not desirable, to run
@code{script} from within another @code{script} session. This usually
happens when you've forgotten that you are running it, and you run it
again inside the current typescript, even multiple times---as a result,
you may end up with multiple sessions ``nested'' inside each other like
a set of Russian dolls.


@node Shell Customizing, , Typescripts, Shell
@comment  node-name,  next,  previous,  up
@section Customizing Your Shell
@cindex customizing your shell
@cindex shell, customizing

@noindent
The following sections describe the most common ways to customize the
shell---including changing the text of the shell prompt and creating
aliases for other commands. These customizations will apply to the rest
of your current shell session, unless you change them again. Eventually,
you will want to make them work all the time, like whenever you log in
or start a new shell---and how to do this is discussed below.

@menu
* Shell Prompt::                Specifying the text to put in the shell prompt.
* Shell Alias::                 Making an alias for a command sequence.
* Adding Path::                 Adding to your path.
* Bash Login::                  Automatically running commands when you first log in.
@end menu


@node Shell Prompt, Shell Alias, Shell Customizing, Shell Customizing
@comment  node-name,  next,  previous,  up
@subsection Changing the Shell Prompt
@cindex changing the shell prompt
@cindex shell prompt, changing
@cindex PS1
@cindex variables, shell
@cindex bell character

@noindent
A shell @dfn{variable} is a symbol that stores a text string, and is
referenced by a unique name. @code{bash} keeps one special variable,
named @code{PS1}, for the text of the shell prompt. To change the text
of the shell prompt, you need to change the contents of the @code{PS1}
variable.

To change a variable's contents, type its name followed by an equal sign
(@samp{=}) character and the string that should replace the variable's
existing contents.

@itemize @bullet
@item
To change your shell prompt to @samp{Your wish is my command: }, type:

@example
@cartouche
$ @kbd{PS1='Your wish is my command: ' @key{RET}}
Your wish is my command: 
@end cartouche
@end example
@end itemize

Since the replacement text has spaces in it, we've quoted it
(@pxref{Quoting, , Passing Special Characters to Commands}).

You can put special characters in the prompt variable in order to output
special text. For example, the characters @samp{\w} in the value of
@code{PS1} will list the current working directory at that place in the
shell prompt text.

@itemize @bullet
@item
To change your prompt to the default @code{bash} prompt---the current
working directory followed by a @samp{$} character---type:

@example
@cartouche
$ @kbd{PS1='\w $ ' @key{RET}}
~ $
@end cartouche
@end example
@end itemize

The following table lists some special characters and their text output
at the shell prompt.

@multitable @columnfractions .30 .70
@item @sc{Special Character}
@tab @sc{Text Output}
@item @code{\a}
@tab Inserts a @kbd{C-g} character, which makes the internal speaker
beep. (It ``rings the system bell''; @kbd{C-g} is sometimes called the
@dfn{bell character}.)

@item @code{\d}
@tab The current date.

@item @code{\h}
@tab The hostname of the system.

@item @code{\n}
@tab A newline character.

@item @code{\t}
@tab The current system time, in 24-hour format.

@item @code{\@@}
@tab The current system time, in 12-hour a.m./p.m. format.

@item @code{\w}
@tab The current working directory.

@item @code{\u}
@tab Your username.

@item @code{\!}
@tab The history number of this command.
@end multitable

You can combine any number of these special characters with regular
characters when creating a value for @code{PS1}.

@itemize @bullet
@item
To change the prompt to the current date followed by a space character,
the hostname of the system in parenthesis, and a greater-than character,
type:

@example
$ @kbd{PS1='\d (\h)>' @key{RET}}
14 Dec 1999 (ithaca)>
@end example
@end itemize


@node Shell Alias, Adding Path, Shell Prompt, Shell Customizing
@comment  node-name,  next,  previous,  up
@subsection Making a Command Alias
@cindex making a command alias
@cindex alias, making a command
@cindex commands, making aliases for
@pindex alias
@pindex ls

@noindent
Use @code{alias} to assign an @dfn{alias}, a name that represents
another command or commands. Aliases are useful for creating short
command names for lengthy and frequently used commands.

@itemize @bullet
@item
To make an alias of @code{bye} for the @code{exit} command, type:

@example
$ @kbd{alias bye="exit" @key{RET}}
@end example
@end itemize

This command makes @samp{bye} an alias for @samp{exit} in the current
shell, so typing @kbd{bye} would then run @kbd{exit}.

You can also include options and arguments in an alias.

@itemize @bullet
@item
To make an alias of @samp{ap} for the command @code{apropos shell bash
shells}, type:

@example
$ @kbd{alias ap="apropos shell bash shells" @key{RET}}
@end example
@end itemize

This command makes @samp{ap} an alias for @samp{apropos shell bash
shells} in the current shell, so typing @kbd{ap} would run @kbd{apropos
shell bash shells}.


@node Adding Path, Bash Login, Shell Alias, Shell Customizing
@comment  node-name,  next,  previous,  up
@subsection Adding to Your Path
@cindex adding to your path
@cindex path, adding to
@cindex .bashrc

@noindent
To add or remove a directory in your path, use a text editor to change
the shell variable @samp{PATH} in the @file{.bashrc} file in your home
directory (@pxref{Text Editing, , Text Editing}). 

For example, suppose the line that defines the @samp{PATH} variable in
your @file{.bashrc} file looks like this:

@example
PATH="/usr/bin:/bin:/usr/bin/X11:/usr/games"
@end example

You can add the directory @file{/home/nancy/bin} to this path,
by editing this line like so:

@example
PATH="/usr/bin:/bin:/usr/bin/X11:/usr/games:/home/nancy/bin"
@end example

@sp .25
@noindent
@strong{NOTE:} See @ref{Files and Directories, , Files and Directories}
for a complete description of directories and the path.


@node Bash Login, , Adding Path, Shell Customizing
@comment  node-name,  next,  previous,  up
@subsection Customizing Future Shells
@cindex customizing future shells
@cindex shell scripts
@cindex clearing the screen
@pindex .bash_profile
@pindex .bash_logout
@pindex .bashrc
@pindex clear

@noindent
There are a number of configuration startup files in your home directory
that you can edit to make your configurations permanent. You can also
edit these files to specify commands to be run whenever you first log
in, log out, or start a new shell. These configuration files are text
files that can be edited with any text editor (@pxref{Text Editing, ,
Text Editing}).

When you log in, @code{bash} first checks to see if the file
@file{/etc/profile} exists, and if so, it executes the commands in this
file. This is a generic, system-wide startup file that is run for all
users; only the system administrator can add or delete commands to this
file.

Next, @code{bash} reads and executes the commands in
@file{.bash_profile}, a ``hidden'' file in your home directory
(@pxref{Listing Hidden, , Listing Hidden Files}). Thus, to make a
command run every time you log in, add the command to this file.

For all new shells after you've logged in (that is, all but the ``login
shell''), @code{bash} reads and executes the commands in the
@file{.bashrc} file in your home directory. Commands in this file run
whenever a new shell is started @emph{except} for the login shell.

There are separate configuration files for login and all other shells so
that you can put specific customizations in your @file{.bash_profile}
that only run when you first log in to the system. To avoid having to
put commands in both files when you want to run the same ones for all
shells, append the following to the end of your @file{.bash_profile}
file:

@example
if [ -f ~/.bashrc ]; then . ~/.bashrc; fi
@end example

This makes @code{bash} run the @file{.bashrc} file in your home
directory when you log in. In this way, you can put @emph{all} of your
customizations in your @file{.bashrc} file, and they will be run
@emph{both} at log in and for all subsequent shells. Any customizations
before this line in @file{.bash_profile} run only when you log in.

For example, a simple @file{.bash_profile} might look like this:

@example
# "Comment" lines in shell scripts begin with a # character.
# They are not executed by bash, but exist so that you may 
# document your file.

# You can insert blank lines in your file to increase readability;
# bash will not mind.

# Generate a welcome message when you log in.
figlet 'Good day, '$USER'!'

# Now run the commands in .bashrc
if [ -f ~/.bashrc ]; then . ~/.bashrc; fi
@end example

This @file{.bash_profile} prints a welcome message with the
@code{figlet} text font tool (@pxref{Figlet, , Horizonal Text Fonts}),
and then runs the commands in the @file{.bashrc} file.

A simple @code{.bashrc} file might look like this:

@example
# Make color directory listings the default.
alias ls="ls --color=auto"

# Make "l" give a verbose directory listing.
alias l="ls -l"

# Set a custom path.
PATH="/usr/local/bin:/usr/bin:/bin:/usr/bin/X11:/usr/games:~/bin:."

# Set a custom shell prompt.
PS1="[\w] $ "

# Make a long history list and history file.
HISTSIZE=20000
HISTFILESIZE=20000

@group
# Export the path and prompt variables for all 
# variables you define.
export HISTSIZE HISTFILESIZE PATH PS1
@end group
@end example

This @file{.bashrc} sets a few useful command aliases and uses a custom
path and shell prompt whenever a new shell is run; with the preceding
@file{.bash_profile}, this @file{.bashrc} is also run at login. 

When you log out, @code{bash} reads and executes the commands in the
@file{.bash_logout} file in your home directory, if it exists. To run
commands when you log out, put them in this file.

@itemize @bullet
@item
To clear the screen every time you log out, your @file{.bash_logout}
would contain the following line:

@example
clear
@end example
@end itemize

This executes the @code{clear} command, which clears the screen of the
current terminal, such as in the @code{xterm} window where you type it,
or in a virtual console. 

@sp .25
@noindent
@strong{NOTE:} Some distributions come with default shell startup files
filled with all kinds of interesting stuff. Debian users might want to
look at the example startup files in
@file{/usr/share/doc/bash/examples/startup-files}.