     This text is a cursory description of the features that are present in
     the Bash shell.

     Copyright (C) 1991 Free Software Foundation, Inc.

     This file is part of GNU Bash, the Bourne Again SHell.

     Bash is free software; you can redistribute it and/or modify it
     under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 1, or (at your option)
     any later version.

     Bash is distributed in the hope that it will be useful, but WITHOUT
     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
     or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
     License for more details.

     You should have received a copy of the GNU General Public License
     along with Bash; see the file COPYING.  If not, write to the Free
     Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

Bash Features
*************

Bash contains features that appear in other popular shells, and some features that only appear in Bash.  Some of the shells that Bash has borrowed concepts from are the Bourne Shell (sh), the Korn Shell (ksh), and the C-shell (csh and its successor, tcsh). The following menu breaks the features up into categories based upon which one of these other shells inspired the feature.

Bourne Shell Style Features
***************************

Bash is an acronym for Bourne Again SHell, the traditional Unix shell written by Stephen Bourne.  All of the Bourne shell builtin commands are available in Bash, and the rules for evaluation and quoting are taken from the Posix 1003 specification for the `standard' Unix shell.

The shell builtin control features are briefly discussed here.

Looping Constructs
==================

Note that wherever you see an ; in the description of a command's syntax, it can be replaced indiscriminately with newlines.

Bash supports the following looping constructs.

until
     The syntax of the until command is:

          until TEST-COMMANDS; do CONSEQUENT-COMMANDS; done

     Execute CONSEQUENT-COMMANDS as long as the final command in TEST-COMMANDS has an exit status which is not zero.

while
     The syntax of the while command is:

          while TEST-COMMANDS; do CONSEQUENT-COMMANDS; done

     Execute CONSEQUENT-COMMANDS as long as the final command in TEST-COMMANDS has an exit status of zero.

for
     The syntax of the for command is:

          for NAME [in WORDS ...]; do COMMANDS; done

     Execute COMMANDS for each member in WORDS, with NAME bound to the current member.  If ``in WORDS'' is not present, ``in "$@"'' is assumed.

Conditional Constructs
======================

if
     The syntax of the if command is:

          if TEST-COMMANDS; then
            CONSEQUENT-COMMANDS;
          [else ALTERNATE-CONSEQUENTS;]
          fi

     Execute CONSEQUENT-COMMANDS only if the final command in TEST-COMMANDS has an exit status of zero.  If ``else ALTERNATE-CONSEQUENTS'' is present, and the final command in TEST-COMMANDS has a non-zero exit status, then execute ALTERNATE-CONSEQUENTS.

case
     The syntax of the case command is:

          case WORD in [PATTERN [| PATTERN]...) COMMANDS ;;]... esac

     Selectively execute COMMANDS based upon WORD matching PATTERN.  The `|' is used to separate multiple patterns.

     Here is an example using case in a script that could be used to describe an interesting feature of an animal:

          echo -n "Enter the name of an animal:"
          read ANIMAL
          echo -n "The $ANIMAL has "
          case $ANIMAL in
            horse | dog | cat) echo -n "four";;
            man | kangaroo ) echo -n "two";;
            *) echo -n "an unknown number of";;
          esac
          echo "legs."

(T)C-Shell Style Features
*************************

The C-Shell csh was created by Bill Joy at UC Berkeley.  It is generally considered to have better features for interactive use than the Bourne shell.  Some of the csh features present in Bash include job control, history expansion, `protected' redirection, and several variables for controlling the interactive behaviour of the shell (e.g. ignoreeof).

For details on history expansion, see Using History Interactively.

Bash has tilde (~) expansion, similar, but not identical, to that of csh.  The following table shows what unquoted words beginning with a tilde expand to.

~
     The current value of $HOME.

~/foo
     $HOME/foo

~fred/foo
     The subdirectory foo of the home directory of the user named fred.

~+/foo
     $PWD/foo

~-
     $OLDPWD/foo

Here is a list of the commands and variables whose meanings were taken from csh.

pushd

          pushd [DIR | +N]

     Save the current directory on a list and then CD to DIR.  With no arguments, exchanges the top two directories.

     +N
          Brings the Nth directory to the top of the list by rotating.

     DIR
          Makes the current working directory be the top of the stack, and then cd's to DIR.  You can see the saved directory list with the `dirs' command.

