bash documentation

The Grand Master asg at sage.cc.purdue.edu
Thu Feb 21 11:46:35 AEST 1991


In article <1991Feb20.203710.21944 at progress.com> andy at progress.COM (Andrew Klein) writes:
>Does anyone have or know where I can find documentation for the
>bash, the Born Again Shell?  Thank you for your help.
>
>Andy
For Andy and all others who would like it, here is some documentation on bash:


-*- text -*-

This isn't real documentation, but we have to tell people how this shell is
different from others.

NEW STUFF SINCE LAST RELEASE:

history_control variable.

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 read
by the parser on the history list.

END OF NEW STUFF


When and how bash executes login, rc, and logout files.

Login shells:
  On login:
	if /etc/profile exists, source it.

	if ~/.bash_profile exists, source it,
	  else if ~/.bash_login exists, source it,
	    else if ~/.profile exists, source it.
  On logout:
	if ~/.bash_logout exists, source it.

Non-login interactive shells:
  On startup:
	if ~/.bashrc exists, source it.

Non-interactive shells:
  On startup:
	if the environment variable "ENV" is non-null, source the file
	mentioned there.

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

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

after (or before) any login specific initializations.

You can tell if a shell is interactive or not from within your ~/.bashrc
file by examining $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 with -rcfile FILENAME.  You can ask bash to not run your
.bash_profile file with -noprofile.

alias: alias [ name [=value] ...]
	Alias with no arguments prints the list of aliases in the form
	name=value on standard output.  An alias is defined for each NAME
	whose VALUE is given.  A trailing space in VALUE causes the next
	word to be checked for alias substitution.  Alias returns true
	unless a NAME is given for which no alias has been defined.

unalias: unalias [name ...]
	Remove NAMEs from the list of defined aliases.

exec: exec [ [-] file [redirections]]
	Exec FILE, replacing this shell with the specified program.
	If FILE is not specified, the redirections take effect in this
	shell.  If the first argument is `-', then place a dash in the
	zeroith arg passed to FILE.  This is what login does.  If the file
	cannot be exec'ed for some reason, the shell exits, unless the
	shell variable "no_exit_on_failed_exec" exists.

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.

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 /bin/test instead of the
	shell builtin version, you would type `enable -n test'.

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'.

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.

********************
NEW Ulimit Implementation

