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