popd

          popd [+N]

     Pops the directory stack, and cd's to the new top directory.  The elements are numbered from 0 starting at the first directory listed with dirs; i.e. popd is equivalent to popd 0.

dirs

          dirs

     Display the list of currently remembered directories.  Directories find their way onto the list with the pushd command; you can get back up through the list with the popd command.

history

          history [N] [ [-w -r] [FILENAME]]

     Display the history list with line numbers.  Lines listed with with a * have been modified.  Argument of N says to list only the last N lines.  Argument -w means write out the current history file.  -r means to read it instead.  If FILENAME is given, then use that file, else if $HISTFILE has a value, use that, else use ~/.bash_history.

ignoreeof
     If this variable is set, it represents the number of consecutive EOFs Bash will read before exiting.  By default, Bash will exit upon reading an EOF character.

Korn Shell Style Features
*************************

fc

          fc [-e ENAME] [-nlr] [FIRST] [LAST]
          fc -s [PAT=REP] [COMMAND]

     Fix Command.  In the first form, a range of commands from FIRST to LAST is selected from the history list.  FIRST and/or LAST may be specified as a string (to locate the most recent command beginning with that string) or as a number (an index into the history list, where a negative number is used as an offset from the current command number).  If LAST is not specified it is set to FIRST.  If FIRST is not specified it is set to the previous command for editing and -16 for listing.  If the -l flag is given, the commands are listed on standard output.  The -n flag suppresses the command numbers when listing.  The -r flag reverses the order of the listing.  Otherwise, the editor given by ENAME is invoked on a file containing those commands.  If ENAME is not given, the value of the following variable expansion is used: ${FCEDIT:-${EDITOR:-vi}.  This says to use the value of the FCEDIT variable if set, or the value of the EDITOR variable if that is set, or vi if neither is set. When editing is complete, the edited commands are echoed and executed.

     In the second form, COMMAND is re-executed after the substitution OLD=NEW is performed.

     A useful alias to use with the fc command is r='fc -s', so that typing r cc runs the last command beginning with cc and typing r re-executes the last command.

typeset
     The typeset command is supplied for compatibility with the Korn shell; however, it has been made obsolete by the presence of the declare command, documented with the Bash specific features.

type
     Bash's type command is a superset of the type found in Korn shells; see Bash Builtins for details.

Bash Specific Features
**********************

Shell Command Line Options
==========================

Along with the single character shell command-line options (see The Set Builtin) there are several other options that you can use. These options must appear on the command line before the single character command options to be recognized.

-norc
     Don't load ~/.bashrc init file. (Default if shell name is `sh').

-rcfile FILENAME
     Load FILENAME init file (instead ~/.bashrc).

-noprofile
     Don't load ~/.bash_profile (nor /etc/profile).

-version
     Display the version number of this shell.

-login
     Make this shell act as if it were directly invoked from login. This is equivalent to ``exec - bash'' but can be issued from another shell, such as csh.  If you wanted to replace your current login shell with a bash login shell, you would say ``exec bash -login''.

-nobraceexpansion
     Do not perform curly brace expansion (foo{a,b} -> fooa foob).

-nolinediting
     Do not use the GNU Readline library to read interactive text lines.

The Set Builtin
===============

This builtin is so overloaded that it deserves its own section.  So here it is.

set

          set [-aefhknotuvxldH] [ARG ...]

     -a
          Mark variables which are modified or created for export.

     -e
          Exit immediately if a command exits with a non-zero status.

     -f
          Disable file name generation (globbing).

     -k
          All keyword arguments are placed in the environment for a command, not just those that precede the command name.

     -m
          Job control is enabled.

     -n
          Read commands but do not execute them.

     -o OPTION-NAME

          Set the variable corresponding to OPTION-NAME:

          allexport
               same as -a.

          braceexpand
               the shell will perform brace expansion.

          emacs
               use an emacs-style line editing interface.

          errexit
               same as -e.

          histexpand
               same as -H.

          ignoreeof
               the shell will not exit upon reading EOF.

          monitor
               same as -m.

          noclobber
               disallow redirection to existing files.

          noexec
               same as -n.

          noglob
               same as -f.

          nohash
               same as -d.

          notify
               notify of job termination immediately.

          nounset
               same as -u.

          verbose
               same as -v.

          vi
               use a vi-style line editing interface.

          xtrace
               same as -x.

     -t
          Exit after reading and executing one command.

     -u
          Treat unset variables as an error when substituting.

     -v
          Print shell input lines as they are read.

     -x
          Print commands and their arguments as they are executed.

     -l
          Save and restore the binding of the NAME in a for command.

     -d
          Disable 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.

     -H
          Enable ! style history substitution.  This flag is on by default.

     Using + rather than - causes these flags to be turned off. The flags can also be used upon invocation of the shell.  The current set of flags may be found in $-.  The remaining ARGs are positional parameters and are assigned, in order, to $1, $2, .. $9.  If no ARGs are given, all shell variables are printed.