ulimit: ulimit [-cdmstf [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:

                -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 milliseconds
                -f      the maximum size of files created by

        If limit is given, it is multiplied by a constant factor (a block
        size, currently 512) and the result becomes the new value of the
        specified resource.  If limit is not given, the current value of
        the specified resource is printed.  If no option is given, then the
        maximum allowable size of a file created by the shell or any of its
        children is printed (equivalent to the -f option).

********************
Tilde expansion:

This shell does tilde  expansion:

~ = $HOME
~/foo = $HOME/foo
~fred/foo = (fred's home directory)/foo
~+/foo = $PWD/foo
~-/foo = $OLDPWD/foo



We have functions.  You can say:

     foo () { ls $1 ; }
or
     function foo () { ls $1 ; }

Here is the comment next to the decode_prompt_string function.

/* Return a string which will be printed as a prompt.  The string
   may contain special characters which are decoded as follows:
   
	\t	the time
	\d	the date
	\n	CRLF
	\s	the name of the shell
	\w	the current working directory
	\u	your username
	\h	the hostname
	\#	the command number of this command
	\!	the history number of this command
	\<octal> character code in octal
	\\	a backslash
*/

Here is the comment next to the check_mail function, which is called
periodically.  See the documentation for ksh MAILCHECK MAILPATH, etc.
We also have MAIL_WARNING, see below.

/* check_mail () is useful for more than just checking mail.  Since it has
   the paranoids dream ability of telling you when someone has read your
   mail, it can just as easily be used to tell you when someones .profile
   file has been read, thus letting one know when someone else has logged
   in.  Pretty good, huh? */

/* Check for mail in some files.  If the modification date of any
   of the files in MAILPATH has changed since we last did a
   remember_mail_dates () then mention that the user has mail.
   Special hack:  If the shell variable MAIL_WARNING is on and the
   mail file has been accessed since the last time we remembered, then
   the message "The mail in <mailfile> has been read" is printed. */

READLINE:

This is the library that handles reading input when using an interactive
shell.  The line editing commands are similar to emacs' line editing commands.
You may change the default key-bindings with a ~/.inputrc file.  Various
programs that use this library may add their own commands and bindings.

If you wanted to make M-C-u do universal-argument, then in your ~/.inputrc file
you would put:

M-Control-u: universal-argument

  or

C-Meta-u:	universal-argument

You can use the following names for characters: RUBOUT, DEL, ESC,
NEWLINE, SPACE, RETURN, LFD, TAB

You can start with a vi-like editing mode by placing

	set editing-mode vi

in your ~/.inputrc file.

You can have readline use a single line for display, scrolling the input
between the two borders by placing

	set horizontal-scroll-mode On

in your ~/.inputrc file.

The following is a list of the names of the commands and the default
key-strokes to get them.

COMMANDS FOR MOVING:

beginning-of-line (C-a)
	Move to the start of the current line.

end-of-line	(C-e)
	Move to the end of the line.

forward-char	(C-f)
	Move forward a character.

backward-char	(C-b)
	Move back a character.

forward-word	(M-f)
	Move forward to the end of the next word.

backward-word	(M-b)
	Move back to the start of this, or the previous, word.

clear-screen	(C-l)
	Clear the screen leaving the current line at the top of the screen.


COMMANDS FOR MANIPULATING THE HISTORY:

accept-line	(Newline, Return)
	Accept the line regardless of where the cursor is.  If this line is
	non-empty, add it too the history list.  If this line was a history
	line, then restore the history line to its original state.

previous-history (C-p)
	Move `up' through the history list.

next-history	(C-n)
	Move `down' through the history list.

beginning-of-history (M-<)
	Move to the first line in the history.

end-of-history	(M->)
	Move to the end of the input history, i.e., the line you are entering!

reverse-search-history (C-r)
	Search backward starting at the current line and moving `up' through
	the history as necessary.  This is an incremental search.  Maybe I
	should have reg-exp searches as well?

forward-search-history (C-s)
	Search forward starting at the current line and moving `down' through
	the the history as neccessary.

expand-line (M-C-e)
	Expand the line the way that the shell will when it reads it.  This
	does alias and history expansion.  See HISTORY EXPANSION below.


COMMANDS FOR CHANGING TEXT:

delete-char	(C-d)
	Delete the character under the cursor.  If the cursor is at the
	beginning of the line, and there are no characters in the line, and
	the last character typed was not C-d, then return EOF.

backward-delete-char (Rubout)
	Delete the character behind the cursor.  A numeric arg says to kill
	the characters instead of deleting them.

quoted-insert	(C-q, C-v)
	Add the next character that you type to the line verbatim.  This is
	how to insert things like C-q for example.

tab-insert	(M-TAB)
	Insert a tab character.

self-insert	(a, b, A, 1, !, ...)
	Insert yourself.

transpose-chars (C-t)
	Drag the character before point forward over the character at point.
	Point moves forward as well.  If point is at the end of the line, then
	transpose the two characters before point.  Negative args don't work.

transpose-words	(M-t)
	Drag the word behind the cursor past the word in front of the cursor
	moving the cursor over that word as well.

upcase-word	(M-u)
	Uppercase the current (or following) word.  With a negative argument,
	do the previous word, but do not move point.

downcase-word	(M-l)
	Lowercase the current (or following) word.  With a negative argument,
	do the previous word, but do not move point.

capitalize-word	(M-c)
	Uppercase the current (or following) word.  With a negative argument,
	do the previous word, but do not move point.

KILLING AND YANKING:

kill-line	(C-k)
	Kill the text from the current cursor position to the end of the line.
	This saves the killed text on the kill-ring.  (see below)
	
backward-kill-line ()
	Kill backward to the beginning of the line.  This is normally unbound.

kill-word	(M-d)
	Kill from the cursor to the end of the current word, or if between
	words, to the end of the next word.

backward-kill-word (M-Rubout)
	Kill the word behind the cursor.

unix-line-discard (C-u)
	Do what C-u used to do in Unix line input.  We save the killed text on
	the kill-ring, though.

unix-word-rubout (C-w)
	Do what C-w used to do in Unix line input.  The killed text is saved
	on the kill-ring.  This is different than backward-kill-word because
	the word boundaries differ.

yank		(C-y)
	Yank the top of the kill ring into the buffer at point.

yank-pop	(M-y)
	Rotate the kill-ring, and yank the new top.  You can only do this if
	the prior command is yank or yank-pop.
	
ARGUMENTS:

digit-argument	(M-0, M-1, ... M--)
	Add this digit to the argument already accumulating, or start a new
	argument.  M-- starts a negative argument.

universal-argument ()
	Do what C-u does in emacs.  By default, this is not bound.
	
COMPLETING:

complete	(TAB)
	Attempt to do completion on the text before point.  In the shell,
	filenames and commands are completed on.

possible-completions (M-?)
	List the possible completions of the text before point.

MISCELLANEOUS:
abort		(C-g)
	Ding!  Stops things.

do-uppercase-version (M-a, M-b, ...)
	Run the command that is bound to your uppercase brother.
	
prefix-meta	(ESC)
	Make the next character that you type be Meta-fied.  This is for
	people without a meta key.  ESC-f is equivalent to Meta-f.

undo		(C-_)
	Incremental undo, separately remembered for each line.

revert-line	(M-r)
	Undo all changes made to this line.  This is like typing the `undo'
	command enough times to get back to the beginning.

The shell has several variables which are there just for controlling the
behavior of the interactive shell.  Here they are:

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: The two characters which control history expansion 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 the remainder of the line is a comment, when found
	  as the first character of a word.

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.  e.g.

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 top-level 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' is present, then:

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

**********************************************************************
Shell Command Line Options

Along with the single character shell command-line options (documented in
`set') 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 (or /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 preform curly brace expansion (foo{a,b} -> fooa foob).

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

**********************************************************************

History Expansion:

The following text is taken directly from the history.texinfo file, node
Interactive Use.

Interactive Use
***************

History Expansion
=================

The shell supports a history expansion feature that is similar to
the history expansion in Csh.  The following text describes what
syntax features are available.

History expansion takes place in two parts.  The first is
determining which line from the previous history to use during
substitution.  The second is to select portions of that line for
inclusion into the current one.  The line selected from the
previous history is called the "event", and the portions of that
line that are acted upon are called "words".  The line is broken
into words in the same fashion that the Bash shell does, so that
several English (or Unix) words surrounded by quotes are considered
as one word.

Event Designators
-----------------

An event designator is a reference to a command line entry in the
history list.

`!'
     Start a history subsititution, except when followed by a SPC,
     TAB, RET, = or (.

`!!'
     Refer to the previous command.  This is a synonym for `!-1'.

`!n'
     Refer to command line N.

`!-n'
     Refer to the current command line minus N.

`!string'
     Refer to the most recent command starting with STRING.

`!?string[?]'
     Refer to the most recent command containing STRING.

Word Designators
----------------

Words  A : separates the event specification from the word
designator.  It can be omitted if the word designator begins with a
^, $, * or %.  Words are numbered from the beginning of the line,
with the first word being denoted by a 0 (zero).

`#'
     The entire command line typed so far.  This means the current
     command, not the previous command, so it really isn't a word
     designator, and doesn't belong in this section.

`0 (zero)'
     The zero'th word.  For most applications, this is the command
     word.

`n'
     The N'th word.

`^'
     The first argument.  that is, word 1.

`$'
     The last argument.

`%'
     The word matched by the most recent `?string?' search.

`x-y'
     A range of words; `-Y' Abbreviates `0-Y'.

`*'
     All of the words, excepting the zero'th.  This is a synonym
     for `1-$'.  It is not an error to use * if there is just one
     word in the event.  The empty string is returned in that case.

Modifiers
---------

After the optional word designator, you can add a sequence of one
or more of the following modifiers, each preceded by a :.

`h'
     Remove a trailing pathname component, leaving only the head.

`r'
     Remove a trailing suffix of the form ".xxx", leaving the
     basename.

`e'
     Remove all but the suffix.

`t'
     Remove all leading  pathname  components, leaving the tail.

`p'
     Print the new command but do not execute it.  This takes
     effect immediately, so it should be the last specifier on the
     line.

------------------------------------------------------------
More redirections than other sh's.  Isn't that great?

	command &>file

redirects both stdout and stderr into FILE.

------------------------------------------------------------
Curly Brace Expansion

	foo{a,b}-> fooa foob

----------------------------------------

Command Substitution with "$( commands ... )

The shell now supports $(command) command substitution.  This is akin to
the older (and still supported) style of command substitution:
`command`.

	Here is one way to get your hostname isolated:

	using $(): echo $(basename $(hostname) $(domainname))

	using ``:  echo `basename \`hostname\` \`domainname\``

type: type [-type | -path] [name ...]
	For each NAME, indicate how it would be interpreted if used as a
	command name.

	If the -type flag is used, 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, either returns the name of the disk file
	that would be exec'ed, or nothing if -type wouldn't return `file'.
 

Hope that helps.



More information about the Comp.unix.shell mailing list