\input texinfo.tex @c -*- texinfo -*- @c %**start of header @setfilename features.info @settitle Bash Features @c %**end of header @setchapternewpage odd @synindex fn cp @set BashFeatures @ifinfo @format 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. @end format @end ifinfo @titlepage @sp 10 @center @titlefont{Bash Features} @center Cursory Documentation for Bash @center Brian Fox, Free Software Foundation @page @vskip 0pt plus 1filll Copyright @copyright{} 1991 Free Software Foundation, Inc. @end titlepage @ifinfo @node Top @top 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 (@file{sh}), the Korn Shell (@file{ksh}), and the C-shell (@file{csh} and its successor, @file{tcsh}). The following menu breaks the features up into categories based upon which one of these other shells inspired the feature. @menu * Bourne Shell Features:: Features originally found in the Bourne shell. * T-Csh Features:: Features originally found in the Berkeley C-Shell. * Korn Shell Features:: Features originally found in the Korn Shell. * Bash Specific Features:: Features found only in the Bash Shell. * Using History Interactively:: Chapter dealing with history expansion rules. * Command Line Editing:: Chapter describing the command line editing features. * Variable Index:: Quick reference helps you find the variable you want. * Concept Index:: General index for this manual. @end menu @end ifinfo @node Bourne Shell Features @chapter Bourne Shell Style Features Bash is an acronym for Bourne Again SHell. The Bourne shell is 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. @menu * Looping Constructs:: Shell commands for iterative action. * Conditional Constructs:: Shell commands for conditional execution. @end menu @node Looping Constructs @section Looping Constructs Note that wherever you see an @samp{;} in the description of a command's syntax, it can be replaced indiscriminately with newlines. Bash supports the following looping constructs. @ftable @code @item until The syntax of the @code{until} command is: @example until @var{test-commands}; do @var{consequent-commands}; done @end example Execute @var{consequent-commands} as long as the final command in @var{test-commands} has an exit status which is not zero. @item while The syntax of the @code{while} command is: @example while @var{test-commands}; do @var{consequent-commands}; done @end example Execute @var{consequent-commands} as long as the final command in @var{test-commands} has an exit status of zero. @item for The syntax of the for command is: @example for @var{name} [in @var{words} ...]; do @var{commands}; done @end example Execute @var{commands} for each member in @var{words}, with @var{name} bound to the current member. If ``@code{in @var{words}}'' is not present, ``@code{in "$@@"}'' is assumed. @end ftable @node Conditional Constructs @section Conditional Constructs @ftable @code @item if The syntax of the @code{if} command is: @example if @var{test-commands}; then @var{consequent-commands}; [else @var{alternate-consequents};] fi @end example Execute @var{consequent-commands} only if the final command in @var{test-commands} has an exit status of zero. If ``@code{else @var{alternate-consequents}}'' is present, and the final command in @var{test-commands} has a non-zero exit status, then execute @var{alternate-consequents}. @item case The syntax of the @code{case} command is: @example @code{case @var{word} in [@var{pattern} [| @var{pattern}]...) @var{commands} ;;]... esac} @end example Selectively execute @var{commands} based upon @var{word} matching @var{pattern}. The `@code{|}' is used to separate multiple patterns. Here is an example using @code{case} in a script that could be used to describe an interesting feature of an animal: @example 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." @end example @end ftable @node T-Csh Features @chapter (T)C-Shell Style Features The C-Shell @dfn{@code{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 @code{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. @code{ignoreeof}). For details on history expansion, @pxref{Using History Interactively}. Bash has tilde (~) expansion, similar, but not identical, to that of @code{csh}. The following table shows what unquoted words beginning with a tilde expand to. @table @code @item ~ The current value of @code{$HOME}. @item ~/foo @code{$HOME}/foo @item ~fred/foo The subdirectory @code{foo} of the home directory of the user named @code{fred}. @item ~+/foo @code{$PWD}/foo @item ~- @code{$OLDPWD}/foo @end table Here is a list of the commands and variables whose meanings were taken from @code{csh}. @ftable @code @item pushd @example pushd [@var{dir} | @var{+n}] @end example Save the current directory on a list and then CD to DIR. With no arguments, exchanges the top two directories. @table @code @item +@var{n} Brings the @var{n}th directory to the top of the list by rotating. @item @var{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. @end table @item popd @example popd [+@var{n}] @end example 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 @code{dirs}; i.e. @code{popd} is equivalent to @code{popd 0}. @item dirs @example dirs @end example Display the list of currently remembered directories. Directories find their way onto the list with the @code{pushd} command; you can get back up through the list with the @code{popd} command. @item history @example history [@var{n}] [ [-w -r] [@var{filename}]] @end example Display the history list with line numbers. Lines listed with with a @code{*} have been modified. Argument of @var{n} says to list only the last @var{n} lines. Argument @code{-w} means write out the current history file. @code{-r} means to read it instead. If @var{filename} is given, then use that file, else if @code{$HISTFILE} has a value, use that, else use @file{~/.bash_history}. @item ignoreeof If this variable is set, it represents the number of consecutive @code{EOF}s Bash will read before exiting. By default, Bash will exit upon reading an @code{EOF} character. @end ftable @node Korn Shell Features @chapter Korn Shell Style Features @ftable @code @item fc @example @code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]} @code{fc -s [@var{pat=rep}] [@var{command}]} @end example Fix Command. In the first form, a range of commands from @var{first} to @var{last} is selected from the history list. @var{First} and/or @var{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 @var{last} is not specified it is set to @var{first}. If @var{first} is not specified it is set to the previous command for editing and -16 for listing. If the @code{-l} flag is given, the commands are listed on standard output. The @code{-n} flag suppresses the command numbers when listing. The @code{-r} flag reverses the order of the listing. Otherwise, the editor given by @var{ename} is invoked on a file containing those commands. If @var{ename} is not given, the value of the following variable expansion is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}}. This says to use the value of the @code{FCEDIT} variable if set, or the value of the @code{EDITOR} variable if that is set, or @code{vi} if neither is set. When editing is complete, the edited commands are echoed and executed. In the second form, @var{command} is re-executed after the substitution @var{old=new} is performed. A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so that typing @code{r cc} runs the last command beginning with @code{cc} and typing @code{r} re-executes the last command. @item typeset The @code{typeset} command is supplied for compatibility with the Korn shell; however, it has been made obsolete by the presence of the @code{declare} command, documented with the Bash specific features. @item type Bash's @code{type} command is a superset of the @code{type} found in Korn shells; @xref{Bash Builtins} for details. @end ftable @node Bash Specific Features @chapter Bash Specific Features @menu * Command Line Options:: Command line options that you can give to Bash. * The Set Builtin:: This builtin is so overloaded it deserves its own section. * Is This Shell Interactive?:: Determining the state of a running Bash. * Printing a Prompt:: Controlling the PS1 string. * Bash Startup Files:: When and how Bash executes scripts. * Bash Builtins:: Table of builtins specific to Bash. * Bash Variables:: List of variables that exist in Bash. @end menu @node Command Line Options @section Shell Command Line Options Along with the single character shell command-line options (@xref{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. @table @code @item -norc Don't load ~/.bashrc init file. (Default if shell name is `sh'). @item -rcfile @var{filename} Load @var{filename} init file (instead @file{~/.bashrc}). @item -noprofile Don't load @file{~/.bash_profile} (nor @file{/etc/profile}). @item -version Display the version number of this shell. @item -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''. @item -nobraceexpansion Do not perform curly brace expansion (foo@{a,b@} @var{->} fooa foob). @item -nolinediting Do not use the GNU Readline library to read interactive text lines. @end table @node The Set Builtin @section The Set Builtin This builtin is so overloaded that it deserves its own section. So here it is. @ftable @code @item set @example set [-aefhknotuvxldH] [@var{arg} ...] @end example @table @code @item -a Mark variables which are modified or created for export. @item -e Exit immediately if a command exits with a non-zero status. @item -f Disable file name generation (globbing). @item -k All keyword arguments are placed in the environment for a command, not just those that precede the command name. @item -m Job control is enabled. @item -n Read commands but do not execute them. @item -o @var{option-name} Set the variable corresponding to @var{option-name}: @table @code @item allexport same as -a. @item braceexpand the shell will perform brace expansion. @item emacs use an emacs-style line editing interface. @item errexit same as -e. @item histexpand same as -H. @item ignoreeof the shell will not exit upon reading EOF. @item monitor same as -m. @item noclobber disallow redirection to existing files. @item noexec same as -n. @item noglob same as -f. @item nohash same as -d. @item notify notify of job termination immediately. @item nounset same as -u. @item verbose same as -v. @item vi use a vi-style line editing interface. @item xtrace same as -x. @end table @item -t Exit after reading and executing one command. @item -u Treat unset variables as an error when substituting. @item -v Print shell input lines as they are read. @item -x Print commands and their arguments as they are executed. @item -l Save and restore the binding of the @var{name} in a @code{for} command. @item -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. @item -H Enable ! style history substitution. This flag is on by default. @end table Using @samp{+} rather than @samp{-} 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 @code{$-}. The remaining @var{arg}s are positional parameters and are assigned, in order, to @code{$1}, @code{$2}, .. @code{$9}. If no @var{arg}s are given, all shell variables are printed. @end ftable @node Is This Shell Interactive? @section 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 @code{$PS1}; it is unset in non-interactive shells, and set in interactive shells. Thus: @example if [ "$PS1" = "" ]; then echo "This shell is not interactive" else echo "This shell is interactive" fi @end example You can ask an interactive Bash to not run your @file{~/.bashrc} file with the @code{-norc} flag. You can change the name of the @file{~/.bashrc} file to any other file name with @code{-rcfile @var{filename}}. You can ask Bash to not run your @file{~/.bash_profile} file with the @code{-noprofile} flag. @node Printing a Prompt @section Controlling the Prompt The value of the variable @code{$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 @code{PS1} variable: @table @code @item \t the time. @item \d the date. @item \n CRLF. @item \s the name of the shell. @item \w the current working directory. @item \W the last element of PWD. @item \u your username. @item \h the hostname. @item \# the command number of this command. @item \! the history number of this command. @item \ the character code in octal. @item \\ a backslash. @end table @node Bash Startup Files @section Bash Startup Files When and how Bash executes @file{~/.bash_profile}, @file{~/.bashrc}, and @file{~/.bash_logout}. @example For Login shells: On logging in: If @file{/etc/profile} exists, then source it. If @file{~/.bash_profile} exists, then source it, else if @file{~/.bash_login} exists, then source it, else if @file{~/.profile} exists, then source it. On logging out: If @file{~/.bash_logout} exists, source it. For non-login interactive shells: On starting up: If @file{~/.bashrc} exists, then source it. For non-interactive shells: On starting up: If the environment variable @code{ENV} is non-null, source the file mentioned there. @end example So, typically, your @code{~/.bash_profile} contains the line @example @code{if [ -f @file{~/.bashrc} ]; then source @file{~/.bashrc}; fi} @end example @noindent after (or before) any login specific initializations. @node Bash Builtins @section Bash Builtin Commands @ftable @code @item builtin @example builtin [@var{shell-builtin} [@var{args}]] @end example 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. @item declare @example declare [-[frxi]] @var{name}[=@var{value}] @end example Declare variables and/or give them attributes. If no @var{name}s are given, then display the values of variables instead. @code{-f} means to use function names only. @code{-r} says to make @var{name}s readonly. @code{-x} says to make @var{name}s export. @code{-i} says that the variable is to be treated as an integer; arithmetic evaluation (see @code{let}) will be done when the variable is assigned to. Using @code{+} instead of @code{-} turns off the attribute instead. When used in a function, makes @var{name}s local, as with the @code{local} command. @item type @example type [-all] [-type | -path] [@var{name} ...] @end example For each @var{name}, indicate how it would be interpreted if used as a command name. If the @code{-type} flag is used, @code{type} returns a single word which is one of ``alias'', ``function'', ``builtin'', ``file'' or ``'', if @var{name} is an alias, shell function, shell builtin, disk file, or unfound, respectively. If the @code{-path} flag is used, @code{type} either returns the name of the disk file that would be exec'ed, or nothing if @code{-type} wouldn't return ``file''. If the @code{-all} flag is used, returns all of the places that contain an executable named @var{file}. This includes aliases and functions, if and only if the @code{-path} flag is not also used. @item enable @example enable [-n] [@var{name} ...] @end example Enable and disable builtin shell commands. This allows you to use a disk command which has the same name as a shell builtin. If @code{-n} is used, the @var{name}s become disabled. Otherwise @var{name}s are enabled. For example, to use the @code{test} found on your path instead of the shell builtin version, you type @w{@code{enable -n test}}. @item help @example help [@var{pattern}] @end example Display helpful information about builtin commands. If @var{pattern} is specified, gives detailed help on all commands matching @var{pattern}, otherwise a list of the builtins is printed. @item command @example command [@var{command} [@var{args} ...]] @end example Runs @var{command} with @var{arg} ignoring shell functions. If you have a shell function called @code{ls}, and you wish to call the command @code{ls}, you can say ``command ls''. @item hash @example hash [-r] [@var{name}] @end example For each @var{name}, the full pathname of the command is determined and remembered. The @code{-r} option causes the shell to forget all remembered locations. If no arguments are given, information about remembered commands is presented. @item local @example local @var{name}[=@var{value}] @end example Create a local variable called @var{name}, and give it @var{value}. @code{local} can only be used within a function; it makes the variable @var{name} have a visible scope restricted to that function and its children. @item readonly @example readonly [-f] [@var{name} ...] @end example The given @var{name}s are marked readonly and the values of these @var{name}s may not be changed by subsequent assignment. If the -f option is given, the functions corresponding to the @var{name}s are so marked. If no arguments are given, a list of all readonly names is printed. @item ulimit @example ulimit [-acdmstfpn [limit]] @end example 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 -a all current limits are reported. @item -c the maximum size of core files created. @item -d the maximum size of a process's data segment. @item -m the maximum resident set size. @item -s the maximum stack size. @item -t the maximum amount of cpu time in seconds. @item -f the maximum size of files created by the shell. @item -p the pipe buffer size. @item -n the maximum number of open file descriptors. @end table If @var{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 @code{-f} is assumed. Values are in 1k increments, except for @code{-t}, which is in seconds, and @code{-p}, which is in increments of 512 bytes. @end ftable @node Bash Variables @section Bash Variables @table @code @vindex history_control @item 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. @vindex HISTFILE @item HISTFILE The name of the file that the command history is saved in. @vindex HISTSIZE @item HISTSIZE If set, this is the maximum number of commands to remember in the history. @vindex histchars @item histchars Up to three characters which control history expansion, quick substitution, and tokenization. The first character is the @dfn{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 `#'. @vindex hostname_completion_file @item hostname_completion_file 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 interactively; the next time you want to complete a hostname Bash will add the contents of the new file to the already existing database. @vindex MAILCHECK @item MAILCHECK How often (in seconds) that the shell should check for mail in the file(s) specified in @code{MAILPATH}. @vindex MAILPATH @item 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 @samp{?}. @code{$_} stands for the name of the current mailfile. For example: @example MAILPATH='/usr/spool/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"' @end example @vindex ignoreeof @item ignoreeof @vindex IGNOREEOF @itemx IGNOREEOF Controls the action of the shell on receipt of an @code{EOF} character as the sole input. If set, then the value of it is the number of @code{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 @code{EOF} signifies the end of input to the shell. This is only in effect for interactive shells. @vindex auto_resume @item 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. @vindex no_exit_on_failed_exec @item 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 @code{exec} command. @vindex PROMPT_COMMAND @item PROMPT_COMMAND If present, this contains a string which is a command to execute before the printing of each toplevel prompt. @vindex nolinks @item 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 @code{cd} type commands. For example, if @file{/usr/sys} is a link to @file{/usr/local/sys} then: @example cd /usr/sys; echo $PWD -> /usr/sys cd ..; pwd -> /usr @end example @noindent If @code{nolinks} exists, then: @example cd /usr/sys; echo $PWD -> /usr/local/sys cd ..; pwd -> /usr/local @end example @end table @set readline-appendix @set history-appendix @cindex History, how to use @include hsuser.texinfo @cindex Readline, how to use @include rluser.texinfo @clear readline-appendix @clear history-appendix @node Variable Index @appendix Variable Index @printindex vr @node Concept Index @appendix Concept Index @printindex cp @contents @bye