Is This Shell Interactive?
==========================

You may wish to determine within a startup script whether Bash is running interactively or not.  To do this, you examine the variable $PS1; it is unset in non-interactive shells, and set in interactive shells.  Thus:

     if [ "$PS1" = "" ]; then
       echo "This shell is not interactive"
     else
       echo "This shell is interactive"
     fi

You can ask an interactive Bash to not run your ~/.bashrc file with the -norc flag.  You can change the name of the ~/.bashrc file to any other file name with -rcfile FILENAME.  You can ask Bash to not run your ~/.bash_profile file with the -noprofile flag.

Controlling the Prompt
======================

The value of the variable $PROMPT_COMMAND is examined just before Bash prints each toplevel prompt.  If it is set and non-null, then the value is executed just as if you had typed it on the command line.

In addition, the following table describes the special characters which can appear in the PS1 variable:

\t
     the time.

\d
     the date.

\n
     CRLF.

\s
     the name of the shell.

\w
     the current working directory.

\W
     the last element of PWD.

\u
     your username.

\h
     the hostname.

\#
     the command number of this command.

\!
     the history number of this command.

\<octal>
     the character code in octal.

\\
     a backslash.

Bash Startup Files
==================

When and how Bash executes ~/.bash_profile, ~/.bashrc, and ~/.bash_logout.

     For Login shells:

         On logging in:
            If /etc/profile exists, then source it.

            If ~/.bash_profile exists, then source it,
               else if ~/.bash_login exists, then source it,
                  else if ~/.profile exists, then source it.

         On logging out:
            If ~/.bash_logout exists, source it.

     For non-login interactive shells:
         On starting up:
            If ~/.bashrc exists, then source it.

     For non-interactive shells:
         On starting up:
            If the environment variable ENV is non-null, source the
            file mentioned there.

So, typically, your ~/.bash_profile contains the line

     if [ -f ~/.bashrc ]; then source ~/.bashrc; fi

after (or before) any login specific initializations.

Bash Builtin Commands
=====================

builtin

          builtin [SHELL-BUILTIN [ARGS]]

     Run a shell builtin.  This is useful when you wish to rename a shell builtin to be a function, but need the functionality of the builtin within the function itself.

declare

          declare [-[frxi]] NAME[=VALUE]

     Declare variables and/or give them attributes.  If no NAMEs are given, then display the values of variables instead.  -f means to use function names only.  -r says to make NAMEs readonly. -x says to make NAMEs export.  -i says that the variable is to be treated as an integer; arithmetic evaluation (see let) will be done when the variable is assigned to.  Using + instead of - turns off the attribute instead.  When used in a function, makes NAMEs local, as with the local command.

type

          type [-all] [-type | -path] [NAME ...]

     For each NAME, indicate how it would be interpreted if used as a command name.

     If the -type flag is used, type returns a single word which is one of ``alias'', ``function'', ``builtin'', ``file'' or ``'', if NAME is an alias, shell function, shell builtin, disk file, or unfound, respectively.

     If the -path flag is used, type either returns the name of the disk file that would be exec'ed, or nothing if -type wouldn't return ``file''.

     If the -all flag is used, returns all of the places that contain an executable named FILE.  This includes aliases and functions, if and only if the -path flag is not also used.

enable

          enable [-n] [NAME ...]

     Enable and disable builtin shell commands.  This allows you to use a disk command which has the same name as a shell builtin.  If -n is used, the NAMEs become disabled.  Otherwise NAMEs are enabled.  For example, to use the test found on your path instead of the shell builtin version, you type enable -n test.

help

          help [PATTERN]

     Display helpful information about builtin commands.  If PATTERN is specified, gives detailed help on all commands matching PATTERN, otherwise a list of the builtins is printed.

command

          command [COMMAND [ARGS ...]]

     Runs COMMAND with ARG ignoring shell functions.  If you have a shell function called ls, and you wish to call the command ls, you can say ``command ls''.

hash

          hash [-r] [NAME]

     For each NAME, the full pathname of the command is determined and remembered.  The -r option causes the shell to forget all remembered locations.  If no arguments are given, information about remembered commands is presented.

local

          local NAME[=VALUE]

     Create a local variable called NAME, and give it VALUE. local can only be used within a function; it makes the variable NAME have a visible scope restricted to that function and its children.

readonly

          readonly [-f] [NAME ...]

     The given NAMEs are marked readonly and the values of these NAMEs may not be changed by subsequent assignment.  If the -f option is given, the functions corresponding to the NAMEs are so marked.  If no arguments are given, a list of all readonly names is printed.

ulimit

          ulimit [-acdmstfpn [limit]]

     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:

     -a
          all current limits are reported.

     -c
          the maximum size of core files created.

     -d
          the maximum size of a process's data segment.

     -m
          the maximum resident set size.

     -s
          the maximum stack size.

     -t
          the maximum amount of cpu time in seconds.

     -f
          the maximum size of files created by the shell.

     -p
          the pipe buffer size.

     -n
          the maximum number of open file descriptors.

     If LIMIT is given, it is the new value of the specified resource. Otherwise, the current value of the specified resource is printed.  If no option is given, then -f is assumed.  Values are in 1k increments, except for -t, which is in seconds, and -p, which is in increments of 512 bytes.

Bash Variables
==============

history_control

     Set to a value of "ignorespace", it means don't enter lines which begin with a SPC on the history list.  Set to a value of "ignoredups", it means don't enter lines which match the last entered line.  Unset, or any other value than those above mean to save all lines on the history list.

HISTFILE
     The name of the file that the command history is saved in.

HISTSIZE
     If set, this is the maximum number of commands to remember in the history.

histchars
     Up to three characters which control history expansion, quick substitution, and tokenization.  The first character is the history-expansion-char, that is, the character which signifies the start of a history expansion, normally `!'.  The second character is the character which signifies `quick substitution' when seen as the first character on a line, normally `^'.  The optional third character is the character which signifies the remainder of the line is a comment, when found as the first character of a word, usually `#'.

hostname_completion_file
     Contains the name of a file in the same format as /etc/hosts that should be read when the shell needs to complete a hostname.  You can change the file interactively; the next time you want to complete a hostname Bash will add the contents of the new file to the already existing database.

MAILCHECK
     How often (in seconds) that the shell should check for mail in the file(s) specified in MAILPATH.

MAILPATH
     Colon separated list of pathnames to check for mail in.  You can also specify what message is printed by separating the pathname from the message with a ?.  $_ stands for the name of the current mailfile.  For example:

          MAILPATH='/usr/spool/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"'

ignoreeof
IGNOREEOF
     Controls the action of the shell on receipt of an EOF character as the sole input.  If set, then the value of it is the number of EOF characters that can be seen in a row as sole input characters before the shell will exit.  If the variable exists but does not have a numeric value (or has no value) then the default is 10. if the variable does not exist, then EOF signifies the end of input to the shell.  This is only in effect for interactive shells.

auto_resume
     This variable controls how the shell interacts with the user and job control.  If this variable exists then single word simple commands without redirects are treated as candidates for resumption of an existing job.  There is no ambiguity allowed; if you have more than one job beginning with the string that you have typed, then the most recently accessed job will be selected.

no_exit_on_failed_exec
     If this variable exists, the shell will not exit in the case that it couldn't execute the file specified in the exec command.

PROMPT_COMMAND
     If present, this contains a string which is a command to execute before the printing of each toplevel prompt.

nolinks
     If present, says not to follow symbolic links when doing commands that change the current working directory.  By default, bash follows the logical chain of directories when performing cd type commands.

     For example, if /usr/sys is a link to /usr/local/sys then:

          cd /usr/sys; echo $PWD -> /usr/sys
          cd ..; pwd -> /usr

     If nolinks exists, then:

          cd /usr/sys; echo $PWD -> /usr/local/sys
          cd ..; pwd -> /usr/local

     [file hsuser.texinfo not included]
     [file rluser.texinfo not included]