diff options
author | Jari Aalto <jari.aalto@cante.net> | 1996-12-23 17:02:34 +0000 |
---|---|---|
committer | Jari Aalto <jari.aalto@cante.net> | 2009-09-12 16:46:49 +0000 |
commit | ccc6cda312fea9f0468ee65b8f368e9653e1380b (patch) | |
tree | b059878adcfd876c4acb8030deda1eeb918c7e75 /doc | |
parent | 726f63884db0132f01745f1fb4465e6621088ccf (diff) | |
download | bash-ccc6cda312fea9f0468ee65b8f368e9653e1380b.tar.gz |
Imported from ../bash-2.0.tar.gz.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/FAQ | 1098 | ||||
-rw-r--r-- | doc/INTRO | 187 | ||||
-rw-r--r-- | doc/Makefile.in | 169 | ||||
-rw-r--r-- | doc/README | 35 | ||||
-rw-r--r-- | doc/article.ms | 1114 | ||||
-rw-r--r-- | doc/bash.1 | 6785 | ||||
-rw-r--r-- | doc/bashbug.1 | 41 | ||||
-rw-r--r-- | doc/bashref.info | 6513 | ||||
-rw-r--r-- | doc/bashref.texi | 5331 | ||||
-rw-r--r-- | doc/builtins.1 | 15 | ||||
-rw-r--r-- | doc/readline.3 | 1103 | ||||
-rw-r--r-- | doc/texinfo.tex | 4421 |
12 files changed, 26812 insertions, 0 deletions
diff --git a/doc/FAQ b/doc/FAQ new file mode 100644 index 00000000..2723f8f3 --- /dev/null +++ b/doc/FAQ @@ -0,0 +1,1098 @@ +This is the Bash FAQ, version 2.1, for Bash version 2.0. + +This document contains a set of frequently-asked questions concerning +Bash, the GNU Bourne-Again Shell. Bash is a freely-available command +interpreter with advanced features for both interactive use and shell +programming. + +Another good source of basic information about shells is the collection +of FAQ articles periodically posted to comp.unix.shell. + +Questions and comments concerning this document should be sent to +chet@po.cwru.edu. + +This document is available for anonymous FTP with the URL + +ftp://slc2.ins.cwru.edu/pub/bash/FAQ + +---------- +Contents: + +Section A: The Basics + +1) What is it? +2) What's the latest version? +3) Where can I get it? +4) On what machines will bash run? +5) How can I build bash with gcc? +6) How can I make bash my login shell? +7) I just changed my login shell to bash, and now I can't FTP into my + machine. Why not? +8) What's the `POSIX 1003.2 standard'? +9) What is the bash `posix mode'? + +Section B: The latest version + +10) What's new in version 2.0? +11) Are there any user-visible incompatibilities between bash-2.0 and + bash-1.14.7? + +Section C: Differences from other Unix shells + +12) How does bash differ from sh, the Bourne shell? +13) How does bash differ from the Korn shell, version ksh88? +14) Which new features in ksh-93 are not in bash, and which are? + +Section D: Why does bash do some things differently than other Unix shells? + +15) Why does bash run a different version of `command' than + `which command' says it will? +16) Why doesn't bash treat brace expansions exactly like csh? +17) Why doesn't bash have csh variable modifiers? +18) How can I make my csh aliases work when I convert to bash? +19) How can I pipe standard output and standard error from one command to + another, like csh does with `|&'? +20) Now that I've converted from ksh to bash, are there equivalents to + ksh features like autoloaded functions and the `whence' command? + +Section E: How can I get bash to do certain things, and why does bash do + things the way it does? + +21) Why is the bash builtin `test' slightly different from /bin/test? +22) Why does bash sometimes say `Broken pipe'? +23) How can I get bash to read and display eight-bit characters? +24) How do I write a function `x' to replace builtin command `x', but + still invoke the command from within the function? +25) When I have terminal escape sequences in my prompt, why does bash + wrap lines at the wrong column? +26) How can I find the value of a shell variable whose name is the value + of another shell variable? +27) If I pipe the output of a command into `read variable', why doesn't + the output show up in $variable when the read command finishes? +28) I have a bunch of shell scripts that use backslash-escaped characters + in arguments to `echo'. Bash doesn't interpret these characters. Why + not, and how can I make it understand them? +29) Why doesn't a while or for loop get suspended when I type ^Z? +30) How can I make the bash `time' reserved word print timing output that + looks like the output from my system's /usr/bin/time? + +Section F: Things to watch out for on certain Unix versions + +31) Why can't I use command line editing in my `cmdtool'? +32) I built bash on Solaris 2. Why do globbing expansions and filename + completion chop off the first few characters of each filename? +33) Why does bash dump core after I interrupt username completion or + `~user' tilde expansion on a machine running NIS? +34) I'm running SVR4.2. Why is the line erased every time I type `@'? +35) Why does bash report syntax errors when my C News scripts use a + redirection before a subshell command? + +Section G: Where do I go from here? + +36) How do I report bugs in bash, and where should I look for fixes and + advice? +37) What kind of bash documentation is there? +38) What's coming in future versions? +39) What's on the bash `wish list'? +40) When will the next release appear? + +---------- +Section A: The Basics + +1) What is it? + +Bash is a Unix command interpreter (shell). It is an implementation of +the Posix 1003.2 shell standard, and resembles the Korn and System V +shells. + +Bash contains a number of enhancements over those shells, both +for interactive use and shell programming. Features geared +toward interactive use include command line editing, command +history, job control, aliases, and prompt expansion. Programming +features include additional variable expansions, shell +arithmetic, and a number of variables and options to control +shell behavior. + +Bash was originally written by Brian Fox of the Free Software +Foundation. The current developer and maintainer is Chet Ramey +of Case Western Reserve University. + +2) What's the latest version? + +The latest version is 2.0, first made available on December 23, 1996. + +3) Where can I get it? + +Bash is the GNU project's shell, and so is available from the +master GNU archive site, prep.ai.mit.edu, and its mirrors. The +latest version is also available for FTP from slc2.ins.cwru.edu, +the maintainer's machine. The following URLs tell how to get +version 2.0: + +ftp://prep.ai.mit.edu/pub/gnu/bash-2.0.tar.gz +ftp://slc2.ins.cwru.edu/pub/dist/bash-2.0.tar.gz + +Formatted versions of the documentation are available with the URLs: + +ftp://prep.ai.mit.edu/pub/gnu/bash-doc-2.0.tar.gz +ftp://slc2.ins.cwru.edu/pub/dist/bash-doc-2.0.tar.gz + +4) On what machines will bash run? + +Bash has been ported to nearly every version of UNIX. All you +should have to do to build it on a machine for which a port +exists is to type `configure' and then `make'. The build process +will attempt to discover the version of UNIX you have and tailor +itself accordingly, using a script created by GNU autoconf. + +More information appears in the file `INSTALL' in the distribution. + +5) How can I build bash with gcc? + +Bash configures to use gcc by default if it is available. Read the +file INSTALL in the distribution for more information. + +6) How can I make bash my login shell? + +Some machines let you use `chsh' to change your login shell. Other +systems use `passwd -s'. If one of these works for you, that's all +you need. Note that many systems require the full pathname to a shell +to appear in /etc/shells before you can make it your login shell. For +this, you may need the assistance of your friendly local system +administrator. + +If you cannot do this, you can still use bash as your login shell, but +you need to perform some tricks. The basic idea is to add a command +to your login shell's startup file to replace your login shell with +bash. + +For example, if your login shell is csh or tcsh, and you have installed +bash in /usr/gnu/bin/bash, add the following line to ~/.login: + + if ( -f /usr/gnu/bin/bash ) exec /usr/gnu/bin/bash --login + +(the `--login' tells bash that it is a login shell). + +It's not a good idea to put this command into ~/.cshrc, because every +csh you run without the `-f' option, even ones started to run csh scripts, +reads that file. If you must put the command in ~/.cshrc, use something +like + + if ( $?prompt ) exec /usr/gnu/bin/bash --login + +to ensure that bash is exec'd only when the csh is interactive. + +If your login shell is sh or ksh, you have to do two things. First, add +a line similar to the above to ~/.profile: + + [ -f /usr/gnu/bin/bash ] && exec /usr/gnu/bin/bash --login + +Next, create an empty file in your home directory named `.bash_profile'. +The existence of this file will prevent the exec'd bash from trying to +read ~/.profile, and re-execing itself over and over again. ~/.bash_profile +is the file bash tries to read initialization commands from when it is +invoked as a login shell. + +7) I just changed my login shell to bash, and now I can't FTP into my + machine. Why not? + +You must add the full pathname to bash to the file /etc/shells. As +noted in the answer to the previous question, many systems require +this before you can make bash your login shell. + +Most versions of ftpd use this file to prohibit `special' users +such as `uucp' and `news' from using FTP. + +8) What's the `POSIX 1003.2 standard'? + +POSIX is a name originally coined by Richard Stallman for a +family of open system standards based on UNIX. There are a +number of aspects of UNIX under consideration for +standardization, from the basic system services at the system +call and C library level to applications and tools to system +administration and management. Each area of standardization is +assigned to a working group in the 1003 series. + +The POSIX Shell and Utilities standard has been developed by IEEE +Working Group 1003.2 (POSIX.2). It concentrates on the command +interpreter interface and utility programs commonly executed from +the command line or by other programs. An initial version of the +standard has been approved and published by the IEEE, and work is +currently underway to update it. + +Bash is concerned with the aspects of the shell's behavior +defined by POSIX.2. The shell command language has of course +been standardized, including the basic flow control and program +execution constructs, I/O redirection and pipelining, argument +handling, variable expansion, and quoting. + +The `special' builtins, which must be implemented as part of the +shell to provide the desired functionality, are specified as +being part of the shell; examples of these are `eval' and +`export'. Other utilities appear in the sections of POSIX.2 not +devoted to the shell which are commonly (and in some cases must +be) implemented as builtin commands, such as `read' and `test'. +POSIX.2 also specifies aspects of the shell's interactive +behavior as part of the UPE, including job control and command +line editing. Only vi-style line editing commands have been +standardized; emacs editing commands were left out due to +objections. + +9) What is the bash `posix mode'? + +Although bash is an implementation of the POSIX.2 shell +specification, there are areas where the bash default behavior +differs from that spec. The bash `posix mode' changes the bash +behavior in these areas so that it obeys the spec more closely. + +Posix mode is entered by starting bash with the --posix option or +executing `set -o posix' after bash is running. + +The specific aspects of bash which change when posix mode is +active are listed in the file CWRU/POSIX.NOTES in the bash +distribution. They are also listed in a section in the Bash +Reference Manual. + +Section B: The latest version + +10) What's new in version 2.0? + +This version contains extensive changes and new features. Here's a +short list: + +new `time' reserved word to time pipelines, shell builtins, and + shell functions +one-dimensional arrays with a new compound assignment statement, + appropriate expansion constructs and modifications to some + of the builtins (read, declare, etc.) to use them +new quoting syntaxes for ANSI-C string expansion and locale-specific + string translation +new expansions to do substring extraction, pattern replacement, and + indirect variable expansion +new builtins: `disown' and `shopt' +new variables: HISTIGNORE, SHELLOPTS, PIPESTATUS, DIRSTACK, GLOBIGNORE, + MACHTYPE, BASH_VERSINFO +special handling of many unused or redundant variables removed + (e.g., $notify, $glob_dot_filenames, $no_exit_on_failed_exec) +dynamic loading of new builtin commands; many loadable examples provided +new prompt expansions: \a, \e, \n, \H, \T, \@, \v, \V +history and aliases available in shell scripts +new readline variables: enable-keypad, mark-directories, input-meta, + visible-stats, disable-completion, comment-begin +new readline commands to manipulate the mark and operate on the region +new readline emacs mode commands and bindings for ksh-88 compatibility +updated and extended builtins +new DEBUG trap +expanded (and now documented) restricted shell mode + +implementation stuff: +autoconf-based configuration +nearly all of the bugs reported since version 1.14 have been fixed +most builtins converted to use builtin `getopt' for consistency +most builtins use -p option to display output in a reusable form + (for consistency) +grammar tighter and smaller (66 reduce-reduce conflicts gone) +lots of code now smaller and faster +test suite greatly expanded + +11) Are there any user-visible incompatibilities between bash-2.0 and + bash-1.14.7? + +There are a few incompatibilities between version 1.14.7 and version 2.0. +They are detailed in the file COMPAT in the bash-2.0 distribution. + +Section C: Differences from other Unix shells + +12) How does bash differ from sh, the Bourne shell? + +This is a non-comprehensive list of features that differentiate bash +from the SVR4.2 shell. The bash manual page explains these more +completely. + +Things bash has that sh does not: + long invocation options + `!' reserved word to invert pipeline return value + `time' reserved word to time pipelines and shell builtins + the `function' reserved word + the select compound command and reserved word + new $'...' and $"..." quoting + the $(...) form of command substitution + the ${#param} parameter value length operator + the ${!param} indirect parameter expansion operator + the ${param:length[:offset]} parameter substring operator + the ${param/pat[/string]} parameter pattern substitution operator + expansions to perform substring removal (${p%[%]w}, ${p#[#]w}) + expansion of positional parameters beyond $9 with ${num} + variables: BASH, BASH_VERSION, BASH_VERSINFO, UID, EUID, REPLY, + TIMEFORMAT, PPID, PWD, OLDPWD, SHLVL, RANDOM, SECONDS, + LINENO, HISTCMD, HOSTTYPE, OSTYPE, MACHTYPE, HOSTNAME, + ENV, PS3, PS4, DIRSTACK, PIPESTATUS, HISTSIZE, HISTFILE, + HISTFILESIZE, HISTCONTROL, HISTIGNORE, GLOBIGNORE, + PROMPT_COMMAND, FCEDIT, FIGNORE, IGNOREEOF, INPUTRC, + SHELLOPTS, OPTERR, HOSTFILE, TMOUT, histchars, auto_resume + DEBUG trap + variable arrays with new compound assignment syntax + redirections: <>, &>, >| + prompt string special char translation and variable expansion + auto-export of modified values of variables in initial environment + command search finds functions before builtins + bash return builtin will exit a file sourced with `.' + builtins: cd -/-L/-P, exec -l/-c/-a, echo -e/-E, hash -p. + export -n/-f/-p/name=value, pwd -L/-P, read -e/-p/-a, + readonly -a/-f/name=value, trap -l, set +o, + set -b/-m/-o option/-h/-p/-B/-C/-H/-P, + unset -f/-v, ulimit -m/-p/-u, + type -a/-p/-t, suspend -f, kill -n, + test -o optname/s1 == s2/s1 < s2/s1 > s2/-nt/-ot/-ef/-O/-G/-S + bash reads ~/.bashrc for interactive shells, $ENV for non-interactive + bash restricted shell mode is more extensive + bash allows functions and variables with the same name + brace expansion + tilde expansion + arithmetic expansion with $((...)) and `let' builtin + process substitution + aliases and alias/unalias builtins + local variables in functions and `local' builtin + readline and command-line editing + command history and history/fc builtins + csh-like history expansion + other new bash builtins: bind, command, builtin, declare/typeset, + dirs, enable, fc, help, history, logout, + popd, pushd, disown, shopt + exported functions + filename generation when using output redirection (command >a*) + variable assignments preceding commands affect only that command, + even for builtins and functions + posix mode + +Things sh has that bash does not: + uses variable SHACCT to do shell accounting + includes `stop' builtin (bash can use alias stop='kill -s STOP') + `newgrp' builtin + turns on job control if called as `jsh' + ulimit attempts to set both soft & hard limits if -S/-H not given + $TIMEOUT (like bash $TMOUT) + `^' is a synonym for `|' + new SVR4.2 sh builtins: mldmode, priv + +Implementation differences: + redirection to/from compound commands causes sh to create a subshell + bash does not allow unbalanced quotes; sh silently inserts them at EOF + bash does not mess with signal 11 + sh sets (euid, egid) to (uid, gid) if -p not supplied and uid < 100 + bash splits only the results of expansions on IFS, using POSIX.2 + field splitting rules; sh splits all words on IFS + sh does not allow MAILCHECK to be unset (?) + sh does not allow traps on SIGALRM or SIGCHLD + bash allows multiple option arguments when invoked (e.g. -x -v); + sh allows only a single option argument (`sh -x -v' attempts + to open a file named `-v', and, on SunOS 4.1.4, dumps core) + sh exits a script if any builtin fails; bash exits only if one of + the POSIX.2 `special' builtins fails + +13) How does bash differ from the Korn shell, version ksh88? + +Things bash has or uses that ksh88 does not: + long invocation options + `!' reserved word + posix mode and posix conformance + command hashing + tilde expansion for assignment statements that look like $PATH + process substitution with named pipes if /dev/fd is not available + the ${!param} indirect parameter expansion operator + the ${param:length[:offset]} parameter substring operator + the ${param/pat[/string]} parameter pattern substitution operator + variables: BASH, BASH_VERSION, BASH_VERSINFO, UID, EUID, SHLVL, + TIMEFORMAT, HISTCMD, HOSTTYPE, OSTYPE, MACHTYPE, + HISTFILESIZE, HISTIGNORE, HISTCONTROL, PROMPT_COMMAND, + IGNOREEOF, FIGNORE, INPUTRC, HOSTFILE, DIRSTACK, + PIPESTATUS, HOSTNAME, OPTERR, SHELLOPTS, GLOBIGNORE, + histchars, auto_resume + prompt expansion with backslash escapes and command substitution + redirection: &> (stdout and stderr) + more extensive and extensible editing and completion + builtins: bind, builtin, command, declare, dirs, echo -e/-E, enable, + exec -l/-c/-a, fc -s, export -n/-f/-p, hash, help, history, + jobs -x/-r/-s, kill -s/-n/-l, local, logout, popd, pushd, + read -e/-p/-a, readonly -a/-n/-f/-p, set -o braceexpand/ + -o histexpand/-o interactive-comments/-o notify/-o physical/ + -o posix/-o hashall/-o onecmd/-h/-B/-C/-b/-H/-P, set +o, + suspend, trap -l, type, typeset -a/-F/-p, ulimit -u, + umask -S, alias -p, shopt, disown + `!' csh-style history expansion + +Things ksh88 has or uses that bash does not: + new version of test: [[...]] + tracked aliases + $(<file) + variables: ERRNO, FPATH, COLUMNS, LINES, EDITOR, VISUAL + extended pattern matching with egrep-style pattern lists + co-processes (|&, >&p, <&p) + weirdly-scoped functions + typeset +f to list all function names without definitions + text of command history kept in a file, not memory + builtins: alias -x, cd old new, fc -e -, newgrp, print, + read -p/-s/-u/var?prompt, set -A/-o gmacs/ + -o bgnice/-o markdirs/-o nolog/-o trackall/-o viraw/-s, + typeset -H/-L/-R/-A/-ft/-fu/-fx/-l/-u/-t, whence + +Implementation differences: + ksh runs last command of a pipeline in parent shell context + ksh ulimit sets hard and soft limits by default + bash has brace expansion by default (ksh88 compile-time option) + bash has fixed startup file for all interactive shells; ksh reads $ENV + bash has exported functions + bash command search finds functions before builtins + +14) Which new features in ksh-93 are not in bash, and which are? + +New things in ksh-93 not in bash-2.0: + associative arrays + floating point arithmetic + ++, --, comma arithmetic operators + math library functions + ${!name[sub]} name of subscript for associative array + ${!prefix*} and {!prefix@} variable name prefix expansions + `.' is allowed in variable names to create a hierarchical namespace + more extensive compound assignment syntax + discipline functions + `sleep' and `getconf' builtins (bash has loadable versions) + typeset -n and `nameref' variables + KEYBD trap + variables: .sh.edchar, .sh.edmode, .sh.edcol, .sh.edtext, HISTEDIT, + .sh.version, .sh.name, .sh.subscript, .sh.value + backreferences in pattern matching + print -f and printf (bash has loadable versions) + `fc' has been renamed to `hist' + read -t/-d + `.' can execute shell functions + ENV processed only for interactive shells + +New things in ksh-93 present in bash-2.0: + ?: arithmetic operator + expansions: ${!param}, ${param:len[:offset]}, ${param/pat[/str]} + compound array assignment + the `!' reserved word + loadable builtins -- but ksh uses `builtin' while bash uses `enable' + `command', `builtin', `disown' builtins + new $'...' and $"..." quoting + FIGNORE (but bash uses GLOBIGNORE), HISTCMD + set -o notify/-C + changes to kill builtin + read -A (bash uses read -a) + trap -p + exec -c/-a + `.' restores the positional parameters when it completes + POSIX.2 `test' + umask -S + unalias -a + command and arithmetic substitution performed on PS1, PS4, and ENV + command name completion + +Section D: Why does bash do some things differently than other Unix shells? + +15) Why does bash run a different version of `command' than + `which command' says it will? + +`which' is actually a csh script that assumes you're running csh. +It reads the csh startup files from your home directory and uses +those to determine which `command' will be invoked. Since bash +doesn't use any of those startup files, there's a good chance +that your bash environment differs from your csh environment. + +16) Why doesn't bash treat brace expansions exactly like csh? + +The only difference between bash and csh brace expansion is that +bash requires a brace expression to contain at least one unquoted +comma if it is to be expanded. Any brace-surrounded word not +containing an unquoted comma is left unchanged by the brace +expansion code. This affords the greatest degree of sh +compatibility. + +Bash, ksh, zsh, and pd-ksh all implement brace expansion this way. + +17) Why doesn't bash have csh variable modifiers? + +Posix has specified a more powerful, albeit somewhat more cryptic, +mechanism cribbed from ksh, and bash implements it. + +${parameter%word} + Remove smallest suffix pattern. The WORD is expanded to produce + a pattern. It then expands to the value of PARAMETER, with the + smallest portion of the suffix matched by the pattern deleted. + + x=file.c + echo ${x%.c}.o + -->file.o + +${parameter%%word} + + Remove largest suffix pattern. The WORD is expanded to produce + a pattern. It then expands to the value of PARAMETER, with the + largest portion of the suffix matched by the pattern deleted. + + x=posix/src/std + echo ${x%%/*} + -->posix + +${parameter#word} + Remove smallest prefix pattern. The WORD is expanded to produce + a pattern. It then expands to the value of PARAMETER, with the + smallest portion of the prefix matched by the pattern deleted. + + x=$HOME/src/cmd + echo ${x#$HOME} + -->/src/cmd + +${parameter##word} + Remove largest prefix pattern. The WORD is expanded to produce + a pattern. It then expands to the value of PARAMETER, with the + largest portion of the prefix matched by the pattern deleted. + + x=/one/two/three + echo ${x##*/} + -->three + + +Given + a=/a/b/c/d + b=b.xxx + + csh bash result + --- ---- ------ + $a:h ${a%/*} /a/b/c + $a:t ${a##*/} d + $b:r ${b%.*} b + $b:e ${b##*.} xxx + + +18) How can I make my csh aliases work when I convert to bash? + +Bash uses a different syntax to support aliases than csh does. +The details can be found in the documentation. We have provided +a shell script which does most of the work of conversion for you; +this script can be found in ./examples/misc/alias-conv.sh. Here is +how you use it: + +Start csh in the normal way for you. (e.g., `csh') + +Pipe the output of `alias' through `alias-conv.sh', saving the +results into `bash_aliases': + + alias | alias-conv.sh >bash_aliases + +Edit `bash_aliases', carefully reading through any created +functions. You will need to change the names of some csh specific +variables to the bash equivalents. The script converts $cwd to +$PWD, $term to $TERM, $home to $HOME, $user to $USER, and $prompt +to $PS1. You may also have to add quotes to avoid unwanted +expansion. + +For example, the csh alias: + + alias cd 'cd \!*; echo $cwd' + +is converted to the bash function: + + cd () { command cd "$@"; echo $PWD ; } + +The only thing that needs to be done is to quote $PWD: + + cd () { command cd "$@"; echo "$PWD" ; } + +Merge the edited file into your ~/.bashrc. + +There is an additional, more ambitious, script in +examples/misc/cshtobash that attempts to convert your entire csh +environment to its bash equivalent. This script can be run as +simply `cshtobash' to convert your normal interactive +environment, or as `cshtobash ~/.login' to convert your login +environment. + +19) How can I pipe standard output and standard error from one command to + another, like csh does with `|&'? + +Use + command 2>&1 | command2 + +The key is to remember that piping is performed before redirection, so +file descriptor 1 points to the pipe when it is duplicated onto file +descriptor 2. + +20) Now that I've converted from ksh to bash, are there equivalents to + ksh features like autoloaded functions and the `whence' command? + +There are features in ksh-88 that do not have direct bash equivalents. +Most, however, can be emulated with very little trouble. + +ksh-88 feature Bash equivalent +-------------- --------------- +[[...]] can usually use [...]; minor differences (no + pattern matching, for one) +compiled-in aliases set up aliases in .bashrc; some ksh aliases are + bash builtins (hash, history, type) +$(<file) $(cat file) +extended patterns no good substitute +coprocesses named pipe pairs (one for read, one for write) +typeset +f declare -F +cd, print, whence function substitutes in examples/functions/kshenv +autoloaded functions examples/functions/autoload is the same as typeset -fu +read var?prompt read -p prompt var + +Section E: How can I get bash to do certain things, and why does bash do + things the way it does? + +21) Why is the bash builtin `test' slightly different from /bin/test? + +The specific example used here is [ ! x -o x ], which is false. + +Bash's builtin `test' implements the Posix.2 spec, which can be +summarized as follows (the wording is due to David Korn): + +Here is the set of rules for processing test arguments. + + 0 Args: False + 1 Arg: True iff argument is not null. + 2 Args: If first arg is !, True iff second argument is null. + If first argument is unary, then true if unary test is true + Otherwise error. + 3 Args: If second argument is a binary operator, do binary test of $1 $3 + If first argument is !, negate two argument test of $2 $3 + If first argument is `(' and third argument is `)', do the + one-argument test of the second argument. + Otherwise error. + 4 Args: If first argument is !, negate three argument test of $2 $3 $4. + Otherwise unspecified + 5 or more Args: unspecified. (Historical shells would use their + current algorithm). + +The operators -a and -o are considered binary operators for the purpose +of the 3 Arg case. + +As you can see, the test becomes (not (x or x)), which is false. + +22) Why does bash sometimes say `Broken pipe'? + +If a sequence of commands appears in a pipeline, and one of the +reading commands finishes before the writer has finished, the +writer receives a SIGPIPE signal. Many other shells special-case +SIGPIPE as an exit status in the pipeline and do not report it. +For example, in: + + ps -aux | head + +`head' can finish before `ps' writes all of its output, and ps +will try to write on a pipe without a reader. In that case, bash +will print `Broken pipe' to stderr when ps is killed by a +SIGPIPE. + +23) How can I get bash to read and display eight-bit characters? + +This is a process requiring several steps. + +First, you must ensure that the `physical' data path is a full eight +bits. For xterms, for example, the `vt100' resources `eightBitInput' +and `eightBitOutput' should be set to `true'. + +Once you have set up an eight-bit path, you must tell the kernel and +tty driver to leave the eighth bit of characters alone when processing +keyboard input. Use `stty' to do this: + + stty cs8 -istrip -parenb + +For old BSD-style systems, you can use + + stty pass8 + +You may also need + + stty even odd + +Finally, you need to tell readline that you will be inputting and +displaying eight-bit characters. You use readline variables to do +this. These variables can be set in your .inputrc or using the bash +`bind' builtin. Here's an example using `bind': + + bash$ bind 'set convert-meta off' + bash$ bind 'set meta-flag on' + bash$ bind 'set output-meta on' + +The `set' commands between the single quotes may also be placed +in ~/.inputrc. + +24) How do I write a function `x' to replace builtin command `x', but + still invoke the command from within the function? + +This is why the `command' and `builtin' builtins exist. The +`command' builtin executes the command supplied as its first +argument, skipping over any function defined with that name. The +`builtin' builtin executes the builtin command given as its first +argument directly. + +For example, to write a function to replace `cd' that writes the +hostname and current directory to an xterm title bar, use +something like the following: + + cd() + { + builtin cd "$@" && xtitle "$HOST: $PWD" + } + +This could also be written using `command' instead of `builtin'; +the version above is marginally more efficient. + +25) When I have terminal escape sequences in my prompt, why does bash + wrap lines at the wrong column? + +Readline, the line editing library that bash uses, does not know +that the terminal escape sequences do not take up space on the +screen. The redisplay code assumes, unless told otherwise, that +each character in the prompt is a `printable' character that +takes up one character position on the screen. + +You can use the bash prompt expansion facility (see the PROMPTING +section in the manual page) to tell readline that sequences of +characters in the prompt strings take up no screen space. + +Use the \[ escape to begin a sequence of non-printing characters, +and the \] escape to signal the end of such a sequence. + +26) How can I find the value of a shell variable whose name is the value + of another shell variable? + +Bash-2.0 supports this directly. You can use + + ${!var} + +For example, the following sequence of commands will echo `z': + + var1=var2 + var2=z + echo ${!var1} + +For sh compatibility, use the `eval' builtin. The important +thing to remember is that `eval' expands the arguments you give +it again, so you need to quote the parts of the arguments that +you want `eval' to act on. + +For example, this expression prints the value of the last positional +parameter: + + eval echo \"\$\{$#\}\" + +The expansion of the quoted portions of this expression will be +deferred until `eval' runs, while the `$#' will be expanded +before `eval' is executed. In bash-2.0, + + echo ${!#} + +does the same thing. + +27) If I pipe the output of a command into `read variable', why doesn't + the output show up in $variable when the read command finishes? + +This has to do with the parent-child relationship between Unix +processes. + +Each element of a pipeline runs in a separate process, a child of +the shell running the pipeline. A subprocess cannot affect its +parent's environment. When the `read' command sets the variable +to the input, that variable is set only in the subshell, not the +parent shell. When the subshell exits, the value of the variable +is lost. + +Many pipelines that end with `read variable' can be converted +into command substitutions, which will capture the output of +a specified command. The output can then be assigned to a +variable: + + grep ^gnu /usr/lib/news/active | wc -l | read ngroup + +can be converted into + + ngroup=$(grep ^gnu /usr/lib/news/active | wc -l) + +This does not, unfortunately, work to split the text among +multiple variables, as read does when given multiple variable +arguments. If you need to do this, you can either use the +command substitution above to read the output into a variable +and chop up the variable using the bash pattern removal +expansion operators or use some variant of the following +approach. + +Say /usr/local/bin/ipaddr is the following shell script: + +#! /bin/sh +host `hostname` | awk '/address/ {print $NF}' + +Instead of using + + /usr/local/bin/ipaddr | read A B C D + +to break the local machine's IP address into separate octets, use + + OIFS="$IFS" + IFS=. + set -- $(/usr/local/bin/ipaddr) + IFS="$OIFS" + A="$1" B="$2" C="$3" D="$4" + +Beware, however, that this will change the shell's positional +parameters. If you need them, you should save them before doing +this. + +This is the general approach -- in most cases you will not need to +set $IFS to a different value. + +28) I have a bunch of shell scripts that use backslash-escaped characters + in arguments to `echo'. Bash doesn't interpret these characters. Why + not, and how can I make it understand them? + +This is the behavior of echo on most Unix System V machines. + +The bash builtin `echo' is modelled after the 9th Edition +Research Unix version of `echo'. It does not interpret +backslash-escaped characters in its argument strings by default; +it requires the use of the -e option to enable the +interpretation. The System V echo provides no way to disable the +special characters; the bash echo has a -E option to disable +them. + +There is a configuration option that will make bash behave like +the System V echo and interpret things like `\t' by default. Run +configure with the --enable-usg-echo-default option to turn this +on. Be aware that this will cause some of the tests run when you +type `make tests' to fail. + +29) Why doesn't a while or for loop get suspended when I type ^Z? + +This is a consequence of how job control works on Unix. The only +thing that can be suspended is the process group. This is a single +command or pipeline of commands that the shell forks and executes. + +When you run a while or for loop, the only thing that the shell forks +and executes are any commands in the while loop test and commands in +the loop bodies. These, therefore, are the only things that can be +suspended when you type ^Z. + +If you want to be able to stop the entire loop, you need to put it +within parentheses, which will force the loop into a subshell that +may be stopped (and subsequently restarted) as a single unit. + +30) How can I make the bash `time' reserved word print timing output that + looks like the output from my system's /usr/bin/time? + +The bash command timing code looks for a variable `TIMEFORMAT' and +uses its value as a format string to decide how to display the +timing statistics. + +The value of TIMEFORMAT is a string with `%' escapes expanded in a +fashion similar in spirit to printf(3). The manual page explains +the meanings of the escape sequences in the format string. + +If TIMEFORMAT is not set, bash acts as if the following assignment had +been performed: + + TIMEFORMAT=$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS' + +The POSIX.2 default time format (used by `time -p command') is + + TIMEFORMAT=$'real %2R\nuser %2U\nsys %2S' + +The BSD /usr/bin/time format can be emulated with: + + TIMEFORMAT=$'\t%1R real\t%1U user\t%1S sys' + +The System V /usr/bin/time format can be emulated with: + + TIMEFORMAT=$'\nreal\t%1R\nuser\t%1U\nsys\t%1S' + +The ksh format can be emulated with: + + TIMEFORMAT=$'\nreal\t%2lR\nuser\t%2lU\nsys\t%2lS' + +Section F: Things to watch out for on certain Unix versions + +31) Why can't I use command line editing in my `cmdtool'? + +The problem is `cmdtool' and bash fighting over the input. When +scrolling is enabled in a cmdtool window, cmdtool puts the tty in +`raw mode' to permit command-line editing using the mouse for +applications that cannot do it themselves. As a result, bash and +cmdtool each try to read keyboard input immediately, with neither +getting enough of it to be useful. + +This mode also causes cmdtool to not implement many of the +terminal functions and control sequences appearing in the +`sun-cmd' termcap entry. For a more complete explanation, see +that file examples/suncmd.termcap in the bash distribution. + +`xterm' is a better choice, and gets along with bash much more +smoothly. + +If you must use cmdtool, you can use the termcap description in +examples/suncmd.termcap. Set the TERMCAP variable to the terminal +description contained in that file, i.e. + +TERMCAP='Mu|sun-cmd:am:bs:km:pt:li#34:co#80:cl=^L:ce=\E[K:cd=\E[J:rs=\E[s:' + +Then export TERMCAP and start a new cmdtool window from that shell. +The bash command-line editing should behave better in the new +cmdtool. If this works, you can put the assignment to TERMCAP +in your bashrc file. + +32) I built bash on Solaris 2. Why do globbing expansions and filename + completion chop off the first few characters of each filename? + +This is the consequence of building bash on SunOS 5 and linking +with the libraries in /usr/ucblib, but using the definitions +and structures from files in /usr/include. + +The actual conflict is between the dirent structure in +/usr/include/dirent.h and the struct returned by the version of +`readdir' in libucb.a (a 4.3-BSD style `struct direct'). + +Make sure you've got /usr/ccs/bin ahead of /usr/ucb in your $PATH +when configuring and building bash. This will ensure that you +use /usr/ccs/bin/cc or acc instead of /usr/ucb/cc and that you +link with libc before libucb. + +If you have installed the Sun C compiler, you may also need to +put /usr/ccs/bin and /opt/SUNWspro/bin into your $PATH before +/usr/ucb. + +33) Why does bash dump core after I interrupt username completion or + `~user' tilde expansion on a machine running NIS? + +This is a famous and long-standing bug in the SunOS YP (sorry, NIS) +client library, which is part of libc. + +The YP library code keeps static state -- a pointer into the data +returned from the server. When YP initializes itself (setpwent), +it looks at this pointer and calls free on it if it's non-null. +So far, so good. + +If one of the YP functions is interrupted during getpwent (the +exact function is interpretwithsave()), and returns NULL, the +pointer is freed without being reset to NULL, and the function +returns. The next time getpwent is called, it sees that this +pointer is non-null, calls free, and the bash free() blows up +because it's being asked to free freed memory. + +The traditional Unix mallocs allow memory to be freed multiple +times; that's probably why this has never been fixed. You can +run configure with the `--without-gnu-malloc' option to use +the C library malloc and avoid the problem. + +34) I'm running SVR4.2. Why is the line erased every time I type `@'? + +The `@' character is the default `line kill' character in most +versions of System V, including SVR4.2. You can change this +character to whatever you want using `stty'. For example, to +change the line kill character to control-u, type + + stty kill ^U + +where the `^' and `U' can be two separate characters. + +35) Why does bash report syntax errors when my C News scripts use a + redirection before a subshell command? + +The actual command in question is something like + + < file ( command ) + +According to the grammar given in the POSIX.2 standard, this construct +is, in fact, a syntax error. Redirections may only precede `simple +commands'. A subshell construct such as the above is one of the shell's +`compound commands'. A redirection may only follow a compound command. + +The file CWRU/sh-redir-hack in the bash-2.0 distribution is an +(unofficial) patch to parse.y that will modify the grammar to +support this construct. It will not apply with `patch'; you must +modify parse.y by hand. Note that if you apply this, you must +recompile with -DREDIRECTION_HACK. This introduces a large +number of reduce/reduce conflicts into the shell grammar. + +Section G: Where do I go from here? + +36) How do I report bugs in bash, and where should I look for fixes and + advice? + +Use the `bashbug' script to report bugs. It is built and +installed at the same time as bash. It provides a standard +template for reporting a problem and automatically includes +information about your configuration and build environment. + +`bashbug' sends its reports to bug-bash@prep.ai.mit.edu, which +is a large mailing list gatewayed to the usenet newsgroup gnu.bash.bug. + +Bug fixes, answers to questions, and announcements of new releases +are all posted to gnu.bash.bug. Discussions concerning bash features +and problems also take place there. + +To reach the bash maintainers directly, send mail to +bash-maintainers@prep.ai.mit.edu. + +37) What kind of bash documentation is there? + +First, look in the doc directory in the bash distribution. It should +contain at least the following files: + +bash.1 an extensive, thorough Unix-style manual page +builtins.1 a manual page covering just bash builtin commands +bashref.texi a reference manual in GNU info format +bash.html an HTML version of the manual page +bashref.html an HTML version of the reference manual +FAQ this file +article.ms text of an article written for The Linux Journal +readline.3 a man page describing readline + +Postscript files created from the above source are available in +the documentation distribution. + +There is additional documentation available for anonymous FTP from host +slc2.ins.cwru.edu in the `pub/bash' directory. + +Cameron Newham and Bill Rosenblatt have written a book on bash, published +by O'Reilly and Associates. The book is based on Bill Rosenblatt's Korn +Shell book. The title is ``Learning the Bash Shell''. The ISBN number is +1-56592-147-X. Look for it in fine bookstores near you. This book covers +bash-1.14, but has an appendix describing some of the new features in +bash-2.0. + +38) What's coming in future versions? + +These are features I plan to include in a future version of bash. + +POSIX.2-style globbing character classes ([:alpha:], [:alnum:], etc.) +a bash debugger (an incomplete, untested version is included with bash-2.0) + +39) What's on the bash `wish list' for future versions? + +These are features that may or may not appear in a future version of bash. + +Programmable completion a la zsh +menu completion a la tcsh +the ksh [[...]] extended test command +the ksh egrep-style extended pattern matching operators +associative arrays (not really all that hard) +breaking some of the shell functionality into embeddable libraries +better internationalization using GNU `gettext' +an option to use external files for the long `help' text +timeouts for the `read' builtin +the ksh-93 ${!prefix*} and ${!prefix@} operators +arithmetic ++ and -- prefix and postfix operators + +40) When will the next release appear? + +The next version will appear sometime in 1997. Never make predictions. + + +This document is Copyright 1995, 1996 by Chester Ramey. + +Permission is hereby granted, without written agreement and +without license or royalty fees, to use, copy, and distribute +this document for any purpose, provided that the above copyright +notice appears in all copies of this document and that the +contents of this document remain unaltered. diff --git a/doc/INTRO b/doc/INTRO new file mode 100644 index 00000000..fc6bce6e --- /dev/null +++ b/doc/INTRO @@ -0,0 +1,187 @@ + BASH - The Bourne-Again Shell + +Bash is the shell, or command language interpreter, that will appear +in the GNU operating system. Bash is an sh-compatible shell that +incorporates useful features from the Korn shell (ksh) and C shell +(csh). It is intended to conform to the IEEE POSIX P1003.2/ISO 9945.2 +Shell and Tools standard. It offers functional improvements over sh +for both programming and interactive use. In addition, most sh scripts +can be run by Bash without modification. + +Bash is quite portable. It uses a configuration system that discovers +characteristics of the compilation platform at build time, and may +therefore be built on nearly every version of UNIX. Ports to +UNIX-like systems such as QNX and Minix and to non-UNIX systems such +as OS/2, Windows 95, and Windows NT are available. + +Bash includes the following features: + +Editing and Completion + +Bash offers a command-line editing facility which permits users to +edit command lines using familiar emacs or vi-style editing commands. +Editing allows corrections to be made without having to erase back +to the point of error or start the command line anew. The editing +facilities include a feature that allows users to complete command and +file names. + +The Bash line editing library is fully customizable. Users may define +their own key bindings -- the action taken when a key is pressed. A +number of variables to fine-tune editing behavior are also available. + +History and Command Re-entry + +The Bash history feature remembers commands entered to the shell and +allows them to be recalled and re-executed. The history list may be +of unlimited size. Bash allows users to search for previous commands +and reuse portions of those commands when composing new ones. The +history list may be saved across shell sessions. + +Bash allows users to control which commands are saved on the history +list. + +Job Control + +On systems that support it, Bash provides an interface to the +operating system's job control facilities, which allow processes +to be suspended and restarted, and moved between the foreground +and background. Bash allows users to selectively `forget' about +background jobs. + +Shell Functions and Aliases + +These mechanisms are available to bind a user-selected identifier to a +list of commands that will be executed when the identifier is used as +a command name. Functions allow local variables and recursion, and +have access to the environment of the calling shell. Aliases may be +used to create a mnemonic for a command name, expand a single word to +a complex command, or ensure that a command is called with a basic set +of options. + +Arrays + +Bash-2.0 supports indexed arrays of unlimited size. The subscript for +an array is an arithmetic expression. Arrays may be assigned to with +a new compound assignment syntax, and several builtins have options to +operate on array variables. Bash includes a number of built-in array +variables. + +Arithmetic + +Bash allows users to perform integer arithmetic in any base from two +to sixty-four. Nearly all of the C language arithmetic operators are +available with the same syntax and precedence as in C. Arithmetic +expansion allows an arithmetic expression to be evaluated and the +result substituted into the command line. Shell variables can be used +as operands, and the value of an expression may be assigned to a +variable. + +An arithmetic expression may be used as a command; the exit status of +the command is the value of the expression. + +ANSI-C Quoting + +There is a new quoting syntax that allows backslash-escaped characters +in strings to be expanded according to the ANSI C standard. + +Tilde Expansion + +Users' home directories may be expanded using this feature. Words +beginning with a tilde may also be expanded to the current or previous +working directory. + +Brace Expansion + +Brace expansion is a convenient way to generate a list of strings that +share a common prefix or suffix. + +Substring Capabilities + +Bash allows new strings to be created by removing leading or trailing +substrings from existing variable values, or by specifying a starting +offset and length. Portions of variable values may be matched against +shell patterns and the matching portion removed or a new value +substituted. + +Indirect Variable Expansion + +Bash makes it easy to find the value of a shell variable whose name is +the value of another variable. + +Expanded I/O Capabilities + +Bash provides several input and output features not available in sh, +including the ability to: + + o specify a file or file descriptor for both input and output + o read from or write to asynchronous processes using named pipes + o read lines ending in backslash + o display a prompt on the terminal before a read + o format menus and interpret responses to them + o echo lines exactly as input without escape processing + +Control of Builtin Commands + +Bash implements several builtin commands to give users more control +over which commands are executed. The enable builtin allows other +builtin commands to be selectively enabled or disabled. The command +and builtin builtins change the order in which the shell searches for +commands. + +On systems that provide dynamic loading, new builtins may be loaded +into a running shell from a shared object file. These new builtins +have access to all of the shell facilities. + +Help + +Bash includes a built-in help factility. + +Shell Optional Behavior + +There is a great deal of customizable shell behavior. The shopt +builtin command provides a unified interface that allows users to +alter shell defaults. + +Prompt Customization + +Bash allows the primary and secondary prompts to be customized by +interpreting a number of backslash-escaped special characters. +Parameter and variable expansion is also performed on the values of +the primary and secondary prompt strings before they are displayed. + +Security + +Bash provides a restricted shell environment. It is also possible to +control the execution of setuid/setgid scripts. + +Directory Stack + +Bash provides a `directory stack', to which directories may be added +and removed. The current directory may be changed to any directory in +the stack. It is easy to toggle between two directories in the stack. +The directory stack may be saved and restored across different shell +invocations. + +POSIX Mode + +Bash is nearly completely conformant to POSIX.2. POSIX mode changes +those few areas where the Bash default behavior differs from the +standard to match the standard. In POSIX mode, Bash is POSIX.2 +compliant. + +Internationalization + +Bash provides a new quoting syntax that allows strings to be +translated according to the current locale. The locale in which the +shell itself runs may also be changed, so that the shell messages +themselves may be language-specific. + +The command-line editing facilities allow the input of eight-bit +characters, so most of the ISO-8859 family of character sets are +supported. + +Command Timing + +Bash allows external commands, shell builtin commands and shell functions +to be timed. The format used to display the timing information may be +changed by the user. diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 00000000..3ac3012c --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,169 @@ +# This Makefile is for the Bash/documentation directory -*- text -*-. +# +RM = rm -f + +topdir = @top_srcdir@ +srcdir = @srcdir@ +VPATH = .:@srcdir@ + +infodir = @infodir@ + +mandir = @mandir@ +manpfx = man + +man1ext = 1 +man1dir = $(mandir)/$(manpfx)$(man1ext) +man3ext = 3 +man3dir = $(mandir)/$(manpfx)$(man3ext) + +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +BUILD_DIR = @BUILD_DIR@ + +# bad style +RL_LIBDIR = $(topdir)/lib/readline + +# unused +TEXINDEX = texindex +TEX = tex + +MAKEINFO = makeinfo +TEXI2DVI = ${topdir}/support/texi2dvi +TEXI2HTML = ${topdir}/support/texi2html +QUIETPS = #set this to -q to shut up dvips +DVIPS = dvips -D 300 $(QUIETPS) -o $@ # tricky +TEXINPUTDIR = $(RL_LIBDIR)/doc + +MKDIRS = ${topdir}/support/mkdirs + +# This should be a program that converts troff to an ascii-readable format +NROFF = groff -Tascii + +# This should be a program that converts troff to postscript +GROFF = groff + +HSUSER = $(RL_LIBDIR)/doc/hsuser.texinfo +RLUSER = $(RL_LIBDIR)/doc/rluser.texinfo + +.SUFFIXES: .0 .1 .3 .ms .ps .txt .dvi + +.1.ps: + $(RM) $@ + -${GROFF} -man $< > $@ + +.1.0: + $(RM) $@ + -${NROFF} -man $< > $@ + +.ms.ps: + $(RM) $@ + -${GROFF} -ms $< > $@ + +.ms.txt: + $(RM) $@ + -${NROFF} -ms $< > $@ + +.3.ps: + $(RM) $@ + -${GROFF} -man $< > $@ + +.3.0: + $(RM) $@ + -${NROFF} -man $< > $@ + +all: ps info dvi text html +nodvi: ps info text html + +ps: bash.ps bashbug.ps readline.ps article.ps builtins.ps +dvi: bashref.dvi bashref.ps +info: bashref.info +text: bash.0 bashbug.0 builtins.0 readline.0 +html: bashref.html + +bashref.dvi: $(srcdir)/bashref.texi $(HSUSER) $(RLUSER) + TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/bashref.texi + +bashref.ps: bashref.dvi + $(RM) $@ + $(DVIPS) bashref.dvi + +bashref.info: $(srcdir)/bashref.texi $(HSUSER) $(RLUSER) + $(MAKEINFO) --no-split -I$(TEXINPUTDIR) $(srcdir)/bashref.texi + +bashref.html: bashref.texi $(HSUSER) $(RLUSER) + $(TEXI2HTML) -I $(TEXINPUTDIR) $(srcdir)/bashref.texi + +bash.dvi: bash.texinfo $(HSUSER) $(RLUSER) + TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) bash.texinfo + +bashman.ps: bash.dvi + $(RM) $@ + $(DVIPS) bash.dvi + +bash.txt: bash.1 +bash.ps: bash.1 +bashbug.ps: bashbug.1 +builtins.ps: builtins.1 bash.1 +bash.0: bash.1 +bashbug.0: bashbug.1 +builtins.0: builtins.1 bash.1 +readline.0: readline.3 +readline.ps: readline.3 +article.ps: article.ms + +faq: faq.news faq.news2 faq.mail faq.version + +faq.version: FAQ.version FAQ + sh mkfaqvers FAQ.version > $@ + +faq.news: FAQ FAQ.headers.news faq.version + $(RM) $@ + cat FAQ.headers.news faq.version FAQ > $@ + +faq.news2: FAQ FAQ.headers.news2 faq.version + $(RM) $@ + cat FAQ.headers.news2 faq.version FAQ > $@ + +faq.mail: FAQ FAQ.headers.mail faq.version + $(RM) $@ + cat FAQ.headers.mail faq.version FAQ > $@ + +clean: + $(RM) *.aux *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.cps \ + *.pgs *.bt *.bts *.rw *.rws *.fns *.kys *.tps *.vrs *.o \ + core rluser.texinfo hsuser.texinfo + +distclean mostlyclean: clean + $(RM) Makefile + +maintainer-clean: clean + $(RM) *.0 *.ps *.dvi *.info *.txt + $(RM) Makefile + +installdirs: + -test -d $(man1dir) || $(SHELL) ${MKDIRS} $(man1dir) + -test -d $(man3dir) || $(SHELL) ${MKDIRS} $(man3dir) + -test -d $(infodir) || $(SHELL) ${MKDIRS} $(infodir) + +install: info installdirs + -$(INSTALL_DATA) $(srcdir)/bash.1 $(man1dir)/bash.${man1ext} + -$(INSTALL_DATA) $(srcdir)/bashbug.1 $(man1dir)/bashbug.${man1ext} + -$(INSTALL_DATA) $(srcdir)/readline.3 $(man3dir)/readline.${man3ext} + -$(INSTALL_DATA) $(srcdir)/bashref.info $(infodir)/bash.info +# uncomment the next line to install the builtins man page +# $(INSTALL_DATA) builtins.1 $(man1dir)/bash_builtins.${man1ext} + +uninstall: + $(RM) $(man1dir)/bash.${man1ext} $(man1dir)/bashbug.${man1ext} + $(RM) $(man3dir)/readline.${man3ext} $(infodir)/bash.info + +# for use by chet +inst: bashref.texi + $(SHELL) ./mkinstall + cmp -s INSTALL ../INSTALL || mv INSTALL ../INSTALL + $(RM) INSTALL + +posix: bashref.texi + $(SHELL) ./mkposix + cmp -s POSIX.NOTES ../CWRU/POSIX.NOTES || mv POSIX.NOTES ../CWRU/POSIX.NOTES + $(RM) POSIX.NOTES diff --git a/doc/README b/doc/README new file mode 100644 index 00000000..932bf7ff --- /dev/null +++ b/doc/README @@ -0,0 +1,35 @@ +This directory contains the bash documentation. + +FAQ - a set of frequently-asked questions about Bash with answers +article.ms - an article I wrote about bash for The Linux Journal +bash.1 - the bash man page +builtins.1 - a man page that documents the builtins, extracted from bash.1 +features.texi - the `bash reference manual' +features.info - the `bash reference manual' processed by `makeinfo' +readline.3 - the readline man page + +The `.ps' files are postscript versions of the above. The `.html' +files are HTML versions of the man page and reference manual. The +`.0' files are formatted manual pages. The `.txt' versions are +ascii -- the output of `groff -Tascii'. + +The rest of this file explains how to use the `builtins.1' man page. + +For each command in the list of builtins create a file in man/man1 called: + +${command}.1 + +eg. +for.1 +type.1 +alias.1 +etc. + +All these files are identical as follows: + +jaws@jaws(264)$ cat alias.1 +.so man1/builtins.1 +jaws@jaws(265)$ + +Make sure you adjust the .so line in builtins.1 to reflect where you +put it. diff --git a/doc/article.ms b/doc/article.ms new file mode 100644 index 00000000..517155a8 --- /dev/null +++ b/doc/article.ms @@ -0,0 +1,1114 @@ +.de SE \" start example +.sp .5 +.RS +.ft CR +.nf +.. +.de EE \" end example +.fi +.sp .5 +.RE +.ft R +.. +.TL +Bash \- The GNU shell* +.AU +Chet Ramey +Case Western Reserve University +chet@po.cwru.edu +.FS +*An earlier version of this article appeared in The Linux Journal. +.FE +.NH 1 +Introduction +.PP +.B Bash +is the shell, or command language interpreter, +that will appear in the GNU operating system. +The name is an acronym for +the \*QBourne-Again SHell\*U, a pun on Steve Bourne, the author +of the direct ancestor of the current +.UX +shell \fI/bin/sh\fP, +which appeared in the Seventh Edition Bell Labs Research version +of \s-1UNIX\s+1. +.PP +Bash is an \fBsh\fP\-compatible shell that incorporates useful +features from the Korn shell (\fBksh\fP) and the C shell (\fBcsh\fP), +described later in this article. It is ultimately intended to be a +conformant implementation of the IEEE POSIX Shell and Utilities +specification (IEEE Working Group 1003.2). It offers functional +improvements over sh for both interactive and programming use. +.PP +While the GNU operating system will most likely include a version +of the Berkeley shell csh, Bash will be the default shell. +Like other GNU software, Bash is quite portable. It currently runs +on nearly every version of +.UX +and a few other operating systems \- an independently-supported +port exists for OS/2, and there are rumors of ports to DOS and +Windows NT. Ports to \s-1UNIX\s+1-like systems such as QNX and Minix +are part of the distribution. +.PP +The original author of Bash +was Brian Fox, an employee of the Free Software Foundation. The +current developer and maintainer is Chet Ramey, a volunteer who +works at Case Western Reserve University. +.NH 1 +What's POSIX, anyway? +.PP +.I POSIX +is a name originally coined by Richard Stallman for a family of open +system standards based on \s-1UNIX\s+1. There are a number of aspects of \s-1UNIX\s+1 +under consideration for standardization, from the basic system services +at the system call and C library level to applications and tools to system +administration and management. Each area of standardization is +assigned to a working group in the 1003 series. +.PP +The POSIX Shell and Utilities standard has been developed by IEEE Working +Group 1003.2 (POSIX.2).\(dd +.FS +\(ddIEEE, \fIIEEE Standard for Information Technology -- Portable +Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, +1992. +.FE +It concentrates on the command interpreter +interface and utility programs +commonly executed from the command line or by other programs. +An initial version of the standard has been +approved and published by the IEEE, and work is currently underway to +update it. +There are four primary areas of work in the 1003.2 standard: +.IP \(bu +Aspects of the shell's syntax and command language. +A number of special builtins such as +.B cd +and +.B exec +are being specified as part of the shell, since their +functionality usually cannot be implemented by a separate executable; +.IP \(bu +A set of utilities to be called by shell scripts and applications. +Examples are programs like +.I sed, +.I tr, +and +.I awk. +Utilities commonly implemented as shell builtins +are described in this section, such as +.B test +and +.B kill . +An expansion of this section's scope, termed the User Portability +Extension, or UPE, has standardized interactive programs such as +.I vi +and +.I mailx; +.IP \(bu +A group of functional interfaces to services provided by the +shell, such as the traditional \f(CRsystem()\fP +C library function. There are functions to perform shell word +expansions, perform filename expansion (\fIglobbing\fP), obtain values +of POSIX.2 system configuration variables, retrieve values of +environment variables (\f(CRgetenv()\fP\^), and other services; +.IP \(bu +A suite of \*Qdevelopment\*U utilities such as +.I c89 +(the POSIX.2 version of \fIcc\fP), +and +.I yacc. +.PP +Bash is concerned with the aspects of the shell's behavior +defined by POSIX.2. The shell command language has of +course been standardized, including the basic flow control +and program execution constructs, I/O redirection and +pipelining, argument handling, variable expansion, and quoting. +The +.I special +builtins, which must be implemented as part of the shell to +provide the desired functionality, are specified as being +part of the shell; examples of these are +.B eval +and +.B export . +Other utilities appear in the sections of POSIX.2 not +devoted to the shell which are commonly (and in some +cases must be) implemented as builtin commands, such as +.B read +and +.B test . +POSIX.2 also specifies aspects of the shell's +interactive behavior as part of +the UPE, including job control and command line editing. +Interestingly enough, only \fIvi\fP-style line editing commands +have been standardized; \fIemacs\fP editing commands were left +out due to objections. +.PP +While POSIX.2 includes much of what the shell has traditionally +provided, some important things have been omitted as being +\*Qbeyond its scope.\*U There is, for instance, no mention of +a difference between a +.I login +shell and any other interactive shell (since POSIX.2 does not +specify a login program). No fixed startup files are defined, +either \- the standard does not mention +.I .profile . +.NH 1 +Basic Bash features +.PP +Since the Bourne shell +provides Bash with most of its philosophical underpinnings, +Bash inherits most of its features and functionality from sh. +Bash implements all of the traditional sh flow +control constructs (\fIfor\fP, \fIif\fP, \fIwhile\fP, etc.). +All of the Bourne shell builtins, including those not specified in +the POSIX.2 standard, appear in Bash. Shell \fIfunctions\fP, +introduced in the SVR2 version of the Bourne shell, +are similar to shell scripts, but are defined using a special +syntax and are executed in the same process as the calling shell. +Bash has shell functions +which behave in a fashion upward-compatible with sh functions. +There are certain shell +variables that Bash interprets in the same way as sh, such as +.B PS1 , +.B IFS , +and +.B PATH . +Bash implements essentially the same grammar, parameter and +variable expansion semantics, redirection, and quoting as the +Bourne shell. Where differences appear between the POSIX.2 +standard and traditional sh behavior, Bash follows POSIX. +.PP +The Korn Shell (\fBksh\fP) is a descendent of the Bourne shell written +at AT&T Bell Laboratories by David Korn\(dg. It provides a number of +useful features that POSIX and Bash have adopted. Many of the +interactive facilities in POSIX.2 have their roots in the ksh: +for example, the POSIX and ksh job control facilities are nearly +identical. Bash includes features from the Korn Shell for both +interactive use and shell programming. For programming, Bash provides +variables such as +.B RANDOM +and +.B REPLY , +the +.B typeset +builtin, +the ability to remove substrings from variables based on patterns, +and shell arithmetic. +.FS +\(dgMorris Bolsky and David Korn, \fIThe KornShell Command and +Programming Language\fP, Prentice Hall, 1989. +.FE +.B RANDOM +expands to a random number each time it is referenced; assigning a +value to +.B RANDOM +seeds the random number generator. +.B REPLY +is the default variable used by the +.B read +builtin when no variable names are supplied as arguments. +The +.B typeset +builtin is used to define variables and give them attributes +such as \fBreadonly\fP. +Bash arithmetic allows the evaluation of an expression and the +substitution of the result. Shell variables may be used as operands, +and the result of an expression may be assigned to a variable. +Nearly all of the operators from the C language are available, +with the same precedence rules: +.SE +$ echo $((3 + 5 * 32)) +163 +.EE +.LP +For interactive use, Bash implements ksh-style aliases and builtins +such as +.B fc +(discussed below) and +.B jobs . +Bash aliases allow a string to be substituted for a command name. +They can be used to create a mnemonic for a \s-1UNIX\s+1 command +name (\f(CRalias del=rm\fP), to expand a single word to a complex command +(\f(CRalias news='xterm -g 80x45 -title trn -e trn -e -S1 -N &'\fP), or to +ensure that a command is invoked with a basic set of options +(\f(CRalias ls="/bin/ls -F"\fP). +.PP +The C shell (\fBcsh\fP)\(dg, originally written by Bill Joy while at +Berkeley, is widely used and quite popular for its interactive +facilities. Bash includes a csh-compatible history expansion +mechanism (\*Q! history\*U), brace expansion, access to a stack +of directories via the +.B pushd , +.B popd , +and +.B dirs +builtins, and tilde expansion, to generate users' home directories. +Tilde expansion has also been adopted by both the Korn Shell and +POSIX.2. +.FS +\(dgBill Joy, An Introduction to the C Shell, \fIUNIX User's Supplementary +Documents\fP, University of California at Berkeley, 1986. +.FE +.PP +There were certain areas in which POSIX.2 felt standardization +was necessary, but no existing implementation provided the proper +behavior. The working group invented and standardized functionality +in these areas, which Bash implements. The +.B command +builtin was invented so that shell functions could be written to +replace builtins; it makes the capabilities of the builtin +available to the function. The reserved word \*Q!\*U was added +to negate the return value of a command or pipeline; it was nearly +impossible to express \*Qif not x\*U cleanly using the sh language. +There exist multiple incompatible implementations of the +.B test +builtin, which tests files for type and other attributes and performs +arithmetic and string comparisons. +POSIX considered none of these correct, so the standard +behavior was specified in terms of the number of arguments to the +command. POSIX.2 dictates exactly what will happen when four or +fewer arguments are given to +.B test , +and leaves the behavior undefined when more arguments are supplied. +Bash uses the POSIX.2 algorithm, which was conceived by David Korn. +.NH 2 +Features not in the Bourne Shell +.PP +There are a number of minor differences between Bash and the +version of sh present on most other versions of \s-1UNIX\s+1. The majority +of these are due to the POSIX standard, but some are the result of +Bash adopting features from other shells. For instance, Bash +includes the new \*Q!\*U reserved word, the +.B command +builtin, the ability of the +.B read +builtin to correctly return a line ending with a backslash, symbolic +arguments to the +.B umask +builtin, variable substring removal, a way to get the length of a variable, +and the new algorithm for the +.B test +builtin from the POSIX.2 standard, none of which appear in sh. +.PP +Bash also implements the \*Q$(...)\*U command substitution syntax, +which supersedes the sh `...` construct. +The \*Q$(...)\*U construct expands to the output of the command +contained within the +parentheses, with trailing newlines removed. The sh syntax is +accepted for backwards compatibility, but the \*Q$(...)\*U form +is preferred because its quoting rules are much simpler and it +is easier to nest. +.PP +The Bourne shell does not provide such features as brace expansion, +the ability +to define a variable and a function with the same name, local variables +in shell functions, the ability to enable and disable individual +builtins or write a function to replace a builtin, or a means to +export a shell function to a child process. +.PP +Bash has closed +a long-standing shell security hole by not using the +.B $IFS +variable to split each word read by the shell, but splitting only +the results of expansion (ksh and the 4.4 BSD sh have fixed this +as well). Useful behavior such as a means to abort +execution of a script read with the \*Q.\*U command using the +\fBreturn\fP builtin or automatically +exporting variables in the shell's environment to children is also +not present in the Bourne shell. Bash provides a much more powerful +environment for both interactive use and programming. +.NH 1 +Bash-specific Features +.PP +This section details a few of the features which make Bash unique. +Most of them provide improved interactive use, but a few programming +improvements are present as well. Full descriptions of these +features can be found in the Bash documentation. +.NH 2 +Startup Files +.PP +Bash executes startup files differently than other shells. The Bash +behavior is a compromise between the csh principle of startup files +with fixed names executed for each shell and the sh +\*Qminimalist\*U behavior. An interactive instance of Bash started +as a login shell reads and executes +.I ~/.bash_profile +(the file .bash_profile in the user's home directory), if it exists. +An interactive non-login shell reads and executes +.I ~/.bashrc . +A non-interactive shell (one begun to execute a shell script, for +example) reads no fixed startup file, but uses the value of the variable +.B $ENV , +if set, as the name of a startup file. The ksh practice of reading +.B $ENV +for every shell, with the accompanying difficulty of defining the +proper variables and functions for interactive and non-interactive +shells or having the file read only for interactive shells, was +considered too complex. Ease of use won out here. Interestingly, +the next release of ksh will change to reading +.B $ENV +only for interactive shells. +.NH 2 +New Builtin Commands +.PP +There are a few builtins which are new or have been extended in Bash. +The +.B enable +builtin allows builtin commands to be turned on and off arbitrarily. +To use the version of +.I echo +found in a user's search path rather than the Bash builtin, +\f(CRenable -n echo\fP suffices. The +.B help +builtin provides +quick synopses of the shell facilities without requiring +access to a manual page. +.B Builtin +is similar to +.B command +in that it bypasses shell functions and directly executes builtin +commands. Access to a csh-style stack of directories is provided +via the +.B pushd , +.B popd , +and +.B dirs +builtins. +.B Pushd +and +.B popd +insert and remove directories from the stack, respectively, and +.B dirs +lists the stack contents. On systems that allow fine-grained control +of resources, the +.B ulimit +builtin can be used to tune these settings. +.B Ulimit +allows a user to control, +among other things, whether core dumps are to be generated, +how much memory the shell or a child process is allowed to allocate, +and how large a file created by a child process can grow. The +.B suspend +command will stop the shell process when job control is active; most +other shells do not allow themselves to be stopped like that. +.B Type, +the Bash answer to +.B which +and +.B whence, +shows what will happen when a word is typed as a command: +.SE +$ type export +export is a shell builtin +$ type -t export +builtin +$ type bash +bash is /bin/bash +$ type cd +cd is a function +cd () +{ + builtin cd ${1+"$@"} && xtitle $HOST: $PWD +} +.EE +.LP +Various +modes tell what a command word is (reserved word, alias, function, builtin, +or file) or which version of a command will be executed based on +a user's search path. Some of this functionality has been adopted +by POSIX.2 and folded into the +.B command +utility. +.NH 2 +Editing and Completion +.PP +One area in which Bash shines is command line editing. Bash uses the +.I readline +library to read and edit lines when interactive. Readline is a +powerful and flexible input facility that a user can configure to +individual tastes. It allows lines to be edited using either emacs +or vi commands, where those commands are appropriate. The full +capability of emacs is not present \- there is no way to execute +a named command with M-x, for instance \- but the existing commands +are more than adequate. The vi mode is compliant with +the command line editing standardized by POSIX.2. +.PP +Readline is fully customizable. In addition to the basic commands +and key bindings, the library allows users to define additional +key bindings using a startup file. The +.I inputrc +file, which defaults to the file +.I ~/.inputrc , +is read each time readline initializes, permitting users to +maintain a consistent interface across a set of programs. Readline +includes an extensible interface, so each program using the +library can add its own bindable commands and program-specific +key bindings. Bash uses this facility to add bindings +that perform history expansion or shell word expansions on the current +input line. +.PP +Readline interprets a number of +variables which further tune its behavior. Variables +exist to control whether or not eight-bit characters are directly +read as input or converted to meta-prefixed key sequences (a +meta-prefixed key sequence consists of the character with the +eighth bit zeroed, preceded by the +.I meta-prefix +character, usually escape, which selects an alternate keymap), to +decide whether to output characters with the eighth bit set +directly or as a meta-prefixed key sequence, whether or not to +wrap to a new screen line when a line being edited is longer than +the screen width, the keymap to which subsequent key bindings should +apply, or even what happens when readline wants to +ring the terminal's bell. All of these variables can be set in +the inputrc file. +.PP +The startup file understands a set of C +preprocessor-like conditional constructs which allow variables or +key bindings to be assigned based on the application using readline, +the terminal currently being used, or the editing mode. Users can +add program-specific bindings to make their lives easier: I have +bindings that let me edit the value of +.B $PATH +and double-quote the current or previous word: +.SE +# Macros that are convenient for shell interaction +$if Bash +# edit the path +"\eC-xp": "PATH=${PATH}\ee\eC-e\eC-a\eef\eC-f" +# prepare to type a quoted word -- insert open and close double +# quotes and move to just after the open quote +"\eC-x\e"": "\e"\e"\eC-b" +# Quote the current or previous word +"\eC-xq": "\eeb\e"\eef\e"" +$endif +.EE +.LP +There is a readline +command to re-read the file, so users can edit the file, change +some bindings, and begin to use them almost immediately. +.PP +Bash implements the +.B bind +builtin for more dyamic control of readline than the startup file +permits. +.B Bind +is used in several ways. In +.I list +mode, it can display the current key bindings, list all the +readline editing directives available for binding, list which keys +invoke a given directive, or output the current set of key +bindings in a format that can be incorporated directly into an inputrc +file. In +.I batch +mode, it reads a series of key bindings directly from a file and +passes them to readline. In its most common usage, +.B bind +takes a single string and passes it directly to readline, which +interprets the line as if it had just been read from the inputrc file. +Both key bindings and variable assignments may appear in the +string given to +.B bind . +.PP +The readline library also provides an interface for \fIword completion\fP. +When the +.I completion +character (usually TAB) is typed, readline looks at the word currently +being entered and computes the set of filenames of which the current +word is a valid prefix. +If there is only one possible completion, the +rest of the characters are inserted directly, otherwise the +common prefix of the set of filenames is added to the current word. +A second TAB character entered immediately after a non-unique +completion causes readline to list the possible completions; there is +an option to have the list displayed immediately. +Readline provides hooks so that applications can provide specific types +of completion before the default filename completion is attempted. +This is quite flexible, though it is not completely user-programmable. +Bash, for example, can complete filenames, command names (including aliases, +builtins, shell reserved words, shell functions, and executables found +in the file system), shell variables, usernames, and hostnames. It +uses a set of heuristics that, while not perfect, is generally quite +good at determining what type of completion to attempt. +.NH 2 +History +.PP +Access to the list of commands previously entered (the \fIcommand history\fP) +is provided jointly by Bash and the readline library. Bash provides +variables (\fB$HISTFILE\fP, \fB$HISTSIZE\fP, and \fB$HISTCONTROL\fP) +and the +.B history +and +.B fc +builtins to manipulate the history list. +The value of +.B $HISTFILE +specifes the file where Bash writes the command history on exit and +reads it on startup. +.B $HISTSIZE +is used to limit the number of commands saved in the history. +.B $HISTCONTROL +provides a crude form of control over which commands are saved on +the history list: a value of +.I ignorespace +means to not save commands which begin with a space; a value of +.I ignoredups +means to not save commands identical to the last command saved. +\fB$HISTCONTROL\fP was named \fB$history_control\fP in earlier +versions of Bash; the old name is still accepted for backwards +compatibility. The +.B history +command can read or write files containing the history list +and display the current list contents. The +.B fc +builtin, adopted from POSIX.2 and the Korn Shell, allows display +and re-execution, with optional editing, +of commands from the history list. The readline +library offers a set of commands to search the history list for +a portion of the current input line or a string typed by the user. +Finally, the +.I history +library, generally incorporated directly into the readline library, +implements a facility for history recall, expansion, and re-execution +of previous commands very similar to csh +(\*Qbang history\*U, so called because the exclamation point +introduces a history substitution): +.SE +$ echo a b c d e +a b c d e +$ !! f g h i +echo a b c d e f g h i +a b c d e f g h i +$ !-2 +echo a b c d e +a b c d e +$ echo !-2:1-4 +echo a b c d +a b c d +.EE +.LP +The command history is only +saved when the shell is interactive, so it is not available for use +by shell scripts. +.NH 2 +New Shell Variables +.PP +There are a number of convenience variables that Bash interprets +to make life easier. These include +.B FIGNORE , +which is a set of filename suffixes identifying files to exclude when +completing filenames; +.B HOSTTYPE , +which is automatically set to a string describing the type of +hardware on which Bash is currently executing; +.B command_oriented_history , +which directs Bash to save all lines of a multiple-line +command such as a \fIwhile\fP or \fIfor\fP loop in a single +history entry, allowing easy re-editing; and +.B IGNOREEOF , +whose value indicates the number of consecutive EOF characters that +an interactive shell will read before exiting \- an easy way to keep +yourself from being logged out accidentally. The +.B auto_resume +variable alters the way the shell treats simple command names: +if job control is active, and this variable is set, single-word +simple commands without redirections cause the shell to first +look for and restart a suspended job with that name before +starting a new process. +.NH 2 +Brace Expansion +.PP +Since sh offers no convenient way to generate arbitrary strings that +share a common prefix or suffix (filename expansion requires that +the filenames exist), Bash implements \fIbrace expansion\fP, a +capability picked up from csh. +Brace expansion is similar to filename expansion, but the strings +generated need not correspond to existing files. A brace expression +consists of an optional +.I preamble , +followed by a pair of braces enclosing a series of comma-separated +strings, and an optional +.I postamble . +The preamble is prepended to each string within the braces, and the +postamble is then appended to each resulting string: +.SE +$ echo a{d,c,b}e +ade ace abe +.EE +.LP +As this example demonstrates, the results of brace expansion are not +sorted, as they are by filename expansion. +.NH 2 +Process Substitution +.PP +On systems that can support it, Bash provides a facility known as +\fIprocess substitution\fP. Process substitution is similar to command +substitution in that its specification includes a command to execute, +but the shell does not collect the command's output and insert it into +the command line. Rather, Bash opens a pipe to the command, which +is run in the background. The shell uses named pipes (FIFOs) or the +.I /dev/fd +method of naming open files to expand the process +substitution to a filename which connects to the pipe when opened. +This filename becomes the result of the expansion. Process substitution +can be used to compare the outputs of two different versions of an +application as part of a regression test: +.SE +$ cmp <(old_prog) <(new_prog) +.EE +.NH 2 +Prompt Customization +.PP +One of the more popular interactive features that Bash provides is +the ability to customize the prompt. Both +.B $PS1 +and +.B $PS2, +the primary and secondary prompts, are expanded before being +displayed. Parameter and variable expansion is performed when +the prompt string is expanded, so any shell variable can be +put into the prompt (e.g., +.B $SHLVL , +which indicates how deeply the current shell is nested). +Bash specially interprets characters in the prompt string +preceded by a backslash. Some of these backslash escapes are +replaced with +the current time, the date, the current working directory, +the username, and the command number or history number of the command +being entered. There is even a backslash escape to cause the shell +to change its prompt when running as root after an \fIsu\fP. +Before printing each primary prompt, Bash expands the variable +.B $PROMPT_COMMAND +and, if it has a value, executes the expanded value as a command, +allowing additional prompt customization. For example, this assignment +causes the current user, the current host, the time, the last +component of the current working directory, the level of shell +nesting, and the history number of the current command to be embedded +into the primary prompt: +.SE +$ PS1='\eu@\eh [\et] \eW($SHLVL:\e!)\e$ ' +chet@odin [21:03:44] documentation(2:636)$ cd .. +chet@odin [21:03:54] src(2:637)$ +.EE +.LP +The string being assigned is surrounded by single quotes so that if +it is exported, the value of +.B $SHLVL +will be updated by a child shell: +.SE +chet@odin [21:17:35] src(2:638)$ export PS1 +chet@odin [21:17:40] src(2:639)$ bash +chet@odin [21:17:46] src(3:696)$ +.EE +.LP +The \fP\e$\fP escape is displayed +as \*Q\fB$\fP\*U when running as a normal user, but as \*Q\fB#\fP\*U when +running as root. +.NH 2 +File System Views +.PP +Since Berkeley introduced symbolic links in 4.2 BSD, one of their most +annoying properties has been the \*Qwarping\*U to a completely +different area of the file system when using +.B cd , +and the resultant non-intuitive behavior of \*Q\fBcd ..\fP\*U. +The \s-1UNIX\s+1 kernel treats symbolic links +.I physically . +When the kernel is translating a pathname +in which one component is a symbolic link, it replaces all or part +of the pathname while processing the link. If the contents of the symbolic +link begin with a slash, the kernel replaces the +pathname entirely; if not, the link contents replace +the current component. In either case, the symbolic link +is visible. If the link value is an absolute pathname, +the user finds himself in a completely different part of the file +system. +.PP +Bash provides a +.I logical +view of the file system. In this default mode, command and filename +completion and builtin commands such as +.B cd +and +.B pushd +which change the current working directory transparently follow +symbolic links as if they were directories. +The +.B $PWD +variable, which holds the shell's idea of the current working directory, +depends on the path used to reach the directory rather than its +physical location in the local file system hierarchy. For example: +.SE +$ cd /usr/local/bin +$ echo $PWD +/usr/local/bin +$ pwd +/usr/local/bin +$ /bin/pwd +/net/share/sun4/local/bin +$ cd .. +$ pwd +/usr/local +$ /bin/pwd +/net/share/sun4/local +$ cd .. +$ pwd +/usr +$ /bin/pwd +/usr +.EE +.LP +One problem with this, of +course, arises when programs that do not understand the shell's logical +notion of the file system interpret \*Q..\*U differently. This generally +happens when Bash completes filenames containing \*Q..\*U according to a +logical hierarchy which does not correspond to their physical location. +For users who find this troublesome, a corresponding +.I physical +view of the file system is available: +.SE +$ cd /usr/local/bin +$ pwd +/usr/local/bin +$ set -o physical +$ pwd +/net/share/sun4/local/bin +.EE +.NH 2 +Internationalization +.PP +One of the most significant improvements in version 1.13 of Bash was the +change to \*Qeight-bit cleanliness\*U. Previous versions used the +eighth bit of characters to mark whether or not they were +quoted when performing word expansions. While this did not affect +the majority of users, most of whom used only seven-bit ASCII characters, +some found it confining. Beginning with version 1.13, Bash +implemented a different quoting mechanism that did not alter the +eighth bit of characters. This allowed Bash +to manipulate files with \*Qodd\*U characters in their names, but +did nothing to help users enter those names, so +version 1.13 introduced changes to readline that +made it eight-bit clean as well. Options exist that force readline to +attach no special significance to characters with the eighth bit set +(the default behavior is to convert these characters to meta-prefixed +key sequences) and to output these characters without conversion to +meta-prefixed sequences. These changes, along with the expansion of +keymaps to a full eight bits, enable readline to work with most of the +ISO-8859 family of character sets, used by many European countries. +.NH 2 +POSIX Mode +.PP +Although Bash is intended to be POSIX.2 conformant, there are areas in +which the default behavior is not compatible with the standard. For +users who wish to operate in a strict POSIX.2 environment, Bash +implements a \fIPOSIX mode\fP. When this mode is active, Bash modifies +its default operation where it differs from POSIX.2 to match the +standard. POSIX mode is entered when Bash is started with the +.B -posix +option. This feature is also available as an option to the +\fBset\fP builtin, \fBset -o posix\fP. +For compatibility with other GNU software that attempts to be POSIX.2 +compliant, Bash also enters POSIX mode if the variable +.B $POSIXLY_CORRECT +is set when Bash is started or assigned a value during execution. +.B $POSIX_PEDANTIC +is accepted as well, to be compatible with some older GNU utilities. +When Bash is started in POSIX mode, for example, it sources the +file named by the value of +.B $ENV +rather than the \*Qnormal\*U startup files, and does not allow +reserved words to be aliased. +.NH 1 +New Features and Future Plans +.PP +There are several features introduced in the current +version of Bash, version 1.14, and a number under consideration +for future releases. This section will briefly detail the new +features in version 1.14 and describe several features +that may appear in later versions. +.NH 2 +New Features in Bash-1.14 +.PP +The new features available in Bash-1.14 answer several of +the most common requests for enhancements. Most notably, there +is a mechanism +for including non-visible character sequences in prompts, such as +those which cause a terminal to print characters in different +colors or in standout mode. There was nothing preventing the use +of these sequences in earlier +versions, but the readline redisplay algorithm assumed each +character occupied physical screen space and would wrap lines +prematurely. +.PP +Readline has a few new +variables, several new bindable commands, and some additional +emacs mode default key bindings. A new history search +mode has been implemented: in this mode, readline searches the +history for lines beginning with the characters between the +beginning of the current line and the cursor. The existing readline +incremental search commands no longer match identical lines more +than once. +Filename completion now expands variables in directory names. +The history expansion facilities are now nearly +completely csh-compatible: missing modifiers have been added and +history substitution has been extended. +.PP +Several of the features described earlier, such as +.B "set -o posix" +and +.B $POSIX_PEDANTIC , +are new in version 1.14. +There is a new shell variable, +.B OSTYPE , +to which Bash assigns a value that identifies the +version of \s-1UNIX\s+1 it's +running on (great for putting architecture-specific binary directories +into the \fB$PATH\fP). +Two variables have been renamed: +.B $HISTCONTROL +replaces +.B $history_control , +and +.B $HOSTFILE +replaces +.B $hostname_completion_file . +In both cases, the old names are accepted for backwards +compatibility. The ksh +.I select +construct, which allows the generation of simple menus, +has been implemented. New capabilities have been added +to existing variables: +.B $auto_resume +can now take values of +.I exact +or +.I substring , +and +.B $HISTCONTROL +understands the value +.I ignoreboth , +which combines the two previously acceptable values. The +.B dirs +builtin has acquired options to print out specific members of the +directory stack. The +.B $nolinks +variable, which forces a physical view of the file system, +has been superseded by the +.B \-P +option to the +.B set +builtin (equivalent to \fBset -o physical\fP); the variable is retained +for backwards compatibility. The version string contained in +.B $BASH_VERSION +now includes an indication of the patch level as well as the +\*Qbuild version\*U. +Some little-used features have +been removed: the +.B bye +synonym for +.B exit +and the +.B $NO_PROMPT_VARS +variable are gone. There is now an organized test suite that can be +run as a regression test when building a new version of Bash. +.PP +The documentation has been thoroughly overhauled: +there is a new manual page on the readline library and the \fIinfo\fP +file has been updated to reflect the current version. +As always, as many bugs as possible have been fixed, although some +surely remain. +.NH 2 +Other Features +.PP +There are a few features that I hope to include in later Bash releases. +Some are based on work already done in other shells. +.PP +In addition to simple variables, a future release of Bash will include +one-dimensional arrays, using the ksh +implementation of arrays as a model. Additions to the ksh syntax, +such as \fIvarname\fP=( ... ) to assign a list of words directly to +an array and a mechanism to allow +the +.B read +builtin to read a list of values directly into an array, would be +desirable. Given those extensions, the ksh +.B "set \-A" +syntax may not be worth supporting (the +.B \-A +option assigns a list of values to an array, but is a rather +peculiar special case). +.PP +Some shells include a means of \fIprogrammable\fP word +completion, where the user specifies on a per-command basis how the +arguments of the command are to be treated when completion is attempted: +as filenames, hostnames, executable files, and so on. The other +aspects of the current Bash implementation could remain as-is; the +existing heuristics would still be valid. Only when completing the +arguments to a simple command would the programmable completion be +in effect. +.PP +It would also be nice to give the user finer-grained +control over which commands are saved onto the history list. One +proposal is for a variable, tentatively named +.B HISTIGNORE , +which would contain a colon-separated list of commands. Lines beginning +with these commands, after the restrictions of +.B $HISTCONTROL +have been applied, would not be placed onto the history list. The +shell pattern-matching capabilities could also be available when +specifying the contents of +.B $HISTIGNORE . +.PP +One thing that newer shells such as +.B wksh +(also known as +.B dtksh ) +provide is a command to dynamically load code +implementing additional builtin commands into a running shell. +This new builtin would take an object file or shared library +implementing the \*Qbody\*U of the +builtin (\fIxxx_builtin()\fP for those familiar with Bash internals) +and a structure containing the name of the new command, the function +to call when the new builtin is invoked (presumably defined in the +shared object specified as an argument), and the documentation to be +printed by the +.B help +command (possibly present in the shared object as well). It would +manage the details of extending the internal table of builtins. +.PP +A few other builtins would also be desirable: two are the POSIX.2 +.B getconf +command, which prints the values of system configuration variables +defined by POSIX.2, and a +.B disown +builtin, which causes a shell running +with job control active to \*Qforget about\*U one or more +background jobs in its internal jobs table. Using +.B getconf , +for example, a user could retrieve a value for +.B $PATH +guaranteed to find all of the POSIX standard utilities, or +find out how long filenames may be in the file system containing +a specified directory. +.PP +There are no implementation timetables for any of these features, nor +are there concrete plans to include them. If anyone has comments on +these proposals, feel free to send me electronic mail. +.NH 1 +Reflections and Lessons Learned +.PP +The lesson that has been repeated most often during Bash +development is that there are dark corners in the Bourne shell, +and people use all of them. In the original description of the +Bourne shell, quoting and the shell grammar are both poorly +specified and incomplete; subsequent descriptions have not helped +much. The grammar presented in Bourne's paper describing +the shell distributed with the Seventh Edition of \s-1UNIX\s+1\(dg +is so far off that it does not allow the command \f(CWwho|wc\fP. +In fact, as Tom Duff states: +.QP +Nobody really knows what the +Bourne shell's grammar is. Even examination of the source code is +little help.\(dd +.FS +\(dgS. R. Bourne, \*QUNIX Time-Sharing System: The UNIX Shell\*U, +\fIBell System Technical Journal\fP, 57(6), July-August, 1978, pp. 1971-1990. +.FE +.FS +\(ddTom Duff, \*QRc \- A Shell for Plan 9 and \s-1UNIX\s+1 systems\*U, +\fIProc. of the Summer 1990 EUUG Conference\fP, London, July, 1990, +pp. 21-33. +.FE +.LP +The POSIX.2 standard includes a \fIyacc\fP grammar that comes close +to capturing the Bourne shell's behavior, but it disallows some +constructs which sh accepts without complaint \- and there are +scripts out there that use them. It took a few versions and +several bug reports before Bash implemented sh-compatible quoting, +and there are still some \*Qlegal\*U sh constructs which Bash flags as +syntax errors. Complete sh compatibility is a tough nut. +.PP +The shell is bigger and slower than I would like, though the current +version is substantially faster than previously. The readline library +could stand a substantial rewrite. A hand-written parser to replace +the current \fIyacc\fP-generated one would probably result in a speedup, +and would solve one glaring problem: the shell could parse +commands in \*Q$(...)\*U constructs +as they are entered, rather than reporting errors when the construct +is expanded. +.PP +As always, there is some chaff to go with the wheat. +Areas of duplicated functionality need to be cleaned +up. There are several cases where Bash treats a variable specially to +enable functionality available another way (\fB$notify\fP vs. +\fBset -o notify\fP and \fB$nolinks\fP vs. \fBset -o physical\fP, for +instance); the special treatment of the variable name should probably +be removed. A few more things could stand removal; the +.B $allow_null_glob_expansion +and +.B $glob_dot_filenames +variables are of particularly questionable value. +The \fB$[...]\fP arithmetic evaluation syntax is redundant now that +the POSIX-mandated \fB$((...))\fP construct has been implemented, +and could be deleted. +It would be nice if the text output by the +.B help +builtin were external to the shell rather than compiled into it. +The behavior enabled by +.B $command_oriented_history , +which causes the shell to attempt to save all lines of a multi-line +command in a single history entry, should be made the default and +the variable removed. +.NH 1 +Availability +.PP +As with all other +GNU software, Bash is available for anonymous FTP from +.I prep.ai.mit.edu:/pub/gnu +and from other GNU software mirror sites. The current version is in +.I bash-1.14.1.tar.gz +in that directory. Use +.I archie +to find the nearest archive site. The +latest version is always available for FTP from +.I bash.CWRU.Edu:/pub/dist. +Bash documentation is available for FTP from +.I bash.CWRU.Edu:/pub/bash. +.PP +The Free Software Foundation sells tapes and CD-ROMs +containing Bash; send electronic mail to +\f(CRgnu@prep.ai.mit.edu\fP or call \f(CR+1-617-876-3296\fP +for more information. +.PP +Bash is also distributed with several versions of \s-1UNIX\s+1-compatible +systems. It is included as /bin/sh and /bin/bash on several Linux +distributions (more about the difference in a moment), and as contributed +software in BSDI's BSD/386* and FreeBSD. +.FS +*BSD/386 is a trademark of Berkeley Software Design, Inc. +.FE +.PP +The Linux distribution deserves special mention. There are two +configurations included in the standard Bash distribution: a +\*Qnormal\*U configuration, in which all of the standard features +are included, and a \*Qminimal\*U configuration, which omits job +control, aliases, history and command line editing, the directory +stack and +.B pushd/popd/dirs, +process substitution, prompt string special character decoding, and the +.I select +construct. This minimal version is designed to be a drop-in replacement +for the traditional \s-1UNIX\s+1 /bin/sh, and is included as the Linux +/bin/sh in several packagings. +.NH 1 +Conclusion +.PP +Bash is a worthy successor to sh. +It is sufficiently portable +to run on nearly every version of \s-1UNIX\s+1 from +4.3 BSD to SVR4.2, and several \s-1UNIX\s+1 workalikes. +It is robust enough to replace sh on most of those systems, +and provides more functionality. It has several thousand regular users, +and their feedback has helped to make it as good as it is today \- a +testament to the benefits of free software. diff --git a/doc/bash.1 b/doc/bash.1 new file mode 100644 index 00000000..68ace07e --- /dev/null +++ b/doc/bash.1 @@ -0,0 +1,6785 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Information Network Services +.\" Case Western Reserve University +.\" chet@ins.CWRU.Edu +.\" +.\" Last Change: Mon Nov 25 15:36:20 EST 1996 +.\" +.\" bash_builtins, strip all but Built-Ins section +.if \n(zZ=1 .ig zZ +.TH BASH 1 "1996 Nov 25" GNU +.\" +.\" There's some problem with having a `@' +.\" in a tagged paragraph with the BSD man macros. +.\" It has to do with `@' appearing in the }1 macro. +.\" This is a problem on 4.3 BSD and Ultrix, but Sun +.\" appears to have fixed it. +.\" If you're seeing the characters +.\" `@u-3p' appearing before the lines reading +.\" `possible-hostname-completions +.\" and `complete-hostname' down in READLINE, +.\" then uncomment this redefinition. +.\" +.de }1 +.ds ]X \&\\*(]B\\ +.nr )E 0 +.if !"\\$1"" .nr )I \\$1n +.}f +.ll \\n(LLu +.in \\n()Ru+\\n(INu+\\n()Iu +.ti \\n(INu +.ie !\\n()Iu+\\n()Ru-\w\\*(]Xu-3p \{\\*(]X +.br\} +.el \\*(]X\h|\\n()Iu+\\n()Ru\c +.}f +.. +.\" +.\" File Name macro. This used to be `.PN', for Path Name, +.\" but Sun doesn't seem to like that very much. +.\" +.de FN +\fI\|\\$1\|\fP +.. +.SH NAME +bash \- GNU Bourne-Again SHell +.SH SYNOPSIS +.B bash +[options] +[file] +.SH COPYRIGHT +.if n Bash is Copyright (C) 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc. +.if t Bash is Copyright \(co 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc. +.SH DESCRIPTION +.B Bash +is an \fBsh\fR-compatible command language interpreter that +executes commands read from the standard input or from a file. +.B Bash +also incorporates useful features from the \fIKorn\fP and \fIC\fP +shells (\fBksh\fP and \fBcsh\fP). +.PP +.B Bash +is ultimately intended to be a conformant implementation of the IEEE +POSIX Shell and Tools specification (IEEE Working Group 1003\.2). +.SH OPTIONS +In addition to the single-character shell options documented in the +description of the \fBset\fR builtin command, \fBbash\fR +interprets the following flags when it is invoked: +.PP +.PD 0 +.TP 10 +.BI \-c "\| string\^" +If the +.B \-c +flag is present, then commands are read from +.IR string . +If there are arguments after the +.IR string , +they are assigned to the positional parameters, starting with +.BR $0 . +.TP +.B \-r +If the +.B \-r +flag is present, the shell becomes +.I restricted +(see +.SM +.B "RESTRICTED SHELL" +below). +.TP +.B \-i +If the +.B \-i +flag is present, the shell is +.IR interactive . +.TP +.B \-s +If the +.B \-s +flag is present, or if no arguments remain after option +processing, then commands are read from the standard input. +This option allows the positional parameters to be set +when invoking an interactive shell. +.TP +.B \-D +A list of all double-quoted strings preceded by \fB$\fP +is printed on the standard ouput. +These are the strings that +are subject to language translation when the current locale +is not C or POSIX. +This implies the \fB\-n\fP option; no commands will be executed. +.TP +.B \-\- +A +.B \-\- +signals the end of options and disables further option processing. +Any arguments after the +.B \-\- +are treated as filenames and arguments. An argument of +.B \- +is equivalent to \fB\-\-\fP. +.PD +.PP +.B Bash +also interprets a number of multi-character options. +These options must appear on the command line before the +single-character options in order for them to be recognized. +.PP +.PD 0 +.TP +.B \-\-dump\-strings +Equivalent to \fB\-D\fP. +.TP +.B \-\-help +Display a usage message on standard output and exit successfully. +.TP +.B \-\-login +Make +.B bash +act as if it had been invoked as a login shell (see +.SM +.B INVOCATION +below). +.TP +.B \-\-noediting +Do not use the GNU +.B readline +library to read command lines if interactive. +.TP +.B \-\-noprofile +Do not read either the system-wide startup file +.FN /etc/profile +or any of the personal initialization files +.IR ~/.bash_profile , +.IR ~/.bash_login , +or +.IR ~/.profile . +By default, +.B bash +reads these files when it is invoked as a login shell (see +.SM +.B INVOCATION +below). +.TP +.B \-\-norc +Do not read and execute the personal initialization file +.I ~/.bashrc +if the shell is interactive. +This option is on by default if the shell is invoked as +.BR sh . +.TP +.B \-\-posix +Change the behavior of \fBbash\fP where the default operation differs +from the POSIX 1003.2 standard to match the standard. +.TP +\fB\-\-rcfile\fP \fIfile\fP +Execute commands from +.I file +instead of the standard personal initialization file +.I ~/.bashrc +if the shell is interactive (see +.SM +.B INVOCATION +below). +.TP +.B \-\-restricted +The shell becomes restricted (see +.SM +.B "RESTRICTED SHELL" +below). +.TP +.B \-\-verbose +Equivalent to \fB\-v\fP. +.TP +.B \-\-version +Show version information for this instance of +.B bash +on the standard output and exit successfully. +.PD +.SH ARGUMENTS +If arguments remain after option processing, and neither the +.B \-c +nor the +.B \-s +option has been supplied, the first argument is assumed to +be the name of a file containing shell commands. +If +.B bash +is invoked in this fashion, +.B $0 +is set to the name of the file, and the positional parameters +are set to the remaining arguments. +.B Bash +reads and executes commands from this file, then exits. +\fBBash\fP's exit status is the exit status of the last command +executed in the script. +If no commands are executed, the exit status is 0. +.SH INVOCATION +A \fIlogin shell\fP is one whose first character of argument zero is a +.BR \- , +or one started with the +.B \-\-login +option. +.PP +An \fIinteractive\fP shell is one whose standard input and output are +both connected to terminals (as determined by +.IR isatty (3)), +or one started with the +.B \-i +option. +.SM +.B PS1 +is set and +.B $\- +includes +.B i +if +.B bash +is interactive, +allowing a shell script or a startup file to test this state. +.PP +The following paragraphs describe how +.B bash +executes its startup files. +If any of the files exist but cannot be read, +.B bash +reports an error. +Tildes are expanded in file names as described below under +.B "Tilde Expansion" +in the +.SM +.B EXPANSION +section. +.PP +When +.B bash +is invoked as a login shell, it first reads and executes commands +from the file \fI/etc/profile\fP, if that file exists. +After reading that file, it looks for \fI~/.bash_profile\fP, +\fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads +and executes commands from the first one that exists and is readable. +The +.B \-\-noprofile +option may be used when the shell is started to inhibit this behavior. +.PP +When a login shell exits, +.B bash +reads and executes commands from the file \fI~/.bash_logout\fP, if it +exists. +.PP +When an interactive shell that is not a login shell is started, +.B bash +reads and executes commands from \fI~/.bashrc\fP, if that file exists. +This may be inhibited by using the +.B \-\-norc +option. +The \fB\-\-rcfile\fP \fIfile\fP option will force +.B bash +to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP. +.PP +When +.B bash +is started non-interactively, to run a shell script, for example, it +looks for the variable +.SM +.B BASH_ENV +in the environment, expands its value if it appears there, and uses the +expanded value as the name of a file to read and execute. +.B Bash +behaves as if the following command were executed: +.sp .5 +.RS +\f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP +.RE +.sp .5 +but the value of the +.SM +.B PATH +variable is not used to search for the file name. +.PP +If +.B bash +is invoked with the name +.BR sh , +it tries to mimic the startup behavior of historical versions of +.B sh +as closely as possible, +while conforming to the POSIX standard as well. +When invoked as a login shell, it first attempts to read and execute +commands from +.I /etc/profile +and +.IR ~/.profile , +in that order. +The +.B \-\-noprofile +option may be used to inhibit this behavior. +When invoked as an interactive shell with the name +.BR sh , +.B bash +looks for the variable +.SM +.BR ENV , +expands its value if it is defined, and uses the +expanded value as the name of a file to read and execute. +Since a shell invoked as +.B sh +does not attempt to read and execute commands from any other startup +files, the +.B \-\-rcfile +option has no effect. +A non-interactive shell invoked with the name +.B sh +does not attempt to read any startup files. +When invoked as +.BR sh , +.B bash +enters +.I posix +mode after the startup files are read. +.PP +When +.B bash +is started in +.I posix +mode, as with the +.B \-\-posix +command line option, it follows the POSIX standard for startup files. +In this mode, the +.SM +.B ENV +variable is expanded and commands are read and executed from the file +whose name is the expanded value. +No other startup files are read. +This is done by interactive shells only. +.PP +.B Bash +attempts to determine when it is being run by the remote shell +daemon, usually \fIrshd\fP. +If +.B bash +determines it is being run by \fIrshd\fP, it reads and executes +commands from \fI~/.bashrc\fP, if that file exists and is readable. +It will not do this if invoked as \fBsh\fP. +The +.B \-\-norc +option may be used to inhibit this behavior, and the +.B \-\-rcfile +option may be used to force another file to be read, but +\fIrshd\fP does not generally invoke the shell with those options +or allow them to be specified. +.SH DEFINITIONS +.PP +The following definitions are used throughout the rest of this +document. +.PD 0 +.TP +.B blank +A space or tab. +.TP +.B word +A sequence of characters considered as a single unit by the shell. +Also known as a +.BR token . +.TP +.B name +A +.I word +consisting only of alphanumeric characters and underscores, and +beginning with an alphabetic character or an underscore. Also +referred to as an +.BR identifier . +.TP +.B metacharacter +A character that, when unquoted, separates words. One of the following: +.br +.RS +.PP +.if t \fB| & ; ( ) < > space tab\fP +.if n \fB| & ; ( ) < > space tab\fP +.RE +.PP +.TP +.B control operator +A \fItoken\fP that performs a control function. It is one of the following +symbols: +.RS +.PP +.if t \fB\(bv\(bv & && ; ;; ( ) | <newline>\fP +.if n \fB|| & && ; ;; ( ) | <newline>\fP +.RE +.PD +.SH "RESERVED WORDS" +\fIReserved words\fP are words that have a special meaning to the shell. +The following words are recognized as reserved when unquoted and either +the first word of a simple command (see +.SM +.B SHELL GRAMMAR +below) or the third word of a +.B case +or +.B for +command: +.if t .RS +.PP +.B +.if n ! case do done elif else esac fi for function if in select then until while { } time +.if t ! case do done elif else esac fi for function if in select then until while { } time +.if t .RE +.RE +.SH "SHELL GRAMMAR" +.SS Simple Commands +.PP +A \fIsimple command\fP is a sequence of optional variable assignments +followed by \fBblank\fP-separated words and redirections, and +terminated by a \fIcontrol operator\fP. The first word +specifies the command to be executed. The remaining words are +passed as arguments to the invoked command. +.PP +The return value of a \fIsimple command\fP is its exit status, or +128+\fIn\^\fP if the command is terminated by signal +.IR n . +.SS Pipelines +.PP +A \fIpipeline\fP is a sequence of one or more commands separated by +the character +.BR | . +The format for a pipeline is: +.RS +.PP +[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand\fP [ \fB|\fP \fIcommand2\fP ... ] +.RE +.PP +The standard output of +.I command +is connected to the standard input of +.IR command2 . +This connection is performed before any redirections specified by the +command (see +.SM +.B REDIRECTION +below). +.PP +If the reserved word +.B ! +precedes a pipeline, the exit status of that +pipeline is the logical NOT of the exit status of the last command. +Otherwise, the status of the pipeline is the exit status of the last +command. +The shell waits for all commands in the pipeline to +terminate before returning a value. +.PP +If the +.B time +reserved word precedes a pipeline, the elapsed as well as user and +system time consumed by its execution are reported when the pipeline +terminates. +The \fB\-p\fP option changes the output format to that specified by POSIX. +The +.SM +.B TIMEFORMAT +variable may be set to a format string that specifies how the timing +information should be displayed; see the description of +.SM +.B TIMEFORMAT +under +.B "Shell Variables" +below. +.PP +Each command in a pipeline is executed as a separate process (i.e., in a +subshell). +.SS Lists +.PP +A \fIlist\fP is a sequence of one or more pipelines separated by one +of the operators +.BR ; , +.BR & , +.BR && , +or +.BR \(bv\(bv , +and optionally terminated by one of +.BR ; , +.BR & , +or +.BR <newline> . +.PP +Of these list operators, +.B && +and +.B \(bv\(bv +have equal precedence, followed by +.B ; +and +.BR &, +which have equal precedence. +.PP +If a command is terminated by the control operator +.BR & , +the shell executes the command in the \fIbackground\fP +in a subshell. The shell does not wait for the command to +finish, and the return status is 0. Commands separated by a +.B ; +are executed sequentially; the shell waits for each +command to terminate in turn. The return status is the +exit status of the last command executed. +.PP +The control operators +.B && +and +.B \(bv\(bv +denote AND lists and OR lists, respectively. +An AND list has the form +.RS +.PP +\fIcommand\fP \fB&&\fP \fIcommand2\fP +.RE +.PP +.I command2 +is executed if, and only if, +.I command +returns an exit status of zero. +.PP +An OR list has the form +.RS +.PP +\fIcommand\fP \fB\(bv\(bv\fP \fIcommand2\fP +.PP +.RE +.PP +.I command2 +is executed if and only if +.I command +returns a non-zero exit status. The return status of +AND and OR lists is the exit status of the last command +executed in the list. +.SS Compound Commands +.PP +A \fIcompound command\fP is one of the following: +.TP +(\fIlist\fP) +\fIlist\fP is executed in a subshell. Variable assignments and builtin +commands that affect the shell's environment do not remain in effect +after the command completes. The return status is the exit status of +\fIlist\fP. +.TP +{ \fIlist\fP; } +\fIlist\fP is simply executed in the current shell environment. +\fIlist\fP must be terminated with a newline or semicolon. +This is known as a \fIgroup command\fP. +The return status is the exit status of +\fIlist\fP. +.TP +((\fIexpression\fP)) +The \fIexpression\fP is evaluated according to the rules described +below under +.SM +.BR "ARITHMETIC EVALUATION" . +If the value of the expression is non-zero, the return status is 0; +otherwise the return status is 1. This is exactly equivalent to +\fBlet "\fIexpression\fP"\fR. +.TP +\fBfor\fP \fIname\fP [ \fBin\fP \fIword\fP; ] \fBdo\fP \fIlist\fP ; \fBdone\fP +The list of words following \fBin\fP is expanded, generating a list +of items. The variable \fIname\fP is set to each element of this list +in turn, and \fIlist\fP is executed each time. If the \fBin\fP +\fIword\fP is omitted, the \fBfor\fP command executes \fIlist\fP +once for each positional parameter that is set (see +.SM +.B PARAMETERS +below). +.TP +\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP; ] \fBdo\fP \fIlist\fP ; \fBdone\fP +The list of words following \fBin\fP is expanded, generating a list +of items. The set of expanded words is printed on the standard +error, each preceded by a number. If the \fBin\fP +\fIword\fP is omitted, the positional parameters are printed (see +.SM +.B PARAMETERS +below). The +.B PS3 +prompt is then displayed and a line read from the standard input. +If the line consists of a number corresponding to one of +the displayed words, then the value of +.I name +is set to that word. If the line is empty, the words and prompt +are displayed again. If EOF is read, the command completes. Any +other value read causes +.I name +to be set to null. The line read is saved in the variable +.BR REPLY . +The +.I list +is executed after each selection until a +.B break +or +.B return +command is executed. +The exit status of +.B select +is the exit status of the last command executed in +.IR list , +or zero if no commands were executed. +.TP +\fBcase\fP \fIword\fP \fBin\fP [ \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \ +... ) \fIlist\fP ;; ] ... \fBesac\fP +A \fBcase\fP command first expands \fIword\fP, and tries to match +it against each \fIpattern\fP in turn, using the same matching rules +as for pathname expansion (see +.B Pathname Expansion +below). When a match is found, the +corresponding \fIlist\fP is executed. After the first match, no +subsequent matches are attempted. The exit status is zero if no +pattern matches. Otherwise, it is the exit status of the +last command executed in \fIlist\fP. +.TP +\fBif\fP \fIlist\fP; \fBthen\fP \fIlist;\fP \ +[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \ +[ \fBelse\fP \fIlist\fP; ] \fBfi\fP +The +.B if +.I list +is executed. If its exit status is zero, the +\fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP +\fIlist\fP is executed in turn, and if its exit status is zero, +the corresponding \fBthen\fP \fIlist\fP is executed and the +command completes. Otherwise, the \fBelse\fP \fIlist\fP is +executed, if present. The exit status is the exit status of the +last command executed, or zero if no condition tested true. +.TP +.PD 0 +\fBwhile\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP +.TP +\fBuntil\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP +.PD +The \fBwhile\fP command continuously executes the \fBdo\fP +\fIlist\fP as long as the last command in \fIlist\fP returns +an exit status of zero. The \fBuntil\fP command is identical +to the \fBwhile\fP command, except that the test is negated; +the +.B do +.I list +is executed as long as the last command in +.I list +returns a non-zero exit status. +The exit status of the \fBwhile\fP and \fBuntil\fP commands +is the exit status +of the last \fBdo\fP \fIlist\fP command executed, or zero if +none was executed. +.TP +[ \fBfunction\fP ] \fIname\fP () { \fIlist\fP; } +This defines a function named \fIname\fP. The \fIbody\fP of the +function is the +.I list +of commands between { and }. This list +is executed whenever \fIname\fP is specified as the +name of a simple command. The exit status of a function is +the exit status of the last command executed in the body. (See +.SM +.B FUNCTIONS +below.) +.SH COMMENTS +In a non-interactive shell, or an interactive shell in which the +.B interactive_comments +option to the +.B shopt +builtin is enabled (see +.SM +.B "SHELL BUILTIN COMMANDS" +below), a word beginning with +.B # +causes that word and all remaining characters on that line to +be ignored. An interactive shell without the +.B interactive_comments +.B shopt +option enabled does not allow comments. The +.B interactive_comments +option is on by default in interactive shells. +.SH QUOTING +\fIQuoting\fP is used to remove the special meaning of certain +characters or words to the shell. Quoting can be used to +disable special treatment for special characters, to prevent +reserved words from being recognized as such, and to prevent +parameter expansion. +.PP +Each of the \fImetacharacters\fP listed above under +.SM +.B DEFINITIONS +has special meaning to the shell and must be quoted if they are to +represent themselves. There are three quoting mechanisms: the +.IR "escape character" , +single quotes, and double quotes. +.PP +A non-quoted backslash (\fB\e\fP) is the +.IR "escape character" . +It preserves the literal value of the next character that follows, +with the exception of <newline>. If a \fB\e\fP<newline> pair +appears, and the backslash is not quoted, the \fB\e\fP<newline> +is treated as a line continuation (that is, it is effectively ignored). +.PP +Enclosing characters in single quotes preserves the literal value +of each character within the quotes. A single quote may not occur +between single quotes, even when preceded by a backslash. +.PP +Enclosing characters in double quotes preserves the literal value +of all characters within the quotes, with the exception of +.BR $ , +.BR ` , +and +.BR \e . +The characters +.B $ +and +.B ` +retain their special meaning within double quotes. The backslash +retains its special meaning only when followed by one of the following +characters: +.BR $ , +.BR ` , +\^\fB"\fP\^, +.BR \e , +or +.BR <newline> . +A double quote may be quoted within double quotes by preceding it with +a backslash. +.PP +The special parameters +.B * +and +.B @ +have special meaning when in double +quotes (see +.SM +.B PARAMETERS +below). +.PP +Words of the form \fB$\fP'\fIstring\fP' are treated specially. The +word expands to \fIstring\fP, with backslash-escaped characters replaced +as specifed by the ANSI C standard. Backslash escape sequences, if +present, are decoded as follows: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ee +an escape character +.TP +.B \ef +form feed +.TP +.B \en +new line +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\e +backslash +.TP +.B \e\fInnn\fP +the character whose ASCII code is \fInnn\fP (octal) +.PD +.RE +.LP +The translated result is single-quoted, as if the dollar sign had +not been present. +.PP +A double-quoted string preceded by a dollar sign (\fB$\fP) will cause +the string to be translated according to the current locale. +If the current locale is \fBC\fP or \fBPOSIX\fP, the dollar sign +is ignored. +If the string is translated and replaced, the replacement is +double-quoted. +.SH PARAMETERS +A +.I parameter +is an entity that stores values. +It can be a +.IR name , +a number, or one of the special characters listed below under +.BR "Special Parameters" . +For the shell's purposes, a +.I variable +is a parameter denoted by a +.IR name . +.PP +A parameter is set if it has been assigned a value. The null string is +a valid value. Once a variable is set, it may be unset only by using +the +.B unset +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.PP +A +.I variable +may be assigned to by a statement of the form +.RS +.PP +\fIname\fP=[\fIvalue\fP] +.RE +.PP +If +.I value +is not given, the variable is assigned the null string. All +.I values +undergo tilde expansion, parameter and variable expansion, string +expansion, command substitution, arithmetic expansion, and quote +removal (see +.SM +.B EXPANSION +below). If the variable has its +.B \-i +attribute set (see +.B declare +below in +.SM +.BR "SHELL BUILTIN COMMANDS" ) +then +.I value +is subject to arithmetic expansion even if the $((...)) syntax does +not appear (see +.B "Arithmetic Expansion" +below). +Word splitting is not performed, with the exception +of \fB"$@"\fP as explained below under +.BR "Special Parameters" . +Pathname expansion is not performed. +.SS Positional Parameters +.PP +A +.I positional parameter +is a parameter denoted by one or more +digits, other than the single digit 0. Positional parameters are +assigned from the shell's arguments when it is invoked, +and may be reassigned using the +.B set +builtin command. Positional parameters may not be assigned to +with assignment statements. The positional parameters are +temporarily replaced when a shell function is executed (see +.SM +.B FUNCTIONS +below). +.PP +When a positional parameter consisting of more than a single +digit is expanded, it must be enclosed in braces (see +.SM +.B EXPANSION +below). +.SS Special Parameters +.PP +The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. +.PD 0 +.TP +.B * +Expands to the positional parameters, starting from one. When the +expansion occurs within double quotes, it expands to a single word +with the value of each parameter separated by the first character +of the +.SM +.B IFS +special variable. That is, ``\fB$*\fP'' is equivalent +to ``\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP'', where +.I c +is the first character of the value of the +.SM +.B IFS +variable. If +.SM +.B IFS +is null or unset, the parameters are separated by spaces. +.TP +.B @ +Expands to the positional parameters, starting from one. When the +expansion occurs within double quotes, each parameter expands as a +separate word. That is, `` +.BR $@ '' +is equivalent to +``\fB$1\fP'' ``\fB$2\fP'' ... +When there are no positional parameters, ``\fB$@\fP'' and +.B $@ +expand to nothing (i.e., they are removed). +.TP +.B # +Expands to the number of positional parameters in decimal. +.TP +.B ? +Expands to the status of the most recently executed foreground +pipeline. +.TP +.B \- +Expands to the current option flags as specified upon invocation, +by the +.B set +builtin command, or those set by the shell itself +(such as the +.B \-i +flag). +.TP +.B $ +Expands to the process ID of the shell. In a () subshell, it +expands to the process ID of the current shell, not the +subshell. +.TP +.B ! +Expands to the process ID of the most recently executed background +(asynchronous) command. +.TP +.B 0 +Expands to the name of the shell or shell script. This is set at +shell initialization. If +.B bash +is invoked with a file of commands, +.B $0 +is set to the name of that file. If +.B bash +is started with the +.B \-c +option, then +.B $0 +is set to the first argument after the string to be +executed, if one is present. Otherwise, it is set +to the file name used to invoke +.BR bash , +as given by argument zero. +.TP +.B _ +At shell startup, set to the absolute file name of the shell or shell +script being executed as passed in the argument list. +Subsequently, expands to the last argument to the previous command, +after expansion. +Also set to the full file name of each command executed and placed in +the environment exported to that command. +When checking mail, this parameter holds the name of the mail file +currently being checked. +.PD +.SS Shell Variables +.PP +The following variables are set by the shell: +.PP +.PD 0 +.TP +.B PPID +The process ID of the shell's parent. +.TP +.B PWD +The current working directory as set by the +.B cd +command. +.TP +.B OLDPWD +The previous working directory as set by the +.B cd +command. +.TP +.B REPLY +Set to the line of input read by the +.B read +builtin command when no arguments are supplied. +.TP +.B UID +Expands to the user ID of the current user, initialized at shell startup. +.TP +.B EUID +Expands to the effective user ID of the current user, initialized at +shell startup. +.TP +.B BASH +Expands to the full file name used to invoke this instance of +.BR bash . +.TP +.B BASH_VERSION +Expands to a string describing the version of this instance of +.BR bash . +.TP +.B BASH_VERSINFO +An array variable whose members hold version information for this +instance of +.BR bash . +The values assigned to the array members are as follows: +.sp .5 +.RS +.PD 0 +.TP 24 +.B BASH_VERSINFO[\fR0\fP] +The major version number (the \fIrelease\fP). +.TP +.B BASH_VERSINFO[\fR1\fP] +The minor version number (the \fIversion\fP). +.TP +.B BASH_VERSINFO[\fR2\fP] +The patch level. +.TP +.B BASH_VERSINFO[\fR3\fP] +The build version. +.TP +.B BASH_VERSINFO[\fR4\fP] +The release status (e.g., \fIbeta1\fP). +.TP +.B BASH_VERSINFO[\fR5\fP] +The value of \fBMACHTYPE\fP. +.PD +.RE +.TP +.B SHLVL +Incremented by one each time an instance of +.B bash +is started. +.TP +.B RANDOM +Each time this parameter is referenced, a random integer between +0 and 32767 is +generated. The sequence of random numbers may be initialized by assigning +a value to +.SM +.BR RANDOM . +If +.SM +.B RANDOM +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B SECONDS +Each time this parameter is +referenced, the number of seconds since shell invocation is returned. If a +value is assigned to +.SM +.BR SECONDS , +the value returned upon subsequent +references is +the number of seconds since the assignment plus the value assigned. +If +.SM +.B SECONDS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B LINENO +Each time this parameter is referenced, the shell substitutes +a decimal number representing the current sequential line number +(starting with 1) within a script or function. When not in a +script or function, the value substituted is not guaranteed to +be meaningful. +If +.SM +.B LINENO +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B HISTCMD +The history number, or index in the history list, of the current +command. +If +.SM +.B HISTCMD +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B DIRSTACK +An array variable (see +.B Arrays +below) containing the current contents of the directory stack. +Directories appear in the stack in the order they are displayed by the +.B dirs +builtin. +Assigning to members of this array variable may be used to modify +directories already in the stack, but the +.B pushd +and +.B popd +builtins must be used to add and remove directories. +Assignment to this variable will not change the current directory. +If +.SM +.B DIRSTACK +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B PIPESTATUS +An array variable (see +.B Arrays +below) containing a list of exit status values from the processes +in the most-recently-executed foreground pipeline (which may +contain only a single command). +.TP +.B OPTARG +The value of the last option argument processed by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.TP +.B OPTIND +The index of the next argument to be processed by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.TP +.B HOSTNAME +Automatically set to the name of the current host. +.TP +.B HOSTTYPE +Automatically set to a string that uniquely +describes the type of machine on which +.B bash +is executing. +The default is system-dependent. +.TP +.B OSTYPE +Automatically set to a string that +describes the operating system on which +.B bash +is executing. +The default is system-dependent. +.TP +.B MACHTYPE +Automatically set to a string that fully describes the system +type on which +.B bash +is executing, in the standard GNU \fIcpu-company-system\fP format. +The default is system-dependent. +.TP +.B SHELLOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the +.B \-o +option to the +.B set +builtin command (see +.SM +.B "SHELL BUILTIN COMMANDS" +below). The options appearing in +.SM +.B SHELLOPTS +are those reported as +.I on +by \fBset \-o\fP. +If this variable is in the environment when +.B bash +starts up, each shell option in the list will be enabled before +reading any startup files. +This variable is read-only. +.PD +.PP +The following variables are used by the shell. In some cases, +.B bash +assigns a default value to a variable; these cases are noted +below. +.PP +.PD 0 +.TP +.B IFS +The +.I Internal Field Separator +that is used +for word splitting after expansion and to +split lines into words with the +.B read +builtin command. The default value is +``<space><tab><newline>''. +.TP +.B PATH +The search path for commands. It +is a colon-separated list of directories in which +the shell looks for commands (see +.SM +.B COMMAND EXECUTION +below). The default path is system-dependent, +and is set by the administrator who installs +.BR bash . +A common value is ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin:.''. +.TP +.B HOME +The home directory of the current user; the default argument for the +\fBcd\fP builtin command. +.TP +.B CDPATH +The search path for the +.B cd +command. This is a colon-separated +list of directories in which the shell looks for destination directories +specified by the +.B cd +command. A sample value is +``.:~:/usr''. +.TP +.B ENV +If this parameter is set when \fBbash\fP is executing a shell script, +its value is interpreted as a filename containing commands to +initialize the shell, as in +.IR .bashrc . +The value of +.SM +.B ENV +is subjected to parameter expansion, command substitution, and arithmetic +expansion before being interpreted as a file name. +.SM +.B PATH +is not used to search for the resultant file name. +.TP +.B MAIL +If this parameter is set to a file name and the +.SM +.B MAILPATH +variable is not set, +.B bash +informs the user of the arrival of mail in the specified file. +.TP +.B MAILCHECK +Specifies how +often (in seconds) +.B bash +checks for mail. The default is 60 seconds. When it is time to check +for mail, the shell does so before displaying the primary prompt. +If this variable is unset, the shell disables mail checking. +.TP +.B MAILPATH +A colon-separated list of file names to be checked for mail. +The message to be printed may be specified by separating the file name from +the message with a `?'. $_ stands for the name of the current mailfile. +Example: +.RS +.PP +\fBMAILPATH\fP='/usr/spool/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"' +.PP +.B Bash +supplies a default value for this variable, but the location of the user +mail files that it uses is system dependent (e.g., /usr/spool/mail/\fB$USER\fP). +.RE +.TP +.B PS1 +The value of this parameter is expanded (see +.SM +.B PROMPTING +below) and used as the primary prompt string. The default value is +``\fB\es\-\ev\e$ \fP''. +.TP +.B PS2 +The value of this parameter is expanded as with +.B PS1 +and used as the secondary prompt string. The default is +``\fB> \fP''. +.TP +.B PS3 +The value of this parameter is used as the prompt for the +.B select +command (see +.SM +.B SHELL GRAMMAR +above). +.TP +.B PS4 +The value of this parameter is expanded as with +.B PS1 +and the value is printed before each command +.B bash +displays during an execution trace. The first character of +.SM +.B PS4 +is replicated multiple times, as necessary, to indicate multiple +levels of indirection. The default is ``\fB+ \fP''. +.TP +.B TIMEFORMAT +The value of this parameter is used as a format string specifying +how the timing information for pipelines prefixed with the +.B time +reserved word should be displayed. +The \fB%\fP character introduces an escape sequence that is +expanded to a time value or other information. +The escape sequences and their meanings are as follows; the +braces denote optional portions. +.sp .5 +.RS +.PD 0 +.TP 10 +.B %% +A literal \fB%\fP. +.TP +.B %[\fIp\fP][l]R +The elapsed time in seconds. +.TP +.B %[\fIp\fP][l]U +The number of CPU seconds spent in user mode. +.TP +.B %[\fIp\fP][l]S +The number of CPU seconds spent in system mode. +.TP +.B %P +The CPU percentage, computed as (%U + %S) / %R. +.PD +.RE +.IP +The optional \fIp\fP is a digit specifying the \fIprecision\fP, +the number of fractional digits after a decimal point. +A value of 0 causes no decimal point or fraction to be output. +At most three places after the decimal point may be specified; +values of \fIp\fP greater than 3 are changed to 3. +If \fIp\fP is not specified, the value 3 is used. +.IP +The optional \fBl\fP specifies a longer format, including +minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs. +The value of \fIp\fP determines whether or not the fraction is +included. +.IP +If this variable is not set, \fBbash\fP acts as if it had the +value \fB$'\enreal\et%3lR\enuser\et%3lU\ensys\t%3lS'\fP. +If the value is null, no timing information is displayed. +A trailing newline is added when the format string is displayed. +.TP +.B HISTSIZE +The number of commands to remember in the command history (see +.SM +.B HISTORY +below). The default value is 500. +.TP +.B HISTFILE +The name of the file in which command history is saved (see +.SM +.B HISTORY +below). The default value is \fI~/.bash_history\fP. If unset, the +command history is not saved when an interactive shell exits. +.TP +.B HISTFILESIZE +The maximum number of lines contained in the history file. When this +variable is assigned a value, the history file is truncated, if +necessary, to contain no more than that number of lines. The default +value is 500. The history file is also truncated to this size after +writing it when an interactive shell exits. +.TP +.B OPTERR +If set to the value 1, +.B bash +displays error messages generated by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SM +.B OPTERR +is initialized to 1 each time the shell is invoked or a shell +script is executed. +.TP +.B LANG +Used to determine the locale category for any category not specifically +selected with a variable starting with \fBLC_\fP. +.TP +.B LC_ALL +This variable overrides the value of \fBLANG\fP and any other +\fBLC_\fP variable specifying a locale category. +.TP +.B LC_COLLATE +This variable determines the collation order used when sorting the +results of pathname expansion. +.TP +.B LC_MESSAGES +This variable determines the locale used to translate double-quoted +strings preceded by a \fB$\fP. +.TP +.B PROMPT_COMMAND +If set, the value is executed as a command prior to issuing each primary +prompt. +.TP +.B IGNOREEOF +Controls the +action of an interactive shell on receipt of an +.SM +.B EOF +character as the sole input. If set, the value is the number of +consecutive +.SM +.B EOF +characters which must be +typed as the first characters on an input line before +.B bash +exits. If the variable exists but does not have a numeric value, or +has no value, the default value is 10. If it does not exist, +.SM +.B EOF +signifies the end of input to the shell. +.TP +.B TMOUT +If set to a value greater than zero, the value is interpreted as the +number of seconds to wait for input after issuing the primary prompt. +.B Bash +terminates after waiting for that number of seconds if input does +not arrive. +.TP +.B FCEDIT +The default editor for the +.B fc +builtin command. +.TP +.B FIGNORE +A colon-separated list of suffixes to ignore when performing +filename completion (see +.SM +.B READLINE +below). +A filename whose suffix matches one of the entries in +.SM +.B FIGNORE +is excluded from the list of matched filenames. +A sample value is ``.o:~''. +.TP +.B GLOBIGNORE +A colon-separated list of patterns defining the set of filenames to +be ignored by pathname expansion. +If a filename matched by a pathname expansion pattern also matches one +of the patterns in +.SM +.BR GLOBIGNORE , +it is removed from the list of matches. +.TP +.B INPUTRC +The filename for the +.B readline +startup file, overriding the default of +.FN ~/.inputrc +(see +.SM +.B READLINE +below). +.TP +.B HISTCONTROL +If set to a value of +.IR ignorespace , +lines which begin with a +.B space +character are not entered on the history list. If set to +a value of +.IR ignoredups , +lines matching the last history line are not entered. +A value of +.I ignoreboth +combines the two options. +If unset, or if set to any other value than those above, +all lines read +by the parser are saved on the history list, subject to the value +of +.BR HISTIGNORE . +This variable's function is superseded by +.BR HISTIGNORE . +.TP +.B HISTIGNORE +A colon-separated list of patterns used to decide which command lines +should be saved on the history list. Each pattern is anchored at the +beginning of the line and must fully specify the line (no implicit +`\fB*\fP' is appended). Each pattern is tested against the line +after the checks specified by +.B HISTCONTROL +are applied. +In addition to the normal shell pattern matching characters, `\fB&\fP' +matches the previous history line. `\fB&\fP' may be escaped using a +backslash. The backslash is removed before attempting a match. +.TP +.B histchars +The two or three characters which control history expansion +and tokenization (see +.SM +.B HISTORY EXPANSION +below). The first character is the +.IR "history expansion character" , +that is, the character which signals the start of a history +expansion, normally `\fB!\fP'. +The second character is the +.IR "quick substitution" +character, which is used as shorthand for re-running the previous +command entered, substituting one string for another in the command. +The default is `\fB^\fP'. +The optional third character is the character +which signifies that the remainder of the line is a comment when found +as the first character of a word, normally `\fB#\fP'. The history +comment character causes history substitution to be skipped for the +remaining words on the line. It does not necessarily cause the shell +parser to treat the rest of the line as a comment. +.TP +.B HOSTFILE +Contains the name of a file in the same format as +.FN /etc/hosts +that should be read when the shell needs to complete a +hostname. The file may be changed interactively; the next +time hostname completion is attempted +.B bash +adds the contents of the new file to the already existing database. +.TP +.B auto_resume +This variable controls how the shell interacts with the user and +job control. If this variable is set, single word simple +commands without redirections are treated as candidates for resumption +of an existing stopped job. There is no ambiguity allowed; if there is +more than one job beginning with the string typed, the job most recently +accessed is selected. The +.I name +of a stopped job, in this context, is the command line used to +start it. +If set to the value +.IR exact , +the string supplied must match the name of a stopped job exactly; +if set to +.IR substring , +the string supplied needs to match a substring of the name of a +stopped job. The +.I substring +value provides functionality analogous to the +.B %? +job identifier (see +.SM +.B JOB CONTROL +below). If set to any other value, the supplied string must +be a prefix of a stopped job's name; this provides functionality +analogous to the +.B % +job identifier. +.PD +.SS Arrays +.B Bash +provides one-dimensional array variables. Any variable may be used as +an array; the +.B declare +builtin will explicitly declare an array. There is no maximum +limit on the size of an array, nor any requirement that members +be indexed or assigned contiguously. Arrays are indexed using +integers and are zero-based. +.PP +An array is created automatically if any variable is assigned to using +the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP. The +.I subscript +is treated as an arithmetic expression that must evaluate to a number +greater than or equal to zero. To explicitly declare an array, use +.B declare \-a \fIname\fP +(see +.SM +.B SHELL BUILTIN COMMANDS +below). +.B declare \-a \fIname\fP[\fIsubscript\fP] +is also accepted; the \fIsubscript\fP is ignored. Attributes may be +specified for an array variable using the +.B declare +and +.B readonly +builtins. Each attribute applies to all members of an array. +.PP +Arrays are assigned to using compound assignments of the form +\fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each +\fIvalue\fP is of the form [\fIsubscript\fP]=\fIstring\fP. Only +\fIstring\fP is required. If +the optional brackets and subscript are supplied, that index is assigned to; +otherwise the index of the element assigned is the last index assigned +to by the statement plus one. Indexing starts at zero. +This syntax is also accepted by the +.B declare +builtin. Individual array elements may be assigned to using the +\fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above. +.PP +Any element of an array may be referenced using +${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid +conflicts with pathname expansion. If +\fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to +all members of \fIname\fP. These subscripts differ only when the +word appears within double quotes. If the word is double-quoted, +${\fIname\fP[*]} expands to a single +word with the value of each array member separated by the first +character of the +.SM +.B IFS +special variable, and ${\fIname\fP[@]} expands each element of +\fIname\fP to a separate word. When there are no array members, +${\fIname\fP[@]} expands to nothing. This is analogous to the expansion +of the special parameters \fB*\fP and \fB@\fP (see +.B Special Parameters +above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of +${\fIname\fP[\fIsubscript\fP]}. If \fIsubscript\fP is \fB*\fP or +\fB@\fP, the expansion is the number of elements in the array. +Referencing an array variable without a subscript is equivalent to +referencing element zero. +.PP +The +.B unset +builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP] +destroys the array element at index \fIsubscript\fP. +\fBunset\fP \fIname\fP, where \fIname\fP is an array, or +\fBunset\fP \fIname\fP[\fIsubscript\fP], where +\fIsubscript\fP is \fB*\fP or \fB@\fP, removes the entire array. +.PP +The +.BR declare , +.BR local , +and +.B readonly +builtins each accept a +.B \-a +option to specify an array. The +.B read +builtin accepts a +.B \-a +option to assign a list of words read from the standard input +to an array. The +.B set +and +.B declare +builtins display array values in a way that allows them to be +reused as assignments. +.SH EXPANSION +Expansion is performed on the command line after it has been split into +words. There are seven kinds of expansion performed: +.IR "brace expansion" , +.IR "tilde expansion" , +.IR "parameter and variable expansion" , +.IR "command substitution" , +.IR "arithmetic expansion" , +.IR "word splitting" , +and +.IR "pathname expansion" . +.PP +The order of expansions is: brace expansion, tilde expansion, +parameter, variable and arithmetic expansion and +command substitution +(done in a left-to-right fashion), word splitting, and pathname +expansion. +.PP +On systems that can support it, there is an additional expansion +available: \fIprocess substitution\fP. +.PP +Only brace expansion, word splitting, and pathname expansion +can change the number of words of the expansion; other expansions +expand a single word to a single word. +The only exceptions to this are the expansions of +``\fB$@\fP'' and ``\fB${\fP\fIname\fP\fB[@]}\fP'' +as explained above (see +.SM +.BR PARAMETERS ). +.SS Brace Expansion +.PP +.I "Brace expansion" +is a mechanism by which arbitrary strings +may be generated. This mechanism is similar to +\fIpathname expansion\fP, but the filenames generated +need not exist. Patterns to be brace expanded take +the form of an optional +.IR preamble , +followed by a series of comma-separated strings +between a pair of braces, followed by an optional +.IR postamble . +The preamble is prefixed to each string contained +within the braces, and the postamble is then appended +to each resulting string, expanding left to right. +.PP +Brace expansions may be nested. The results of each expanded +string are not sorted; left to right order is preserved. +For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'. +.PP +Brace expansion is performed before any other expansions, +and any characters special to other expansions are preserved +in the result. It is strictly textual. +.B Bash +does not apply any syntactic interpretation to the context of the +expansion or the text between the braces. +.PP +A correctly-formed brace expansion must contain unquoted opening +and closing braces, and at least one unquoted comma. +Any incorrectly formed brace expansion is left unchanged. +A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its +being considered part of a brace expression. +.PP +This construct is typically used as shorthand when the common +prefix of the strings to be generated is longer than in the +above example: +.RS +.PP +mkdir /usr/local/src/bash/{old,new,dist,bugs} +.RE +or +.RS +chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} +.RE +.PP +Brace expansion introduces a slight incompatibility with +historical versions of +.BR sh . +.B sh +does not treat opening or closing braces specially when they +appear as part of a word, and preserves them in the output. +.B Bash +removes braces from words as a consequence of brace +expansion. For example, a word entered to +.B sh +as \fIfile{1,2}\fP +appears identically in the output. The same word is +output as +.I file1 file2 +after expansion by +.BR bash . +If strict compatibility with +.B sh +is desired, start +.B bash +with the +.B +B +option or disable brace expansion with the +.B +B +option to the +.B set +command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SS Tilde Expansion +.PP +If a word begins with a tilde character (`\fB~\fP'), all of the characters +preceding the first slash (or all characters, if there is no slash) +are treated as a possible \fIlogin name\fP. If this \fIlogin name\fP +is the null string, the tilde is replaced with the value of the +parameter +.SM +.BR HOME . +If +.SM +.B HOME +is unset, the home directory of +the user executing the shell is substituted instead. +.PP +If a `+' follows the tilde, the value of +.SM +.B PWD +replaces the tilde and `+'. If +a `\-' follows, the value of +.SM +.B OLDPWD +is substituted. +If the value following the tilde is a valid \fIlogin name\fP, +the tilde and \fIlogin name\fP are replaced with the home directory +associated with that name. If the name is invalid, or the tilde +expansion fails, the word is unchanged. +.PP +Each variable assignment is checked for unquoted +tildes immediately following a +.B : +or +.BR = . +In these cases, tilde substitution is also performed. Consequently, one +may use file names with tildes in assignments to +.SM +.BR PATH , +.SM +.BR MAILPATH , +and +.SM +.BR CDPATH , +and the shell assigns the expanded value. +.SS Parameter Expansion +.PP +The `\fB$\fP' character introduces parameter expansion, +command substitution, or arithmetic expansion. The parameter name +or symbol to be expanded may be enclosed in braces, which +are optional but serve to protect the variable to be expanded from +characters immediately following it which could be +interpreted as part of the name. +.PP +.PD 0 +.TP +${\fIparameter\fP} +The value of \fIparameter\fP is substituted. The braces are required +when +.I parameter +is a positional parameter with more than one digit, +or when +.I parameter +is followed by a character which is not to be +interpreted as part of its name. +.PD +.PP +If the first character of \fIparameter\fP is an exclamation point, +a level of variable indirection is introduced. +\fBBash\fP uses the value of the variable formed from the rest of +\fIparameter\fP as the name of the variable; this variable is then +expanded and that value used in the rest of the substitution, rather +than the value of \fIparameter\fP itself. +This is known as \fIindirect expansion\fP. +.PP +In each of the cases below, \fIword\fP is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +When not performing substring expansion, \fBbash\fP tests for a parameter +that is unset or null; omitting the colon results in a test only for a +parameter that is unset. +.PP +.PD 0 +.TP +${\fIparameter\fP\fB:\-\fP\fIword\fP} +\fBUse Default Values\fP. If +.I parameter +is unset or null, the expansion of +.I word +is substituted. Otherwise, the value of +.I parameter +is substituted. +.TP +${\fIparameter\fP\fB:=\fP\fIword\fP} +\fBAssign Default Values\fP. +If +.I parameter +is unset or null, the expansion of +.I word +is assigned to +.IR parameter . +The value of +.I parameter +is then substituted. Positional parameters and special parameters may +not be assigned to in this way. +.TP +${\fIparameter\fP\fB:?\fP\fIword\fP} +\fBDisplay Error if Null or Unset\fP. +If +.I parameter +is null or unset, the expansion of \fIword\fP (or a message to that effect +if +.I word +is not present) is written to the standard error and the shell, if it +is not interactive, exits. Otherwise, the value of \fIparameter\fP is +substituted. +.TP +${\fIparameter\fP\fB:+\fP\fIword\fP} +\fBUse Alternate Value\fP. +If +.I parameter +is null or unset, nothing is substituted, otherwise the expansion of +.I word +is substituted. +.TP +.PD 0 +${\fIparameter\fP\fB:\fP\fIoffset\fP} +.TP +${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP} +.PD +\fBSubstring Expansion.\fP +Expands to up to \fIlength\fP characters of \fIparameter\fP, +starting at \fIoffset\fP. +If \fIlength\fP is omitted, expands to the substring of +\fIparameter\fP, starting at the character specified by \fIoffset\fP. +\fIlength\fP and \fIoffset\fP are arithmetic expressions (see +.SM +.B +ARITHMETIC EVALUATION +below). +\fIlength\fP must evaluate to a number greater than or equal to zero. +If \fIoffset\fP evaluates to a number less than zero, the value +is used as an offset from the end of the value of \fIparameter\fP. +If \fIparameter\fP is \fB@\fP, the result is \fIlength\fP positional +parameters beginning at \fIoffset\fP. +If \fIparameter\fP is an array name indexed by @ or *, +the result is the \fIlength\fP +members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}. +Substring indexing is zero-based unless the positional parameters are +used, in which case the indexing starts at 1. +.TP +${\fB#\fP\fIparameter\fP} +The length in characters of the value of \fIparameter\fP is substituted. +If +.I parameter +is +.B * +or +.BR @ , +the length substituted is the number of positional parameters. +If +.I parameter +is an array name subscripted by +.B * +or +.BR @ , +the length substituted is the number of elements in the array. +.TP +.PD 0 +${\fIparameter\fP\fB#\fP\fIword\fP} +.TP +${\fIparameter\fP\fB##\fP\fIword\fP} +.PD +The +.I word +is expanded to produce a pattern just as in pathname +expansion. If the pattern matches the beginning of +the value of +.IR parameter , +then the expansion is the value of +.I parameter +with the shortest matching pattern (the ``\fB#\fP'' case) or the +longest matching pattern (the ``\fB##\fP'' case) deleted. +If +.I parameter +is +.B @ +or +.BR * , +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +.PD 0 +${\fIparameter\fP\fB%\fP\fIword\fP} +.TP +${\fIparameter\fP\fB%%\fP\fIword\fP} +.PD +The \fIword\fP is expanded to produce a pattern just as in +pathname expansion. +If the pattern matches a trailing portion of the value of +.IR parameter , +then the expansion is the value of +.I parameter +with the shortest matching pattern (the ``\fB%\fP'' case) or the +longest matching pattern (the ``\fB%%\fP'' case) deleted. +If +.I parameter +is +.B @ +or +.BR * , +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +.PD 0 +${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.TP +${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.PD +The \fIpattern\fP is expanded to produce a pattern just as in +pathname expansion. +\fIParameter\fP is expanded and the longest match of \fIpattern\fP +against its value is replaced with \fIstring\fP. +In the first form, only the first match is replaced. +The second form causes all matches of \fIpattern\fP to be +replaced with \fIstring\fP. +If \fIpattern\fP begins with \fB#\fP, it must match at the beginning +of \fIstring\fP. +If \fIpattern\fP begins with \fB%\fP, it must match at the end +of \fIstring\fP. +If \fIstring\fP is null, matches of \fIpattern\fP are deleted +and the \fB/\fP following \fIpattern\fP may be omitted. +If +.I parameter +is +.B @ +or +.BR * , +the substitution operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the substitution operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.SS Command Substitution +.PP +\fICommand substitution\fP allows the output of a command to replace +the command name. There are two forms: +.PP +.RS +.PP +\fB$(\fP\fIcommand\fP\|\fB)\fP +.RE +or +.RS +\fB`\fP\fIcommand\fP\fB`\fP +.RE +.PP +.B Bash +performs the expansion by executing \fIcommand\fP and +replacing the command substitution with the standard output of the +command, with any trailing newlines deleted. +.PP +When the old-style backquote form of substitution is used, +backslash retains its literal meaning except when followed by +.BR $ , +.BR ` , +or +.BR \e . +When using the $(\^\fIcommand\fP\|) form, all characters between the +parentheses make up the command; none are treated specially. +.PP +Command substitutions may be nested. To nest when using the old form, +escape the inner backquotes with backslashes. +.PP +If the substitution appears within double quotes, word splitting and +pathname expansion are not performed on the results. +.SS Arithmetic Expansion +.PP +Arithmetic expansion allows the evaluation of an arithmetic expression +and the substitution of the result. The format for arithmetic expansion is: +.RS +.PP +\fB$((\fP\fIexpression\fP\fB))\fP +.RE +.PP +The +.I expression +is treated as if it were within double quotes, but a double quote +inside the parentheses is not treated specially. +All tokens in the expression undergo parameter expansion, string +expansion, command substitution, and quote removal. +Arithmetic substitutions may be nested. +.PP +The evaluation is performed according to the rules listed below under +.SM +.BR "ARITHMETIC EVALUATION" . +If +.I expression +is invalid, +.B bash +prints a message indicating failure and no substitution occurs. +.SS Process Substitution +.PP +\fIProcess substitution\fP is supported on systems that support named +pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files. +It takes the form of +\fB<(\fP\fIlist\^\fP\fB)\fP +or +\fB>(\fP\fIlist\^\fP\fB)\fP. +The process \fIlist\fP is run with its input or output connected to a +\fIFIFO\fP or some file in \fB/dev/fd\fP. The name of this file is +passed as an argument to the current command as the result of the +expansion. If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to +the file will provide input for \fIlist\fP. If the +\fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an +argument should be read to obtain the output of \fIlist\fP. +.PP +On systems that support it, \fIprocess substitution\fP is performed +simultaneously with parameter and variable expansion, +command substitution, +and arithmetic expansion. +.SS Word Splitting +.PP +The shell scans the results of +parameter expansion, +command substitution, +and +arithmetic expansion +that did not occur within double quotes for +.IR "word splitting" . +.PP +The shell treats each character of +.SM +.B IFS +as a delimiter, and splits the results of the other +expansions into words on these characters. If +.SM +.B IFS +is unset, or its +value is exactly +.BR <space><tab><newline> , +the default, then +any sequence of +.SM +.B IFS +characters serves to delimit words. If +.SM +.B IFS +has a value other than the default, then sequences of +the whitespace characters +.B space +and +.B tab +are ignored at the beginning and end of the +word, as long as the whitespace character is in the +value of +.SM +.BR IFS +(an +.SM +.B IFS +whitespace character). +Any character in +.SM +.B IFS +that is not +.SM +.B IFS +whitespace, along with any adjacent +.SM +.B IFS +whitespace characters, delimits a field. +A sequence of +.SM +.B IFS +whitespace characters is also treated as a delimiter. +If the value of +.SM +.B IFS +is null, no word splitting occurs. +.PP +Explicit null arguments (\^\f3"\^"\fP or \^\f3'\^'\fP\^) are retained. +Unquoted implicit null arguments, resulting from the expansion of +.I parameters +that have no values, are removed. +If a parameter with no value is expanded within double quotes, a +null argument results and is retained. +.PP +Note that if no expansion occurs, no splitting +is performed. +.SS Pathname Expansion +.PP +After word splitting, +unless the +.B \-f +option has been set, +.B bash +scans each word for the characters +.BR * , +.BR ? , +and +.BR [ . +If one of these characters appears, then the word is +regarded as a +.IR pattern , +and replaced with an alphabetically sorted list of +file names matching the pattern. +If no matching file names are found, +and the shell option +.B nullglob +is disabled, the word is left unchanged. +If the option is set, and no matches are found, +the word is removed. +When a pattern is used for pathname expansion, +the character +.B ``.'' +at the start of a name or immediately following a slash +must be matched explicitly, unless the shell option +.B dotglob +is set. +The slash character must always be matched explicitly. +In other cases, the +.B ``.'' +character is not treated specially. +See the description of +.B shopt +below under +.SM +.B SHELL BUILTIN COMMANDS +for a description of the +.B nullglob +and +.B dotglob +shell options. +.PP +The +.SM +.B GLOBIGNORE +shell variable may be used to restrict the set of file names matching a +.IR pattern . +If +.SM +.B GLOBIGNORE +is set, each matching file name that also matches one of the patterns in +.SM +.B GLOBIGNORE +is removed from the list of matches. +The file names +.B ``.'' +and +.B ``..'' +are always ignored, even when +.SM +.B GLOBIGNORE +is set. However, setting +.SM +.B GLOBIGNORE +has the effect of enabling the +.B dotglob +shell option, so all other file names beginning with a +.B ``.'' +will match. +To get the old behavior of ignoring file names beginning with a +.BR ``.'' , +make +.B ``.*'' +one of the patterns in +.SM +.BR GLOBIGNORE . +The +.B dotglob +option is disabled when +.SM +.B GLOBIGNORE +is unset. +.PP +The special pattern characters have the following meanings: +.PP +.PD 0 +.TP +.B * +Matches any string, including the null string. +.TP +.B ? +Matches any single character. +.TP +.B [...] +Matches any one of the enclosed characters. A pair of characters +separated by a minus sign denotes a +.IR range ; +any character lexically between those two characters, inclusive, +is matched. If the first character following the +.B [ +is a +.B ! +or a +.B ^ +then any character not enclosed is matched. +A +.B \- +may be matched by including it as the first or last character +in the set. +A +.B ] +may be matched by including it as the first character +in the set. +.PD +.SS Quote Removal +.PP +After the preceding expansions, all unquoted occurrences of the +characters +.BR \e , +.BR ` , +and \^\f3"\fP\^ that did not result from one of the above +expansions are removed. +.SH REDIRECTION +Before a command is executed, its input and output +may be +.I redirected +using a special notation interpreted by the shell. +Redirection may also be used to open and close files for the +current shell execution environment. The following redirection +operators may precede or appear anywhere within a +.I simple command +or may follow a +.IR command . +Redirections are processed in the order they appear, from +left to right. +.PP +In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is +.BR < , +the redirection refers to the standard input (file descriptor +0). If the first character of the redirection operator is +.BR > , +the redirection refers to the standard output (file descriptor +1). +.PP +The word that follows the redirection operator in the following +descriptions is subjected to brace expansion, tilde expansion, +parameter expansion, command substitution, arithmetic expansion, +quote removal, and pathname expansion. If it expands to more +than one word, +.B bash +reports an error. +.PP +Note that the order of redirections is significant. For example, +the command +.RS +.PP +ls \fB>\fP dirlist 2\fB>&\fP1 +.RE +.PP +directs both standard output and standard error to the file +.IR dirlist , +while the command +.RS +.PP +ls 2\fB>&\fP1 \fB>\fP dirlist +.RE +.PP +directs only the standard output to file +.IR dirlist , +because the standard error was duplicated as standard output +before the standard output was redirected to +.IR dirlist . +.SS Redirecting Input +.PP +Redirection of input causes the file whose name results from +the expansion of +.I word +to be opened for reading on file descriptor +.IR n , +or the standard input (file descriptor 0) if +.I n +is not specified. +.PP +The general format for redirecting input is: +.RS +.PP +[\fIn\fP]\fB<\fP\fIword\fP +.RE +.SS Redirecting Output +.PP +Redirection of output causes the file whose name results from +the expansion of +.I word +to be opened for writing on file descriptor +.IR n , +or the standard output (file descriptor 1) if +.I n +is not specified. If the file does not exist it is created; +if it does exist it is truncated to zero size. +.PP +The general format for redirecting output is: +.RS +.PP +[\fIn\fP]\fB>\fP\fIword\fP +.RE +.PP +If the redirection operator is +.BR > , +and the +.B \-C +option to the +.B set +builtin has been enabled, the redirection will fail if the filename +whose name results from the expansion of \fIword\fP exists. +If the redirection operator is +.BR >| , +then the value of the +.B \-C +option to the +.B set +builtin command is not tested, and the redirection is attempted even +if the file named by \fIword\fP exists. +.SS Appending Redirected Output +.PP +Redirection of output in this fashion +causes the file whose name results from +the expansion of +.I word +to be opened for appending on file descriptor +.IR n , +or the standard output (file descriptor 1) if +.I n +is not specified. If the file does not exist it is created. +.PP +The general format for appending output is: +.RS +.PP +[\fIn\fP]\fB>>\fP\fIword\fP +.RE +.PP +.SS Redirecting Standard Output and Standard Error +.PP +.B Bash +allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be redirected to the file whose name is the +expansion of +.I word +with this construct. +.PP +There are two formats for redirecting standard output and +standard error: +.RS +.PP +\fB&>\fP\fIword\fP +.RE +and +.RS +\fB>&\fP\fIword\fP +.RE +.PP +Of the two forms, the first is preferred. +This is semantically equivalent to +.RS +.PP +\fB>\fP\fIword\fP 2\fB>&\fP1 +.RE +.SS Here Documents +.PP +This type of redirection instructs the shell to read input from the +current source until a line containing only +.I word +(with no trailing blanks) +is seen. All of +the lines read up to that point are then used as the standard +input for a command. +.PP +The format of here-documents is as follows: +.RS +.PP +.nf +\fB<<\fP[\fB\-\fP]\fIword\fP + \fIhere\-document\fP +\fIdelimiter\fP +.fi +.RE +.PP +No parameter expansion, command substitution, pathname +expansion, or arithmetic expansion is performed on +.IR word . +If any characters in +.I word +are quoted, the +.I delimiter +is the result of quote removal on +.IR word , +and the lines in the here-document are not expanded. Otherwise, +all lines of the here-document are subjected to parameter expansion, +command substitution, and arithmetic expansion. In the latter +case, the pair +.B \e<newline> +is ignored, and +.B \e +must be used to quote the characters +.BR \e , +.BR $ , +and +.BR ` . +.PP +If the redirection operator is +.BR <<\- , +then all leading tab characters are stripped from input lines and the +line containing +.IR delimiter . +This allows +here-documents within shell scripts to be indented in a +natural fashion. +.SS "Duplicating File Descriptors" +.PP +The redirection operator +.RS +.PP +[\fIn\fP]\fB<&\fP\fIword\fP +.RE +.PP +is used to duplicate input file descriptors. +If +.I word +expands to one or more digits, the file descriptor denoted by +.I n +is made to be a copy of that file descriptor. If +.I word +evaluates to +.BR \- , +file descriptor +.I n +is closed. If +.I n +is not specified, the standard input (file descriptor 0) is used. +.PP +The operator +.RS +.PP +[\fIn\fP]\fB>&\fP\fIword\fP +.RE +.PP +is used similarly to duplicate output file descriptors. If +.I n +is not specified, the standard output (file descriptor 1) is used. +As a special case, if \fIn\fP is omitted, and \fIword\fP does not +expand to one or more digits, the standard output and standard +error are redirected as described previously. +.SS "Opening File Descriptors for Reading and Writing" +.PP +The redirection operator +.RS +.PP +[\fIn\fP]\fB<>\fP\fIword\fP +.RE +.PP +causes the file whose name is the expansion of +.I word +to be opened for both reading and writing on file descriptor +.IR n , +or on file descriptor 0 if +.I n +is not specified. If the file does not exist, it is created. +.SH ALIASES +The shell maintains a list of +.I aliases +that may be set and unset with the +.B alias +and +.B unalias +builtin commands (see +.SM +.B SHELL BUILTIN COMMANDS +below). +The first word of each command, if unquoted, +is checked to see if it has an +alias. If so, that word is replaced by the text of the alias. +The alias name and the replacement text may contain any valid +shell input, including the +.I metacharacters +listed above, with the exception that the alias name may not +contain \fI=\fP. The first word of the replacement text is tested +for aliases, but a word that is identical to an alias being expanded +is not expanded a second time. This means that one may alias +.B ls +to +.BR "ls \-F" , +for instance, and +.B bash +does not try to recursively expand the replacement text. +If the last character of the alias value is a +.IR blank , +then the next command +word following the alias is also checked for alias expansion. +.PP +Aliases are created and listed with the +.B alias +command, and removed with the +.B unalias +command. +.PP +There is no mechanism for using arguments in the replacement text. +If arguments are needed, a shell function should be used. +.PP +Aliases are not expanded when the shell is not interactive, unless +the +.B expand_aliases +shell option is set using +.B shopt +(see the description of +.B shopt +under +.SM +\fBSHELL BUILTIN COMMANDS\fP +below). +.PP +The rules concerning the definition and use of aliases are +somewhat confusing. +.B Bash +always reads at least one complete line +of input before executing any +of the commands on that line. Aliases are expanded when a +command is read, not when it is executed. Therefore, an +alias definition appearing on the same line as another +command does not take effect until the next line of input is read. +The commands following the alias definition +on that line are not affected by the new alias. +This behavior is also an issue when functions are executed. +Aliases are expanded when the function definition is read, +not when the function is executed, because a function definition +is itself a compound command. As a consequence, aliases +defined in a function are not available until after that +function is executed. To be safe, always put +alias definitions on a separate line, and do not use +.B alias +in compound commands. +.PP +Note that for almost every purpose, aliases are superseded by +shell functions. +.SH FUNCTIONS +A shell function, defined as described above under +.SM +.BR "SHELL GRAMMAR" , +stores a series of commands for later execution. +Functions are executed in the context of the +current shell; no new process is created to interpret +them (contrast this with the execution of a shell script). +When a function is executed, the arguments to the +function become the positional parameters +during its execution. The special parameter +.B # +is updated to reflect the change. Positional parameter 0 +is unchanged. All other aspects of the shell execution +environment are identical between a function and its caller +with the exception that the +.SM +.B DEBUG +trap (see the description of the +.B trap +builtin under +.SM +.B SHELL BUILTIN COMMANDS +below) is not inherited. +.PP +Variables local to the function may be declared with the +.B local +builtin command. Ordinarily, variables and their values +are shared between the function and its caller. +.PP +If the builtin command +.B return +is executed in a function, the function completes and +execution resumes with the next command after the function +call. When a function completes, the values of the +positional parameters and the special parameter +.B # +are restored to the values they had prior to function +execution. +.PP +Function names and definitions may be listed with the +.B \-f +option to the +.B declare +or +.B typeset +builtin commands. The +.B \-F +option to +.B declare +or +.B typeset +will list the function names only. +Functions may be exported so that subshells +automatically have them defined with the +.B \-f +option to the +.B export +builtin. +.PP +Functions may be recursive. No limit is imposed on the number +of recursive calls. +.SH "COMMAND EXECUTION" +After a command has been split into words, if it results in a +simple command and an optional list of arguments, the following +actions are taken. +.PP +If the command name contains no slashes, the shell attempts to +locate it. If there exists a shell function by that name, that +function is invoked as described above in +.SM +.BR FUNCTIONS . +If the name does not match a function, the shell searches for +it in the list of shell builtins. If a match is found, that +builtin is invoked. +.PP +If the name is neither a shell function nor a builtin, +and contains no slashes, +.B bash +searches each element of the +.SM +.B PATH +for a directory containing an executable file by that name. +.B Bash +uses a hash table to remember the full file names of executable +files (see +.B hash +under +.SM +.B "SHELL BUILTIN COMMANDS" +below). +A full search of the directories in +.SM +.B PATH +is performed only if the command is not found in the hash table. +If the search is unsuccessful, the shell prints an error +message and returns a non-zero exit status. +.PP +If the search is successful, or if the command name contains +one or more slashes, the shell executes the named program. +Argument 0 is set to the name given, and the remaining arguments +to the command are set to the arguments given, if any. +.PP +If this execution fails because the file is not in executable +format, and the file is not a directory, it is assumed to be +a \fIshell script\fP, a file +containing shell commands. A subshell is spawned to execute +it. This subshell reinitializes itself, so +that the effect is as if a new shell had been invoked +to handle the script, with the exception that the locations of +commands remembered by the parent (see +.B hash +below under +.SM +\fBSHELL BUILTIN COMMANDS\fP) +are retained by the child. +.PP +If the program is a file beginning with +.BR #! , +the remainder of the first line specifies an interpreter +for the program. The shell executes the +specified interpreter on operating systems that do not +handle this executable format themselves. The arguments to the +interpreter consist of a single optional argument following the +interpreter name on the first line of the program, followed +by the name of the program, followed by the command +arguments, if any. +.SH ENVIRONMENT +When a program is invoked it is given an array of strings +called the +.IR environment . +This is a list of +\fIname\fP\-\fIvalue\fP pairs, of the form +.IR "name\fR=\fPvalue" . +.PP +The shell allows you to manipulate the environment in several +ways. On invocation, the shell scans its own environment and +creates a parameter for each name found, automatically marking +it for +.I export +to child processes. Executed commands inherit the environment. +The +.B export +and +.B declare \-x +commands allow parameters and functions to be added to and +deleted from the environment. If the value of a parameter +in the environment is modified, the new value becomes part +of the environment, replacing the old. The environment +inherited by any executed command consists of the shell's +initial environment, whose values may be modified in the shell, +less any pairs removed by the +.B unset +command, plus any additions via the +.B export +and +.B declare \-x +commands. +.PP +The environment for any +.I simple command +or function may be augmented temporarily by prefixing it with +parameter assignments, as described above in +.SM +.BR PARAMETERS . +These assignment statements affect only the environment seen +by that command. +.PP +If the +.B \-k +flag is set (see the +.B set +builtin command below), then +.I all +parameter assignments are placed in the environment for a command, +not just those that precede the command name. +.PP +When +.B bash +invokes an external command, the variable +.B _ +is set to the full file name of the command and passed to that +command in its environment. +.SH "EXIT STATUS" +For the purposes of the shell, a command which exits with a +zero exit status has succeeded. An exit status of zero +indicates success. A non-zero exit status indicates failure. +When a command terminates on a fatal signal, \fBbash\fP uses +the value of 128+\fBsignal\fP as the exit status. +.PP +If a command is not found, the child process created to +execute it returns a status of 127. If a command is found +but is not executable, the return status is 126. +.PP +Shell builtin commands return a status of 0 (\fItrue\fP) if +successful, and non-zero (\fIfalse\fP) if an error occurs +while they execute. +All builtins return an exit status of 2 to indicate incorrect usage. +.PP +\fBBash\fP itself returns the exit status of the last command +executed, unless a syntax error occurs, in which case it exits +with a non-zero value. See also the \fBexit\fP builtin +command below. +.SH SIGNALS +When \fBbash\fP is interactive, it ignores +.SM +.B SIGTERM +(so that \fBkill 0\fP does not kill an interactive shell), +and +.SM +.B SIGINT +is caught and handled (so that the \fBwait\fP builtin is interruptible). +In all cases, \fBbash\fP ignores +.SM +.BR SIGQUIT . +If job control is in effect, +.B bash +ignores +.SM +.BR SIGTTIN , +.SM +.BR SIGTTOU , +and +.SM +.BR SIGTSTP . +.PP +Synchronous jobs started by \fBbash\fP have signals set to the +values inherited by the shell from its parent. When job control +is not in effect, background jobs (jobs started with +.BR & ) +ignore +.SM +.B SIGINT +and +.SM +.BR SIGQUIT . +Commands run as a result of command substitution ignore the +keyboard-generated job control signals +.SM +.BR SIGTTIN , +.SM +.BR SIGTTOU , +and +.SM +.BR SIGTSTP . +.PP +The shell exits by default upon receipt of a +.SM +.BR SIGHUP . +Before exiting, it resends the +.SM +.B SIGHUP +to all jobs, running or stopped. To prevent the shell from +sending the signal to a particular job, remove it from the +jobs table with the +.B disown +builtin (see +.SM +.B "SHELL BUILTIN COMMANDS" +below) or use +.B "disown \-h" +to mark it to not receive +.SM +.BR SIGHUP . +.SH "JOB CONTROL" +.I Job control +refers to the ability to selectively stop (\fIsuspend\fP) +the execution of processes and continue (\fIresume\fP) +their execution at a later point. A user typically employs +this facility via an interactive interface supplied jointly +by the system's terminal driver and +.BR bash . +.PP +The shell associates a +.I job +with each pipeline. It keeps a table of currently executing +jobs, which may be listed with the +.B jobs +command. When +.B bash +starts a job asynchronously (in the +.IR background ), +it prints a line that looks like: +.RS +.PP +[1] 25647 +.RE +.PP +indicating that this job is job number 1 and that the process ID +of the last process in the pipeline associated with this job is 25647. +All of the processes in a single pipeline are members of the same job. +.B Bash +uses the +.I job +abstraction as the basis for job control. +.PP +To facilitate the implementation of the user interface to job +control, the system maintains the notion of a \fIcurrent terminal +process group ID\fP. Members of this process group (processes whose +process group ID is equal to the current terminal process group ID) +receive keyboard-generated signals such as +.SM +.BR SIGINT . +These processes are said to be in the +.IR foreground . +.I Background +processes are those whose process group ID differs from the terminal's; +such processes are immune to keyboard-generated signals. +Only foreground processes are allowed to read from or write to the +terminal. Background processes which attempt to read from (write to) the +terminal are sent a +.SM +.B SIGTTIN (SIGTTOU) +signal by the terminal driver, +which, unless caught, suspends the process. +.PP +If the operating system on which +.B bash +is running supports +job control, +.B bash +allows you to use it. +Typing the +.I suspend +character (typically +.BR ^Z , +Control-Z) while a process is running +causes that process to be stopped and returns you to +.BR bash . +Typing the +.I "delayed suspend" +character (typically +.BR ^Y , +Control-Y) causes the process to be stopped when it +attempts to read input from the terminal, and control to +be returned to +.BR bash . +You may then manipulate the state of this job, using the +.B bg +command to continue it in the background, the +.B fg +command to continue it in the foreground, or +the +.B kill +command to kill it. A \fB^Z\fP takes effect immediately, +and has the additional side effect of causing pending output +and typeahead to be discarded. +.PP +There are a number of ways to refer to a job in the shell. +The character +.B % +introduces a job name. Job number +.I n +may be referred to as +.BR %n . +A job may also be referred to using a prefix of the name used to +start it, or using a substring that appears in its command line. +For example, +.B %ce +refers to a stopped +.B ce +job. If a prefix matches more than one job, +.B bash +reports an error. Using +.BR %?ce , +on the other hand, refers to any job containing the string +.B ce +in its command line. If the substring matches more than one job, +.B bash +reports an error. The symbols +.B %% +and +.B %+ +refer to the shell's notion of the +.IR "current job" , +which is the last job stopped while it was in +the foreground. +The +.I "previous job" +may be referenced using +.BR %\- . +In output pertaining to jobs (e.g., the output of the +.B jobs +command), the current job is always flagged with a +.BR + , +and the previous job with a +.BR \- . +.PP +Simply naming a job can be used to bring it into the +foreground: +.B %1 +is a synonym for +\fB``fg %1''\fP, +bringing job 1 from the background into the foreground. +Similarly, +.B ``%1 &'' +resumes job 1 in the background, equivalent to +\fB``bg %1''\fP. +.PP +The shell learns immediately whenever a job changes state. +Normally, +.B bash +waits until it is about to print a prompt before reporting +changes in a job's status so as to not interrupt +any other output. If the +.B \-b +option to the +.B set +builtin command +is set, +.B bash +reports such changes immediately. +.PP +If an attempt to exit +.B bash +is made while jobs are stopped, the shell prints a warning message. The +.B jobs +command may then be used to inspect their status. +If a second attempt to exit is made without an intervening command, +the shell does not print another warning, and the stopped +jobs are terminated. +.SH PROMPTING +When executing interactively, +.B bash +displays the primary prompt +.SM +.B PS1 +when it is ready to read a command, and the secondary prompt +.SM +.B PS2 +when it needs more input to complete a command. +.B Bash +allows these prompt strings to be customized by inserting a number of +backslash-escaped special characters that are decoded as follows: +.RS +.PD 0 +.TP +.B \ea +an ASCII bell character (07) +.TP +.B \ed +the date in "Weekday Month Date" format (e.g., "Tue May 26") +.TP +.B \ee +an ASCII escape character (033) +.TP +.B \eh +the hostname up to the first `.' +.TP +.B \eH +the hostname +.TP +.B \en +newline +.TP +.B \es +the name of the shell, the basename of +.B $0 +(the portion following the final slash) +.TP +.B \et +the current time in 24-hour HH:MM:SS format +.TP +.B \eT +the current time in 12-hour HH:MM:SS format +.TP +.B \e@ +the current time in 12-hour am/pm format +.TP +.B \eu +the username of the current user +.TP +.B \ev +the version of \fBbash\fP (e.g., 2.00) +.TP +.B \eV +the release of \fBbash\fP, version + patchlevel (e.g., 2.00.0) +.TP +.B \ew +the current working directory +.TP +.B \eW +the basename of the current working directory +.TP +.B \e! +the history number of this command +.TP +.B \e# +the command number of this command +.TP +.B \e$ +if the effective UID is 0, a +.BR # , +otherwise a +.B $ +.TP +.B \e\fInnn\fP +the character corresponding to the octal number \fInnn\fP +.TP +.B \e\e +a backslash +.TP +.B \e[ +begin a sequence of non-printing characters, which could be used to +embed a terminal control sequence into the prompt +.TP +.B \e] +end a sequence of non-printing characters +.PD +.RE +.PP +The command number and the history number are usually different: +the history number of a command is its position in the history +list, which may include commands restored from the history file +(see +.SM +.B HISTORY +below), while the command number is the position in the sequence +of commands executed during the current shell session. +After the string is decoded, it is expanded via +parameter expansion, command substitution, arithmetic expansion, +string expansion, and quote removal, subject to the value of the +.B promptvars +shell option (see the description of the +.B shopt +command under +.SM +.B "SHELL BUILTIN COMMANDS" +below). +.SH READLINE +This is the library that handles reading input when using an interactive +shell, unless the +.B \-noediting +option is given at shell invocation. +By default, the line editing commands are similar to those of emacs. +A vi-style line editing interface is also available. +To turn off line editing after the shell is running, use the +.B +o emacs +or +.B +o vi +options to the +.B set +builtin (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SS "Readline Notation" +.PP +In this section, the emacs-style notation is used to denote +keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n +means Control\-N. Similarly, +.I meta +keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards +without a +.I meta +key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key +then the +.I x +key. This makes ESC the \fImeta prefix\fP. +The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP, +or press the Escape key +then hold the Control key while pressing the +.I x +key.) +.PP +Readline commands may be given numeric +.IR arguments , +which normally act as a repeat count. +Sometimes, however, it is the sign of the argument that is significant. +Passing a negative argument to a command that acts in the forward +direction (e.g., \fBkill\-line\fP) causes that command to act in a +backward direction. +Commands whose behavior with arguments deviates from this are noted +below. +.PP +When a command is described as \fIkilling\fP text, the text +deleted is saved for possible future retrieval +(\fIyanking\fP). The killed text is saved in a +\fIkill ring\fP. Consecutive kills cause the text to be +accumulated into one unit, which can be yanked all at once. +Commands which do not kill text separate the chunks of text +on the kill ring. +.SS "Readline Initialization" +.PP +Readline is customized by putting commands in an initialization +file (the \fIinputrc\fP file). +The name of this file is taken from the value of the +.SM +.B INPUTRC +variable. If that variable is unset, the default is +.IR ~/.inputrc . +When a program which uses the readline library starts up, the +initialization file is read, and the key bindings and variables +are set. +There are only a few basic constructs allowed in the +readline initialization file. +Blank lines are ignored. +Lines beginning with a \fB#\fP are comments. +Lines beginning with a \fB$\fP indicate conditional constructs. +Other lines denote key bindings and variable settings. +.PP +The default key-bindings may be changed with an +.I inputrc +file. +Other programs that use this library may add their own commands +and bindings. +.PP +For example, placing +.RS +.PP +M\-Control\-u: universal\-argument +.RE +or +.RS +C\-Meta\-u: universal\-argument +.RE +into the +.I inputrc +would make M\-C\-u execute the readline command +.IR universal\-argument . +.PP +The following symbolic character names are recognized: +.IR RUBOUT , +.IR DEL , +.IR ESC , +.IR LFD , +.IR NEWLINE , +.IR RET , +.IR RETURN , +.IR SPC , +.IR SPACE , +and +.IR TAB . +In addition to command names, readline allows keys to be bound +to a string that is inserted when the key is pressed (a \fImacro\fP). +.SS "Readline Key Bindings" +.PP +The syntax for controlling key bindings in the +.I ~/.inputrc +file is simple. All that is required is the name of the +command or the text of a macro and a key sequence to which +it should be bound. The name may be specified in one of two ways: +as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP +prefixes, or as a key sequence. +When using the form \fBkeyname\fP:\fIfunction\-name\fP or \fImacro\fP, +.I keyname +is the name of a key spelled out in English. For example: +.sp +.RS +Control-u: universal\-argument +.br +Meta-Rubout: backward-kill-word +.br +Control-o: "> output" +.RE +.LP +In the above example, +.I C\-u +is bound to the function +.BR universal\-argument , +.I M\-DEL +is bound to the function +.BR backward\-kill\-word , +and +.I C\-o +is bound to run the macro +expressed on the right hand side (that is, to insert the text +.I "> output" +into the line). +.PP +In the second form, \fB"keyseq"\fP:\fIfunction\-name\fP or \fImacro\fP, +.B keyseq +differs from +.B keyname +above in that strings denoting +an entire key sequence may be specified by placing the sequence +within double quotes. Some GNU Emacs style key escapes can be +used, as in the following example. +.sp +.RS +"\eC\-u": universal\-argument +.br +"\eC\-x\eC\-r": re\-read\-init\-file +.br +"\ee[11~": "Function Key 1" +.RE +.PP +In this example, +.I C\-u +is again bound to the function +.BR universal\-argument . +.I "C\-x C\-r" +is bound to the function +.BR re\-read\-init\-file , +and +.I "ESC [ 1 1 ~" +is bound to insert the text +.BR "Function Key 1" . +The full set of escape sequences is +.RS +.TP +.B \eC\- +control prefix +.TP +.B \eM\- +meta prefix +.TP +.B \ee +an escape character +.TP +.B \e\e +backslash +.TP +.B \e" +literal " +.TP +.B \e' +literal ' +.RE +.PP +When entering the text of a macro, single or double quotes should +be used to indicate a macro definition. Unquoted text +is assumed to be a function name. Backslash +will quote any character in the macro text, including " and '. +.PP +.B Bash +allows the current readline key bindings to be displayed or modified +with the +.B bind +builtin command. The editing mode may be switched during interactive +use by using the +.B \-o +option to the +.B set +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SS "Readline Variables" +.PP +Readline has variables that can be used to further customize its +behavior. A variable may be set in the +.I inputrc +file with a statement of the form +.RS +.PP +\fBset\fP \fIvariable\-name\fP \fIvalue\fP +.RE +.PP +Except where noted, readline variables can take the values +.B On +or +.BR Off . +The variables and their default values are: +.PP +.PD 0 +.TP +.B bell\-style (audible) +Controls what happens when readline wants to ring the terminal bell. +If set to \fBnone\fP, readline never rings the bell. If set to +\fBvisible\fP, readline uses a visible bell if one is available. +If set to \fBaudible\fP, readline attempts to ring the terminal's bell. +.TP +.B comment\-begin (``#'') +The string that is inserted when the +.B readline +.B insert\-comment +command is executed. +This command is bound to +.B M\-# +in emacs mode and to +.B # +in vi command mode. +.TP +.B completion\-query\-items (100) +This determines when the user is queried about viewing +the number of possible completions +generated by the \fBpossible\-completions\fP command. +It may be set to any integer value greater than or equal to +zero. If the number of possible completions is greater than +or equal to the value of this variable, the user is asked whether +or not he wishes to view them; otherwise they are simply listed +on the terminal. +.TP +.B convert\-meta (On) +If set to \fBOn\fP, readline will convert characters with the +eighth bit set to an ASCII key sequence +by stripping the eighth bit and prepending an +escape character (in effect, using escape as the \fImeta prefix\fP). +.TP +.B disable\-completion (Off) +If set to \fBOn\fP, readline will inhibit word completion. Completion +characters will be inserted into the line as if they had been +mapped to \fBself-insert\fP. +.TP +.B editing\-mode (emacs) +Controls whether readline begins with a set of key bindings similar +to \fIemacs\fP or \fIvi\fP. +.B editing\-mode +can be set to either +.B emacs +or +.BR vi . +.TP +.B enable\-keypad (Off) +When set to \fBOn\fP, readline will try to enable the application +keypad when it is called. Some systems need this to enable the +arrow keys. +.TP +.B expand\-tilde (Off) +If set to \fBon\fP, tilde expansion is performed when readline +attempts word completion. +.TP +.B horizontal\-scroll\-mode (Off) +When set to \fBOn\fP, makes readline use a single line for display, +scrolling the input horizontally on a single screen line when it +becomes longer than the screen width rather than wrapping to a new line. +.TP +.B input\-meta (Off) +If set to \fBOn\fP, readline will enable eight-bit input (that is, +it will not strip the high bit from the characters it reads), +regardless of what the terminal claims it can support. The name +.B meta\-flag +is a synonym for this variable. +.TP +.B keymap (emacs) +Set the current readline keymap. The set of legal keymap names is +\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, +vi\-command\fP, and +.IR vi\-insert . +\fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is +equivalent to \fIemacs\-standard\fP. The default value is +.IR emacs ; +the value of +.B editing\-mode +also affects the default keymap. +.TP +.B mark\-directories (On) +If set to \fBOn\fP, completed directory names have a slash +appended. +.TP +.B mark\-modified\-lines (Off) +If set to \fBOn\fP, history lines that have been modified are displayed +with a preceding asterisk (\fB*\fP). +.TP +.B output\-meta (Off) +If set to \fBOn\fP, readline will display characters with the +eighth bit set directly rather than as a meta-prefixed escape +sequence. +.TP +.B show\-all\-if\-ambiguous (Off) +This alters the default behavior of the completion functions. If +set to +.BR on , +words which have more than one possible completion cause the +matches to be listed immediately instead of ringing the bell. +.TP +.B visible\-stats (Off) +If set to \fBOn\fP, a character denoting a file's type as reported +by \fIstat\fP(2) is appended to the filename when listing possible +completions. +.PD +.SS "Readline Conditional Constructs" +.PP +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are three parser directives used. +.IP \fB$if\fP +The +.B $if +construct allows bindings to be made based on the +editing mode, the terminal being used, or the application using +readline. The text of the test extends to the end of the line; +no characters are required to isolate it. +.RS +.IP \fBmode\fP +The \fBmode=\fP form of the \fB$if\fP directive is used to test +whether readline is in emacs or vi mode. +This may be used in conjunction +with the \fBset keymap\fP command, for instance, to set bindings in +the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if +readline is starting out in emacs mode. +.IP \fBterm\fP +The \fBterm=\fP form may be used to include terminal-specific +key bindings, perhaps to bind the key sequences output by the +terminal's function keys. The word on the right side of the +.B = +is tested against the full name of the terminal and the portion +of the terminal name before the first \fB\-\fP. This allows +.I sun +to match both +.I sun +and +.IR sun\-cmd , +for instance. +.IP \fBapplication\fP +The \fBapplication\fP construct is used to include +application-specific settings. Each program using the readline +library sets the \fIapplication name\fP, and an initialization +file can test for a particular value. +This could be used to bind key sequences to functions useful for +a specific program. For instance, the following command adds a +key sequence that quotes the current or previous word in Bash: +.RS +.nf +\fB$if\fP Bash +# Quote the current or previous word +"\eC\-xq": "\eeb\e"\eef\e"" +\fB$endif\fP +.fi +.RE +.RE +.IP \fB$endif\fP +This command, as you saw in the previous example, terminates an +\fB$if\fP command. +.IP \fB$else\fP +Commands in this branch of the \fB$if\fP directive are executed if +the test fails. +.SS Searching +.PP +Readline provides commands for searching through the command history +(see +.SM +.B HISTORY +below) for lines containing a specified string. +There are two search modes: +.I incremental +and +.IR non-incremental . +.PP +Incremental searches begin before the user has finished typing the +search string. +As each character of the search string is typed, readline displays +the next entry from the history matching the string typed so far. +An incremental search requires only as many characters as needed to +find the desired history entry. +The Escape character is used to terminate an incremental search. +Control-J will also terminate the search. +Control-G will abort an incremental search and restore the original +line. +When the search is terminated, the history entry containing the +search string becomes the current line. +To find other matching entries in the history list, type Control-S or +Control-R as appropriate. +This will search backward or forward in the history for the next +entry matching the search string typed so far. +Any other key sequence bound to a readline command will terminate +the search and execute that command. +For instance, a \fInewline\fP will terminate the search and accept +the line, thereby executing the command from the history list. +.PP +Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or part of the contents of the current line. +.SS "Readline Command Names" +.PP +The following is a list of the names of the commands and the default +key sequences to which they are bound. +Command names without an accompanying key sequence are unbound by default. +.SS Commands for Moving +.PP +.PD 0 +.TP +.B beginning\-of\-line (C\-a) +Move to the start of the current line. +.TP +.B end\-of\-line (C\-e) +Move to the end of the line. +.TP +.B forward\-char (C\-f) +Move forward a character. +.TP +.B backward\-char (C\-b) +Move back a character. +.TP +.B forward\-word (M\-f) +Move forward to the end of the next word. Words are composed of +alphanumeric characters (letters and digits). +.TP +.B backward\-word (M\-b) +Move back to the start of this, or the previous, word. Words are +composed of alphanumeric characters (letters and digits). +.TP +.B clear\-screen (C\-l) +Clear the screen leaving the current line at the top of the screen. +With an argument, refresh the current line without clearing the +screen. +.TP +.B redraw\-current\-line +Refresh the current line. +.PD +.SS Commands for Manipulating the History +.PP +.PD 0 +.TP +.B accept\-line (Newline, Return) +Accept the line regardless of where the cursor is. If this line is +non-empty, add it to the history list according to the state of the +.SM +.B HISTCONTROL +variable. If the line is a modified history +line, then restore the history line to its original state. +.TP +.B previous\-history (C\-p) +Fetch the previous command from the history list, moving back in +the list. +.TP +.B next\-history (C\-n) +Fetch the next command from the history list, moving forward in the +list. +.TP +.B beginning\-of\-history (M\-<) +Move to the first line in the history. +.TP +.B end\-of\-history (M\->) +Move to the end of the input history, i.e., the line currently being +entered. +.TP +.B 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. +.TP +.B forward\-search\-history (C\-s) +Search forward starting at the current line and moving `down' through +the history as necessary. This is an incremental search. +.TP +.B non\-incremental\-reverse\-search\-history (M\-p) +Search backward through the history starting at the current line +using a non-incremental search for a string supplied by the user. +.TP +.B non\-incremental\-forward\-search\-history (M\-n) +Search forward through the history using a non-incremental search for +a string supplied by the user. +.TP +.B history\-search\-forward +Search forward through the history for the string of characters +between the start of the current line and the current cursor +position (the \fIpoint\fP). +This is a non-incremental search. +.TP +.B history\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the point. +This is a non-incremental search. +.TP +.B yank\-nth\-arg (M\-C\-y) +Insert the first argument to the previous command (usually +the second word on the previous line) at point (the current +cursor position). With an argument +.IR n , +insert the \fIn\fPth word from the previous command (the words +in the previous command begin with word 0). A negative argument +inserts the \fIn\fPth word from the end of the previous command. +.TP +.B +yank\-last\-arg (M\-.\^, M\-_\^) +Insert the last argument to the previous command (the last word of +the previous history entry). With an argument, +behave exactly like \fByank\-nth\-arg\fP. +.TP +.B shell\-expand\-line (M\-C\-e) +Expand the line the way the shell does when it reads it. This +performs alias and history expansion as well as all of the shell +word expansions. See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B history\-expand\-line (M\-^) +Perform history expansion on the current line. See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B insert\-last\-argument (M\-.\^, M\-_\^) +A synonym for \fByank\-last\-arg\fP. +.TP +.B operate\-and\-get\-next (C\-o) +Accept the current line for execution and fetch the next line +relative to the current line from the history for editing. Any +argument is ignored. +.PD +.SS Commands for Changing Text +.PP +.PD 0 +.TP +.B delete\-char (C\-d) +Delete the character under the cursor. If point is at the +beginning of the line, there are no characters in the line, and +the last character typed was not +.BR C\-d , +then return +.SM +.BR EOF . +.TP +.B backward\-delete\-char (Rubout) +Delete the character behind the cursor. When given a numeric argument, +save the deleted text on the kill ring. +.TP +.B quoted\-insert (C\-q, C\-v) +Add the next character that you type to the line verbatim. This is +how to insert characters like \fBC\-q\fP, for example. +.TP +.B tab\-insert (C\-v TAB) +Insert a tab character. +.TP +.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...) +Insert the character typed. +.TP +.B 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 arguments don't work. +.TP +.B 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. +.TP +.B upcase\-word (M\-u) +Uppercase the current (or following) word. With a negative argument, +do the previous word, but do not move point. +.TP +.B downcase\-word (M\-l) +Lowercase the current (or following) word. With a negative argument, +do the previous word, but do not move point. +.TP +.B capitalize\-word (M\-c) +Capitalize the current (or following) word. With a negative argument, +do the previous word, but do not move point. +.PD +.SS Killing and Yanking +.PP +.PD 0 +.TP +.B kill\-line (C\-k) +Kill the text from the current cursor position to the end of the line. +.TP +.B backward\-kill\-line (C\-x Rubout) +Kill backward to the beginning of the line. +.TP +.B unix\-line\-discard (C\-u) +Kill backward from point to the beginning of the line. +.\" There is no real difference between this and backward-kill-line +.TP +.B kill\-whole\-line +Kill all characters on the current line, no matter where the +cursor is. +.TP +.B 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. Word boundaries are the same as +those used by \fBforward\-word\fP. +.TP +.B backward\-kill\-word (M\-Rubout) +Kill the word behind the cursor. Word boundaries are the same as +those used by \fBbackward\-word\fP. +.TP +.B unix\-word\-rubout (C\-w) +Kill the word behind the cursor, using white space as a word boundary. +The word boundaries are different from \fBbackward\-kill\-word\fP. +.TP +.B delete\-horizontal\-space (M\-\e) +Delete all spaces and tabs around point. +.TP +.B kill\-region +Kill the text between the point and \fImark\fP (saved cursor position). +This text is referred to as the \fIregion\fP. +.TP +.B copy\-region\-as\-kill +Copy the text in the region to the kill buffer. +.TP +.B copy\-backward\-word +Copy the word before point to the kill buffer. +.TP +.B copy\-forward\-word +Copy the word following point to the kill buffer. +.TP +.B yank (C\-y) +Yank the top of the kill ring into the buffer at the cursor. +.TP +.B yank\-pop (M\-y) +Rotate the kill ring, and yank the new top. Only works following +.B yank +or +.BR yank\-pop . +.PD +.SS Numeric Arguments +.PP +.PD 0 +.TP +.B 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. +.TP +.B universal\-argument +Each time this is executed, the argument count is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four. +.PD +.SS Completing +.PP +.PD 0 +.TP +.B complete (TAB) +Attempt to perform completion on the text before point. +.B Bash +attempts completion treating the text as a variable (if the +text begins with \fB$\fP), username (if the text begins with +\fB~\fP), hostname (if the text begins with \fB@\fP), or +command (including aliases and functions) in turn. If none +of these produces a match, filename completion is attempted. +.TP +.B possible\-completions (M\-?) +List the possible completions of the text before point. +.TP +.B insert\-completions (M\-*) +Insert all completions of the text before point +that would have been generated by +\fBpossible\-completions\fP. +.TP +.B complete\-filename (M\-/) +Attempt filename completion on the text before point. +.TP +.B possible\-filename\-completions (C\-x /) +List the possible completions of the text before point, +treating it as a filename. +.TP +.B complete\-username (M\-~) +Attempt completion on the text before point, treating +it as a username. +.TP +.B possible\-username\-completions (C\-x ~) +List the possible completions of the text before point, +treating it as a username. +.TP +.B complete\-variable (M\-$) +Attempt completion on the text before point, treating +it as a shell variable. +.TP +.B possible\-variable\-completions (C\-x $) +List the possible completions of the text before point, +treating it as a shell variable. +.TP +.B complete\-hostname (M\-@) +Attempt completion on the text before point, treating +it as a hostname. +.TP +.B possible\-hostname\-completions (C\-x @) +List the possible completions of the text before point, +treating it as a hostname. +.TP +.B complete\-command (M\-!) +Attempt completion on the text before point, treating +it as a command name. Command completion attempts to +match the text against aliases, reserved words, shell +functions, builtins, and finally executable filenames, +in that order. +.TP +.B possible\-command\-completions (C\-x !) +List the possible completions of the text before point, +treating it as a command name. +.TP +.B dynamic\-complete\-history (M\-TAB) +Attempt completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. +.TP +.B complete\-into\-braces (M\-{) +Perform filename completion and return the list of possible completions +enclosed within braces so the list is available to the shell (see +.B Brace Expansion +above). +.PD +.SS Keyboard Macros +.PP +.PD 0 +.TP +.B start\-kbd\-macro (C\-x (\^) +Begin saving the characters typed into the current keyboard macro. +.TP +.B end\-kbd\-macro (C\-x )\^) +Stop saving the characters typed into the current keyboard macro +and store the definition. +.TP +.B call\-last\-kbd\-macro (C\-x e) +Re-execute the last keyboard macro defined, by making the characters +in the macro appear as if typed at the keyboard. +.PD +.SS Miscellaneous +.PP +.PD 0 +.TP +.B re\-read\-init\-file (C\-x C\-r) +Read in the contents of the \fIinputrc\fP file, and incorporate +any bindings or variable assignments found there. +.TP +.B abort (C\-g) +Abort the current editing command and +ring the terminal's bell (subject to the setting of +.BR bell\-style ). +.TP +.B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...) +If the metafied character \fIx\fP is lowercase, run the command +that is bound to the corresponding uppercase character. +.TP +.B prefix\-meta (ESC) +Metafy the next character typed. +.SM +.B ESC +.B f +is equivalent to +.BR Meta\-f . +.TP +.B undo (C\-_, C\-x C\-u) +Incremental undo, separately remembered for each line. +.TP +.B revert\-line (M\-r) +Undo all changes made to this line. This is like typing the +.B undo +command enough times to return the line to its initial state. +.TP +.B tilde\-expand (M\-~) +Perform tilde expansion on the current word. +.TP +.B set\-mark (C\-@, M\-<space>) +Set the mark to the current point. If a +numeric argument is supplied, the mark is set to that position. +.TP +.B exchange\-point\-and\-mark (C\-x C\-x) +Swap the point with the mark. The current cursor position is set to +the saved position, and the old cursor position is saved as the mark. +.TP +.B character\-search (C\-]) +A character is read and point is moved to the next occurrence of that +character. A negative count searches for previous occurrences. +.TP +.B character\-search\-backward (M\-C\-]) +A character is read and point is moved to the previous occurrence of that +character. A negative count searches for subsequent occurrences. +.TP +.B insert\-comment (M\-#) +The value of the +.B readline +.B comment\-begin +variable is inserted at the beginning of the current line, and the line +is accepted as if a newline had been typed. This makes the current line +a shell comment. +.TP +.B glob\-expand\-word (C\-x *) +The word before point is treated as a pattern for pathname expansion, +and the list of matching file names is inserted, replacing the word. +.TP +.B glob\-list\-expansions (C\-x g) +The list of expansions that would have been generated by +.B glob\-expand\-word +is displayed, and the line is redrawn. +.TP +.B dump\-functions +Print all of the functions and their key bindings to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-variables +Print all of the settable readline variables and their values to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-macros +Print all of the readline key sequences bound to macros and the +strings they ouput. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B display\-shell\-version (C\-x C\-v) +Display version information about the current instance of +.BR bash . +.PD +.SH HISTORY +When the +.B -o history +option to the +.B set +builtin is enabled, the shell provides access to the +\fIcommand history\fP, +the list of commands previously typed. The text of the last +.SM +.B HISTSIZE +commands (default 500) is saved in a history list. The shell +stores each command in the history list prior to parameter and +variable expansion (see +.SM +.B EXPANSION +above) but after history expansion is performed, subject to the +values of the shell variables +.SM +.B HISTIGNORE +and +.SM +.BR HISTCONTROL . +On startup, the history is initialized from the file named by +the variable +.SM +.B HISTFILE +(default \fI~/.bash_history\fP). +.SM +.B HISTFILE +is truncated, if necessary, to contain no more than +.SM +.B HISTFILESIZE +lines. +When an interactive shell exits, the last +.SM +.B HISTSIZE +lines are copied from the history list to +.SM +.BR HISTFILE . +If the +.B histappend +shell option is enabled +(see the description of +.B shopt +under +.SM +.B "SHELL BUILTIN COMMANDS" +below), the lines are appended to the history file, +otherwise the history file is overwritten. +If +.SM +.B HISTFILE +is unset, or if the history file is unwritable, the history is +not saved. After saving the history, the history file is truncated +to contain no more than +.SM +.B HISTFILESIZE +lines. If +.SM +.B HISTFILESIZE +is not set, no truncation is performed. +.PP +The builtin command +.B fc +(see +.SM +.B SHELL BUILTIN COMMANDS +below) may be used to list or edit and re-execute a portion of +the history list. +The +.B history +builtin can be used to display or modify the history list and +manipulate the history file. +When using the command-line editing, search commands +are available in each editing mode that provide access to the +history list. +.PP +The shell allows control over which commands are saved on the history +list. The +.SM +.B HISTCONTROL +and +.SM +.B HISTIGNORE +variables may be set to cause the shell to save only a subset of the +commands entered. +The +.B cmdhist +shell option, if enabled, causes the shell to attempt to save each +line of a multi-line command in the same history entry, adding +semicolons where necessary to preserve syntactic correctness. +The +.B lithist +shell option causes the shell to save the command with embedded newlines +instead of semicolons. See the description of the +.B shopt +builtin below under +.SM +.B "SHELL BUILTIN COMMANDS" +for information on setting and unsetting shell options. +.SH "HISTORY EXPANSION" +.PP +The shell supports a history expansion feature that +is similar to the history expansion in +.BR csh. +This section describes what syntax features are available. This +feature is enabled by default for interactive shells, and can be +disabled using the +.B \+H +option to the +.B set +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). Non-interactive shells do not perform history expansion +by default. +.PP +History expansions introduce words from the history list into +the input stream, making it easy to repeat commands, insert the +arguments to a previous command into the current input line, or +fix errors in previous commands quickly. +.PP +History expansion is performed immediately after a complete line +is read, before the shell breaks it into words. +It takes place in two parts. +The first is to determine 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 the \fIevent\fP, +and the portions of that line that are acted upon are \fIwords\fP. +Various \fImodifiers\fP are available to manipulate the selected words. +The line is broken into words in the same fashion as when reading input, +so that several \fImetacharacter\fP-separated words surrounded by +quotes are considered as one word. +History expansions are introduced by the appearance of the +history expansion character, which is \^\fB!\fP\^ by default. +Only backslash (\^\fB\e\fP\^) and single quotes can quote +the history expansion character. +.PP +Several shell options settable with the +.B shopt +builtin may be used to tailor the behavior of history expansion. +If the +.B histverify +shell option is enabled (see the description of the +.B shopt +builtin), and +.B readline +is being used, history substitutions are not immediately passed to +the shell parser. +Instead, the expanded line is reloaded into the +.B readline +editing buffer for further modification. +If +.B readline +is being used, and the +.B histreedit +shell option is enabled, a failed history substitution will be reloaded +into the +.B readline +editing buffer for correction. +The +.B \-p +option to the +.B history +builtin command may be used to see what a history expansion will +do before using it. +The +.B \-s +option to the +.B history +builtin may be used to add commands to the end of the history list +without actually executing them, so that they are available for +subsequent recall. +.PP +The shell allows control of the various characters used by the +history expansion mechanism (see the description of +.B histchars +above under +.BR "Shell Variables" ). +.SS Event Designators +.PP +An event designator is a reference to a command line entry in the +history list. +.PP +.PD 0 +.TP +.B ! +Start a history substitution, except when followed by a +.BR blank , +newline, = or (. +.TP +.B !\fIn\fR +Refer to command line +.IR n . +.TP +.B !\-\fIn\fR +Refer to the current command line minus +.IR n . +.TP +.B !! +Refer to the previous command. This is a synonym for `!\-1'. +.TP +.B !\fIstring\fR +Refer to the most recent command starting with +.IR string . +.TP +.B !?\fIstring\fR\fB[?]\fR +Refer to the most recent command containing +.IR string . +The trailing \fB?\fP may be omitted if +.I string +is followed immediately by a newline. +.TP +.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u +Quick substitution. Repeat the last command, replacing +.I string1 +with +.IR string2 . +Equivalent to +``!!:s/\fIstring1\fP/\fIstring2\fP/'' +(see \fBModifiers\fP below). +.TP +.B !# +The entire command line typed so far. +.PD +.SS Word Designators +.PP +Word designators are used to select desired words from the event. +A +.B : +separates the event specification from the word designator. +It can be omitted if the word designator begins with a +.BR ^ , +.BR $ , +.BR * , +.BR \- , +or +.BR % . +Words are numbered from the beginning of the line, +with the first word being denoted by 0 (zero). +Words are inserted into the current line separated by single spaces. +.PP +.PD 0 +.TP +.B 0 (zero) +The zeroth word. For the shell, this is the command +word. +.TP +.I n +The \fIn\fRth word. +.TP +.B ^ +The first argument. That is, word 1. +.TP +.B $ +The last argument. +.TP +.B % +The word matched by the most recent `?\fIstring\fR?' search. +.TP +.I x\fB\-\fPy +A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. +.TP +.B * +All of the words but the zeroth. This is a synonym +for `\fI1\-$\fP'. It is not an error to use +.B * +if there is just one +word in the event; the empty string is returned in that case. +.TP +.B x* +Abbreviates \fIx\-$\fP. +.TP +.B x\- +Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. +.PD +.PP +If a word designator is supplied without an event specification, the +previous command is used as the event. +.SS Modifiers +.PP +After the optional word designator, there may appear a sequence of +one or more of the following modifiers, each preceded by a `:'. +.PP +.PD 0 +.PP +.TP +.B h +Remove a trailing file name component, leaving only the head. +.TP +.B t +Remove all leading file name components, leaving the tail. +.TP +.B r +Remove a trailing suffix of the form \fI.xxx\fP, leaving the +basename. +.TP +.B e +Remove all but the trailing suffix. +.TP +.B p +Print the new command but do not execute it. +.TP +.B q +Quote the substituted words, escaping further substitutions. +.TP +.B x +Quote the substituted words as with +.BR q , +but break into words at +.B blanks +and newlines. +.TP +.B s/\fIold\fP/\fInew\fP/ +Substitute +.I new +for the first occurrence of +.I old +in the event line. Any delimiter can be used in place of /. The +final delimiter is optional if it is the last character of the +event line. The delimiter may be quoted in +.I old +and +.I new +with a single backslash. If & appears in +.IR new , +it is replaced by +.IR old . +A single backslash will quote the &. If +.I old +is null, it is set to the last +.I old +substituted, or, if no previous history substitutions took place, +the last +.I string +in a +.B !?\fIstring\fR\fB[?]\fR +search. +.TP +.B & +Repeat the previous substitution. +.TP +.B g +Cause changes to be applied over the entire event line. This is +used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') +or `\fB:&\fP'. If used with +`\fB:s\fP', any delimiter can be used +in place of /, and the final delimiter is optional +if it is the last character of the event line. +.PD +.SH "ARITHMETIC EVALUATION" +The shell allows arithmetic expressions to be evaluated, under +certain circumstances (see the \fBlet\fP builtin command and +\fBArithmetic Expansion\fP). +Evaluation +is done in long integers with no check for overflow, though division +by 0 is trapped and flagged as an error. The following list of +operators is grouped into levels of equal-precedence operators. +The levels are listed in order of decreasing precedence. +.PP +.PD 0 +.TP +.B \- + +unary minus and plus +.TP +.B ! ~ +logical and bitwise negation +.TP +.B * / % +multiplication, division, remainder +.TP +.B + \- +addition, subtraction +.TP +.B << >> +left and right bitwise shifts +.TP +.B <= >= < > +comparison +.TP +.B == != +equality and inequality +.TP +.B & +bitwise AND +.TP +.B ^ +bitwise exclusive OR +.TP +.B | +bitwise OR +.TP +.B && +logical AND +.TP +.B || +logical OR +.TP +.B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP +conditional evaluation +.TP +.B = *= /= %= += \-= <<= >>= &= ^= |= +assignment +.PD +.PP +Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. +The value of a parameter is coerced to a long integer within +an expression. A shell variable need not have its integer attribute +turned on to be used in an expression. +.PP +Constants with a leading 0 are interpreted as octal numbers. +A leading 0x or 0X denotes hexadecimal. +Otherwise, numbers take the form [\fIbase#\fP]n, where \fIbase\fP +is a decimal number between 2 and 64 representing the arithmetic +base, and \fIn\fP is a number in that base. +If \fIbase\fP is omitted, then base 10 is used. +The digits greater than 9 are represented by the lowercase letters, +the uppercase letters, _, and @, in that order. +If \fIbase\fP is less than or equal to 36, lowercase and uppercase +letters may be used interchangably to represent numbers between 10 +and 35. +.PP +Operators are evaluated in order of precedence. Sub-expressions in +parentheses are evaluated first and may override the precedence +rules above. +.SH "SHELL BUILTIN COMMANDS" +.\" start of bash_builtins +.zZ +.PP +Unless otherwise noted, each builtin command documented in this +section as accepting options preceded by +.B \- +accepts +.B \-\- +to signify the end of the options. +.sp .5 +.PD 0 +.TP +\fB:\fP [\fIarguments\fP] +.PD +No effect; the command does nothing beyond expanding +.I arguments +and performing any specified +redirections. A zero exit code is returned. +.TP +.PD 0 +\fB .\| \fP \fIfilename\fP [\fIarguments\fP] +.TP +\fBsource\fP \fIfilename\fP [\fIarguments\fP] +.PD +Read and execute commands from +.I filename +in the current +shell environment and return the exit status of the last command +executed from +.IR filename . +If +.I filename +does not contain a slash, file names in +.SM +.B PATH +are used to find the directory containing +.IR filename . +The file searched for in +.SM +.B PATH +need not be executable. The current directory is +searched if no file is found in +.SM +.BR PATH . +If the +.B sourcepath +option to the +.B shopt +builtin command is turned off, the +.SM +.B PATH +is not searched. +If any \fIarguments\fP are supplied, they become the positional +parameters when \fIfilename\fP is executed. Otherwise the positional +parameters are unchanged. +The return status is the status of the last command exited within +the script (0 if no commands are executed), and false if +.I filename +is not found. +.TP +\fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +\fBAlias\fP with no arguments or with the +.B \-p +option prints the list of aliases in the form +\fBalias\fP \fIname\fP=\fIvalue\fP on standard output. +When arguments are supplied, an alias is defined for +each \fIname\fP whose \fIvalue\fP is given. +A trailing space in \fIvalue\fP causes the next word to be +checked for alias substitution when the alias is expanded. +For each \fIname\fP in the argument list for which no \fIvalue\fP +is supplied, the name and value of the alias is printed. +\fBAlias\fP returns true unless a \fIname\fP is given for which +no alias has been defined. +.TP +\fBbg\fP [\fIjobspec\fP] +Place \fIjobspec\fP in the background, as if it had been started with +.BR & . +If \fIjobspec\fP is not present, the shell's notion of the +\fIcurrent job\fP is used. +.B bg +.I jobspec +returns 0 unless run when job control is disabled or, when run with +job control enabled, if \fIjobspec\fP was not found or started without +job control. +.TP +.PD 0 +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSV\fP] [\fB\-q\fP \fIname\fP] [\fB\-r\fP \fIkeyseq\fP] +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP +.PD +Display current +.B readline +key and function bindings, or bind a key sequence to a +.B readline +function or macro. The binding syntax accepted is identical to that of +.IR .inputrc , +but each binding must be passed as a separate argument; +e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'. Options, if supplied, have the +following meanings: +.RS +.PD 0 +.TP +.B \-m \fIkeymap\fP +Use +.I keymap +as the keymap to be affected by the subsequent bindings. +Acceptable +.I keymap +names are +\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, +vi\-command\fP, and +.IR vi\-insert . +\fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is +equivalent to \fIemacs\-standard\fP. +.TP +.B \-l +List the names of all \fBreadline\fP functions. +.TP +.B \-p +Display \fBreadline\fP function names and bindings in such a way +that they can be re-read. +.TP +.B \-P +List current \fBreadline\fP function names and bindings. +.TP +.B \-v +Display \fBreadline\fP variable names and values in such a way that they +can be re-read. +.TP +.B \-V +List current \fBreadline\fP variable names and values. +.TP +.B \-s +Display \fBreadline\fP key sequences bound to macros and the strings +they output in such a way that they can be re-read. +.TP +.B \-S +Display \fBreadline\fP key sequences bound to macros and the strings +they output. +.TP +.B \-f \fIfilename\fP +Read key bindings from \fIfilename\fP. +.TP +.B \-q \fIfunction\fP +Query about which keys invoke the named \fIfunction\fP. +.TP +.B \-r \fIkeyseq\fP +Remove any current binding for \fIkeyseq\fP. +.PD +.PP +The return value is 0 unless an unrecognized option is given or an +error occurred. +.RE +.TP +\fBbreak\fP [\fIn\fP] +Exit from within a +.BR for , +.BR while , +.BR until , +or +.B select +loop. If \fIn\fP is specified, break \fIn\fP levels. +.I n +must be \(>= 1. If +.I n +is greater than the number of enclosing loops, all enclosing loops +are exited. The return value is 0 unless the shell is not executing +a loop when +.B break +is executed. +.TP +\fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP] +Execute the specified shell builtin, passing it +.IR arguments , +and return its exit status. +This is useful when you wish to define a +function whose name is the same as a shell builtin, +but need the functionality of the +builtin within the function itself. The \fBcd\fP builtin is +commonly redefined this way. The return status is false if +.I shell\-builtin +is not a shell builtin command. +.TP +\fBcd\fP [\fB\-LP\fP] [\fIdir\fP] +Change the current directory to \fIdir\fP. The variable +.SM +.B HOME +is the +default +.IR dir . +The variable +.SM +.B CDPATH +defines the search path for the directory containing +.IR dir . +Alternative directory names in +.SM +.B CDPATH +are separated by a colon (:). A null directory name in +.SM +.B CDPATH +is the same as the current directory, i.e., ``\fB.\fP''. If +.I dir +begins with a slash (/), +then +.SM +.B CDPATH +is not used. The +.B \-P +option says to use the physical directory structure instead of +following symbolic links (see also the +.B \-P +option to the +.B set +builtin command); the +.B \-L +option forces symbolic links to be followed. An argument of +.B \- +is equivalent to +.SM +.BR $OLDPWD . +The return value is true if the directory was successfully changed; +false otherwise. +.TP +\fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...] +Run +.I command +with +.I args +suppressing the normal shell function lookup. Only builtin +commands or commands found in the +.SM +.B PATH +are executed. If the +.B \-p +option is given, the search for +.I command +is performed using a default value for +.B PATH +that is guaranteed to find all of the standard utilities. +If either the +.B \-V +or +.B \-v +option is supplied, a description of +.I command +is printed. The +.B \-v +option causes a single word indicating the command or file name +used to invoke +.I command +to be printed; the +.B \-V +option produces a more verbose description. +If the +.B \-V +or +.B \-v +option is supplied, the exit status is 0 if +.I command +was found, and 1 if not. If neither option is supplied and +an error occurred or +.I command +cannot be found, the exit status is 127. Otherwise, the exit status of the +.B command +builtin is the exit status of +.IR command . +.TP +\fBcontinue\fP [\fIn\fP] +Resume the next iteration of the enclosing +.BR for , +.BR while , +.BR until , +or +.B select +loop. +If +.I n +is specified, resume at the \fIn\fPth enclosing loop. +.I n +must be \(>= 1. If +.I n +is greater than the number of enclosing loops, the last enclosing loop +(the ``top-level'' loop) is resumed. The return value is 0 unless the +shell is not executing a loop when +.B continue +is executed. +.TP +.PD 0 +\fBdeclare\fP [\fB\-afFirx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP]] +.TP +\fBtypeset\fP [\fB\-afFirx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP]] +.PD +Declare variables and/or give them attributes. +If no \fIname\fPs are given then display the values of variables. +The +.B \-p +option will display the attributes and values of each +.IR name . +When +.B \-p +is used, additional options are ignored. +The +.B \-F +option inhibits the display of function definitions; only the +function name and attributes are printed. +The +.B \-F +option implies +.BR \-f . +The following options can +be used to restrict output to variables with the specified attribute or +to give variables attributes: +.RS +.PD 0 +.TP +.B \-a +Each \fIname\fP is an array variable (see +.B Arrays +above). +.TP +.B \-f +Use function names only. +.TP +.B \-i +The variable is treated as an integer; arithmetic evaluation (see +.SM +.B "ARITHMETIC EVALUATION" ") " +is performed when the variable is assigned a value. +.TP +.B \-r +Make \fIname\fPs readonly. These names cannot then be assigned values +by subsequent assignment statements. +.TP +.B \-x +Mark \fIname\fPs for export to subsequent commands via the environment. +.PD +.PP +Using `+' instead of `\-' +turns off the attribute instead, with the exception that \fB+a\fP +may not be used to destroy an array variable. When used in a function, +makes each +\fIname\fP local, as with the +.B local +command. The return value is 0 unless an illegal option is encountered, +an attempt is made to define a function using "\-f foo=bar", +an attempt is made to assign a value to a readonly variable, +an attempt is made to assign a value to an array variable without +using the compound assignment syntax (see +.B Arrays +above), one of the \fInames\fP is not a legal shell variable name, +an attempt is made to turn off readonly status for a readonly variable, +an attempt is made to turn off array status for an array variable, +or an attempt is made to display a non-existent function with \-f. +.RE +.TP +.B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP] +Without options, displays the list of currently remembered directories. +The default display is on a single line with directory names separated +by spaces. +Directories are added to the list with the +.B pushd +command; the +.B popd +command removes entries from the list. +.RS +.PD 0 +.TP +\fB+\fP\fIn\fP +Displays the \fIn\fPth entry counting from the left of the list +shown by +.B dirs +when invoked without options, starting with zero. +.TP +\fB\-\fP\fIn\fP +Displays the \fIn\fPth entry counting from the right of the list +shown by +.B dirs +when invoked without options, starting with zero. +.TP +.B \-c +Clears the directory stack by deleting all of the entries. +.TP +.B \-l +Produces a longer listing; the default listing format uses a +tilde to denote the home directory. +.TP +.B \-p +Print the directory stack with one entry per line. +.TP +.B \-v +Print the directory stack with one entry per line, +prefixing each entry with its index in the stack. +.PD +.PP +The return value is 0 unless an +illegal option is supplied or \fIn\fP indexes beyond the end +of the directory stack. +.RE +.TP +\fBdisown\fP [\fB\-h\fP] [\fIjobspec\fP ...] +Without options, each +.I jobspec +is removed from the table of active jobs. +If the \fB\-h\fP option is given, the job is not removed from the table, +but is marked so that +.SM +.B SIGHUP +is not sent to the job if the shell receives a +.SM +.BR SIGHUP . +If no +.I jobspec +is present, the \fIcurrent job\fP is used. The return value is +0 unless a +.I jobspec +does not specify a valid job. +.TP +\fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...] +Output the \fIarg\fPs, separated by spaces, followed by a newline. +The return status is always 0. +If \fB\-n\fP is specified, the trailing newline is +suppressed. If the \fB\-e\fP option is given, interpretation of +the following backslash-escaped characters is enabled. The +.B \-E +option disables the interpretation of these escape characters, +even on systems where they are interpreted by default. +.B echo +does not interpret +.B \-\- +to mean the end of options. +.B echo +interprets the following escape sequences: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ec +suppress trailing newline +.TP +.B \ee +an escape character +.TP +.B \ef +form feed +.TP +.B \en +new line +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\e +backslash +.TP +.B \ennn +the character whose ASCII code is \fInnn\fP (octal) +.PD +.RE +.TP +\fBenable\fP [\fB\-adnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...] +Enable and disable builtin shell commands. This allows +the execution of a disk command which has the same name as a shell +builtin without specifying a full file name. +If \fB\-n\fP is used, each \fIname\fP +is disabled; otherwise, +\fInames\fP are enabled. For example, to use the +.B test +binary found via the +.SM +.B PATH +instead of the shell builtin version, run +\f(CWenable -n test\fP. +The +.B \-f +option means to load the new builtin command +.I name +from shared object +.IR filename , +on systems that support dynamic loading. The +.B \-d +option will delete a builtin previously loaded with +.BR \-f . +If no \fIname\fP arguments are given, or if the +.B \-p +option is supplied, a list of shell builtins is printed. +With no other option arguments, the list consists of all enabled +shell builtins. +If \fB\-n\fP is supplied, only disabled builtins are printed. +If \fB\-a\fP is supplied, the list printed includes all builtins, with an +indication of whether or not each is enabled. +If \fB\-s\fP is supplied, the output is restricted to the POSIX +\fIspecial\fP builtins. +The return value is 0 unless a +.I name +is not a shell builtin or there is a problem loading a new builtin +from a shared object. +.TP +\fBeval\fP [\fIarg\fP ...] +The \fIarg\fPs are read and concatenated together into a single +command. This command is then read and executed by the shell, and +its exit status is returned as the value of +.BR eval . +If there are no +.IR args , +or only null arguments, +.B eval +returns 0. +.TP +\fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP] [\fIarguments\fP] +If +.I command +is specified, it replaces the shell. +No new process is created. The +.I arguments +become the arguments to \fIcommand\fP. +If the +.B \-l +option is supplied, +the shell places a dash in the zeroth arg passed to +.IR command . +This is what +.IR login (1) +does. The +.B \-c +option causes +.I command +to be executed with an empty environment. If +.B \-a +is supplied, the shell passes +.I name +as the zeroth argument to the executed command. If +.I command +cannot be executed for some reason, a non-interactive shell exits, +unless the shell option +.B execfail +is enabled, in which case it returns failure. +An interactive shell returns failure if the file cannot be executed. +If +.I command +is not specified, any redirections take effect in the current shell, +and the return status is 0. +.TP +\fBexit\fP [\fIn\fP] +Cause the shell to exit +with a status of \fIn\fP. If +.I n +is omitted, the exit status +is that of the last command executed. +A trap on +.SM +.B EXIT +is executed before the shell terminates. +.TP +.PD 0 +\fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ... +.TP +.B export \-p +.PD +The supplied +.I names +are marked for automatic export to the environment of +subsequently executed commands. If the +.B \-f +option is given, +the +.I names +refer to functions. +If no +.I names +are given, or if the +.B \-p +option is supplied, a list +of all names that are exported in this shell is printed. +The +.B \-n +option causes the export property to be removed from the +named variables. +.B export +returns an exit status of 0 unless an illegal option is +encountered, +one of the \fInames\fP is not a legal shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +.PD 0 +\fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-nlr\fP] [\fIfirst\fP] [\fIlast\fP] +.TP +\fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP] +.PD +Fix Command. In the first form, a range of commands from +.I first +to +.I last +is selected from the history list. +.I First +and +.I last +may be specified as a string (to locate the last 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 +.I last +is not specified it is set to +the current command for listing (so that +.B fc \-l \-10 +prints the last 10 commands) and to +.I first +otherwise. +If +.I first +is not specified it is set to the previous +command for editing and \-16 for listing. +.sp 1 +The +.B \-n +flag suppresses +the command numbers when listing. The +.B \-r +flag reverses the order of +the commands. If the +.B \-l +flag is given, +the commands are listed on +standard output. Otherwise, the editor given by +.I ename +is invoked +on a file containing those commands. If +.I ename +is not given, the +value of the +.SM +.B FCEDIT +variable is used, and +the value of +.SM +.B EDITOR +if +.SM +.B FCEDIT +is not set. If neither variable is set, +.FN vi +is used. When editing is complete, the edited commands are +echoed and executed. +.sp 1 +In the second form, \fIcommand\fP is re-executed after each instance +of \fIpat\fP is replaced by \fIrep\fP. +A useful alias to use with this is +.if n ``r=fc -s'', +.if t \f(CWr='fc \-s'\fP, +so that typing +.if n ``r cc'' +.if t \f(CWr cc\fP +runs the last command beginning with +.if n ``cc'' +.if t \f(CWcc\fP +and typing +.if n ``r'' +.if t \f(CWr\fP +re-executes the last command. +.sp 1 +If the first form is used, the return value is 0 unless an illegal +option is encountered or +.I first +or +.I last +specify history lines out of range. +If the +.B \-e +option is supplied, the return value is the value of the last +command executed or failure if an error occurs with the temporary +file of commands. If the second form is used, the return status +is that of the command re-executed, unless +.I cmd +does not specify a valid history line, in which case +.B fc +returns failure. +.TP +\fBfg\fP [\fIjobspec\fP] +Place +.I jobspec +in the foreground, and make it the current job. If +.I jobspec +is not present, the shell's notion of the \fIcurrent job\fP is used. +The return value is that of the command placed into the foreground, +or failure if run when job control is disabled or, when run with +job control enabled, if +.I jobspec +does not specify a valid job or +.I jobspec +specifies a job that was started without job control. +.TP +\fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIargs\fP] +.B getopts +is used by shell procedures to parse positional parameters. +.I optstring +contains the option letters to be recognized; if a letter +is followed by a colon, the option is expected to have an +argument, which should be separated from it by white space. +Each time it is invoked, +.B getopts +places the next option in the shell variable +.IR name , +initializing +.I name +if it does not exist, +and the index of the next argument to be processed into the +variable +.SM +.BR OPTIND . +.SM +.B OPTIND +is initialized to 1 each time the shell or a shell script +is invoked. When an option requires an argument, +.B getopts +places that argument into the variable +.SM +.BR OPTARG . +The shell does not reset +.SM +.B OPTIND +automatically; it must be manually reset between multiple +calls to +.B getopts +within the same shell invocation if a new set of parameters +is to be used. +.sp 1 +.B getopts +can report errors in two ways. If the first character of +.I optstring +is a colon, +.I silent +error reporting is used. In normal operation diagnostic messages +are printed when illegal options or missing option arguments are +encountered. +If the variable +.SM +.B OPTERR +is set to 0, no error message will be displayed, even if the first +character of +.I optstring +is not a colon. +.sp 1 +If an illegal option is seen, +.B getopts +places ? into +.I name +and, if not silent, +prints an error message and unsets +.SM +.BR OPTARG . +If +.B getopts +is silent, +the option character found is placed in +.SM +.B OPTARG +and no diagnostic message is printed. +.sp 1 +If a required argument is not found, and +.B getopts +is not silent, +a question mark (\^\fB?\fP\^) is placed in +.IR name , +.B OPTARG +is unset, and a diagnostic message is printed. +If +.B getopts +is silent, then a colon (\^\fB:\fP\^) is placed in +.I name +and +.SM +.B OPTARG +is set to the option character found. +.sp 1 +.B getopts +normally parses the positional parameters, but if more arguments are +given in +.IR args , +.B getopts +parses those instead. +.B getopts +returns true if an option, specified or unspecified, is found. +It returns false if the end of options is encountered or an +error occurs. +.TP +\fBhash\fP [\fB\-r\fP] [\fB\-p\fP \fIfilename\fP] [\fIname\fP] +For each +.IR name , +the full file name of the command is determined by searching +the directories in +.B $PATH +and remembered. +If the +.B \-p +option is supplied, no path search is performed, and +.I filename +is used as the full file name of the command. +The +.B \-r +option causes the shell to forget all +remembered locations. If no arguments are given, information +about remembered commands is printed. +The return status is true unless a +.I name +is not found or an illegal option is supplied. +.TP +\fBhelp\fP [\fIpattern\fP] +Display helpful information about builtin commands. If +.I pattern +is specified, +.B help +gives detailed help on all commands matching +.IR pattern ; +otherwise help for all the builtins and shell control structures +is printed. The return status is 0 unless no command matches +.IR pattern . +.TP +.PD 0 +\fBhistory\fP [\fB\-c\fP] [\fIn\fP] +.TP +\fBhistory\fP \fB\-anrw\fP [\fIfilename\fP] +.TP +\fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP] +.TP +\fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP] +.PD +With no options, display the command +history list with line numbers. Lines listed +with a +.B * +have been modified. An argument of +.I n +lists only the last +.I n +lines. If \fIfilename\fP is supplied, it is used as the +name of the history file; if not, the value of +.SM +.B HISTFILE +is used. Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-a +Append the ``new'' history lines (history lines entered since the +beginning of the current \fBbash\fP session) to the history file. +.TP +.B \-n +Read the history lines not already read from the history +file into the current history list. These are lines +appended to the history file since the beginning of the +current \fBbash\fP session. +.TP +.B \-r +Read the contents of the history file +and use them as the current history. +.TP +.B \-w +Write the current history to the history file, overwriting the +history file's contents. +.TP +.B \-c +Clear the history list by deleting all the entries. +.TP +.B \-p +Perform history substitution on the following \fIargs\fP and display +the result on the standard output. +Does not store the results in the history list. +Each \fIarg\fP must be quoted to disable normal history expansion. +.TP +.B \-s +Store the +.I args +in the history list as a single entry. The last command in the +history list is removed before the +.I args +are added. +.PD +.PP +The return value is 0 unless an illegal option is encountered or an +error occurs while reading or writing the history file. +.RE +.TP +.PD 0 +\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ] +.TP +\fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ] +.PD +The first form lists the active jobs. The options have the following +meanings: +.RS +.PD 0 +.TP +.B \-l +List process IDs +in addition to the normal information. +.TP +.B \-p +List only the process ID of the job's process group +leader. +.TP +.B \-n +Display information only about jobs that have changed status since +the user was last notified of their status. +.TP +.B \-r +Restrict output to running jobs. +.TP +.B \-s +Restrict output to stopped jobs. +.PD +.PP +If +.I jobspec +is given, output is restricted to information about that job. +The return status is 0 unless an illegal option is encountered +or an illegal +.I jobspec +is supplied. +.PP +If the +.B \-x +option is supplied, +.B jobs +replaces any +.I jobspec +found in +.I command +or +.I args +with the corresponding process group ID, and executes +.I command +passing it +.IR args , +returning its exit status. +.RE +.TP +.PD 0 +\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ... +.TP +\fBkill\fP \fB\-l\fP [\fIsignum\fP | \fIsigspec\fP] +.PD +Send the signal named by +.I sigspec +or +.I signum +to the processes named by +.I pid +or +.IR jobspec . +.I sigspec +is either a signal name such as +.SM +.B SIGKILL +or a signal number; +.I signum +is a signal number. If +.I sigspec +is a signal name, the name may be +given with or without the +.SM +.B SIG +prefix. +If +.I sigspec +is not present, then +.SM +.B SIGTERM +is assumed. An argument of +.B \-l +lists the signal names. If any arguments are supplied when +.B \-l +is given, the names of the specified signals are listed, and +the return status is 0. The arguments to +.B \-l +may be either signal names or signal numbers; if signal names +are given, the corresponding signal number is displayed. +.B kill +returns true if at least one signal was successfully sent, or false +if an error occurs or an illegal option is encountered. +.TP +\fBlet\fP \fIarg\fP [\fIarg\fP ...] +Each +.I arg +is an arithmetic expression to be evaluated (see +.SM +.BR "ARITHMETIC EVALUATION" ). +If the last +.I arg +evaluates to 0, +.B let +returns 1; 0 is returned otherwise. +.TP +\fBlocal\fP [\fIname\fP[=\fIvalue\fP] ...] +For each argument, create a local variable named +.IR name , +and assign it +.IR value . +When +.B local +is used within a function, it causes the variable +.I name +to have a visible scope restricted to that function and its children. +With no operands, +.B local +writes a list of local variables to the standard output. It is +an error to use +.B local +when not within a function. The return status is 0 unless +.B local +is used outside a function, or an illegal +.I name +is supplied. +.TP +.B logout +Exit a login shell. +.TP +\fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP] +Removes entries from the directory stack. With no arguments, +removes the top directory from the stack, and performs a +.B cd +to the new top directory. +Arguments, if supplied, have the following meanings: +.RS +.PD 0 +.TP +\fB+\fP\fIn\fP +Removes the \fIn\fPth entry counting from the left of the list +shown by +.BR dirs , +starting with zero. For example: ``popd +0'' +removes the first directory, ``popd +1'' the second. +.TP +\fB\-\fP\fIn\fP +Removes the \fIn\fPth entry counting from the right of the list +shown by +.BR dirs , +starting with zero. For example: ``popd -0'' +removes the last directory, ``popd -1'' the next to last. +.TP +.B \-n +Suppresses the normal change of directory when removing directories +from the stack, so that only the stack is manipulated. +.PD +.PP +If the +.B popd +command is successful, a +.B dirs +is performed as well, and the return status is 0. +.B popd +returns false if an illegal option is encountered, the directory stack +is empty, a non-existent directory stack entry is specified, or the +directory change fails. +.RE +.TP +.PD 0 +\fBpushd\fP [\fB\-n\fP] [\fIdir\fP] +.TP +\fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP] +.PD +Adds a directory to the top of the directory stack, or rotates +the stack, making the new top of the stack the current working +directory. With no arguments, exchanges the top two directories +and returns 0, unless the directory stack is empty. +Arguments, if supplied, have the following meanings: +.RS +.PD 0 +.TP +\fB+\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the left of the list shown by +.BR dirs ) +is at the top. +.TP +\fB\-\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the right) is at the top. +.TP +.B \-n +Suppresses the normal change of directory when adding directories +to the stack, so that only the stack is manipulated. +.TP +.B dir +Adds +.I dir +to the directory stack at the top, making it the +new current working directory. +.PD +.PP +If the +.B pushd +command is successful, a +.B dirs +is performed as well. +If the first form is used, +.B pushd +returns 0 unless the cd to +.I dir +fails. With the second form, +.B pushd +returns 0 unless the directory stack is empty, +a non-existent directory stack element is specified, +or the directory change to the specified new current directory +fails. +.RE +.TP +\fBpwd\fP [\fB\-LP\fP] +Print the absolute file name of the current working directory. +The file name printed contains no symbolic links if the +.B \-P +option is supplied or the +.B \-o physical +option to the +.B set +builtin command is enabled. +If the +.B \-L +option is used, symbolic links are followed. +The return status is 0 unless an error occurs while +reading the name of the current directory. +.TP +\fBread\fP [\fB\-er\fP] [\fB\-a\fP \fIaname\fP] [\fB\-p\fP \fIprompt\fP] [\fIname\fP ...] +One line is read from the standard input, and the first word +is assigned to the first +.IR name , +the second word to the second +.IR name , +and so on, with leftover words assigned to the last +.IR name . +Only the characters in +.SM +.B IFS +are recognized as word delimiters. Options, if supplied, have the +following meanings: +.RS +.PD 0 +.TP +.B \-r +A backslash-newline pair is not ignored, and +the backslash is considered to be part of the line. +.TP +.B \-p +Display \fIprompt\fP, without a +trailing newline, before attempting to read any input. The prompt +is displayed only if input is coming from a terminal. +.TP +.B \-a +The words are assigned to sequential indices +of the array variable +.IR aname , +starting at 0. +.I aname +is unset before any new values are assigned. +.TP +.B \-e +If the standard input +is coming from a terminal, +.B readline +(see +.SM +.B READLINE +above) is used to obtain the line. +.PD +.PP +If no +.I names +are supplied, the line read is assigned to the variable +.SM +.BR REPLY . +The return code is zero, unless end-of-file is encountered. +.RE +.TP +\fBreadonly\fP [\fB\-apf\fP] [\fIname\fP ...] +.PD +The given +\fInames\fP are marked readonly; the values of these +.I names +may not be changed by subsequent assignment. +If the +.B \-f +option is supplied, the functions corresponding to the +\fInames\fP are so +marked. +The +.B \-a +option restricts the variables to arrays. +If no +.I name +arguments are given, or if the +.B \-p +option is supplied, a list of all readonly names is printed. +The return status is 0 unless an illegal option is encountered, +one of the +.I names +is not a legal shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +\fBreturn\fP [\fIn\fP] +Causes a function to exit with the return value specified by +.IR n . +If +.I n +is omitted, the return status is that of the last command +executed in the function body. If used outside a function, +but during execution of a script by the +.B . +(\fBsource\fP) command, it causes the shell to stop executing +that script and return either +.I n +or the exit status of the last command executed within the +script as the exit status of the script. If used outside a +function and not during execution of a script by \fB.\fP\^, +the return status is false. +.TP +\fBset\fP [\fB\-\-abefhkmnptuvxBCHP\fP] [\fB\-o\fP \fIoption\fP] [\fIarg\fP ...] +Without options, the name and value of each shell variable are displayed +in a format that can be re-used as input. +When options are specified, they set or unset shell attributes. +Any arguments remaining after the options are processed are treated +as values for the positional parameters and are assigned, in order, to +.BR $1 , +.BR $2 , +.B ... +.BR $\fIn\fP . +Options, if specified, have the following meanings: +.RS +.PD 0 +.TP 8 +.B \-a +Automatically mark variables which are modified or created for export +to the environment of subsequent commands. +.TP 8 +.B \-b +Report the status of terminated background jobs +immediately, rather than before the next primary prompt. This is +effective only when job control is enabled. +.TP 8 +.B \-e +Exit immediately if a \fIsimple command\fP (see +.SM +.B SHELL GRAMMAR +above) exits with a non-zero status. The shell does not exit if the +command that fails is part of an +.I until +or +.I while +loop, +part of an +.I if +statement, part of a +.B && +or +.B \(bv\(bv +list, or if the command's return value is +being inverted via +.BR ! . +.TP 8 +.B \-f +Disable pathname expansion. +.TP 8 +.B \-h +Remember the location of commands as they are looked up for execution. +This is on by default. +.TP 8 +.B \-k +All arguments in the form of assignment statements +are placed in the environment for a command, not just +those that precede the command name. +.TP 8 +.B \-m +Monitor mode. Job control is enabled. This flag is on +by default for interactive shells on systems that support +it (see +.SM +.B JOB CONTROL +above). Background processes run in a separate process +group and a line containing their exit status is printed +upon their completion. +.TP 8 +.B \-n +Read commands but do not execute them. This may be used to +check a shell script for syntax errors. This is ignored by +interactive shells. +.TP 8 +.B \-o \fIoption\-name\fP +The \fIoption\-name\fP can be one of the following: +.RS +.TP 8 +.B allexport +Same as +.BR \-a . +.TP 8 +.B braceexpand +Same as +.BR \-B . +.TP 8 +.B emacs +Use an emacs-style command line editing interface. This is enabled +by default when the shell is interactive, unless the shell is started +with the +.B \-\-noediting +option. +.TP 8 +.B errexit +Same as +.BR \-e . +.TP 8 +.B hashall +Same as +.BR \-h . +.TP 8 +.B histexpand +Same as +.BR \-H . +.TP 8 +.B history +Enable command history, as described above under +.SM +.BR HISTORY . +This option is on by default in interactive shells. +.TP 8 +.B ignoreeof +The effect is as if the shell command \f(CWIGNOREEOF=10\fP had been executed +(see +.B Shell Variables +above). +.TP 8 +.B keyword +Same as +.BR \-k . +.TP 8 +.B monitor +Same as +.BR \-m . +.TP 8 +.B noclobber +Same as +.BR \-C . +.TP 8 +.B noexec +Same as +.BR \-n . +.TP 8 +.B noglob +Same as +.BR \-f . +.TP 8 +.B notify +Same as +.BR \-b . +.TP 8 +.B nounset +Same as +.BR \-u . +.TP 8 +.B onecmd +Same as +.BR \-t . +.TP 8 +.B physical +Same as +.BR \-P . +.TP 8 +.B posix +Change the behavior of +.B bash +where the default operation differs +from the POSIX 1003.2 standard to match the standard. +.TP 8 +.B privileged +Same as +.BR \-p . +.TP 8 +.B verbose +Same as +.BR \-v . +.TP 8 +.B vi +Use a vi-style command line editing interface. +.TP 8 +.B xtrace +Same as +.BR \-x . +.sp .5 +.PP +If +.B \-o +is supplied with no \fIoption\-name\fP, the values of the current options are +printed. +If +.B +o +is supplied with no \fIoption\-name\fP, a series of +.B set +commands to recreate the current option settings is displayed on +the standard output. +.RE +.TP 8 +.B \-p +Turn on +.I privileged +mode. In this mode, the +.B $ENV +file is not processed, and shell functions +are not inherited from the environment. This is enabled automatically +on startup if the effective user (group) id is not equal to the real +user (group) id. Turning this option off causes the effective user +and group ids to be set to the real user and group ids. +.TP 8 +.B \-t +Exit after reading and executing one command. +.TP 8 +.B \-u +Treat unset variables as an error when performing +parameter expansion. If expansion is attempted on an +unset variable, the shell prints an error message, and, +if not interactive, exits with a non-zero status. +.TP 8 +.B \-v +Print shell input lines as they are read. +.TP 8 +.B \-x +After expanding each \fIsimple command\fP, +display the expanded value of +.SM +.BR PS4 , +followed by the command and its expanded arguments. +.TP 8 +.B \-B +The shell performs brace expansion (see +.B Brace Expansion +above). This is on by default. +.TP 8 +.B \-C +If set, +.B bash +does not overwrite an existing file with the +.BR > , +.BR >& , +and +.B <> +redirection operators. This may be overridden when +creating output files by using the redirection operator +.B >| +instead of +.BR > . +.TP 8 +.B \-H +Enable +.B ! +style history substitution. This flag is on by +default when the shell is interactive. +.TP 8 +.B \-P +If set, the shell does not follow symbolic links when executing +commands such as +.B cd +that change the current working directory. It uses the +physical directory structure instead. By default, +.B bash +follows the logical chain of directories when performing commands +which change the current directory. +.TP 8 +.B \-\- +If no arguments follow this flag, then the positional parameters are +unset. Otherwise, the positional parameters are set to the +\fIarg\fPs, even if some of them begin with a +.BR \- . +.TP 8 +.B \- +Signal the end of options, cause all remaining \fIarg\fPs to be +assigned to the positional parameters. The +.B \-x +and +.B \-v +options are turned off. +If there are no \fIarg\fPs, +the positional parameters remain unchanged. +.PD +.PP +The flags are off by default +unless otherwise noted. +Using + rather than \- causes these flags +to be turned off. The +flags can also be specified as options to an +invocation of the shell. The current +set of flags may be found in +.BR $\- . +The return status is always true +unless an illegal option is encountered. +.RE +.TP +\fBshift\fP [\fIn\fP] +The positional parameters from \fIn\fP+1 ... are renamed to +.B $1 +.B .... +Parameters represented by the numbers \fB$#\fP +down to \fB$#\fP\-\fIn\fP+1 are unset. +.I n +must be a non-negative number less than or equal to \fB$#\fP. +If +.I n +is 0, no parameters are changed. +If +.I n +is not given, it is assumed to be 1. +If +.I n +is greater than \fB$#\fP, the positional parameters are not changed. +The return status is greater than zero if +.I n +is greater than +.B $# +or less than zero; otherwise 0. +.TP +\fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...] +Toggle the values of variables controlling optional shell behavior. +With no options, or with the +.B \-p +option, a list of all settable options is displayed, with +an indication of whether or not each is set. Other options have +the following meanings: +.RS +.PD 0 +.TP +.B \-s +Enable (set) each \fIoptname\fP. +.TP +.B \-u +Disable (unset) each \fIoptname\fP. +.TP +.B \-q +Suppresses normal output (quiet mode); the return status indicates +whether the \fIoptname\fP is set or unset. +If multiple \fIoptname\fP arguments are given with +.BR \-q , +the return status is zero if all \fIoptnames\fP are enabled; non-zero +otherwise. +.TP +.B \-o +Restricts the values of \fIoptname\fP to be those defined for the +.B \-o +option to the +.B set +builtin. +.PD +.PP +If either +.B \-s +or +.B \-u +is used with no \fIoptname\fP arguments, the display is limited to +those options which are set or unset, respectively. +Unless otherwise noted, the \fBshopt\fP options are disabled (unset) +by default. +.PP +The return status when listing options is zero if all \fIoptnames\fP +are enabled, non-zero otherwise. When setting or unsetting options, +the return status is zero unless an \fIoptname\fP is not a legal shell +option. +.PP +The list of \fBshopt\fP options is: +.if t .sp .5v +.if n .sp 1v +.PD 0 +.TP 8 +.B cdable_vars +If set, an argument to the +.B cd +builtin command that +is not a directory is assumed to be the name of a variable whose +value is the directory to change to. +.TP 8 +.B cdspell +If set, minor errors in the spelling of a directory component in a +.B cd +command will be corrected. +The errors checked for are transposed characters, +a missing character, and one character too many. +If a correction is found, the corrected file name is printed, +and the command proceeds. +This option is enabled by default, but is only used by interactive shells. +.TP 8 +.B checkhash +If set, \fBbash\fP checks that a command found in the hash +table exists before trying to execute it. If a hashed command no +longer exists, a normal path search is performed. +.TP 8 +.B checkwinsize +If set, \fBbash\fP checks the window size after each command +and, if necessary, updates the values of +.SM +.B LINES +and +.SM +.BR COLUMNS . +.TP 8 +.B cmdhist +If set, +.B bash +attempts to save all lines of a multiple-line +command in the same history entry. This allows +easy re-editing of multi-line commands. +.TP 8 +.B dotglob +If set, +.B bash +includes filenames beginning with a `.' in the results of pathname +expansion. +.TP 8 +.B execfail +If set, a non-interactive shell will not exit if +it cannot execute the file specified as an argument to the +.B exec +builtin command. An interactive shell does not exit if +.B exec +fails. +.TP 8 +.B expand_aliases +If set, aliases are expanded as described above under +.SM +.BR ALIASES . +This option is enabled by default for interactive shells. +.TP 8 +.B histappend +If set, the history list is appended to the file named by the value +of the +.B HISTFILE +variable when the shell exits, rather than overwriting the file. +.TP 8 +.B histreedit +If set, and +.B readline +is being used, a user is given the opportunity to re-edit a +failed history substitution. +.TP 8 +.B histverify +If set, and +.B readline +is being used, the results of history substitution are not immediately +passed to the shell parser. Instead, the resulting line is loaded into +the \fBreadline\fP editing buffer, allowing further modification. +.TP 8 +.B hostcomplete +If set, and +.B readline +is being used, bash will attempt to perform hostname completion when a +word beginning with \fB@\fP is being completed (see +.B Completing +under +.SM +.B READLINE +above). +This is enabled by default. +.TP 8 +.B interactive_comments +If set, allow a word beginning with +.B # +to cause that word and all remaining characters on that +line to be ignored in an interactive shell (see +.SM +.B COMMENTS +above). This option is enabled by default. +.TP 8 +.B lithist +If set, and the +.B cmdhist +option is enabled, multi-line commands are saved to the history with +embedded newlines rather than using semicolon separators where possible. +.TP 8 +.B mailwarn +If set, and a file that \fBbash\fP is checking for mail has been +accessed since the last time it was checked, the message ``The mail in +\fImailfile\fP has been read'' is displayed. +.TP 8 +.B nullglob +If set, +.B bash +allows patterns which match no +files (see +.B Pathname Expansion +above) +to expand to a null string, rather than themselves. +.TP 8 +.B promptvars +If set, prompt strings undergo variable and parameter expansion after +being expanded as described in +.SM +.B PROMPTING +above. This option is enabled by default. +.TP 8 +.B shift_verbose +If set, the +.B shift +builtin prints an error message when the shift count exceeds the +number of positional parameters. +.TP 8 +.B sourcepath +If set, the +\fBsource\fP (\fB.\fP) builtin uses the value of +.SM +.B PATH +to find the directory containing the file supplied as an argument. +This is enabled by default. +.RE +.TP +\fBsuspend\fP [\fB\-f\fP] +Suspend the execution of this shell until it receives a +.SM +.B SIGCONT +signal. The +.B \-f +option says not to complain if this is +a login shell; just suspend anyway. The return status is 0 unless +the shell is a login shell and +.B \-f +is not supplied, or if job control is not enabled. +.TP +.PD 0 +\fBtest\fP \fIexpr\fP +.TP +\fB[\fP \fIexpr\fP \fB]\fP +Return a status of 0 or 1 depending on +the evaluation of the conditional expression +.IR expr . +Expressions may be unary or binary. Unary +expressions are often used to examine the status of a file. There +are string operators and numeric comparison operators as well. Each +operator and operand must be a separate argument. If \fIfile\fP +is of the form /dev/fd/\fIn\fP, then file descriptor \fIn\fP is +checked. Expressions are composed of the following primaries: +.RS +.PD 0 +.TP +.B \-b \fIfile\fP +True if \fIfile\fP exists and is a block special file. +.TP +.B \-c \fIfile\fP +True if \fIfile\fP exists and is a character special file. +.TP +.B \-d \fIfile\fP +True if \fIfile\fP exists and is a directory. +.TP +.B \-e \fIfile\fP +True if \fIfile\fP exists. +.TP +.B \-f \fIfile\fP +True if \fIfile\fP exists and is a regular file. +.TP +.B \-g \fIfile\fP +True if \fIfile\fP exists and is set-group-id. +.TP +.B \-k \fIfile\fP +True if \fIfile\fP has its ``sticky'' bit set. +.TP +.B \-L \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP +.B \-p \fIfile\fP +True if \fIfile\fP exists and is a named pipe. +.TP +.B \-r \fIfile\fP +True if \fIfile\fP exists and is readable. +.TP +.B \-s \fIfile\fP +True if \fIfile\fP exists and has a size greater than zero. +.TP +.B \-S \fIfile\fP +True if \fIfile\fP exists and is a socket. +.TP +.B \-t \fIfd\fP +True if +.I fd +is opened on a terminal. +.TP +.B \-u \fIfile\fP +True if \fIfile\fP exists and its set-user-id bit is set. +.TP +.B \-w \fIfile\fP +True if \fIfile\fP exists and is writable. +.TP +.B \-x \fIfile\fP +True if \fIfile\fP exists and is executable. +.TP +.B \-O \fIfile\fP +True if \fIfile\fP exists and is owned by the effective user id. +.TP +.B \-G \fIfile\fP +True if \fIfile\fP exists and is owned by the effective group id. +.TP +\fIfile1\fP \-\fBnt\fP \fIfile2\fP +True if \fIfile1\fP is newer (according to +modification date) than \fIfile2\fP. +.TP +\fIfile1\fP \-\fBot\fP \fIfile2\fP +True if \fIfile1\fP is older than \fIfile2\fP. +.TP +\fIfile1\fP \fB\-ef\fP \fIfile2\fP +True if \fIfile1\fP and \fIfile2\fP have the same device and +inode numbers. +.TP +.B \-o \fIoptname\fP +True if shell option +.I optname +is enabled. +See the list of options under the description of the +.B \-o +option to the +.B set +builtin above. +.TP +.B \-z \fIstring\fP +True if the length of \fIstring\fP is zero. +.TP +.B \-n \fIstring\fP +.TP +\fIstring\fP +True if the length of +.I string +is non-zero. +.TP +\fIstring1\fP \fB=\fP \fIstring2\fP +True if the strings are equal. \fB==\fP may be used in place of +\fB=\fP. +.TP +\fIstring1\fP \fB!=\fP \fIstring2\fP +True if the strings are not equal. +.TP +\fIstring1\fP \fB<\fP \fIstring2\fP +True if \fIstring1\fP sorts before \fIstring2\fP lexicographically. +.TP +\fIstring1\fP \fB>\fP \fIstring2\fP +True if \fIstring1\fP sorts after \fIstring2\fP lexicographically. +.TP +.B ! \fIexpr\fP +True if +.I expr +is false. +.TP +\fIexpr1\fP \-\fBa\fP \fIexpr2\fP +True if both +.I expr1 +AND +.I expr2 +are true. +.TP +\fIexpr1\fP \-\fBo\fP \fIexpr2\fP +True if either +.I expr1 +OR +.I expr2 +is true. +.TP +.I \fIarg1\fP \fBOP\fP \fIarg2\fP +.SM +.B OP +is one of +.BR \-eq , +.BR \-ne , +.BR \-lt , +.BR \-le , +.BR \-gt , +or +.BR \-ge . +These arithmetic binary operators return true if \fIarg1\fP +is equal to, not equal to, less than, less than or equal to, +greater than, or greater than or equal to \fIarg2\fP, respectively. +.I Arg1 +and +.I arg2 +may be positive or negative integers. +.PD +.RE +.TP +.B times +Print the accumulated user and system times for the shell and +for processes run from the shell. The return status is 0. +.TP +\fBtrap\fP [\fB\-lp\fP] [\fIarg\fP] [\fIsigspec\fP] +The command +.I arg +is to be read and executed when the shell receives +signal(s) +.IR sigspec . +If +.I arg +is absent or +.BR \- , +all specified signals are +reset to their original values (the values they had +upon entrance to the shell). If +.I arg +is the null string this +signal is ignored by the shell and by the +commands it invokes. +If +.I arg +is +.B \-p +then the trap commands associated with +each +.I sigspec +are displayed. If no arguments are supplied or if +only +.B \-p +is given, +.B trap +prints the list of commands associated with each signal number. +.I sigspec +is either +a signal name defined in <\fIsignal.h\fP>, or a signal number. If +.I sigspec +is +.SM +.B EXIT +(0) the command +.I arg +is executed on exit from the shell. If +.I sigspec +is +.SM +.BR DEBUG , +the command +.I arg +is executed after every \fIsimple command\fP (see +.SM +.B SHELL GRAMMAR +above). +The +.B \-l +option causes the shell to print a list of signal names and +their corresponding numbers. +Signals ignored upon entry to the shell cannot be trapped or reset. +Trapped signals are reset to their original values in a child +process when it is created. The return status is false if any +.I sigspec +is invalid; otherwise +.B trap +returns true. +.TP +\fBtype\fP [\fB\-all\fP] [\fB\-type\fP | \fB\-path\fP] \fIname\fP [\fIname\fP ...] +With no options, +indicate how each +.I name +would be interpreted if used as a command name. +If the +.B \-type +flag is used, +.B type +prints a string which is one of +.IR alias , +.IR keyword , +.IR function , +.IR builtin , +or +.I file +if +.I name +is an alias, shell reserved word, function, builtin, or disk file, +respectively. +If the +.I name +is not found, then nothing is printed, and an exit status of false +is returned. +If the +.B \-path +flag is used, +.B type +either returns the name of the disk file +that would be executed if +.I name +were specified as a command name, +or nothing if +.B \-type +would not return +.IR file . +If a command is hashed, +.B \-path +prints the hashed value, not necessarily the file that appears +first in +.SM +.BR PATH . +If the +.B \-all +flag is used, +.B type +prints all of the places that contain +an executable named +.IR name . +This includes aliases and functions, +if and only if the +.B \-path +flag is not also used. +The table of hashed commands is not consulted +when using +.BR \-all . +.B type +accepts +.BR \-a , +.BR \-t , +and +.B \-p +in place of +.BR \-all , +.BR \-type , +and +.BR \-path , +respectively. +.B type +returns true if any of the arguments are found, false if +none are found. +.TP +\fBulimit\fP [\fB\-SHacdflmnpstuv\fP [\fIlimit\fP]] +Provides control over the resources available to the shell and to +processes started by it, on systems that allow such control. The +value of +.I limit +can be a number in the unit specified for the resource, or the +value +.BR unlimited . +The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is +set for the given resource. A hard limit cannot be increased once it +is set; a soft limit may be increased up to the value of the hard limit. +If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard +limits are set. +If +.I limit +is omitted, the current value of the soft limit of the resource is +printed, unless the \fB\-H\fP option is given. When more than one +resource is specified, the limit name and unit are printed before the value. +Other options are interpreted as follows: +.RS +.PD 0 +.TP +.B \-a +All current limits are reported +.TP +.B \-c +The maximum size of core files created +.TP +.B \-d +The maximum size of a process's data segment +.TP +.B \-f +The maximum size of files created by the shell +.TP +.B \-l +The maximum size that may be locked into memory +.TP +.B \-m +The maximum resident set size +.TP +.B \-n +The maximum number of open file descriptors (most systems do not +allow this value to be set) +.TP +.B \-p +The pipe size in 512-byte blocks (this may not be set) +.TP +.B \-s +The maximum stack size +.TP +.B \-t +The maximum amount of cpu time in seconds +.TP +.B \-u +The maximum number of processes available to a single user +.TP +.B \-v +The maximum amount of virtual memory available to the shell +.PD +.PP +If +.I limit +is given, it is the new value of the specified resource (the +.B \-a +option is display only). +If no option is given, then +.B \-f +is assumed. Values are in 1024-byte increments, except for +.BR \-t , +which is in seconds, +.BR \-p , +which is in units of 512-byte blocks, +and +.B \-n +and +.BR \-u , +which are unscaled values. The return status is 0 +unless an illegal option is encountered, a non-numeric argument +other than \fBunlimited\fP is supplied as \fIlimit\fP, or an +error occurs while setting a new limit. +.RE +.TP +\fBumask\fP [\fB\-S\fP] [\fImode\fP] +The user file-creation mask is set to +.IR mode . +If +.I mode +begins with a digit, it +is interpreted as an octal number; otherwise +it is interpreted as a symbolic mode mask similar +to that accepted by +.IR chmod (1). +If +.I mode +is omitted, or if the +.B \-S +option is supplied, the +current value of the mask is printed. +The +.B \-S +option causes the mask to be printed in symbolic form; the +default output is an octal number. +The return status is 0 if the mode was successfully changed or if +no \fImode\fP argument was supplied, and false otherwise. +.TP +\fBunalias\fP [\-\fBa\fP] [\fIname\fP ...] +Remove \fIname\fPs from the list of defined aliases. If +.B \-a +is supplied, all alias definitions are removed. The return +value is true unless a supplied +.I name +is not a defined alias. +.TP +\fBunset\fP [\-\fBfv\fP] [\fIname\fP ...] +For each +.IR name , +remove the corresponding variable or function. +If no options are supplied, or the +.B \-v +option is given, each +.I name +refers to a shell variable. +Read-only variables may not be unset. +If +.B \-f +is specifed, +each +.I name +refers to a shell function, and the function definition +is removed. +Each unset variable or function is removed from the environment +passed to subsequent commands. +If any of +.SM +.BR RANDOM , +.SM +.BR SECONDS , +.SM +.BR LINENO , +.SM +.BR HISTCMD , +or +.SM +.B DIRSTACK +are unset, they lose their special properties, even if they are +subsequently reset. The exit status is true unless a +.I name +does not exist or is readonly. +.TP +\fBwait\fP [\fIn\fP] +Wait for the specified process and return its termination +status. +.I n +may be a process +ID or a job specification; if a job spec is given, all processes +in that job's pipeline are waited for. If +.I n +is not given, all currently active child processes +are waited for, and the return status is zero. If +.I n +specifies a non-existent process or job, the return status is +127. Otherwise, the return status is the exit status of the last +process or job waited for. +.\" bash_builtins +.if \n(zZ=1 .ig zZ +.SH "RESTRICTED SHELL" +.PP +If +.B bash +is started with the name +.BR rbash , +or the +.B \-r +option is supplied at invocation, +the shell becomes restricted. +A restricted shell is used to +set up an environment more controlled than the standard shell. +It behaves identically to +.B bash +with the exception that the following are disallowed: +.IP \(bu +changing directories with \fBcd\fP +.IP \(bu +setting or unsetting the values of +.B SHELL +or +.B PATH +.IP \(bu +specifying command names containing +.B / +.IP \(bu +specifying a file name containing a +.B / +as an argument to the +.B . +builtin command +.IP \(bu +importing function definitions from the shell environment at startup +.IP \(bu +redirecting output using the >, >|, <>, >&, &>, and >> redirection operators +.IP \(bu +using the +.B exec +builtin command to replace the shell with another command +.IP \(bu +adding or deleting builtin commands with the +.B \-f +and +.B \-d +options to the +.B enable +builtin command +.IP \(bu +specifying the +.B \-p +option to the +.B command +builtin command +.IP \(bu +turning off restricted mode with +.BR "set +r" . +.PP +These restrictions are enforced after any startup files are read. +.PP +When a command that is found to be a shell script is executed (see +.SM +.B "COMMAND EXECUTION" +above), +.B rbash +turns off any restrictions in the shell spawned to execute the +script. +.SH "SEE ALSO" +.PD 0 +.TP +\fIBash Features\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey +.TP +\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE +.TP +\fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1) +.TP +\fIemacs\fP(1), \fIvi\fP(1) +.TP +\fIreadline\fP(3) +.PD +.SH FILES +.PD 0 +.TP +.FN /bin/bash +The \fBbash\fP executable +.TP +.FN /etc/profile +The systemwide initialization file, executed for login shells +.TP +.FN ~/.bash_profile +The personal initialization file, executed for login shells +.TP +.FN ~/.bashrc +The individual per-interactive-shell startup file +.TP +.FN ~/.inputrc +Individual \fIreadline\fP initialization file +.PD +.SH AUTHORS +Brian Fox, Free Software Foundation +.br +bfox@gnu.ai.MIT.Edu +.PP +Chet Ramey, Case Western Reserve University +.br +chet@ins.CWRU.Edu +.SH BUG REPORTS +If you find a bug in +.B bash, +you should report it. But first, you should +make sure that it really is a bug, and that it appears in the latest +version of +.B bash +that you have. +.PP +Once you have determined that a bug actually exists, use the +.I bashbug +command to submit a bug report. +If you have a fix, you are welcome to mail that +as well! +Suggestions and `philosophical' bug reports may be mailed +to \fPbug-bash\fP@\fIprep.ai.MIT.Edu\fP or posted to the Usenet +newsgroup +.BR gnu.bash.bug . +.PP +ALL bug reports should include: +.PP +.PD 0 +.TP 20 +The version number of \fBbash\fR +.TP +The hardware and operating system +.TP +The compiler used to compile +.TP +A description of the bug behaviour +.TP +A short script or `recipe' which exercises the bug +.PD +.PP +.I bashbug +inserts the first three items automatically into the template +it provides for filing a bug report. +.PP +Comments and bug reports concerning +this manual page should be directed to +.IR chet@ins.CWRU.Edu . +.SH BUGS +.PP +It's too big and too slow. +.PP +There are some subtle differences between +.B bash +and traditional versions of +.BR sh , +mostly because of the +.SM +.B POSIX +specification. +.PP +Aliases are confusing in some uses. +.PP +Shell builtin commands and functions are not stoppable/restartable. +.PP +Compound commands and command sequences of the form `a ; b ; c' +are not handled gracefully when process suspension is attempted. +When a process is stopped, the shell immediately executes the next +command in the sequence. +It suffices to place the sequence of commands between +parentheses to force it into a subshell, which may be stopped as +a unit. +.PP +Commands inside of \fB$(\fP...\fB)\fP command substitution are not +parsed until substitution is attempted. This will delay error +reporting until some time after the command is entered. +.PP +Array variables may not (yet) be exported. +.zZ diff --git a/doc/bashbug.1 b/doc/bashbug.1 new file mode 100644 index 00000000..39abaf2a --- /dev/null +++ b/doc/bashbug.1 @@ -0,0 +1,41 @@ +.TH BASHBUG 1 "1995 August 10" GNU +.SH NAME +bashbug \- report a bug in bash +.SH SYNOPSIS +\fBbashbug\fP [\fIaddress\fP] +.SH DESCRIPTION +.B bashbug +is a shell script to help the user compose and mail bug reports +concerning bash in a standard format. +.B bashbug +invokes the editor specified by the environment variable +.SM +.B EDITOR +on a temporary copy of the bug report format outline. The user must +fill in the appropriate fields and exit the editor. +.B bashbug +then mails the completed report to \fIbug-bash@prep.ai.mit.edu\fP, or +\fIaddress\fP. If the report cannot be mailed, it is saved in the +file \fIdead.bashbug\fP in the invoking user's home directory. +.PP +The bug report format outline consists of several sections. The first +section provides information about the machine, operating system, the +bash version, and the compilation environment. The second section +should be filled in with a description of the bug. The third section +should be a description of how to reproduce the bug. The optional +fourth section is for a proposed fix. Fixes are encouraged. +.SH ENVIRONMENT +.B bashbug +will utilize the following environment variables if they exist: +.TP +.B EDITOR +Specifies the preferred editor. If +.SM +.B EDITOR +is not set, +.B bashbug +defaults to +.BR emacs . +.TP +.B HOME +Directory in which the failed bug report is saved if the mail fails. diff --git a/doc/bashref.info b/doc/bashref.info new file mode 100644 index 00000000..6e4ecc12 --- /dev/null +++ b/doc/bashref.info @@ -0,0 +1,6513 @@ +This is Info file bashref.info, produced by Makeinfo-1.64 from the +input file ./bashref.texi. + +This text is a brief description of the features that are present in +the Bash shell. + +This is Edition 2.0, last updated 25 November 1996, +of `The GNU Bash Reference Manual', +for `Bash', Version 2.0. + +Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. + + +File: bashref.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +Bash Features +************* + + This text is a brief description of the features that are present in +the Bash shell. + + This is Edition 2.0, last updated 25 November 1996, of `The GNU Bash +Reference Manual', for `Bash', Version 2.0. + + Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc. + + 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. + + This manual is meant as a brief introduction to features found in +Bash. The Bash manual page should be used as the definitive reference +on shell behavior. + +* Menu: + +* Introduction:: An introduction to the shell. + +* Definitions:: Some definitions used in the rest of this + manual. + +* Basic Shell Features:: The shell "building blocks". + +* Bourne Shell Features:: Features similar to those found in the + Bourne shell. + +* Csh Features:: Features originally found in the + Berkeley C-Shell. + +* Korn Shell Features:: Features originally found in the Korn + Shell. + +* Bash Features:: Features found only in Bash. + +* Job Control:: A chapter describing what job control is + and how Bash allows you to use it. + +* Using History Interactively:: Chapter dealing with history expansion + rules. + +* Command Line Editing:: Chapter describing the command line + editing features. + +* Installing Bash:: How to build and install Bash on your system. + +* Reporting Bugs:: How to report bugs in Bash. + +* Builtin Index:: Index of Bash builtin commands. + +* Reserved Word Index:: Index of Bash reserved words. + +* Variable Index:: Quick reference helps you find the + variable you want. + +* Function Index:: Index of bindable Readline functions. + +* Concept Index:: General index for concepts described in + this manual. + + +File: bashref.info, Node: Introduction, Next: Definitions, Prev: Top, Up: Top + +Introduction +************ + +* Menu: + +* What is Bash?:: A short description of Bash. + +* What is a shell?:: A brief introduction to shells. + + +File: bashref.info, Node: What is Bash?, Next: What is a shell?, Up: Introduction + +What is Bash? +============= + + Bash is the shell, or command language interpreter, that will appear +in the GNU operating system. The name is an acronym for the +`Bourne-Again SHell', a pun on Steve Bourne, the author of the direct +ancestor of the current Unix shell `/bin/sh', which appeared in the +Seventh Edition Bell Labs Research version of Unix. + + Bash is an `sh'-compatible shell that incorporates useful features +from the Korn shell `ksh' and the C shell `csh'. It is ultimately +intended to be a conformant implementation of the IEEE POSIX Shell and +Tools specification (IEEE Working Group 1003.2). It offers functional +improvements over `sh' for both interactive and programming use. + + While the GNU operating system will include a version of `csh', Bash +will be the default shell. Like other GNU software, Bash is quite +portable. It currently runs on nearly every version of Unix and a few +other operating systems - independently-supported ports exist for OS/2 +and Windows NT. + + +File: bashref.info, Node: What is a shell?, Prev: What is Bash?, Up: Introduction + +What is a shell? +================ + + At its base, a shell is simply a macro processor that executes +commands. A Unix shell is both a command interpreter, which provides +the user interface to the rich set of Unix utilities, and a programming +language, allowing these utilitites to be combined. The shell reads +commands either from a terminal or a file. Files containing commands +can be created, and become commands themselves. These new commands +have the same status as system commands in directories like `/bin', +allowing users or groups to establish custom environments. + + A shell allows execution of Unix commands, both synchronously and +asynchronously. The "redirection" constructs permit fine-grained +control of the input and output of those commands, and the shell allows +control over the contents of their environment. Unix shells also +provide a small set of built-in commands ("builtins") implementing +functionality impossible (e.g., `cd', `break', `continue', and `exec'), +or inconvenient (`history', `getopts', `kill', or `pwd', for example) +to obtain via separate utilities. Shells may be used interactively or +non-interactively: they accept input typed from the keyboard or from a +file. All of the shell builtins are described in subsequent sections. + + While executing commands is essential, most of the power (and +complexity) of shells is due to their embedded programming languages. +Like any high-level language, the shell provides variables, flow +control constructs, quoting, and functions. + + Shells have begun offering features geared specifically for +interactive use rather than to augment the programming language. These +interactive features include job control, command line editing, history +and aliases. Each of these features is described in this manual. + + +File: bashref.info, Node: Definitions, Next: Basic Shell Features, Prev: Introduction, Up: Top + +Definitions +*********** + + These definitions are used throughout the remainder of this manual. + +`POSIX' + A family of open system standards based on Unix. Bash is + concerned with POSIX 1003.2, the Shell and Tools Standard. + +`blank' + A space or tab character. + +`builtin' + A command that is implemented internally by the shell itself, + rather than by an executable program somewhere in the file system. + +`control operator' + A `word' that performs a control function. It is a `newline' or + one of the following: `||', `&&', `&', `;', `;;', `|', `(', or `)'. + +`exit status' + The value returned by a command to its caller. + +`field' + A unit of text that is the result of one of the shell expansions. + After expansion, when executing a command, the resulting fields + are used as the command name and arguments. + +`filename' + A string of characters used to identify a file. + +`job' + A set of processes comprising a pipeline, and any processes + descended from it, that are all in the same process group. + +`job control' + A mechanism by which users can selectively start and stop execution + of processes. + +`metacharacter' + A character that, when unquoted, separates words. A metacharacter + is a `blank' or one of the following characters: `|', `&', `;', + `(', `)', `<', or `>'. + +`name' + A `word' consisting solely of letters, numbers, and underscores, + and beginning with a letter or underscore. `Name's are used as + shell variable and function names. Also referred to as an + `identifier'. + +`operator' + A `control operator' or a `redirection operator'. *Note + Redirections::, for a list of redirection operators. + +`process group' + A collection of related processes each having the same process + group ID. + +`process group ID' + A unique identifer that represents a `process group' during its + lifetime. + +`reserved word' + A `word' that has a special meaning to the shell. Most reserved + words introduce shell flow control constructs, such as `for' and + `while'. + +`return status' + A synonym for `exit status'. + +`signal' + A mechanism by which a process may be notified by the kernal of an + event occurring in the system. + +`special builtin' + A shell builtin command that has been classified as special by the + POSIX.2 standard. + +`token' + A sequence of characters considered a single unit by the shell. + It is either a `word' or an `operator'. + +`word' + A `token' that is not an `operator'. + + +File: bashref.info, Node: Basic Shell Features, Next: Bourne Shell Features, Prev: Definitions, Up: Top + +Basic Shell Features +******************** + + Bash is an acronym for `Bourne-Again SHell'. The Bourne shell is +the traditional Unix shell originally 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.2 +specification for the `standard' Unix shell. + + This chapter briefly summarizes the shell's "building blocks": +commands, control structures, shell functions, shell parameters, shell +expansions, redirections, which are a way to direct input and output +from and to named files, and how the shell executes commands. + +* Menu: + +* Shell Syntax:: What your input means to the shell. +* Simple Commands:: The most common type of command. +* Pipelines:: Connecting the input and output of several + commands. +* Lists:: How to execute commands sequentially. +* Looping Constructs:: Shell commands for iterative action. +* Conditional Constructs:: Shell commands for conditional execution. +* Command Grouping:: Ways to group commands. +* Shell Functions:: Grouping commands by name. +* Shell Parameters:: Special shell variables. +* Shell Expansions:: How Bash expands variables and the various + expansions available. +* Redirections:: A way to control where input and output go. +* Executing Commands:: What happens when you run a command. +* Shell Scripts:: Executing files of shell commands. + + +File: bashref.info, Node: Shell Syntax, Next: Simple Commands, Up: Basic Shell Features + +Shell Syntax +============ + +* Menu: + +* Shell Operation:: The basic operation of the shell. + +* Quoting:: How to remove the special meaning from characters. + +* Comments:: How to specify comments. + + +File: bashref.info, Node: Shell Operation, Next: Quoting, Up: Shell Syntax + +Shell Operation +--------------- + + The following is a brief description of the shell's operation when it +reads and executes a command. Basically, the shell does the following: + + 1. Reads its input from a file (*note Shell Scripts::.), from a string + supplied as an argument to the `-c' invocation option (*note + Invoking Bash::.), or from the user's terminal. + + 2. Breaks the input into words and operators, obeying the quoting + rules described in *Note Quoting::. Tokens are separated by + `metacharacters'. Alias expansion is performed by this step + (*note Aliases::.). + + 3. Parses the tokens into simple and compound commands. + + 4. Performs the various shell expansions (*note Shell Expansions::.), + breaking the expanded tokens into lists of filenames (*note + Filename Expansion::.) and commands and arguments. + + 5. Performs any necessary redirections (*note Redirections::.) and + removes the redirection operators and their operands from the + argument list. + + 6. Executes the command (*note Executing Commands::.). + + 7. Optionally waits for the command to complete and collects its exit + status. + + + +File: bashref.info, Node: Quoting, Next: Comments, Prev: Shell Operation, Up: Shell Syntax + +Quoting +------- + +* Menu: + +* Escape Character:: How to remove the special meaning from a single + character. +* Single Quotes:: How to inhibit all interpretation of a sequence + of characters. +* Double Quotes:: How to suppress most of the interpretation of a + sequence of characters. +* ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. + +* Locale Translation:: How to translate strings into different languages. + + Quoting is used to remove the special meaning of certain characters +or words to the shell. Quoting can be used to disable special +treatment for special characters, to prevent reserved words from being +recognized as such, and to prevent parameter expansion. + + Each of the shell `metacharacters' (*note Definitions::.) has +special meaning to the shell and must be quoted if they are to +represent themselves. There are three quoting mechanisms: the ESCAPE +CHARACTER, single quotes, and double quotes. + + +File: bashref.info, Node: Escape Character, Next: Single Quotes, Up: Quoting + +Escape Character +................ + + A non-quoted backslash `\' is the Bash escape character. It +preserves the literal value of the next character that follows, with +the exception of `newline'. If a `\newline' pair appears, and the +backslash is not quoted, the `\newline' is treated as a line +continuation (that is, it is effectively ignored). + + +File: bashref.info, Node: Single Quotes, Next: Double Quotes, Prev: Escape Character, Up: Quoting + +Single Quotes +............. + + Enclosing characters in single quotes preserves the literal value of +each character within the quotes. A single quote may not occur between +single quotes, even when preceded by a backslash. + + +File: bashref.info, Node: Double Quotes, Next: ANSI-C Quoting, Prev: Single Quotes, Up: Quoting + +Double Quotes +............. + + Enclosing characters in double quotes preserves the literal value of +all characters within the quotes, with the exception of `$', ``', and +`\'. The characters `$' and ``' retain their special meaning within +double quotes. The backslash retains its special meaning only when +followed by one of the following characters: `$', ``', `"', `\', or +`newline'. A double quote may be quoted within double quotes by +preceding it with a backslash. + + The special parameters `*' and `@' have special meaning when in +double quotes (*note Shell Parameter Expansion::.). + + +File: bashref.info, Node: ANSI-C Quoting, Next: Locale Translation, Prev: Double Quotes, Up: Quoting + +ANSI-C Quoting +.............. + + Words of the form `$'STRING'' are treated specially. The word +expands to STRING, with backslash-escaped characters replaced as +specifed by the ANSI C standard. Backslash escape sequences, if +present, are decoded as follows: + +`\a' + alert (bell) + +`\b' + backspace + +`\e' + an escape character (not ANSI C) + +`\f' + form feed + +`\n' + newline + +`\r' + carriage return + +`\t' + horizontal tab + +`\v' + vertical tab + +`\\' + backslash + +`\NNN' + the character whose `ASCII' code is NNN in octal + +The result is single-quoted, as if the dollar sign had not been present. + + +File: bashref.info, Node: Locale Translation, Prev: ANSI-C Quoting, Up: Quoting + +Locale-Specific Translation +........................... + + A double-quoted string preceded by a dollar sign (`$') will cause +the string to be translated according to the current locale. If the +current locale is `C' or `POSIX', the dollar sign is ignored. If the +string is translated and replaced, the replacement is double-quoted. + + +File: bashref.info, Node: Comments, Prev: Quoting, Up: Shell Syntax + +Comments +-------- + + In a non-interactive shell, or an interactive shell in which the +`interactive_comments' option to the `shopt' builtin is enabled (*note +Bash Builtins::.), a word beginning with `#' causes that word and all +remaining characters on that line to be ignored. An interactive shell +without the `interactive_comments' option enabled does not allow +comments. The `interactive_comments' option is on by default in +interactive shells. + + +File: bashref.info, Node: Simple Commands, Next: Pipelines, Prev: Shell Syntax, Up: Basic Shell Features + +Simple Commands +=============== + + A simple command is the kind of command you'll encounter most often. +It's just a sequence of words separated by `blank's, terminated by one +of the shell control operators (*note Definitions::.). The first word +generally specifies a command to be executed. + + The return status (*note Exit Status::.) of a simple command is its +exit status as provided by the POSIX.1 `waitpid' function, or 128+N if +the command was terminated by signal N. + + +File: bashref.info, Node: Pipelines, Next: Lists, Prev: Simple Commands, Up: Basic Shell Features + +Pipelines +========= + + A `pipeline' is a sequence of simple commands separated by `|'. + + The format for a pipeline is + [`time' [`-p']] [`!'] COMMAND1 [`|' COMMAND2 ...] + +The output of each command in the pipeline is connected to the input of +the next command. That is, each command reads the previous command's +output. + + The reserved word `time' causes timing statistics to be printed for +the pipeline once it finishes. The `-p' option changes the output +format to that specified by POSIX. The `TIMEFORMAT' variable may be +set to a format string that specifies how the timing information should +be displayed. *Note Bash Variables::, for a description of the +available formats. + + Each command in a pipeline is executed in its own subshell. The exit +status of a pipeline is the exit status of the last command in the +pipeline. If the reserved word `!' precedes the pipeline, the exit +status is the logical NOT of the exit status of the last command. + + +File: bashref.info, Node: Lists, Next: Looping Constructs, Prev: Pipelines, Up: Basic Shell Features + +Lists of Commands +================= + + A `list' is a sequence of one or more pipelines separated by one of +the operators `;', `&', `&&', or `||', and optionally terminated by one +of `;', `&', or a `newline'. + + Of these list operators, `&&' and `||' have equal precedence, +followed by `;' and `&', which have equal precedence. + + If a command is terminated by the control operator `&', the shell +executes the command in the BACKGROUND in a subshell. The shell does +not wait for the command to finish, and the return status is 0 (true). +Commands separated by a `;' are executed sequentially; the shell waits +for each command to terminate in turn. The return status is the exit +status of the last command executed. + + The control operators `&&' and `||' denote AND lists and OR lists, +respectively. An AND list has the form + COMMAND && COMMAND2 + +COMMAND2 is executed if, and only if, COMMAND returns an exit status of +zero. + + An OR list has the form + COMMAND || COMMAND2 + +COMMAND2 is executed if and only if COMMAND returns a non-zero exit +status. + + The return status of AND and OR lists is the exit status of the last +command executed in the list. + + +File: bashref.info, Node: Looping Constructs, Next: Conditional Constructs, Prev: Lists, Up: Basic Shell Features + +Looping Constructs +================== + + Note that wherever you see a `;' in the description of a command's +syntax, it may be replaced indiscriminately with one or more 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. + + The `break' and `continue' builtins (*note Bourne Shell Builtins::.) +may be used to control loop execution. + + +File: bashref.info, Node: Conditional Constructs, Next: Command Grouping, Prev: Looping Constructs, Up: Basic Shell Features + +Conditional Constructs +====================== + +`if' + The syntax of the `if' command is: + + if TEST-COMMANDS; then + CONSEQUENT-COMMANDS; + [elif MORE-TEST-COMMANDS; then + MORE-CONSEQUENTS;] + [else ALTERNATE-CONSEQUENTS;] + fi + + Execute CONSEQUENT-COMMANDS only if the final command in + TEST-COMMANDS has an exit status of zero. Otherwise, each `elif' + list is executed in turn, and if its exit status is zero, the + corresponding MORE-CONSEQUENTS is executed and the command + completes. If `else ALTERNATE-CONSEQUENTS' is present, and the + final command in the final `if' or `elif' clause 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 one 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." + +`((...))' + (( EXPRESSION )) + + The EXPRESSION is evaluated according to the rules described below + ((*note Arithmetic Evaluation::.). If the value of the expression + is non-zero, the return status is 0; otherwise the return status + is 1. This is exactly equivalent to + let "EXPRESSION" + + The `select' construct, which allows users to choose from a list of +items presented as a menu, is also available. *Note Korn Shell +Constructs::, for a full description of `select'. + + +File: bashref.info, Node: Command Grouping, Next: Shell Functions, Prev: Conditional Constructs, Up: Basic Shell Features + +Grouping Commands +================= + + Bash provides two ways to group a list of commands to be executed as +a unit. When commands are grouped, redirections may be applied to the +entire command list. For example, the output of all the commands in +the list may be redirected to a single stream. + +`()' + ( LIST ) + + Placing a list of commands between parentheses causes a subshell + to be created, and each of the commands to be executed in that + subshell. Since the LIST is executed in a subshell, variable + assignments do not remain in effect after the subshell completes. + +`{}' + { LIST; } + + Placing a list of commands between curly braces causes the list to + be executed in the current shell context. No subshell is created. + The semicolon following LIST is required. + + In addition to the creation of a subshell, there is a subtle +difference between these two constructs due to historical reasons. The +braces are `reserved words', so they must be separated from the LIST by +`blank's. The parentheses are `operators', and are recognized as +separate tokens by the shell even if they are not separated from `list' +by whitespace. + + The exit status of both of these constructs is the exit status of +LIST. + + +File: bashref.info, Node: Shell Functions, Next: Shell Parameters, Prev: Command Grouping, Up: Basic Shell Features + +Shell Functions +=============== + + Shell functions are a way to group commands for later execution +using a single name for the group. They are executed just like a +"regular" command. Shell functions are executed in the current shell +context; no new process is created to interpret them. + + Functions are declared using this syntax: + [ `function' ] NAME () { COMMAND-LIST; } + + This defines a shell function named NAME. The reserved word +`function' is optional. The BODY of the function is the COMMAND-LIST +between { and }. This list is executed whenever NAME is specified as +the name of a command. The exit status of a function is the exit +status of the last command executed in the body. + + When a function is executed, the arguments to the function become +the positional parameters during its execution (*note Positional +Parameters::.). The special parameter `#' that gives the number of +positional parameters is updated to reflect the change. Positional +parameter `0' is unchanged. + + If the builtin command `return' is executed in a function, the +function completes and execution resumes with the next command after +the function call. When a function completes, the values of the +positional parameters and the special parameter `#' are restored to the +values they had prior to function execution. If a numeric argument is +given to `return', that is the function return status. + + Variables local to the function may be declared with the `local' +builtin. These variables are visible only to the function and the +commands it invokes. + + Functions may be recursive. No limit is placed on the number of +recursive calls. + + +File: bashref.info, Node: Shell Parameters, Next: Shell Expansions, Prev: Shell Functions, Up: Basic Shell Features + +Shell Parameters +================ + +* Menu: + +* Positional Parameters:: The shell's command-line arguments. +* Special Parameters:: Parameters with special meanings. + + A PARAMETER is an entity that stores values. It can be a `name', a +number, or one of the special characters listed below. For the shell's +purposes, a VARIABLE is a parameter denoted by a `name'. + + A parameter is set if it has been assigned a value. The null string +is a valid value. Once a variable is set, it may be unset only by using +the `unset' builtin command. + + A variable may be assigned to by a statement of the form + NAME=[VALUE] + +If VALUE is not given, the variable is assigned the null string. All +VALUEs undergo tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote removal (detailed +below). If the variable has its `-i' attribute set (see the +description of the `declare' builtin in *Note Bash Builtins::), then +VALUE is subject to arithmetic expansion even if the `$((...))' syntax +does not appear (*note Arithmetic Expansion::.). Word splitting is not +performed, with the exception of `"$@"' as explained below. Filename +expansion is not performed. + + +File: bashref.info, Node: Positional Parameters, Next: Special Parameters, Up: Shell Parameters + +Positional Parameters +--------------------- + + A POSITIONAL PARAMETER is a parameter denoted by one or more digits, +other than the single digit `0'. Positional parameters are assigned +from the shell's arguments when it is invoked, and may be reassigned +using the `set' builtin command. Positional parameters may not be +assigned to with assignment statements. The positional parameters are +temporarily replaced when a shell function is executed (*note Shell +Functions::.). + + When a positional parameter consisting of more than a single digit +is expanded, it must be enclosed in braces. + + +File: bashref.info, Node: Special Parameters, Prev: Positional Parameters, Up: Shell Parameters + +Special Parameters +------------------ + + The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. + +`*' + Expands to the positional parameters, starting from one. When the + expansion occurs within double quotes, it expands to a single word + with the value of each parameter separated by the first character + of the `IFS' special variable. That is, `"$*"' is equivalent to + `"$1C$2C..."', where C is the first character of the value of the + `IFS' variable. If `IFS' is null or unset, the parameters are + separated by spaces. + +`@' + Expands to the positional parameters, starting from one. When the + expansion occurs within double quotes, each parameter expands as a + separate word. That is, `"$@"' is equivalent to `"$1" "$2" ...'. + When there are no positional parameters, `"$@"' and `$@' expand to + nothing (i.e., they are removed). + +`#' + Expands to the number of positional parameters in decimal. + +`?' + Expands to the exit status of the most recently executed foreground + pipeline. + +`-' + Expands to the current option flags as specified upon invocation, + by the `set' builtin command, or those set by the shell itself + (such as the `-i' option). + +`$' + Expands to the process ID of the shell. In a `()' subshell, it + expands to the process ID of the current shell, not the subshell. + +`!' + Expands to the process ID of the most recently executed background + (asynchronous) command. + +`0' + Expands to the name of the shell or shell script. This is set at + shell initialization. If Bash is invoked with a file of commands, + `$0' is set to the name of that file. If Bash is started with the + `-c' option, then `$0' is set to the first argument after the + string to be executed, if one is present. Otherwise, it is set to + the filename used to invoke Bash, as given by argument zero. + +`_' + At shell startup, set to the absolute filename of the shell or + shell script being executed as passed in the argument list. + Subsequently, expands to the last argument to the previous command, + after expansion. Also set to the full filename of each command + executed and placed in the environment exported to that command. + When checking mail, this parameter holds the name of the mail file. + + +File: bashref.info, Node: Shell Expansions, Next: Redirections, Prev: Shell Parameters, Up: Basic Shell Features + +Shell Expansions +================ + + Expansion is performed on the command line after it has been split +into `token's. There are seven kinds of expansion performed: + * brace expansion + + * tilde expansion + + * parameter and variable expansion + + * command substitution + + * arithmetic expansion + + * word splitting + + * filename expansion + +* Menu: + +* Shell Parameter Expansion:: How Bash expands variables to their values. +* Command Substitution:: Using the output of a command as an argument. +* Process Substitution:: A way to write and read to and from a + command. +* Word Splitting:: How the results of expansion are split into separate + arguments. +* Filename Expansion:: A shorthand for specifying filenames matching patterns. +* Quote Removal:: How and when quote characters are removed from + words. + + Brace expansion, tilde expansion, and arithmetic expansion are +described in other sections. For brace expansion, see *Note Brace +Expansion::; for tilde expansion, see *Note Tilde Expansion::; and for +arithmetic expansion, see *Note Arithmetic Expansion::. + + The order of expansions is: brace expansion, tilde expansion, +parameter, variable, and arithmetic expansion and command substitution +(done in a left-to-right fashion), word splitting, and filename +expansion. + + On systems that can support it, there is an additional expansion +available: PROCESS SUBSTITUTION. This is performed at the same time as +parameter, variable, and arithemtic expansion and command substitution. + + Only brace expansion, word splitting, and filename expansion can +change the number of words of the expansion; other expansions expand a +single word to a single word. The only exceptions to this are the +expansions of `"$@"' (*note Special Parameters::.) and `"${[@]}"' +(*note Arrays::.). + + After all expansions, `quote removal' (*note Quote Removal::.) is +performed. + + +File: bashref.info, Node: Shell Parameter Expansion, Next: Command Substitution, Up: Shell Expansions + +Shell Parameter Expansion +------------------------- + + The `$' character introduces parameter expansion, command +substitution, or arithmetic expansion. The parameter name or symbol to +be expanded may be enclosed in braces, which are optional but serve to +protect the variable to be expanded from characters immediately +following it which could be interpreted as part of the name. + + The basic form of parameter expansion is ${PARAMETER}. The value of +PARAMETER is substituted. The braces are required when PARAMETER is a +positional parameter with more than one digit, or when PARAMETER is +followed by a character that is not to be interpreted as part of its +name. + + If the first character of PARAMETER is an exclamation point, a level +of variable indirection is introduced. Bash uses the value of the +variable formed from the rest of PARAMETER as the name of the variable; +this variable is then expanded and that value used in the rest of the +substitution, rather than the value of PARAMETER itself. This is known +as `indirect expansion'. + + In each of the cases below, WORD is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +When not performing substring expansion, Bash tests for a parameter +that is unset or null; omitting the colon results in a test only for a +parameter that is unset. + +`${PARAMETER:-WORD}' + If PARAMETER is unset or null, the expansion of WORD is + substituted. Otherwise, the value of PARAMETER is substituted. + +`${PARAMETER:=WORD}' + If PARAMETER is unset or null, the expansion of WORD is assigned + to PARAMETER. The value of PARAMETER is then substituted. + Positional parameters and special parameters may not be assigned + to in this way. + +`${PARAMETER:?WORD}' + If PARAMETER is null or unset, the expansion of WORD (or a message + to that effect if WORD is not present) is written to the standard + error and the shell, if it is not interactive, exits. Otherwise, + the value of PARAMETER is substituted. + +`${PARAMETER:+WORD}' + If PARAMETER is null or unset, nothing is substituted, otherwise + the expansion of WORD is substituted. + +`${PARAMETER:OFFSET}' +`${PARAMETER:OFFSET:LENGTH}' + Expands to up to LENGTH characters of PARAMETER, starting at + OFFSET. If LENGTH is omitted, expands to the substring of + PARAMETER, starting at the character specified by OFFSET. LENGTH + and OFFSET are arithmetic expressions (*note Arithmetic + Evaluation::.). This is referred to as Substring Expansion. + + LENGTH must evaluate to a number greater than or equal to zero. + If OFFSET evaluates to a number less than zero, the value is used + as an offset from the end of the value of PARAMETER. If PARAMETER + is `@', the result is LENGTH positional parameters beginning at + OFFSET. If PARAMETER is an array name indexed by `@' or `*', the + result is the LENGTH members of the array beginning with + ${PARAMETER[OFFSET]}. Substring indexing is zero-based unless the + positional parameters are used, in which case the indexing starts + at 1. + +`${#PARAMETER}' + The length in characters of the value of PARAMETER is substituted. + If PARAMETER is `*' or `@', the length substituted is the number + of positional parameters. If PARAMETER is an array name + subscripted by `*' or `@', the length substituted is the number of + elements in the array. + +`${PARAMETER#WORD}' +`${PARAMETER##WORD}' + The WORD is expanded to produce a pattern just as in filename + expansion (*note Filename Expansion::.). If the pattern matches + the beginning of the value of PARAMETER, then the expansion is the + value of PARAMETER with the shortest matching pattern (the `#' + case) or the longest matching pattern (the `##' case) deleted. If + PARAMETER is `@' or `*', the pattern removal operation is applied + to each positional parameter in turn, and the expansion is the + resultant list. If PARAMETER is an array variable subscripted with + `@' or `*', the pattern removal operation is applied to each + member of the array in turn, and the expansion is the resultant + list. + +`${PARAMETER%WORD}' +`${PARAMETER%%WORD}' + The WORD is expanded to produce a pattern just as in filename + expansion. If the pattern matches a trailing portion of the value + of PARAMETER, then the expansion is the value of PARAMETER with + the shortest matching pattern (the `%' case) or the longest + matching pattern (the `%%' case) deleted. If PARAMETER is `@' or + `*', the pattern removal operation is applied to each positional + parameter in turn, and the expansion is the resultant list. If + PARAMETER is an array variable subscripted with `@' or `*', the + pattern removal operation is applied to each member of the array + in turn, and the expansion is the resultant list. + +`${PARAMETER/PATTERN/STRING}' +`${PARAMETER//PATTERN/STRING}' + The PATTERN is expanded to produce a pattern just as in filename + expansion. PARAMETER is expanded and the longest match of PATTERN + against its value is replaced with STRING. In the first form, + only the first match is replaced. The second form causes all + matches of PATTERN to be replaced with STRING. If PATTERN begins + with `#', it must match at the beginning of STRING. If PATTERN + begins with `%', it must match at the end of STRING. If STRING is + null, matches of PATTERN are deleted and the `/' following PATTERN + may be omitted. If PARAMETER is `@' or `*', the substitution + operation is applied to each positional parameter in turn, and the + expansion is the resultant list. If PARAMETER is an array + variable subscripted with `@' or `*', the substitution operation + is applied to each member of the array in turn, and the expansion + is the resultant list. + + +File: bashref.info, Node: Command Substitution, Next: Process Substitution, Prev: Shell Parameter Expansion, Up: Shell Expansions + +Command Substitution +-------------------- + + Command substitution allows the output of a command to replace the +command name. There are two forms: + $(COMMAND) + +or + `COMMAND` + +Bash performs the expansion by executing COMMAND and replacing the +command substitution with the standard output of the command, with any +trailing newlines deleted. + + When the old-style backquote form of substitution is used, backslash +retains its literal meaning except when followed by `$', ``', or `\'. +When using the `$(COMMAND)' form, all characters between the +parentheses make up the command; none are treated specially. + + Command substitutions may be nested. To nest when using the old +form, escape the inner backquotes with backslashes. + + If the substitution appears within double quotes, word splitting and +filename expansion are not performed on the results. + + +File: bashref.info, Node: Process Substitution, Next: Word Splitting, Prev: Command Substitution, Up: Shell Expansions + +Process Substitution +-------------------- + + Process substitution is supported on systems that support named +pipes (FIFOs) or the `/dev/fd' method of naming open files. It takes +the form of + <(LIST) + +or + >(LIST) + +The process LIST is run with its input or output connected to a FIFO or +some file in `/dev/fd'. The name of this file is passed as an argument +to the current command as the result of the expansion. If the +`>(LIST)' form is used, writing to the file will provide input for +LIST. If the `<(LIST)' form is used, the file passed as an argument +should be read to obtain the output of LIST. + + On systems that support it, process substitution is performed +simultaneously with parameter and variable expansion, command +substitution, and arithmetic expansion. + + +File: bashref.info, Node: Word Splitting, Next: Filename Expansion, Prev: Process Substitution, Up: Shell Expansions + +Word Splitting +-------------- + + The shell scans the results of parameter expansion, command +substitution, and arithmetic expansion that did not occur within double +quotes for word splitting. + + The shell treats each character of `$IFS' as a delimiter, and splits +the results of the other expansions into words on these characters. If +`IFS' is unset, or its value is exactly `<space><tab><newline>', the +default, then any sequence of `IFS' characters serves to delimit words. +If `IFS' has a value other than the default, then sequences of the +whitespace characters `space' and `tab' are ignored at the beginning +and end of the word, as long as the whitespace character is in the +value of `IFS' (an `IFS' whitespace character). Any character in `IFS' +that is not `IFS' whitespace, along with any adjacent `IFS' whitespace +characters, delimits a field. A sequence of `IFS' whitespace +characters is also treated as a delimiter. If the value of `IFS' is +null, no word splitting occurs. + + Explicit null arguments (`""' or `''') are retained. Unquoted +implicit null arguments, resulting from the expansion of PARAMETERs +that have no values, are removed. If a parameter with no value is +expanded within double quotes, a null argument results and is retained. + + Note that if no expansion occurs, no splitting is performed. + + +File: bashref.info, Node: Filename Expansion, Next: Quote Removal, Prev: Word Splitting, Up: Shell Expansions + +Filename Expansion +------------------ + + After word splitting, unless the `-f' option has been set (*note The +Set Builtin::.), Bash scans each word for the characters `*', `?', and +`['. If one of these characters appears, then the word is regarded as +a PATTERN, and replaced with an alphabetically sorted list of file +names matching the pattern. If no matching file names are found, and +the shell option `nullglob' is disabled, the word is left unchanged. If +the option is set, and no matches are found, the word is removed. When +a pattern is used for filename generation, the character `.' at the +start of a filename or immediately following a slash must be matched +explicitly, unless the shell option `dotglob' is set. The slash +character must always be matched explicitly. In other cases, the `.' +character is not treated specially. See the description of `shopt' in +*Note Bash Builtins::, for a description of the `nullglob' and +`dotglob' options. + + The `GLOBIGNORE' shell variable may be used to restrict the set of +filenames matching a PATTERN. If `GLOBIGNORE' is set, each matching +filename that also matches one of the patterns in `GLOBIGNORE' is +removed from the list of matches. The filenames `.' and `..' are +always ignored, even when `GLOBIGNORE'. is set. However, setting +`GLOBIGNORE' has the effect of enabling the `dotglob' shell option, so +all other filenames beginning with a `.' will match. To get the old +behavior of ignoring filenames beginning with a `.', make `.*' one of +the patterns in `GLOBIGNORE'. The `dotglob' option is disabled when +`GLOBIGNORE' is unset. + + The special pattern characters have the following meanings: +`*' + Matches any string, including the null string. + +`?' + Matches any single character. + +`[...]' + Matches any one of the enclosed characters. A pair of characters + separated by a minus sign denotes a RANGE; any character lexically + between those two characters, inclusive, is matched. If the first + character following the `[' is a `!' or a `^' then any character + not enclosed is matched. A `-' may be matched by including it as + the first or last character in the set. A `]' may be matched by + including it as the first character in the set. + + +File: bashref.info, Node: Quote Removal, Prev: Filename Expansion, Up: Shell Expansions + +Quote Removal +------------- + + After the preceding expansions, all unquoted occurrences of the +characters `\', `'', and `"' that did not result from one of the above +expansions are removed. + + +File: bashref.info, Node: Redirections, Next: Executing Commands, Prev: Shell Expansions, Up: Basic Shell Features + +Redirections +============ + + Before a command is executed, its input and output may be REDIRECTED +using a special notation interpreted by the shell. Redirection may +also be used to open and close files for the current shell execution +environment. The following redirection operators may precede or appear +anywhere within a simple command or may follow a command. Redirections +are processed in the order they appear, from left to right. + + In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is `<', +the redirection refers to the standard input (file descriptor 0). If +the first character of the redirection operator is `>', the redirection +refers to the standard output (file descriptor 1). + + The word that follows the redirection operator in the following +descriptions is subjected to brace expansion, tilde expansion, +parameter expansion, command substitution, arithmetic expansion, quote +removal, and filename expansion. If it expands to more than one word, +Bash reports an error. + + Note that the order of redirections is significant. For example, +the command + ls > DIRLIST 2>&1 + +directs both standard output and standard error to the file DIRLIST, +while the command + ls 2>&1 > DIRLIST + +directs only the standard output to file DIRLIST, because the standard +error was duplicated as standard output before the standard output was +redirected to DIRLIST. + +Redirecting Input +----------------- + + Redirection of input causes the file whose name results from the +expansion of WORD to be opened for reading on file descriptor `n', or +the standard input (file descriptor 0) if `n' is not specified. + + The general format for redirecting input is: + [n]<WORD + +Redirecting Output +------------------ + + Redirection of output causes the file whose name results from the +expansion of WORD to be opened for writing on file descriptor `n', or +the standard output (file descriptor 1) if `n' is not specified. If +the file does not exist it is created; if it does exist it is truncated +to zero size. + + The general format for redirecting output is: + [n]>[|]WORD + + If the redirection operator is `>', and the `-C' option to the `set' +builtin has been enabled, the redirection will fail if the filename +whose name results from the expansion of WORD exists. If the +redirection operator is `>|', then the value of the `-C' option to the +`set' builtin command is not tested, and the redirection is attempted +even if the file named by WORD exists. + +Appending Redirected Output +--------------------------- + + Redirection of output in this fashion causes the file whose name +results from the expansion of WORD to be opened for appending on file +descriptor `n', or the standard output (file descriptor 1) if `n' is +not specified. If the file does not exist it is created. + + The general format for appending output is: + [n]>>WORD + +Redirecting Standard Output and Standard Error +---------------------------------------------- + + Bash allows both the standard output (file descriptor 1) and the +standard error output (file descriptor 2) to be redirected to the file +whose name is the expansion of WORD with this construct. + + There are two formats for redirecting standard output and standard +error: + &>WORD + +and + >&WORD + +Of the two forms, the first is preferred. This is semantically +equivalent to + >WORD 2>&1 + +Here Documents +-------------- + + This type of redirection instructs the shell to read input from the +current source until a line containing only WORD (with no trailing +blanks) is seen. All of the lines read up to that point are then used +as the standard input for a command. + + The format of here-documents is as follows: + <<[-]WORD + HERE-DOCUMENT + DELIMITER + + No parameter expansion, command substitution, filename expansion, or +arithmetic expansion is performed on WORD. If any characters in WORD +are quoted, the DELIMITER is the result of quote removal on WORD, and +the lines in the here-document are not expanded. Otherwise, all lines +of the here-document are subjected to parameter expansion, command +substitution, and arithmetic expansion. In the latter case, the pair +`\newline' is ignored, and `\' must be used to quote the characters +`\', `$', and ``'. + + If the redirection operator is `<<-', then all leading tab +characters are stripped from input lines and the line containing +DELIMITER. This allows here-documents within shell scripts to be +indented in a natural fashion. + +Duplicating File Descriptors +---------------------------- + + The redirection operator + [n]<&WORD + +is used to duplicate input file descriptors. If WORD expands to one or +more digits, the file descriptor denoted by `n' is made to be a copy of +that file descriptor. If WORD evaluates to `-', file descriptor `n' is +closed. If `n' is not specified, the standard input (file descriptor +0) is used. + + The operator + [n]>&WORD + +is used similarly to duplicate output file descriptors. If `n' is not +specified, the standard output (file descriptor 1) is used. As a +special case, if `n' is omitted, and WORD does not expand to one or +more digits, the standard output and standard error are redirected as +described previously. + +Opening File Descriptors for Reading and Writing +------------------------------------------------ + + The redirection operator + [n]<>WORD + +causes the file whose name is the expansion of WORD to be opened for +both reading and writing on file descriptor `n', or on file descriptor +0 if `n' is not specified. If the file does not exist, it is created. + + +File: bashref.info, Node: Executing Commands, Next: Shell Scripts, Prev: Redirections, Up: Basic Shell Features + +Executing Commands +================== + +* Menu: + +* Command Search and Execution:: How Bash finds commands and runs them. + +* Environment:: The environment given to a command. + +* Exit Status:: The status returned by commands and how Bash + interprets it. + +* Signals:: What happens when Bash or a command it runs + receives a signal. + + +File: bashref.info, Node: Command Search and Execution, Next: Environment, Up: Executing Commands + +Command Search and Execution +---------------------------- + + After a command has been split into words, if it results in a simple +command and an optional list of arguments, the following actions are +taken. + + 1. If the command name contains no slashes, the shell attempts to + locate it. If there exists a shell function by that name, that + function is invoked as described above in *Note Shell Functions::. + + 2. If the name does not match a function, the shell searches for it + in the list of shell builtins. If a match is found, that builtin + is invoked. + + 3. If the name is neither a shell function nor a builtin, and + contains no slashes, Bash searches each element of `$PATH' for a + directory containing an executable file by that name. Bash uses a + hash table to remember the full filenames of executable files (see + the description of `hash' in *Note Bourne Shell Builtins::) to + avoid multiple `PATH' searches. A full search of the directories + in `$PATH' is performed only if the command is not found in the + hash table. If the search is unsuccessful, the shell prints an + error message and returns a nonzero exit status. + + 4. If the search is successful, or if the command name contains one + or more slashes, the shell executes the named program. Argument 0 + is set to the name given, and the remaining arguments to the + command are set to the arguments supplied, if any. + + 5. If this execution fails because the file is not in executable + format, and the file is not a directory, it is assumed to be SHELL + SCRIPT (*note Shell Scripts::.). + + +File: bashref.info, Node: Environment, Next: Exit Status, Prev: Command Search and Execution, Up: Executing Commands + +Environment +----------- + + When a program is invoked it is given an array of strings called the +ENVIRONMENT. This is a list of name-value pairs, of the form +`name=value'. + + Bash allows you to manipulate the environment in several ways. On +invocation, the shell scans its own environment and creates a parameter +for each name found, automatically marking it for EXPORT to child +processes. Executed commands inherit the environment. The `export' +and `declare -x' commands allow parameters and functions to be added to +and deleted from the environment. If the value of a parameter in the +environment is modified, the new value becomes part of the environment, +replacing the old. The environment inherited by any executed command +consists of the shell's initial environment, whose values may be +modified in the shell, less any pairs removed by the `unset' command, +plus any additions via the `export' and `declare -x' commands. + + The environment for any simple command or function may be augmented +temporarily by prefixing it with parameter assignments, as described in +*Note Shell Parameters::. These assignment statements affect only the +environment seen by that command. + + If the `-k' flag is set (*note The Set Builtin::., then all +parameter assignments are placed in the environment for a command, not +just those that precede the command name. + + When Bash invokes an external command, the variable `$_' is set to +the full path name of the command and passed to that command in its +environment. + + +File: bashref.info, Node: Exit Status, Next: Signals, Prev: Environment, Up: Executing Commands + +Exit Status +----------- + + For the purposes of the shell, a command which exits with a zero +exit status has succeeded. A non-zero exit status indicates failure. +This seemingly counter-intuitive scheme is used so there is one +well-defined way to indicate success and a variety of ways to indicate +various failure modes. When a command terminates on a fatal signal +whose number is N, Bash uses the value 128+N as the exit status. + + If a command is not found, the child process created to execute it +returns a status of 127. If a command is found but is not executable, +the return status is 126. + + The exit status is used by the Bash conditional commands (*note +Conditional Constructs::.) and some of the list constructs (*note +Lists::.). + + All of the Bash builtins return an exit status of zero if they +succeed and a non-zero status on failure, so they may be used by the +conditional and list constructs. + + +File: bashref.info, Node: Signals, Prev: Exit Status, Up: Executing Commands + +Signals +------- + + When Bash is interactive, it ignores `SIGTERM' (so that `kill 0' +does not kill an interactive shell), and `SIGINT' is caught and handled +(so that the `wait' builtin is interruptible). When Bash receives a +`SIGINT', it breaks out of any executing loops. In all cases, Bash +ignores `SIGQUIT'. If job control is in effect (*note Job Control::.), +Bash ignores `SIGTTIN', `SIGTTOU', and `SIGTSTP'. + + Synchronous jobs started by Bash have signals set to the values +inherited by the shell from its parent. When job control is not in +effect, background jobs (commands terminated with `&') ignore `SIGINT' +and `SIGQUIT'. Commands run as a result of command substitution ignore +the keyboard-generated job control signals `SIGTTIN', `SIGTTOU', and +`SIGTSTP'. + + The shell exits by default upon receipt of a `SIGHUP'. Before +exiting, it resends the `SIGHUP' to all jobs, running or stopped. To +prevent the shell from sending the `SIGHUP' signal to a particular job, +remove it from the jobs table with the `disown' builtin (*note Job +Control Builtins::.) or use `disown -h' to mark it to not receive +`SIGHUP'. + + +File: bashref.info, Node: Shell Scripts, Prev: Executing Commands, Up: Basic Shell Features + +Shell Scripts +============= + + A shell script is a text file containing shell commands. When such +a file is used as the first non-option argument when invoking Bash, and +neither the `-c' nor `-s' option is supplied (*note Invoking Bash::.), +Bash reads and executes commands from the file, then exits. This mode +of operation creates a non-interactive shell. When Bash runs a shell +script, it sets the special parameter `0' to the name of the file, +rather than the name of the shell, and the positional parameters are +set to the remaining arguments, if any are given. If no additional +arguments are supplied, the positional parameters are unset. + + A shell script may be made executable by using the `chmod' command +to turn on the execute bit. When Bash finds such a file while +searching the `$PATH' for a command, it spawns a subshell to execute +it. In other words, executing + filename ARGUMENTS + +is equivalent to executing + bash filename ARGUMENTS + +if `filename' is an executable shell script. This subshell +reinitializes itself, so that the effect is as if a new shell had been +invoked to interpret the script. + + Most versions of Unix make this a part of the kernel's command +execution mechanism. If the first line of a script begins with the two +characters `#!', the remainder of the line specifies an interpreter for +the program. The arguments to the interpreter consist of a single +optional argument following the interpreter name on the first line of +the script file, followed by the name of the script file, followed by +the rest of the arguments. Bash will perform this action on operating +systems that do not handle it themselves. Note that some older +versions of Unix limit the interpreter name and argument to a maximum +of 32 characters. + + +File: bashref.info, Node: Bourne Shell Features, Next: Csh Features, Prev: Basic Shell Features, Up: Top + +Bourne Shell Style Features +*************************** + +* Menu: + +* Bourne Shell Builtins:: Builtin commands inherited from the Bourne + Shell. +* Bourne Shell Variables:: Variables which Bash uses in the same way + as the Bourne Shell. +* Other Bourne Shell Features:: Addtional aspects of Bash which behave in + the same way as the Bourne Shell. + + This section briefly summarizes things which Bash inherits from the +Bourne Shell: builtins, variables, and other features. It also lists +the significant differences between Bash and the Bourne Shell. + + +File: bashref.info, Node: Bourne Shell Builtins, Next: Bourne Shell Variables, Up: Bourne Shell Features + +Bourne Shell Builtins +===================== + + The following shell builtin commands are inherited from the Bourne +Shell. These commands are implemented as specified by the POSIX 1003.2 +standard. + +`:' + : [ARGUMENTS] + Do nothing beyond expanding ARGUMENTS and performing redirections. + +`.' + . FILENAME + Read and execute commands from the FILENAME argument in the + current shell context. + +`break' + break [N] + Exit from a `for', `while', `until', or `select' loop. If N is + supplied, the Nth enclosing loop is exited. + +`cd' + cd [-LP] [DIRECTORY] + Change the current working directory to DIRECTORY. If DIRECTORY + is not given, the value of the `HOME' shell variable is used. If + the shell variable `CDPATH' exists, it is used as a search path. + If DIRECTORY begins with a slash, `CDPATH' is not used. The `-P' + option means to not follow symbolic links; symlinks are followed + by default or with the `-L' option. + +`continue' + continue [N] + Resume the next iteration of an enclosing `for', `while', `until', + or `select' loop. If N is supplied, the execution of the Nth + enclosing loop is resumed. + +`eval' + eval [ARGUMENTS] + The arguments are concatenated together into a single command, + which is then read and executed. + +`exec' + exec [-cl] [-a NAME] [COMMAND] [ARGUMENTS] + If COMMAND is supplied, it replaces the shell. If the `-l' option + is supplied, the shell places a dash in the zeroth arg passed to + COMMAND. This is what the `login' program does. The `-c' option + causes COMMAND to be executed with an empty environment. If `-a' + is supplied, the shell passes NAME as the zeroth argument to + COMMAND. If no COMMAND is specified, redirections may be used to + affect the current shell environment. + +`exit' + exit [N] + Exit the shell, returning a status of N to the shell's parent. + +`export' + export [-fn] [-p] [NAME[=VALUE]] + Mark each NAME to be passed to child processes in the environment. + If the `-f' option is supplied, the NAMEs refer to shell + functions. The `-n' option means to no longer mark each NAME for + export. If no NAMES are supplied, or if the `-p' option is given, + a list of exported names is displayed. + +`getopts' + getopts OPTSTRING NAME [ARGS] + `getopts' is used by shell scripts to parse positional parameters. + OPTSTRING contains the option letters to be recognized; if a letter + is followed by a colon, the option is expected to have an + argument, which should be separated from it by white space. Each + time it is invoked, `getopts' places the next option in the shell + variable NAME, initializing NAME if it does not exist, and the + index of the next argument to be processed into the variable + `OPTIND'. `OPTIND' is initialized to 1 each time the shell or a + shell script is invoked. When an option requires an argument, + `getopts' places that argument into the variable `OPTARG'. The + shell does not reset `OPTIND' automatically; it must be manually + reset between multiple calls to `getopts' within the same shell + invocation if a new set of parameters is to be used. + + `getopts' can report errors in two ways. If the first character of + OPTSTRING is a colon, SILENT error reporting is used. In normal + operation diagnostic messages are printed when illegal options or + missing option arguments are encountered. If the variable `OPTERR' + is set to 0, no error message will be displayed, even if the first + character of `optstring' is not a colon. + + If an illegal option is seen, `getopts' places `?' into NAME and, + if not silent, prints an error message and unsets `OPTARG'. If + `getopts' is silent, the option character found is placed in + `OPTARG' and no diagnostic message is printed. + + If a required argument is not found, and `getopts' is not silent, + a question mark (`?') is placed in NAME, `OPTARG' is unset, and a + diagnostic message is printed. If `getopts' is silent, then a + colon (`:') is placed in NAME and `OPTARG' is set to the option + character found. + + `getopts' normally parses the positional parameters, but if more + arguments are given in ARGS, `getopts' parses those instead. + +`hash' + hash [-r] [-p FILENAME] [NAME] + Remember the full filenames of commands specified as arguments, so + they need not be searched for on subsequent invocations. The + commands are found by searching through the directories listed in + `$PATH'. The `-p' option inhibits the path search, and FILENAME + is used as the location of NAME. The `-r' option causes the shell + to forget all remembered locations. If no arguments are given, + information about remembered commands is printed. + +`pwd' + pwd [-LP] + Print the current working directory. If the `-P' option is + supplied, the path printed will not contain symbolic links. If + the `-L' option is supplied, the path printed may contain symbolic + links. + +`readonly' + readonly [-apf] [NAME] ... + Mark each NAME as unchangable. The values of these names may not + be changed by subsequent assignment. If the `-f' option is + supplied, each NAME refers to a shell function. The `-a' option + means each NAME refers to an array variable. If no NAME arguments + are given, or if the `-p' option is supplied, a list of all + readonly names is printed. + +`return' + return [N] + Cause a shell function to exit with value N. This may also be used + to terminate execution of a script being executed with the `.' + builtin. + +`shift' + shift [N] + Shift positional parameters to the left by N. The positional + parameters from N+1 ... are renamed to `$1' ... . Parameters + represented by the numbers `$#' to N+1 are unset. N must be a + non-negative number less than or equal to `$#'. + +`test' +`[' + Evaluate a conditional expression (*note Bash Conditional + Expressions::.). + +`times' + times + Print out the user and system times used by the shell and its + children. + +`trap' + trap [-lp] [ARG] [SIGSPEC] + The commands in ARG are to be read and executed when the shell + receives signal SIGSPEC. If ARG is absent or equal to `-', all + specified signals are reset to the values they had when the shell + was started. If ARG is the null string, then SIGSPEC is ignored by + the shell and commands it invokes. If ARG is `-p', the shell + displays the trap commands associated with each SIGSPEC. If no + arguments are supplied, or only `-p' is given, `trap' prints the + list of commands associated with each signal number. SIGSPEC is + either a signal name such as `SIGINT' or a signal number. If + SIGSPEC is `0' or `EXIT', ARG is executed when the shell exits. + If SIGSPEC is `DEBUG', the command ARG is executed after every + simple command. The `-l' option causes the shell to print a list + of signal names and their corresponding numbers. + + Signals ignored upon entry to the shell cannot be trapped or reset. + Trapped signals are reset to their original values in a child + process when it is created. + +`umask' + umask [-S] [MODE] + Set the shell process's file creation mask to MODE. If MODE + begins with a digit, it is interpreted as an octal number; if not, + it is interpreted as a symbolic mode mask similar to that accepted + by the `chmod' command. If MODE is omitted, the current value of + the mask is printed. If the `-S' option is supplied without a + MODE argument, the mask is printed in a symbolic format. + +`unset' + unset [-fv] [NAME] + Each variable or function NAME is removed. If no options are + supplied, or the `-v' option is given, each NAME refers to a shell + variable. If the `-f' option is given, the NAMEs refer to shell + functions, and the function definition is removed. Read-only + variables and functions may not be unset. + + +File: bashref.info, Node: Bourne Shell Variables, Next: Other Bourne Shell Features, Prev: Bourne Shell Builtins, Up: Bourne Shell Features + +Bourne Shell Variables +====================== + + Bash uses certain shell variables in the same way as the Bourne +shell. In some cases, Bash assigns a default value to the variable. + +`IFS' + A list of characters that separate fields; used when the shell + splits words as part of expansion. + +`PATH' + A colon-separated list of directories in which the shell looks for + commands. + +`HOME' + The current user's home directory; the default for the `cd' builtin + command. + +`CDPATH' + A colon-separated list of directories used as a search path for + the `cd' command. + +`MAILPATH' + A colon-separated list of files which the shell periodically checks + for new mail. You can also specify what message is printed by + separating the file name from the message with a `?'. When used + in the text of the message, `$_' stands for the name of the + current mailfile. + +`MAIL' + If this parameter is set to a filename and the `MAILPATH' variable + is not set, Bash informs the user of the arrival of mail in the + specified file. + +`PS1' + The primary prompt string. The default value is `\s-\v\$ '. + +`PS2' + The secondary prompt string. The default value is `> '. + +`OPTIND' + The index of the last option processed by the `getopts' builtin. + +`OPTARG' + The value of the last option argument processed by the `getopts' + builtin. + + +File: bashref.info, Node: Other Bourne Shell Features, Prev: Bourne Shell Variables, Up: Bourne Shell Features + +Other Bourne Shell Features +=========================== + +* Menu: + +* Major Differences From The Bourne Shell:: Major differences between + Bash and the Bourne shell. + + Bash implements essentially the same grammar, parameter and variable +expansion, redirection, and quoting as the Bourne Shell. Bash uses the +POSIX 1003.2 standard as the specification of how these features are to +be implemented. There are some differences between the traditional +Bourne shell and the POSIX standard; this section quickly details the +differences of significance. A number of these differences are +explained in greater depth in subsequent sections. + + +File: bashref.info, Node: Major Differences From The Bourne Shell, Up: Other Bourne Shell Features + +Major Differences From The SVR4.2 Bourne Shell +---------------------------------------------- + + Bash is POSIX-conformant, even where the POSIX specification differs +from traditional `sh' behavior. + + Bash has multi-character invocation options (*note Invoking Bash::.). + + Bash has command-line editing (*note Command Line Editing::.) and +the `bind' builtin. + + Bash has command history (*note Bash History Facilities::.) and the +`history' and `fc' builtins to manipulate it. + + Bash implements `csh'-like history expansion (*note History +Interaction::.). + + Bash has one-dimensional array variables (*note Arrays::.), and the +appropriate variable expansions and assignment syntax to use them. +Some of the Bash builtins take options to act on arrays. Bash provides +some built-in array variables. + + Bash implements the `!' keyword to negate the return value of a +pipeline (*note Pipelines::.). Very useful when an `if' statement +needs to act only if a test fails. + + Bash includes the `select' compound command, which allows the +generation of simple menus (*note Korn Shell Constructs::.). + + Bash includes brace expansion (*note Brace Expansion::.) and tilde +expansion (*note Tilde Expansion::.). + + Bash implements command aliases and the `alias' and `unalias' +builtins (*note Aliases::.). + + Bash provides shell arithmetic and arithmetic expansion (*note Shell +Arithmetic::.). + + The POSIX and `ksh'-style `$()' form of command substitution is +implemented (*note Command Substitution::.), and preferred to the +Bourne shell's ```' (which is also implemented for backwards +compatibility). + + Variables present in the shell's initial environment are +automatically exported to child processes. The Bourne shell does not +normally do this unless the variables are explicitly marked using the +`export' command. + + Bash includes the POSIX and `ksh'-style pattern removal `%', `#', +`%%' and `##' constructs to remove leading or trailing substrings from +variable values (*note Shell Parameter Expansion::.). + + The expansion `${#xx}', which returns the length of `$xx', is +supported (*note Shell Parameter Expansion::.). + + The `$'...'' quoting syntax, which expands ANSI-C backslash-escaped +characters in the text between the single quotes, is supported (*note +ANSI-C Quoting::.). + + Bash supports the `$"..."' quoting syntax to do locale-specific +translation of the characters between the double quotes. The `-D' and +`--dump-strings' invocation options list the translatable strings found +in a script (*note Locale Translation::.). + + The expansion `${var:'LENGTH`[:'OFFSET`]}', which expands to the +substring of `var''s value of length LENGTH, optionally beginning at +OFFSET, is present (*note Shell Parameter Expansion::.). + + The expansion `${var/[/]'PATTERN`[/'REPLACEMENT`]}', which matches +PATTERN and replaces it with REPLACEMENT in the value of `var', is +available (*note Shell Parameter Expansion::.). + + Bash has INDIRECT variable expansion using `${!word}' (*note Shell +Parameter Expansion::.). + + Bash can expand positional parameters beyond `$9' using `${NUM}'. + + Bash has process substitution (*note Process Substitution::.). + + Bash automatically assigns variables that provide information about +the current user (`UID' and `EUID'), the current host (`HOSTTYPE', +`OSTYPE', `MACHTYPE', and `HOSTNAME'), and the instance of Bash that is +running (`BASH', `BASH_VERSION', and `BASH_VERSINFO'. *Note Bash +Variables::, for details. + + The `IFS' variable is used to split only the results of expansion, +not all words (*note Word Splitting::.). This closes a longstanding +shell security hole. + + It is possible to have a variable and a function with the same name; +`sh' does not separate the two name spaces. + + Bash functions are permitted to have local variables using the +`local' builtin, and thus useful recursive functions may be written. + + Variable assignments preceding commands affect only that command, +even builtins and functions. In `sh', all variable assignments +preceding commands are global unless the command is executed from the +file system. + + Bash performs filename expansion on filenames specified as operands +to output redirection operators. + + Bash contains the `<>' redirection operator, allowing a file to be +opened for both reading and writing, and the `&>' redirection operator, +for directing standard output and standard error to the same file +(*note Redirections::.). + + The `noclobber' option is available to avoid overwriting existing +files with output redirection (*note The Set Builtin::.). The `>|' +redirection operator may be used to override `noclobber'. + + Bash interprets special backslash-escaped characters in the prompt +strings when interactive (*note Printing a Prompt::.). + + Bash allows you to write a function to override a builtin, and +provides access to that builtin's functionality within the function via +the `builtin' and `command' builtins (*note Bash Builtins::.). + + The `command' builtin allows selective disabling of functions when +command lookup is performed (*note Bash Builtins::.). + + Individual builtins may be enabled or disabled using the `enable' +builtin (*note Bash Builtins::.). + + The Bash `hash' builtin allows a name to be associated with an +arbitrary filename, even when that filename cannot be found by +searching the `$PATH', using `hash -p'. + + Shell functions may be exported to children via the environment +(*note Shell Functions::.). + + Bash includes a `help' builtin for quick reference to shell +facilities (*note Bash Builtins::.). + + The Bash `read' builtin (*note Bash Builtins::.) will read a line +ending in `\' with the `-r' option, and will use the `REPLY' variable +as a default if no arguments are supplied. The Bash `read' builtin +also accepts a prompt string with the `-p' option and will use Readline +to obtain the line when given the `-e' option. + + Bash includes the `shopt' builtin, for finer control of shell +optional capabilities (*note Bash Builtins::.). + + Bash has much more optional behavior controllable with the `set' +builtin (*note The Set Builtin::.). + + The `disown' builtin can remove a job from the internal shell job +table (*note Job Control Builtins::.). + + The `return' builtin may be used to abort execution of scripts +executed with the `.' or `source' builtins (*note Bourne Shell +Builtins::.). + + The `test' builtin (*note Bourne Shell Builtins::.) is slightly +different, as it implements the POSIX 1003.2 algorithm, which specifies +the behavior based on the number of arguments. + + The `trap' builtin (*note Bourne Shell Builtins::.) allows a `DEBUG' +pseudo-signal specification, similar to `EXIT'. Commands specified +with a `DEBUG' trap are executed after every simple command. The +`DEBUG' trap is not inherited by shell functions. + + The Bash `export', `readonly', and `declare' builtins can take a +`-f' option to act on shell functions, a `-p' option to display +variables with various attributes set in a format that can be used as +shell input, a `-n' option to remove various variable attributes, and +`name=value' arguments to set variable attributes and values +simultaneously. + + The Bash `cd' and `pwd' builtins each take `-L' and `-P' builtins to +switch between logical and physical modes. + + The Bash `type' builtin is more extensive and gives more information +about the names it finds. + + Bash implements a `csh'-like directory stack, and provides the +`pushd', `popd', and `dirs' builtins to manipulate it. Bash also makes +the directory stack visible as the value of the `DIRSTACK' shell +variable. + + The Bash restricted mode is more useful (*note The Restricted +Shell::.); the SVR4.2 shell restricted mode is too limited. + + Bash has the `time' reserved word and command timing (*note +Pipelines::.). The display of the timing statistics may be controlled +with the `TIMEFORMAT' variable. + + The SVR4.2 shell has two privilege-related builtins (`mldmode' and +`priv') not present in Bash. + + Bash does not have the `stop' or `newgrp' builtins. + + Bash does not use the `SHACCT' variable or perform shell accounting. + + The SVR4.2 `sh' uses a `TIMEOUT' variable like Bash uses `TMOUT'. + + More features unique to Bash may be found in *Note Bash Features::. + +Implementation Differences From The SVR4.2 Shell +------------------------------------------------ + + Since Bash is a completely new implementation, it does not suffer +from many of the limitations of the SVR4.2 shell. For instance: + + * Bash does not fork a subshell when redirecting into or out of a + shell control structure such as an `if' or `while' statement. + + * Bash does not allow unbalanced quotes. The SVR4.2 shell will + silently insert a needed closing quote at `EOF' under certain + circumstances. This can be the cause of some hard-to-find errors. + + * The SVR4.2 shell uses a baroque memory management scheme based on + trapping `SIGSEGV'. If the shell is started from a process with + `SIGSEGV' blocked (e.g., by using the `system()' C library + function call), the shell misbehaves badly. + + * In a questionable attempt at security, the SVR4.2 shell will alter + its real and effective UID and GID if they are less than some + threshold value, commonly 100. This can lead to unexpected + results. + + * The SVR4.2 shell does not allow users to trap `SIGALRM' or + `SIGCHLD'. + + * For some reason, the SVR4.2 shell does not allow the `MAILCHECK' + variable to be unset. + + * The SVR4.2 shell treats `^' as the undocumented equivalent of `|'. + + * Bash allows multiple option arguments when it is invoked (`-x -v'); + the SVR4.2 shell allows only one option argument (`-xv'). In + fact, some versions of the shell dump core if the second argument + begins with a `-'. + + * The SVR4.2 shell exits a script if any builtin fails; Bash exits a + script only if one of the POSIX.2 special builtins fails, and only + for certain failures, as enumerated in the `POSIX.2' standard. + + * The SVR4.2 shell behaves differently when invoked as `jsh' (it + turns on job control). + + +File: bashref.info, Node: Csh Features, Next: Korn Shell Features, Prev: Bourne Shell Features, Up: Top + +C-Shell Style Features +********************** + + The C-Shell ("`csh'") was created by Bill Joy at The University of +California at Berkeley. It is generally considered to have better +features for interactive use than the original Bourne shell. Some of +the `csh' features present in Bash include job control, history +expansion, `protected' redirection, and several variables to control +the interactive behaviour of the shell (e.g., `IGNOREEOF'). + + *Note Using History Interactively::, for details on history +expansion. + +* Menu: + +* Brace Expansion:: Expansion of expressions within braces. +* Tilde Expansion:: Expansion of the ~ character. +* C Shell Builtins:: Builtin commands adopted from the C Shell. +* C Shell Variables:: Variables which Bash uses in essentially + the same way as the C Shell. + + +File: bashref.info, Node: Brace Expansion, Next: Tilde Expansion, Up: Csh Features + +Brace Expansion +=============== + + Brace expansion is a mechanism by which arbitrary strings may be +generated. This mechanism is similar to FILENAME EXPANSION (*note +Filename Expansion::.), but the file names generated need not exist. +Patterns to be brace expanded take the form of an optional PREAMBLE, +followed by a series of comma-separated strings between a pair of +braces, followed by an optional POSTAMBLE. The preamble is prepended +to each string contained within the braces, and the postamble is then +appended to each resulting string, expanding left to right. + + Brace expansions may be nested. The results of each expanded string +are not sorted; left to right order is preserved. For example, + bash$ echo a{d,c,b}e + ade ace abe + + Brace expansion is performed before any other expansions, and any +characters special to other expansions are preserved in the result. It +is strictly textual. Bash does not apply any syntactic interpretation +to the context of the expansion or the text between the braces. + + A correctly-formed brace expansion must contain unquoted opening and +closing braces, and at least one unquoted comma. Any incorrectly +formed brace expansion is left unchanged. + + This construct is typically used as shorthand when the common prefix +of the strings to be generated is longer than in the above example: + mkdir /usr/local/src/bash/{old,new,dist,bugs} + or + chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} + + +File: bashref.info, Node: Tilde Expansion, Next: C Shell Builtins, Prev: Brace Expansion, Up: Csh Features + +Tilde Expansion +=============== + + 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 `fred'. + +`~+/foo' + `$PWD/foo' + +`~-/foo' + `$OLDPWD/foo' + + Bash will also tilde expand words following redirection operators +and words following `=' in assignment statements. + + +File: bashref.info, Node: C Shell Builtins, Next: C Shell Variables, Prev: Tilde Expansion, Up: Csh Features + +C Shell Builtins +================ + + Bash has several builtin commands whose definition is very similar +to `csh'. + +`pushd' + pushd [DIR | +N | -N] [-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 (counting from the left of the list + printed by `dirs') to the top of the list by rotating the + stack. + + `-N' + Brings the Nth directory (counting from the right of the list + printed by `dirs') to the top of the list by rotating the + stack. + + `-n' + Suppresses the normal change of directory when adding + directories to the stack, so that only the stack is + manipulated. + + `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 | -N] [-n] + + Pop the directory stack, and `cd' to the new top directory. When + no arguments are given, `popd' removes the top directory from the + stack and performs a `cd' 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'. + `+N' + Removes the Nth directory (counting from the left of the list + printed by `dirs'), starting with zero. + + `-N' + Removes the Nth directory (counting from the right of the + list printed by `dirs'), starting with zero. + + `-n' + Suppresses the normal change of directory when removing + directories from the stack, so that only the stack is + manipulated. + +`dirs' + dirs [+N | -N] [-clvp] + 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. + `+N' + Displays the Nth directory (counting from the left of the + list printed by `dirs' when invoked without options), starting + with zero. + + `-N' + Displays the Nth directory (counting from the right of the + list printed by `dirs' when invoked without options), starting + with zero. + + `-c' + Clears the directory stack by deleting all of the elements. + + `-l' + Produces a longer listing; the default listing format uses a + tilde to denote the home directory. + + `-p' + Causes `dirs' to print the directory stack with one entry per + line. + + `-v' + Causes `dirs' to print the directory stack with one entry per + line, prepending each entry with its index in the stack. + +`history' + history [-c] [N] + history [-anrw] [FILENAME] + history -ps ARG + + Display the history list with line numbers. Lines prefixed with + with a `*' have been modified. An argument of N says to list only + the last N lines. Options, if supplied, have the following + meanings: + + `-w' + Write out the current history to the history file. + + `-r' + Read the current history file and append its contents to the + history list. + + `-a' + Append the new history lines (history lines entered since the + beginning of the current Bash session) to the history file. + + `-n' + Append the history lines not already read from the history + file to the current history list. These are lines appended + to the history file since the beginning of the current Bash + session. + + `-c' + Clear the history list. This may be combined with the other + options to replace the history list completely. + + `-s' + The ARGs are added to the end of the history list as a single + entry. + + `-p' + Perform history substitution on the ARGs and display the + result on the standard output, without storing the results in + the history list. + + When the `-w', `-r', `-a', or `-n' option is used, if FILENAME is + given, then it is used as the history file. If not, then the + value of the `HISTFILE' variable is used. + +`logout' + Exit a login shell. + +`source' + A synonym for `.' (*note Bourne Shell Builtins::.). + + +File: bashref.info, Node: C Shell Variables, Prev: C Shell Builtins, Up: Csh Features + +C Shell Variables +================= + +`IGNOREEOF' + If this variable is set, its value is used the number of + consecutive `EOF's Bash will read before exiting. By default, + Bash will exit upon reading a single `EOF'. If `IGNOREEOF' is not + set to a numeric value, Bash acts as if its value were 10. + + +File: bashref.info, Node: Korn Shell Features, Next: Bash Features, Prev: Csh Features, Up: Top + +Korn Shell Style Features +************************* + + This section describes features primarily inspired by the Korn Shell +(`ksh'). In some cases, the POSIX 1003.2 standard has adopted these +commands and variables from the Korn Shell; Bash implements those +features using the POSIX standard as a guide. + +* Menu: + +* Korn Shell Constructs:: Shell grammar constructs adopted from the + Korn Shell +* Korn Shell Builtins:: Builtin commands adopted from the Korn Shell. +* Korn Shell Variables:: Variables which Bash uses in essentially + the same way as the Korn Shell. +* Aliases:: Substituting one command for another. + + +File: bashref.info, Node: Korn Shell Constructs, Next: Korn Shell Builtins, Up: Korn Shell Features + +Korn Shell Constructs +===================== + + Bash includes the Korn Shell `select' construct. This construct +allows the easy generation of menus. It has almost the same syntax as +the `for' command. + + The syntax of the `select' command is: + select NAME [in WORDS ...]; do COMMANDS; done + + The list of words following `in' is expanded, generating a list of +items. The set of expanded words is printed on the standard error, +each preceded by a number. If the `in WORDS' is omitted, the +positional parameters are printed. The `PS3' prompt is then displayed +and a line is read from the standard input. If the line consists of a +number corresponding to one of the displayed words, then the value of +NAME is set to that word. If the line is empty, the words and prompt +are displayed again. If `EOF' is read, the `select' command completes. +Any other value read causes NAME to be set to null. The line read is +saved in the variable `REPLY'. + + The COMMANDS are executed after each selection until a `break' or +`return' command is executed, at which point the `select' command +completes. + + Bash also has adopted command timing from the Korn shell. If the +`time' reserved word precedes a pipeline or simple command, timing +statistics for the pipeline are displayed when it completes. The +statistics currently consist of elapsed (wall-clock) time and user and +system time consumed by the command's execution. + + The use of `time' as a reserved word permits the timing of shell +builtins, shell functions, and pipelines. An external `time' command +cannot time these easily. + + +File: bashref.info, Node: Korn Shell Builtins, Next: Korn Shell Variables, Prev: Korn Shell Constructs, Up: Korn Shell Features + +Korn Shell Builtins +=================== + + This section describes Bash builtin commands taken from `ksh'. + +`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. Both FIRST and 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 each instance of + PAT in the selected command is replaced by REP. + + 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 (*note Aliases::.). + +`let' + The `let' builtin allows arithmetic to be performed on shell + variables. For details, refer to *Note Arithmetic Builtins::. + +`typeset' + The `typeset' command is supplied for compatibility with the Korn + shell; however, it has been deprecated in favor of the `declare' + command (*note Bash Builtins::.). + + +File: bashref.info, Node: Korn Shell Variables, Next: Aliases, Prev: Korn Shell Builtins, Up: Korn Shell Features + +Korn Shell Variables +==================== + +`REPLY' + The default variable for the `read' builtin. + +`RANDOM' + Each time this parameter is referenced, a random integer between 0 + and 32767 is generated. Assigning a value to this variable seeds + the random number generator. + +`SECONDS' + This variable expands to the number of seconds since the shell was + started. Assignment to this variable resets the count to the + value assigned, and the expanded value becomes the value assigned + plus the number of seconds since the assignment. + +`PS3' + The value of this variable is used as the prompt for the `select' + command. If this variable is not set, the `select' command + prompts with `#? ' + +`PS4' + This is the prompt printed before the command line is echoed when + the `-x' option is set (*note The Set Builtin::.). The default is + `+ '. + +`PWD' + The current working directory as set by the `cd' builtin. + +`OLDPWD' + The previous working directory as set by the `cd' builtin. + +`TMOUT' + If set to a value greater than zero, the value is interpreted as + the number of seconds to wait for input after issuing the primary + prompt. Bash terminates after that number of seconds if input does + not arrive. + +`LINENO' + The line number in the script or shell function currently + executing. + +`ENV' + If this variable is set when Bash is invoked to execute a shell + script, its value is expanded and used as the name of a startup + file to read before executing the script. *Note Bash Startup + Files::. + +`FCEDIT' + The editor used as a default by the `fc' builtin command. + + +File: bashref.info, Node: Aliases, Prev: Korn Shell Variables, Up: Korn Shell Features + +Aliases +======= + +* Menu: + +* Alias Builtins:: Builtins commands to maniuplate aliases. + + The shell maintains a list of ALIASES that may be set and unset with +the `alias' and `unalias' builtin commands. + + The first word of each command, if unquoted, is checked to see if it +has an alias. If so, that word is replaced by the text of the alias. +The alias name and the replacement text may contain any valid shell +input, including shell metacharacters, with the exception that the +alias name may not contain =. The first word of the replacement text +is tested for aliases, but a word that is identical to an alias being +expanded is not expanded a second time. This means that one may alias +`ls' to `"ls -F"', for instance, and Bash does not try to recursively +expand the replacement text. If the last character of the alias value +is a space or tab character, then the next command word following the +alias is also checked for alias expansion. + + Aliases are created and listed with the `alias' command, and removed +with the `unalias' command. + + There is no mechanism for using arguments in the replacement text, +as in `csh'. If arguments are needed, a shell function should be used +(*note Shell Functions::.). + + Aliases are not expanded when the shell is not interactive, unless +the `expand_aliases' shell option is set using `shopt' (*note Bash +Builtins::.). + + The rules concerning the definition and use of aliases are somewhat +confusing. Bash always reads at least one complete line of input +before executing any of the commands on that line. Aliases are +expanded when a command is read, not when it is executed. Therefore, an +alias definition appearing on the same line as another command does not +take effect until the next line of input is read. The commands +following the alias definition on that line are not affected by the new +alias. This behavior is also an issue when functions are executed. +Aliases are expanded when the function definition is read, not when the +function is executed, because a function definition is itself a +compound command. As a consequence, aliases defined in a function are +not available until after that function is executed. To be safe, +always put alias definitions on a separate line, and do not use `alias' +in compound commands. + + Note that for almost every purpose, aliases are superseded by shell +functions. + + +File: bashref.info, Node: Alias Builtins, Up: Aliases + +Alias Builtins +-------------- + +`alias' + alias [`-p'] [NAME[=VALUE] ...] + + Without arguments or with the `-p' option, `alias' prints the list + of aliases on the standard output in a form that allows them to be + reused as input. If arguments are supplied, an alias is defined + for each NAME whose VALUE is given. If no VALUE is given, the name + and value of the alias is printed. + +`unalias' + unalias [-a] [NAME ... ] + + Remove each NAME from the list of aliases. If `-a' is supplied, + all aliases are removed. + + +File: bashref.info, Node: Bash Features, Next: Job Control, Prev: Korn Shell Features, Up: Top + +Bash Features +************* + + This section describes features unique to Bash. + +* Menu: + +* Invoking Bash:: Command line options that you can give + to Bash. +* Bash Startup Files:: When and how Bash executes scripts. +* Is This Shell Interactive?:: Determining the state of a running Bash. +* Bash Builtins:: Table of builtins specific to Bash. +* The Set Builtin:: This builtin is so overloaded it + deserves its own section. +* Bash Conditional Expressions:: Primitives used in composing expressions for + the `test' builtin. +* Bash Variables:: List of variables that exist in Bash. +* Shell Arithmetic:: Arithmetic on shell variables. +* Arrays:: Array Variables +* Printing a Prompt:: Controlling the PS1 string. +* The Restricted Shell:: A more controlled mode of shell execution. +* Bash POSIX Mode:: Making Bash behave more closely to what + the POSIX standard specifies. + + +File: bashref.info, Node: Invoking Bash, Next: Bash Startup Files, Up: Bash Features + +Invoking Bash +============= + + bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o OPTION] [ARGUMENT ...] + bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o OPTION] -c STRING [ARGUMENT ...] + bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o OPTION] [ARGUMENT ...] + + In addition to the single-character shell command-line options +(*note The Set Builtin::.), there are several multi-character options +that you can use. These options must appear on the command line before +the single-character options in order for them to be recognized. + +`--dump-strings' + Equivalent to `-D'. + +`--help' + Display a usage message on standard output and exit sucessfully. + +`--login' + Make this shell act as if it were directly invoked by login. This + is equivalent to `exec -l 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'. + +`--noediting' + Do not use the GNU Readline library (*note Command Line Editing::.) + to read interactive command lines. + +`--noprofile' + Don't load the system-wide startup file `/etc/profile' or any of + the personal initialization files `~/.bash_profile', + `~/.bash_login', or `~/.profile' when Bash is invoked as a login + shell. + +`--norc' + Don't read the `~/.bashrc' initialization file in an interactive + shell. This is on by default if the shell is invoked as `sh'. + +`--posix' + Change the behavior of Bash where the default operation differs + from the POSIX 1003.2 standard to match the standard. This is + intended to make Bash behave as a strict superset of that + standard. *Note Bash POSIX Mode::, for a description of the Bash + POSIX mode. + +`--rcfile FILENAME' + Execute commands from FILENAME (instead of `~/.bashrc') in an + interactive shell. + +`--restricted' + Make the shell a restricted shell (*note The Restricted Shell::.). + +`--verbose' + Equivalent to `-v'. + +`--version' + Show version information for this instance of Bash on the standard + output and exit successfully. + + There are several single-character options you can give which are +not available with the `set' builtin. + +`-c STRING' + Read and execute commands from STRING after processing the + options, then exit. Any remaining arguments are assigned to the + positional parameters, starting with `$0'. + +`-i' + Force the shell to run interactively. + +`-r' + Make the shell restricted. + +`-s' + If this flag is present, or if no arguments remain after option + processing, then commands are read from the standard input. This + option allows the positional parameters to be set when invoking an + interactive shell. + +`-D' + A list of all double-quoted strings preceded by `$' is printed on + the standard ouput. These are the strings that are subject to + language translation when the current locale is not `C' or `POSIX' + (*note Locale Translation::.). This implies the `-n' option; no + commands will be executed. + + An *interactive* shell is one whose input and output are both +connected to terminals (as determined by `isatty()'), or one started +with the `-i' option. + + If arguments remain after option processing, and neither the `-c' +nor the `-s' option has been supplied, the first argument is assumed to +be the name of a file containing shell commands (*note Shell +Scripts::.). When Bash is invoked in this fashion, `$0' is set to the +name of the file, and the positional parameters are set to the +remaining arguments. Bash reads and executes commands from this file, +then exits. Bash's exit status is the exit status of the last command +executed in the script. If no commands are executed, the exit status +is 0. + + +File: bashref.info, Node: Bash Startup Files, Next: Is This Shell Interactive?, Prev: Invoking Bash, Up: Bash Features + +Bash Startup Files +================== + + This section describs how bash executes its startup files. If any +of the files exist but cannot be read, bash reports an error. Tildes +are expanded in file names as described above under Tilde Expansion +(*note Tilde Expansion::.). + + When Bash is invoked as a login shell, it first reads and executes +commands from the file `/etc/profile', if that file exists. After +reading that file, it looks for `~/.bash_profile', `~/.bash_login', and +`~/.profile', in that order, and reads and executes commands from the +first one that exists and is readable. The `--noprofile' option may be +used when the shell is started to inhibit this behavior. + + When a login shell exits, Bash reads and executes commands from the +file `~/.bash_logout', if it exists. + + When an interactive shell that is not a login shell is started, Bash +reads and executes commands from `~/.bashrc', if that file exists. +This may be inhibited by using the `--norc' option. The `--rcfile +FILE' option will force Bash to read and execute commands from FILE +instead of `~/.bashrc'. + + So, typically, your `~/.bash_profile' contains the line + `if [ -f `~/.bashrc' ]; then . `~/.bashrc'; fi' + +after (or before) any login-specific initializations. + + When Bash is started non-interactively, to run a shell script, for +example, it looks for the variable `BASH_ENV' in the environment, +expands its value if it appears there, and uses the expanded value as +the name of a file to read and execute. Bash behaves as if the +following command were executed: + `if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi' + +but the value of the `PATH' variable is not used to search for the file +name. + + If Bash is invoked with the name `sh', it tries to mimic the startup +behavior of historical versions of `sh' as closely as possible, while +conforming to the POSIX standard as well. + + When invoked as a login shell, it first attempts to read and execute +commands from `/etc/profile' and `~/.profile', in that order. The +`--noprofile' option may be used to inhibit this behavior. When +invoked as an interactive shell with the name `sh', `bash' looks for +the variable `ENV', expands its value if it is defined, and uses the +expanded value as the name of a file to read and execute. Since a +shell invoked as `sh' does not attempt to read and execute commands +from any other startup files, the `--rcfile' option has no effect. A +non-interactive shell invoked with the name `sh' does not attempt to +read any startup files. + + When invoked as `sh', Bash enters POSIX mode after the startup files +are read. + + When Bash is started in POSIX mode, as with the `--posix' command +line option, it follows the POSIX standard for startup files. In this +mode, the `ENV' variable is expanded and commands are read and executed +from the file whose name is the expanded value. No other startup files +are read. This is done by both interactive and non-interactive shells. + + Bash attempts to determine when it is being run by the remote shell +daemon, usually `rshd'. If Bash determines it is being run by rshd, it +reads and executes commands from `~/.bashrc', if that file exists and +is readable. It will not do this if invoked as `sh'. The `--norc' +option may be used to inhibit this behavior, and the `--rcfile' option +may be used to force another file to be read, but rshd does not +generally invoke the shell with those options or allow them to be +specified. + + +File: bashref.info, Node: Is This Shell Interactive?, Next: Bash Builtins, Prev: Bash Startup Files, Up: Bash Features + +Is This Shell Interactive? +========================== + + As defined in *Note Invoking Bash::, an interactive shell is one +whose input and output are both connected to terminals (as determined +by `isatty(3)'), or one started with the `-i' option. + + You may wish to determine within a startup script whether Bash is +running interactively or not. To do this, examine the variable `$PS1'; +it is unset in non-interactive shells, and set in interactive shells. +Thus: + + if [ -z "$PS1" ]; then + echo This shell is not interactive + else + echo This shell is interactive + fi + + +File: bashref.info, Node: Bash Builtins, Next: The Set Builtin, Prev: Is This Shell Interactive?, Up: Bash Features + +Bash Builtin Commands +===================== + + This section describes builtin commands which are unique to or have +been extended in Bash. + +`bind' + bind [-m KEYMAP] [-lpsvPSV] [-q NAME] [-r KEYSEQ] + bind [-m KEYMAP] -f FILENAME + bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME + + Display current Readline (*note Command Line Editing::.) key and + function bindings, or bind a key sequence to a Readline function + or macro. The binding syntax accepted is identical to that of + `.inputrc' (*note Readline Init File::.), but each binding must be + passed as a separate argument: e.g., + `"\C-x\C-r":re-read-init-file'. Options, if supplied, have the + following meanings: + + `-m KEYMAP' + Use KEYMAP as the keymap to be affected by the subsequent + bindings. Acceptable KEYMAP names are `emacs', + `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', + `vi-command', and `vi-insert'. `vi' is equivalent to + `vi-command'; `emacs' is equivalent to `emacs-standard'. + + `-l' + List the names of all Readline functions + + `-p' + Display Readline function names and bindings in such a way + that they can be re-read + + `-P' + List current Readline function names and bindings + + `-v' + Display Readline variable names and values in such a way that + they can be re-read + + `-V' + List current Readline variable names and values + + `-s' + Display Readline key sequences bound to macros and the + strings they output in such a way that they can be re-read + + `-S' + Display Readline key sequences bound to macros and the + strings they output + + `-f FILENAME' + Read key bindings from FILENAME + + `-q' + Query about which keys invoke the named FUNCTION + + `-r KEYSEQ' + Remove any current binding for KEYSEQ + +`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. + +`command' + command [-pVv] 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'. The `-p' option means to use a default + value for `$PATH' that is guaranteed to find all of the standard + utilities. + + If either the `-V' or `-v' option is supplied, a description of + COMMAND is printed. The `-v' option causes a single word + indicating the command or file name used to invoke COMMAND to be + printed; the `-V' option produces a more verbose description. + +`declare' + declare [-afFrxi] [-p] [NAME[=VALUE]] + + Declare variables and give them attributes. If no NAMEs are + given, then display the values of variables instead. + + The `-p' option will display the attributes and values of each + NAME. When `-p' is used, additional options are ignored. The + `-F' option inhibits the display of function definitions; only the + function name and attributes are printed. `-F' implies `-f'. The + following options can be used to restrict output to variables with + the specified attributes or to give variables attributes: + + `-a' + Each NAME is an array variable (*note Arrays::.). + + `-f' + Use function names only. + + `-i' + The variable is to be treated as an integer; arithmetic + evaluation (*note Shell Arithmetic::.) is performed when the + variable is assigned a value. + + `-r' + Make NAMEs readonly. These names cannot then be assigned + values by subsequent assignment statements. + + `-x' + Mark each NAME for export to subsequent commands via the + environment. + + Using `+' instead of `-' turns off the attribute instead. When + used in a function, `declare' makes each NAME local, as with the + `local' command. + +`echo' + echo [-neE] [arg ...] + Output the `arg's, separated by spaces, terminated with a newline. + The return status is always 0. If `-n' is specified, the + trailing newline is suppressed. If the `-e' option is given, + interpretation of the following backslash-escaped characters is + enabled. The `-E' option disables the interpretation of these + escape characters, even on systems where they are interpreted by + default. `echo' interprets the following escape sequences: + `\a' + alert (bell) + + `\b' + backspace + + `\c' + suppress trailing newline + + `\e' + escape + + `\f' + form feed + + `\n' + new line + + `\r' + carriage return + + `\t' + horizontal tab + + `\v' + vertical tab + + `\\' + backslash + + `\nnn' + the character whose ASCII code is `nnn' (octal) + +`enable' + enable [-n] [-p] [-f FILENAME] [-ads] [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' binary found via `$PATH' + instead of the shell builtin version, type `enable -n test'. + + If the `-p' option is supplied, or no NAME arguments appear, a + list of shell builtins is printed. With no other arguments, the + list consists of all enabled shell builtins. The `-a' option + means to list each builtin with an indication of whether or not it + is enabled. + + The `-f' option means to load the new builtin command NAME from + shared object FILENAME, on systems that support dynamic loading. + The `-d' option will delete a builtin loaded with `-f'. If there + are no options, a list of the shell builtins is displayed. The + `-s' option restricts `enable' to the POSIX.2 special builtins. + If `-s' is used with `-f', the new builtin becomes a special + builtin. + +`help' + help [PATTERN] + Display helpful information about builtin commands. If PATTERN is + specified, `help' gives detailed help on all commands matching + PATTERN, otherwise a list of the builtins is printed. + +`local' + local NAME[=VALUE] + For each argument, 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. + +`logout' + logout [N] + Exit a login shell, returning a status of N to the shell's parent. + +`read' + read [-a ANAME] [-p PROMPT] [-er] [NAME ...] + One line is read from the standard input, and the first word is + assigned to the first NAME, the second word to the second NAME, + and so on, with leftover words assigned to the last NAME. Only + the characters in the value of the `IFS' variable are recognized + as word delimiters. If no names are supplied, the line read is + assigned to the variable `REPLY'. The return code is zero, unless + end-of-file is encountered. Options, if supplied, have the + following meanings: + + `-r' + If this option is given, a backslash-newline pair is not + ignored, and the backslash is considered to be part of the + line. + + `-p PROMPT' + Display `prompt', without a trailing newline, before + attempting to read any input. The prompt is displayed only + if input is coming from a terminal. + + `-a ANAME' + The words are assigned to sequential indices of the array + variable ANAME, starting at 0. + + `-e' + Readline (*note Command Line Editing::.) is used to obtain + the line. + +`shopt' + shopt [-pqsu] [-o] [OPTNAME ...] + Toggle the values of variables controlling optional shell behavior. + With no options, or with the `-p' option, a list of all settable + options is displayed, with an indication of whether or not each is + set. Other options have the following meanings: + + `-s' + Enable (set) each OPTNAME + + `-u' + Disable (unset) each OPTNAME. + + `-q' + Suppresses normal output; the return status indicates whether + the OPTNAME is set or unset. If multiple OPTNAME arguments + are given with `-q', the return status is zero if all + OPTNAMES are enabled; non-zero otherwise. + + `-o' + Restricts the values of OPTNAME to be those defined for the + `-o' option to the `set' builtin (*note The Set Builtin::.). + + If either of `-s' or `-u' is used with no OPTNAME arguments, the + display is limited to those options which are set or unset, + respectively. + + Unless otherwise noted, the `shopt' options are disabled (off) by + default. + + The return status when listing options is zero if all OPTNAMES are + enabled, non-zero otherwise. When setting or unsetting options, + the return status is zero unless an OPTNAME is not a legal shell + option. + + The list of `shopt' options is: + `cdable_vars' + If this is set, an argument to the `cd' builtin command that + is not a directory is assumed to be the name of a variable + whose value is the directory to change to. + + `cdspell' + If set, minor errors in the spelling of a directory component + in a `cd' command will be corrected. The errors checked for + are transposed characters, a missing character, and a + character too many. If a correction is found, the corrected + path is printed, and the command proceeds. This option is + enabled by default, but is only used by interactive shells. + + `checkhash' + If this is set, Bash checks that a command found in the hash + table exists before trying to execute it. If a hashed + command no longer exists, a normal path search is performed. + + `checkwinsize' + If set, Bash checks the window size after each command and, + if necessary, updates the values of `LINES' and `COLUMNS'. + + `cmdhist' + If set, Bash attempts to save all lines of a multiple-line + command in the same history entry. This allows easy + re-editing of multi-line commands. + + `dotglob' + If set, Bash includes filenames beginning with a `.' in the + results of filename expansion. + + `execfail' + If this is set, a non-interactive shell will not exit if it + cannot execute the file specified as an argument to the `exec' + builtin command. An interactive shell does not exit if `exec' + fails. + + `histappend' + If set, the history list is appended to the file named by the + value of the `HISTFILE' variable when the shell exits, rather + than overwriting the file. + + `histreedit' + If set, and Readline is being used, a user is given the + opportunity to re-edit a failed history substitution. + + `histverify' + If set, and Readline is being used, the results of history + substitution are not immediately passed to the shell parser. + Instead, the resulting line is loaded into the Readline + editing buffer, allowing further modification. + + `hostcomplete' + If set, and Readline is being used, Bash will attempt to + perform hostname completion when a word beginning with `@' is + being completed (*note Commands For Completion::.). + + `interactive_comments' + Allow a word beginning with `#' to cause that word and all + remaining characters on that line to be ignored in an + interactive shell. This option is enabled by default. + + `lithist' + If enabled, and the `cmdhist' option is enabled, multi-line + commands are saved to the history with embedded newlines + rather than using semicolon separators where possible. + + `mailwarn' + If set, and a file that Bash is checking for mail has been + accessed since the last time it was checked, the message + `"The mail in MAILFILE has been read"' is displayed. + + `nullglob' + If set, Bash allows filename patterns which match no files to + expand to a null string, rather than themselves. + + `promptvars' + If set, prompt strings undergo variable and parameter + expansion after being expanded (*note Printing a Prompt::.). + This option is enabled by default. + + `shift_verbose' + If this is set, the `shift' builtin prints an error message + when the shift count exceeds the number of positional + parameters. + + `sourcepath' + If set, the `source' builtin uses the value of `PATH' to find + the directory containing the file supplied as an argument. + This is enabled by default. + +`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 `keyword', if + NAME is an alias, shell function, shell builtin, disk file, or + shell reserved word, respectively. If the NAME is not found, then + nothing is printed, and `type' returns a failure status. + + If the `-path' flag is used, `type' either returns the name of the + disk file that would be executed, or nothing if `-type' would not + 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. + + `type' accepts `-a', `-t', and `-p' as equivalent to `-all', + `-type', and `-path', respectively. + +`ulimit' + ulimit [-acdflmnpstuvSH] [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: + `-S' + change and report the soft limit associated with a resource. + + `-H' + change and report the hard limit associated with a resource. + + `-a' + all current limits are reported. + + `-c' + the maximum size of core files created. + + `-d' + the maximum size of a process's data segment. + + `-f' + the maximum size of files created by the shell. + + `-l' + The maximum size that may be locked into memory. + + `-m' + the maximum resident set size. + + `-n' + the maximum number of open file descriptors. + + `-p' + the pipe buffer size. + + `-s' + the maximum stack size. + + `-t' + the maximum amount of cpu time in seconds. + + `-u' + the maximum number of processes available to a single user. + + `-v' + the maximum amount of virtual memory available to the process. + + If LIMIT is given, it is the new value of the specified resource. + Otherwise, the current value of the soft limit for the specified + resource is printed, unless the `-H' option is supplied. When + setting new limits, if neither `-H' nor `-S' is supplied, both the + hard and soft limits are set. If no option is given, then `-f' is + assumed. Values are in 1024-byte increments, except for `-t', + which is in seconds, `-p', which is in units of 512-byte blocks, + and `-n' and `-u', which are unscaled values. + + +File: bashref.info, Node: The Set Builtin, Next: Bash Conditional Expressions, Prev: Bash Builtins, Up: Bash Features + +The Set Builtin +=============== + + This builtin is so overloaded that it deserves its own section. + +`set' + set [-abefhkmnptuvxdBCHP] [-o OPTION] [ARGUMENT ...] + + `-a' + Mark variables which are modified or created for export. + + `-b' + Cause the status of terminated background jobs to be reported + immediately, rather than before printing the next primary + prompt. + + `-e' + Exit immediately if a simple command exits with a non-zero + status. + + `-f' + Disable file name generation (globbing). + + `-h' + Locate and remember (hash) commands as they are looked up for + execution. + + `-k' + All arguments in the form of assignment statements are placed + in the environment for a command, not just those that precede + the command name. + + `-m' + Job control is enabled (*note Job Control::.). + + `-n' + Read commands but do not execute them. + + `-o OPTION-NAME' + Set the flag corresponding to OPTION-NAME: + + `allexport' + same as `-a'. + + `braceexpand' + same as `-B'. + + `emacs' + use an `emacs'-style line editing interface (*note + Command Line Editing::.). + + `errexit' + same as `-e'. + + `hashall' + same as `-h'. + + `histexpand' + same as `-H'. + + `history' + Enable command history, as described in *Note Bash + History Facilities::. This option is on by default in + interactive shells. + + `ignoreeof' + the shell will not exit upon reading EOF. + + `keyword' + same as `-k'. + + `monitor' + same as `-m'. + + `noclobber' + same as `-C'. + + `noexec' + same as `-n'. + + `noglob' + same as `-f'. + + `notify' + same as `-b'. + + `nounset' + same as `-u'. + + `onecmd' + same as `-t'. + + `physical' + same as `-P'. + + `posix' + change the behavior of Bash where the default operation + differs from the POSIX 1003.2 standard to match the + standard. This is intended to make Bash behave as a + strict superset of that standard. + + `privileged' + same as `-p'. + + `verbose' + same as `-v'. + + `vi' + use a `vi'-style line editing interface. + + `xtrace' + same as `-x'. + + `-p' + Turn on privileged mode. In this mode, the `$ENV' file is + not processed, and shell functions are not inherited from the + environment. This is enabled automatically on startup if the + effective user (group) id is not equal to the real user + (group) id. Turning this option off causes the effective user + and group ids to be set to the real user and group ids. + + `-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. + + `-B' + The shell will perform brace expansion (*note Brace + Expansion::.). This option is on by default. + + `-C' + Disallow output redirection to existing files. + + `-H' + Enable `!' style history substitution (*note History + Interaction::.). This flag is on by default for interactive + shells. + + `-P' + If set, do not follow symbolic links when performing commands + such as `cd' which change the current directory. The + physical directory is used instead. By default, Bash follows + the logical chain of directories when performing commands + which change the current directory. + + For example, if `/usr/sys' is a link to `/usr/local/sys' then: + $ cd /usr/sys; echo $PWD + /usr/sys + $ cd ..; pwd + /usr + + If `set -P' is on, then: + $ cd /usr/sys; echo $PWD + /usr/local/sys + $ cd ..; pwd + /usr/local + + `--' + If no arguments follow this flag, then the positional + parameters are unset. Otherwise, the positional parameters + are set to the ARGUMENTS, even if some of them begin with a + `-'. + + `-' + Signal the end of options, cause all remaining ARGUMENTS to + be assigned to the positional parameters. The `-x' and `-v' + options are turned off. If there are no arguments, the + positional parameters remain unchanged. + + 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 N ARGUMENTS are positional parameters and are + assigned, in order, to `$1', `$2', ... `$N'. If no arguments are + given, all shell variables are printed. + + +File: bashref.info, Node: Bash Conditional Expressions, Next: Bash Variables, Prev: The Set Builtin, Up: Bash Features + +Bash Conditional Expressions +============================ + + Conditional expressions are used by the `test' and `[' builtins. + + Expressions may be unary or binary. Unary expressions are often +used to examine the status of a file. There are string operators and +numeric comparison operators as well. Each operator and operand must +be a separate argument. If FILE is of the form `/dev/fd/N', then file +descriptor N is checked. Expressions are composed of the following +primaries: + +`-b FILE' + True if FILE exists and is a block special file. + +`-c FILE' + True if FILE exists and is a character special file. + +`-d FILE' + True if FILE exists and is a directory. + +`-e FILE' + True if FILE exists. + +`-f FILE' + True if FILE exists and is a regular file. + +`-g FILE' + True if FILE exists and is set-group-id. + +`-k FILE' + True if FILE has its "sticky" bit set. + +`-L FILE' + True if FILE exists and is a symbolic link. + +`-p FILE' + True if FILE exists and is a named pipe. + +`-r FILE' + True if FILE exists and is readable. + +`-s FILE' + True if FILE exists and has a size greater than zero. + +`-S FILE' + True if FILE exists and is a socket. + +`-t FD' + True if FD is opened on a terminal. + +`-u FILE' + True if FILE exists and its set-user-id bit is set. + +`-w FILE' + True if FILE exists and is writable. + +`-x FILE' + True if FILE exists and is executable. + +`-O FILE' + True if FILE exists and is owned by the effective user id. + +`-G FILE' + True if FILE exists and is owned by the effective group id. + +`FILE1 -nt FILE2' + True if FILE1 is newer (according to modification date) than FILE2. + +`FILE1 -ot FILE2' + True if FILE1 is older than FILE2. + +`FILE1 -ef FILE2' + True if FILE1 and FILE2 have the same device and inode numbers. + +`-o OPTNAME' + True if shell option OPTNAME is enabled. The list of options + appears in the description of the `-o' option to the `set' builtin + (*note The Set Builtin::.). + +`-z STRING' + True if the length of STRING is zero. + +`-n STRING' +`STRING' + True if the length of STRING is non-zero. + +`STRING1 = STRING2' + True if the strings are equal. `==' may be used in place of `='. + +`STRING1 != STRING2' + True if the strings are not equal. + +`STRING1 < STRING2' + True if STRING1 sorts before STRING2 lexicographically. + +`STRING1 > STRING2' + True if STRING1 sorts after STRING2 lexicographically. + +`! EXPR' + True if EXPR is false. + +`EXPR1 -a EXPR2' + True if both EXPR1 and EXPR2 are true. + +`EXPR1 -o EXPR2' + True if either EXPR1 and EXPR2 is true. + +`ARG1 OP ARG2' + `OP' is one of `-eq', `-ne', `-lt', `-le', `-gt', or `-ge'. These + arithmetic binary operators return true if ARG1 is equal to, not + equal to, less than, less than or equal to, greater than, or + greater than or equal to ARG2, respectively. ARG1 and ARG2 may be + positive or negative integers. + + The Bash `test' and `[' builtins evaluate conditional expressions +using a set of rules based on the number of arguments. These are the +rules: + +0 arguments + The expression is false. + +1 argument + The expression is true if and only if the argument is not null. + +2 arguments + If the first argument is `!', the expression is true if and only + if the second argument is null. If the first argument is one of + the listed unary operators, the expression is true if the unary + test is true. If the first argument is not a legal unary + operator, the expression is false. + +3 arguments + If the first argument is `!', the value is the negation of the + two-argument test using the second and third arguments. If the + second argument is one of the binary operators, the result of the + expression is the result of the binary test using the first and + third arguments as operands. If the first argument is exactly `(' + and the third argument is exactly `)', the result is the + one-argument test of the second argument. Otherwise, the + expression is false. The `-a' and `-o' operators are considered + binary operators in this case. + +4 arguments + If the first argument is `!', the result is the negation of the + three-argument expression composed of the remaining arguments. + Otherwise, the expression is parsed and evaluated according to + precedence. `-a' has a higher precedence than `-o'. + +5 or more arguments + The expression is parsed and evaluated according to precedence, + with `-a' having a higher precedence than `-o'. + + +File: bashref.info, Node: Bash Variables, Next: Shell Arithmetic, Prev: Bash Conditional Expressions, Up: Bash Features + +Bash Variables +============== + + These variables are set or used by Bash, but other shells do not +normally treat them specially. + +`TIMEFORMAT' + The value of this parameter is used as a format string specifying + how the timing information for pipelines prefixed with the `time' + reserved word should be displayed. The `%' character introduces an + escape sequence that is expanded to a time value or other + information. The escape sequences and their meanings are as + follows; the braces denote optional portions. + + `%%' + A literal `%'. + + `%[P][l]R' + The elapsed time in seconds. + + `%[P][l]U' + The number of CPU seconds spent in user mode. + + `%[P][l]S' + The number of CPU seconds spent in system mode. + + `%P' + The CPU percentage, computed as (%U + %S) / %R. + + The optional P is a digit specifying the precision, the number of + fractional digits after a decimal point. A value of 0 causes no + decimal point or fraction to be output. At most three places + after the decimal point may be specified; values of P greater than + 3 are changed to 3. If P is not specified, the value 3 is used. + + The optional `l' specifies a longer format, including minutes, of + the form MMmSS.FFs. The value of P determines whether or not the + fraction is included. + + If this variable is not set, bash acts as if it had the value + `$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS''. If the value is null, + no timing information is displayed. A trailing newline is added + when the format string is displayed. + +`HISTCONTROL' + Set to a value of `ignorespace', it means don't enter lines which + begin with a space or tab into the history list. Set to a value + of `ignoredups', it means don't enter lines which match the last + entered line. A value of `ignoreboth' combines the two options. + Unset, or set to any other value than those above, means to save + all lines on the history list. + +`HISTIGNORE' + A colon-separated list of patterns used to decide which command + lines should be saved on the history list. Each pattern is + anchored at the beginning of the line and must fully specify the + line (no implicit `*' is appended). Each pattern is tested + against the line after the checks specified by `HISTCONTROL' are + applied. In addition to the normal shell pattern matching + characters, `&' matches the previous history line. `&' may be + escaped using a backslash. The backslash is removed before + attempting a match. + + `HISTIGNORE' subsumes the function of `HISTCONTROL'. A pattern of + `&' is identical to `ignoredups', and a pattern of `[ ]*' is + identical to `ignorespace'. Combining these two patterns, + separating them with a colon, provides the functionality of + `ignoreboth'. + +`HISTFILE' + The name of the file to which the command history is saved. The + default is `~/.bash_history'. + +`HISTSIZE' + If set, this is the maximum number of commands to remember in the + history. + +`HISTFILESIZE' + The maximum number of lines contained in the history file. When + this variable is assigned a value, the history file is truncated, + if necessary, to contain no more than that number of lines. The + default value is 500. The history file is also truncated to this + size after writing it when an interactive shell exits. + +`histchars' + Up to three characters which control history expansion, quick + substitution, and tokenization (*note History Interaction::.). + 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 `#'. The + history comment character causes history substitution to be + skipped for the remaining words on the line. It does not + necessarily cause the shell parser to treat the rest of the line + as a comment. + +`HISTCMD' + The history number, or index in the history list, of the current + command. If `HISTCMD' is unset, it loses its special properties, + even if it is subsequently reset. + +`HOSTFILE' + 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 attempt 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 + files specified in `MAILPATH'. + +`PROMPT_COMMAND' + If present, this contains a string which is a command to execute + before the printing of each primary prompt (`$PS1'). + +`UID' + The numeric real user id of the current user. + +`EUID' + The numeric effective user id of the current user. + +`PPID' + The process id of the shell's parent process. + +`HOSTNAME' + The name of the current host. + +`HOSTTYPE' + A string describing the machine Bash is running on. + +`OSTYPE' + A string describing the operating system Bash is running on. + +`MACHTYPE' + A string that fully describes the system type on which Bash is + executing, in the standard GNU CPU-COMPANY-SYSTEM format. + +`SHELLOPTS' + A colon-separated list of enabled shell options. Each word in the + list is a valid argument for the `-o' option to the `set' builtin + command (*note The Set Builtin::.). The options appearing in + `SHELLOPTS' are those reported as `on' by `set -o'. If this + variable is in the environment when Bash starts up, each shell + option in the list will be enabled before reading any startup + files. This variable is readonly. + +`FIGNORE' + A colon-separated list of suffixes to ignore when performing + filename completion. A file name whose suffix matches one of the + entries in `FIGNORE' is excluded from the list of matched file + names. A sample value is `.o:~' + +`GLOBIGNORE' + A colon-separated list of patterns defining the set of filenames to + be ignored by filename expansion. If a filename matched by a + filename expansion pattern also matches one of the patterns in + `GLOBIGNORE', it is removed from the list of matches. + +`DIRSTACK' + An array variable (*note Arrays::.) containing the current + contents of the directory stack. Directories appear in the stack + in the order they are displayed by the `dirs' builtin. Assigning + to members of this array variable may be used to modify + directories already in the stack, but the `pushd' and `popd' + builtins must be used to add and remove directories. Assignment + to this variable will not change the current directory. If + `DIRSTACK' is unset, it loses its special properties, even if it + is subsequently reset. + +`PIPESTATUS' + An array variable (*note Arrays::.) containing a list of exit + status values from the processes in the most-recently-executed + foreground pipeline (which may contain only a single command). + +`INPUTRC' + The name of the Readline startup file, overriding the default of + `~/.inputrc'. + +`BASH' + The full filename used to execute the current instance of Bash. + +`BASH_VERSION' + The version number of the current instance of Bash. + +`BASH_VERSINFO' + An array variable whose members hold version information for this + instance of Bash. The values assigned to the array members are as + follows: + + `BASH_VERSINFO[0]' + The major version number (the RELEASE). + + `BASH_VERSINFO[1]' + The minor version number (the VERSION). + + `BASH_VERSINFO[2]' + The patch level. + + `BASH_VERSINFO[3]' + The build version. + + `BASH_VERSINFO[4]' + The release status (e.g., BETA1). + + `BASH_VERSINFO[5]' + The value of `MACHTYPE'. + +`SHLVL' + Incremented by one each time a new instance of Bash is started. + This is intended to be an account of how deeply your Bash shells + are nested. + +`OPTERR' + If set to the value 1, Bash displays error messages generated by + the `getopts' builtin command. + +`LANG' + Used to determine the locale category for any category not + specifically selected with a variable starting with `LC_'. + +`LC_ALL' + This variable overrides the value of `LANG' and any other `LC_' + variable specifying a locale category. + +`LC_MESSAGES' + This variable determines the locale used to translate double-quoted + strings preceded by a `$'. + +`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 + consecutive `EOF' characters that can be read as the first + character on an input line 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. + + +File: bashref.info, Node: Shell Arithmetic, Next: Arrays, Prev: Bash Variables, Up: Bash Features + +Shell Arithmetic +================ + +* Menu: + +* Arithmetic Evaluation:: How shell arithmetic works. +* Arithmetic Expansion:: How to use arithmetic in shell expansions. +* Arithmetic Builtins:: Builtin commands that use shell arithmetic. + + Bash includes several mechanisms to evaluate arithmetic expressions +and display the result or use it as part of a command. + + +File: bashref.info, Node: Arithmetic Evaluation, Next: Arithmetic Expansion, Up: Shell Arithmetic + +Arithmetic Evaluation +--------------------- + + The shell allows arithmetic expressions to be evaluated, as one of +the shell expansions or by the `let' builtin. + + Evaluation is done in long integers with no check for overflow, +though division by 0 is trapped and flagged as an error. The following +list of operators is grouped into levels of equal-precedence operators. +The levels are listed in order of decreasing precedence. + +`- +' + unary minus and plus + +`! ~' + logical and bitwise negation + +`* / %' + multiplication, division, remainder + +`+ -' + addition, subtraction + +`<< >>' + left and right bitwise shifts + +`<= >= < >' + comparison + +`== !=' + equality and inequality + +`&' + bitwise AND + +`^' + bitwise exclusive OR + +`|' + bitwise OR + +`&&' + logical AND + +`||' + logical OR + +`expr ? expr : expr' + conditional evaluation + +`= *= /= %= += -= <<= >>= &= ^= |=' + assignment + + Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. The value of a parameter +is coerced to a long integer within an expression. A shell variable +need not have its integer attribute turned on to be used in an +expression. + + Constants with a leading 0 are interpreted as octal numbers. A +leading `0x' or `0X' denotes hexadecimal. Otherwise, numbers take the +form [BASE`#']N, where BASE is a decimal number between 2 and 64 +representing the arithmetic base, and N is a number in that base. If +BASE is omitted, then base 10 is used. The digits greater than 9 are +represented by the lowercase letters, the uppercase letters, `_', and +`@', in that order. If BASE is less than or equal to 36, lowercase and +uppercase letters may be used interchangably to represent numbers +between 10 and 35. + + Operators are evaluated in order of precedence. Sub-expressions in +parentheses are evaluated first and may override the precedence rules +above. + + +File: bashref.info, Node: Arithmetic Expansion, Next: Arithmetic Builtins, Prev: Arithmetic Evaluation, Up: Shell Arithmetic + +Arithmetic Expansion +-------------------- + + Arithmetic expansion allows the evaluation of an arithmetic +expression and the substitution of the result. The format for +arithmetic expansion is: + + $(( EXPRESSION )) + + The expression is treated as if it were within double quotes, but a +double quote inside the braces or parentheses is not treated specially. +All tokens in the expression undergo parameter expansion, command +substitution, and quote removal. Arithmetic substitutions may be +nested. + + The evaluation is performed according to the rules listed above. If +the expression is invalid, Bash prints a message indicating failure and +no substitution occurs. + + +File: bashref.info, Node: Arithmetic Builtins, Prev: Arithmetic Expansion, Up: Shell Arithmetic + +Arithmetic Builtins +------------------- + +`let' + let EXPRESSION [EXPRESSION] + The `let' builtin allows arithmetic to be performed on shell + variables. Each EXPRESSION is evaluated according to the rules + given previously (*note Arithmetic Evaluation::.). If the last + EXPRESSION evaluates to 0, `let' returns 1; otherwise 0 is + returned. + + +File: bashref.info, Node: Arrays, Next: Printing a Prompt, Prev: Shell Arithmetic, Up: Bash Features + +Arrays +====== + + Bash provides one-dimensional array variables. Any variable may be +used as an array; the `declare' builtin will explicitly declare an +array. There is no maximum limit on the size of an array, nor any +requirement that members be indexed or assigned contiguously. Arrays +are zero-based. + + An array is created automatically if any variable is assigned to +using the syntax + name[SUBSCRIPT]=VALUE + +The SUBSCRIPT is treated as an arithmetic expression that must evaluate +to a number greater than or equal to zero. To explicitly declare an +array, use + declare -a NAME + +The syntax + declare -a NAME[SUBSCRIPT] + +is also accepted; the SUBSCRIPT is ignored. Attributes may be +specified for an array variable using the `declare' and `readonly' +builtins. Each attribute applies to all members of an array. + + Arrays are assigned to using compound assignments of the form + name=(value1 ... valueN) + +where each VALUE is of the form `[[SUBSCRIPT]=]'STRING. If the +optional subscript is supplied, that index is assigned to; otherwise +the index of the element assigned is the last index assigned to by the +statement plus one. Indexing starts at zero. This syntax is also +accepted by the `declare' builtin. Individual array elements may be +assigned to using the `name['SUBSCRIPT`]='VALUE syntax introduced above. + + Any element of an array may be referenced using +`${name['SUBSCRIPT`]}'. The braces are required to avoid conflicts +with the shell's filename expansion operators. If the SUBSCRIPT is `@' +or `*', the word expands to all members of the array NAME. These +subscripts differ only when the word appears within double quotes. If +the word is double-quoted, `${name[*]}' expands to a single word with +the value of each array member separated by the first character of the +`IFS' variable, and `${name[@]}' expands each element of NAME to a +separate word. When there are no array members, `${name[@]}' expands +to nothing. This is analogous to the expansion of the special +parameters `@' and `*'. `${#name['SUBSCRIPT`]}' expands to the length +of `${name['SUBSCRIPT`]}'. If SUBSCRIPT is `@' or `*', the expansion +is the number of elements in the array. Referencing an array variable +without a subscript is equivalent to referencing element zero. + + The `unset' builtin is used to destroy arrays. `unset' +NAME[SUBSCRIPT] destroys the array element at index SUBSCRIPT. `unset' +NAME, where NAME is an array, removes the entire array. A subscript of +`*' or `@' also removes the entire array. + + The `declare', `local', and `readonly' builtins each accept a `-a' +option to specify an array. The `read' builtin accepts a `-a' option +to assign a list of words read from the standard input to an array, and +can read values from the standard input into individual array elements. +The `set' and `declare' builtins display array values in a way that +allows them to be reused as input. + + +File: bashref.info, Node: Printing a Prompt, Next: The Restricted Shell, Prev: Arrays, Up: Bash Features + +Controlling the Prompt +====================== + + The value of the variable `PROMPT_COMMAND' is examined just before +Bash prints each primary 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 prompt variables: + +`\a' + a bell character. + +`\d' + the date, in "Weekday Month Date" format (e.g., "Tue May 26"). + +`\e' + an escape character. + +`\h' + the hostname, up to the first `.'. + +`\H' + the hostname. + +`\n' + newline. + +`\s' + the name of the shell, the basename of `$0' (the portion following + the final slash). + +`\t' + the time, in 24-hour HH:MM:SS format. + +`\T' + the time, in 12-hour HH:MM:SS format. + +`\@' + the time, in 12-hour am/pm format. + +`\v' + the version of Bash (e.g., 2.00) + +`\V' + the release of Bash, version + patchlevel (e.g., 2.00.0) + +`\w' + the current working directory. + +`\W' + the basename of `$PWD'. + +`\u' + your username. + +`\!' + the history number of this command. + +`\#' + the command number of this command. + +`\$' + if the effective uid is 0, `#', otherwise `$'. + +`\nnn' + the character corresponding to the octal number `nnn'. + +`\\' + a backslash. + +`\[' + begin a sequence of non-printing characters. This could be used to + embed a terminal control sequence into the prompt. + +`\]' + end a sequence of non-printing characters. + + +File: bashref.info, Node: The Restricted Shell, Next: Bash POSIX Mode, Prev: Printing a Prompt, Up: Bash Features + +The Restricted Shell +==================== + + If Bash is started with the name `rbash', or the `--restricted' +option is supplied at invocation, the shell becomes restricted. A +restricted shell is used to set up an environment more controlled than +the standard shell. A restricted shell behaves identically to `bash' +with the exception that the following are disallowed: + * Changing directories with the `cd' builtin. + + * Setting or unsetting the values of the `SHELL' or `PATH' variables. + + * Specifying command names containing slashes. + + * Specifying a filename containing a slash as an argument to the `.' + builtin command. + + * Importing function definitions from the shell environment at + startup. + + * Redirecting output using the `>', `>|', `<>', `>&', `&>', and `>>' + redirection operators. + + * Using the `exec' builtin to replace the shell with another command. + + * Adding or deleting builtin commands with the `-f' and `-d' options + to the `enable' builtin. + + * Specifying the `-p' option to the `command' builtin. + + * Turning off restricted mode with `set +r'. + + +File: bashref.info, Node: Bash POSIX Mode, Prev: The Restricted Shell, Up: Bash Features + +Bash POSIX Mode +=============== + + Starting Bash with the `--posix' command-line option or executing +`set -o posix' while Bash is running will cause Bash to conform more +closely to the POSIX.2 standard by changing the behavior to match that +specified by POSIX.2 in areas where the Bash default differs. + + The following list is what's changed when `POSIX mode' is in effect: + + 1. When a command in the hash table no longer exists, Bash will + re-search `$PATH' to find the new location. This is also + available with `shopt -s checkhash'. + + 2. The `>&' redirection does not redirect stdout and stderr. + + 3. The message printed by the job control code and builtins when a job + exits with a non-zero status is `Done(status)'. + + 4. Reserved words may not be aliased. + + 5. The POSIX.2 `PS1' and `PS2' expansions of `!' to the history + number and `!!' to `!' are enabled, and parameter expansion is + performed on the value regardless of the setting of the + `promptvars' option. + + 6. Interactive comments are enabled by default. (Note that Bash has + them on by default anyway.) + + 7. The POSIX.2 startup files are executed (`$ENV') rather than the + normal Bash files. + + 8. Tilde expansion is only performed on assignments preceding a + command name, rather than on all assignment statements on the line. + + 9. The default history file is `~/.sh_history' (this is the default + value of `$HISTFILE'). + + 10. The output of `kill -l' prints all the signal names on a single + line, separated by spaces. + + 11. Non-interactive shells exit if FILENAME in `.' FILENAME is not + found. + + 12. Redirection operators do not perform filename expansion on the word + in the redirection unless the shell is interactive. + + 13. Function names must be valid shell `name's. That is, they may not + contain characters other than letters, digits, and underscores, and + may not start with a digit. Declaring a function with an illegal + name causes a fatal syntax error in non-interactive shells. + + 14. POSIX.2 `special' builtins are found before shell functions during + command lookup. + + 15. If a POSIX.2 special builtin returns an error status, a + non-interactive shell exits. The fatal errors are those listed in + the POSIX.2 standard, and include things like passing incorrect + options, redirection errors, variable assignment errors for + assignments preceding the command name, and so on. + + 16. If the `cd' builtin finds a directory to change to using + `$CDPATH', the value it assigns to the `PWD' variable does not + contain any symbolic links, as if `cd -P' had been executed. + + 17. A non-interactive shell exits with an error status if a variable + assignment error occurs when no command name follows the assignment + statements. A variable assignment error occurs, for example, when + trying to assign a value to a read-only variable. + + 18. A non-interactive shell exits with an error status if the iteration + variable in a `for' statement or the selection variable in a + `select' statement is a read-only variable. + + 19. Process substitution is not available. + + 20. Assignment statements preceding POSIX.2 `special' builtins persist + in the shell environment after the builtin completes. + + + There is other POSIX.2 behavior that Bash does not implement. +Specifically: + + 1. Assignment statements affect the execution environment of all + builtins, not just special ones. + + +File: bashref.info, Node: Job Control, Next: Using History Interactively, Prev: Bash Features, Up: Top + +Job Control +*********** + + This chapter disusses what job control is, how it works, and how +Bash allows you to access its facilities. + +* Menu: + +* Job Control Basics:: How job control works. +* Job Control Builtins:: Bash builtin commands used to interact + with job control. +* Job Control Variables:: Variables Bash uses to customize job + control. + + +File: bashref.info, Node: Job Control Basics, Next: Job Control Builtins, Up: Job Control + +Job Control Basics +================== + + Job control refers to the ability to selectively stop (suspend) the +execution of processes and continue (resume) their execution at a later +point. A user typically employs this facility via an interactive +interface supplied jointly by the system's terminal driver and Bash. + + The shell associates a JOB with each pipeline. It keeps a table of +currently executing jobs, which may be listed with the `jobs' command. +When Bash starts a job asynchronously (in the background), it prints a +line that looks like: + [1] 25647 + +indicating that this job is job number 1 and that the process ID of the +last process in the pipeline associated with this job is 25647. All of +the processes in a single pipeline are members of the same job. Bash +uses the JOB abstraction as the basis for job control. + + To facilitate the implementation of the user interface to job +control, the system maintains the notion of a current terminal process +group ID. Members of this process group (processes whose process group +ID is equal to the current terminal process group ID) receive +keyboard-generated signals such as `SIGINT'. These processes are said +to be in the foreground. Background processes are those whose process +group ID differs from the terminal's; such processes are immune to +keyboard-generated signals. Only foreground processes are allowed to +read from or write to the terminal. Background processes which attempt +to read from (write to) the terminal are sent a `SIGTTIN' (`SIGTTOU') +signal by the terminal driver, which, unless caught, suspends the +process. + + If the operating system on which Bash is running supports job +control, Bash allows you to use it. Typing the SUSPEND character +(typically `^Z', Control-Z) while a process is running causes that +process to be stopped and returns you to Bash. Typing the DELAYED +SUSPEND character (typically `^Y', Control-Y) causes the process to be +stopped when it attempts to read input from the terminal, and control to +be returned to Bash. You may then manipulate the state of this job, +using the `bg' command to continue it in the background, the `fg' +command to continue it in the foreground, or the `kill' command to kill +it. A `^Z' takes effect immediately, and has the additional side +effect of causing pending output and typeahead to be discarded. + + There are a number of ways to refer to a job in the shell. The +character `%' introduces a job name. Job number `n' may be referred to +as `%n'. A job may also be referred to using a prefix of the name used +to start it, or using a substring that appears in its command line. +For example, `%ce' refers to a stopped `ce' job. Using `%?ce', on the +other hand, refers to any job containing the string `ce' in its command +line. If the prefix or substring matches more than one job, Bash +reports an error. The symbols `%%' and `%+' refer to the shell's +notion of the current job, which is the last job stopped while it was +in the foreground. The previous job may be referenced using `%-'. In +output pertaining to jobs (e.g., the output of the `jobs' command), the +current job is always flagged with a `+', and the previous job with a +`-'. + + Simply naming a job can be used to bring it into the foreground: +`%1' is a synonym for `fg %1', bringing job 1 from the background into +the foreground. Similarly, `%1 &' resumes job 1 in the background, +equivalent to `bg %1' + + The shell learns immediately whenever a job changes state. +Normally, Bash waits until it is about to print a prompt before +reporting changes in a job's status so as to not interrupt any other +output. If the the `-b' option to the `set' builtin is set, Bash +reports such changes immediately (*note The Set Builtin::.). + + If you attempt to exit Bash while jobs are stopped, the shell prints +a message warning you that you have stopped jobs. You may then use the +`jobs' command to inspect their status. If you do this, or try to exit +again immediately, you are not warned again, and the stopped jobs are +terminated. + + +File: bashref.info, Node: Job Control Builtins, Next: Job Control Variables, Prev: Job Control Basics, Up: Job Control + +Job Control Builtins +==================== + +`bg' + bg [JOBSPEC] + Place JOBSPEC into the background, as if it had been started with + `&'. If JOBSPEC is not supplied, the current job is used. + +`fg' + fg [JOBSPEC] + Bring JOBSPEC into the foreground and make it the current job. If + JOBSPEC is not supplied, the current job is used. + +`jobs' + jobs [-lpnrs] [JOBSPEC] + jobs -x COMMAND [JOBSPEC] + + The first form lists the active jobs. The options have the + following meanings: + + `-l' + List process IDs in addition to the normal information + + `-n' + Display information only about jobs that have changed status + since you were last notified of their status. + + `-p' + List only the process ID of the job's process group leader. + + `-r' + Restrict output to running jobs. + + `-s' + Restrict output to stopped jobs. + + If JOBSPEC is given, output is restricted to information about + that job. If JOBSPEC is not supplied, the status of all jobs is + listed. + + If the `-x' option is supplied, `jobs' replaces any JOBSPEC found + in COMMAND or ARGUMENTS with the corresponding process group ID, + and executes COMMAND, passing it ARGUMENTs, returning its exit + status. + +`kill' + kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] JOBSPEC + kill -l [SIGSPEC] + Send a signal specified by SIGSPEC or SIGNUM to the process named + by JOBSPEC. SIGSPEC is either a signal name such as `SIGINT' or a + signal number; SIGNUM is a signal number. If SIGSPEC and SIGNUM + are not present, `SIGTERM' is used. The `-l' option lists the + signal names, or the signal name corresponding to SIGSPEC. + +`wait' + wait [JOBSPEC|PID] + Wait until the child process specified by process ID PID or job + specification JOBSPEC exits and report its exit status. If a job + spec is given, all processes in the job are waited for. If no + arguments are given, all currently active child processes are + waited for. + +`disown' + disown [-h] [JOBSPEC ...] + Without options, each JOBSPEC is removed from the table of active + jobs. If the `-h' option is given, the job is not removed from + the table, but is marked so that `SIGHUP' is not sent to the job + if the shell receives a `SIGHUP'. If JOBSPEC is not present, the + current job is used. + +`suspend' + suspend [-f] + Suspend the execution of this shell until it receives a `SIGCONT' + signal. The `-f' option means to suspend even if the shell is a + login shell. + + When job control is not active, the `kill' and `wait' builtins do +not accept JOBSPEC arguments. They must be supplied process IDs. + + +File: bashref.info, Node: Job Control Variables, Prev: Job Control Builtins, Up: Job Control + +Job Control Variables +===================== + +`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. The name of + a stopped job, in this context, is the command line used to start + it. If this variable is set to the value `exact', the string + supplied must match the name of a stopped job exactly; if set to + `substring', the string supplied needs to match a substring of the + name of a stopped job. The `substring' value provides + functionality analogous to the `%?' job ID (*note Job Control + Basics::.). If set to any other value, the supplied string must + be a prefix of a stopped job's name; this provides functionality + analogous to the `%' job ID. + + +File: bashref.info, Node: Using History Interactively, Next: Command Line Editing, Prev: Job Control, Up: Top + +Using History Interactively +*************************** + + This chapter describes how to use the GNU History Library +interactively, from a user's standpoint. It should be considered a +user's guide. For information on using the GNU History Library in your +own programs, see the GNU Readline Library Manual. + +* Menu: + +* Bash History Facilities:: How Bash lets you manipulate your command + history. +* History Interaction:: What it feels like using History as a user. + + +File: bashref.info, Node: Bash History Facilities, Next: History Interaction, Up: Using History Interactively + +Bash History Facilities +======================= + + When the `-o history' option to the `set' builtin is enabled (*note +The Set Builtin::.), the shell provides access to the COMMAND HISTORY, +the list of commands previously typed. The text of the last `HISTSIZE' +commands (default 500) is saved in a history list. The shell stores +each command in the history list prior to parameter and variable +expansion but after history expansion is performed, subject to the +values of the shell variables `HISTIGNORE' and `HISTCONTROL'. When the +shell starts up, the history is initialized from the file named by the +`HISTFILE' variable (default `~/.bash_history'). `HISTFILE' is +truncated, if necessary, to contain no more than the number of lines +specified by the value of the `HISTFILESIZE' variable. When an +interactive shell exits, the last `HISTSIZE' lines are copied from the +history list to `HISTFILE'. If the `histappend' shell option is set +(*note Bash Builtins::.), the lines are appended to the history file, +otherwise the history file is overwritten. If `HISTFILE' is unset, or +if the history file is unwritable, the history is not saved. After +saving the history, the history file is truncated to contain no more +than `$HISTFILESIZE' lines. If `HISTFILESIZE' is not set, no +truncation is performed. + + The builtin command `fc' (*note Korn Shell Builtins::.) may be used +to list or edit and re-execute a portion of the history list. The +`history' builtin (*note C Shell Builtins::.) can be used to display or +modify the history list and manipulate the history file. When using +the command-line editing, search commands are available in each editing +mode that provide access to the history list. + + The shell allows control over which commands are saved on the history +list. The `HISTCONTROL' and `HISTIGNORE' variables may be set to cause +the shell to save only a subset of the commands entered. The `cmdhist' +shell option, if enabled, causes the shell to attempt to save each line +of a multi-line command in the same history entry, adding semicolons +where necessary to preserve syntactic correctness. The `lithist' shell +option causes the shell to save the command with embedded newlines +instead of semicolons. *Note Bash Builtins:: for a description of +`shopt'. + + +File: bashref.info, Node: History Interaction, Prev: Bash History Facilities, Up: Using History Interactively + +Interactive History Expansion +============================= + + The History library provides a history expansion feature that is +similar to the history expansion provided by `csh'. This section +describes the syntax used to manipulate the history information. + + History expansions introduce words from the history list into the +input stream, making it easy to repeat commands, insert the arguments +to a previous command into the current input line, or fix errors in +previous commands quickly. + + History expansion takes place in two parts. The first is to +determine which line from the previous history should be used 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". Various "modifiers" are available to +manipulate the selected words. The line is broken into words in the +same fashion that Bash does, so that several English (or Unix) words +surrounded by quotes are considered as one word. History expansions +are introduced by the appearance of the history expansion character, +which is `!' by default. Only `\' and `'' may be used to escape the +history expansion character. + + Several shell options settable with the `shopt' builtin (*note Bash +Builtins::.) may be used to tailor the behavior of history expansion. +If the `histverify' shell option is enabled, and Readline is being +used, history substitutions are not immediately passed to the shell +parser. Instead, the expanded line is reloaded into the Readline +editing buffer for further modification. If Readline is being used, +and the `histreedit' shell option is enabled, a failed history +expansion will be reloaded into the Readline editing buffer for +correction. The `-p' option to the `history' builtin command may be +used to see what a history expansion will do before using it. The `-s' +option to the `history' builtin may be used to add commands to the end +of the history list without actually executing them, so that they are +available for subsequent recall. + + The shell allows control of the various characters used by the +history expansion mechanism with the `histchars' variable. + +* Menu: + +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. + + +File: bashref.info, Node: Event Designators, Next: Word Designators, Up: History Interaction + +Event Designators +----------------- + + An event designator is a reference to a command line entry in the +history list. + +`!' + Start a history substitution, except when followed by a space, tab, + the end of the line, = or (. + +`!N' + Refer to command line N. + +`!-N' + Refer to the command N lines back. + +`!!' + Refer to the previous command. This is a synonym for `!-1'. + +`!STRING' + Refer to the most recent command starting with STRING. + +`!?STRING[?]' + Refer to the most recent command containing STRING. The trailing + `?' may be omitted if the STRING is followed immediately by a + newline. + +`^STRING1^STRING2^' + Quick Substitution. Repeat the last command, replacing STRING1 + with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. + +`!#' + The entire command line typed so far. + + +File: bashref.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction + +Word Designators +---------------- + + Word designators are used to select desired words from the event. 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 0 (zero). Words are inserted into the current +line separated by single spaces. + +`0 (zero)' + The `0'th word. For many applications, this is the command word. + +`N' + The Nth 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, except the `0'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. + +`X*' + Abbreviates `X-$' + +`X-' + Abbreviates `X-$' like `X*', but omits the last word. + + If a word designator is supplied without an event specification, the +previous command is used as the event. + + +File: bashref.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction + +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. + +`t' + Remove all leading pathname components, leaving the tail. + +`r' + Remove a trailing suffix of the form `.SUFFIX', leaving the + basename. + +`e' + Remove all but the trailing suffix. + +`p' + Print the new command but do not execute it. + +`q' + Quote the substituted words, escaping further substitutions. + +`x' + Quote the substituted words as with `q', but break into words at + spaces, tabs, and newlines. + +`s/OLD/NEW/' + Substitute NEW for the first occurrence of OLD in the event line. + Any delimiter may be used in place of `/'. The delimiter may be + quoted in OLD and NEW with a single backslash. If `&' appears in + NEW, it is replaced by OLD. A single backslash will quote the + `&'. The final delimiter is optional if it is the last character + on the input line. + +`&' + Repeat the previous substitution. + +`g' + Cause changes to be applied over the entire event line. Used in + conjunction with `s', as in `gs/OLD/NEW/', or with `&'. + + +File: bashref.info, Node: Command Line Editing, Next: Installing Bash, Prev: Using History Interactively, Up: Top + +Command Line Editing +******************** + + This chapter describes the basic features of the GNU command line +editing interface. + +* Menu: + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. + + +File: bashref.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing + +Introduction to Line Editing +============================ + + The following paragraphs describe the notation used to represent +keystrokes. + + The text C-k is read as `Control-K' and describes the character +produced when the k key is pressed while the Control key is depressed. + + The text M-k is read as `Meta-K' and describes the character +produced when the meta key (if you have one) is depressed, and the k +key is pressed. If you do not have a meta key, the identical keystroke +can be generated by typing ESC first, and then typing k. Either +process is known as "metafying" the k key. + + The text M-C-k is read as `Meta-Control-k' and describes the +character produced by "metafying" C-k. + + In addition, several keys have their own names. Specifically, DEL, +ESC, LFD, SPC, RET, and TAB all stand for themselves when seen in this +text, or in an init file (*note Readline Init File::.). + + +File: bashref.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing + +Readline Interaction +==================== + + Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press RETURN. You do not have to be at the end of +the line to press RETURN; the entire line is accepted regardless of the +location of the cursor within the line. + +* Menu: + +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. + + +File: bashref.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction + +Readline Bare Essentials +------------------------ + + In order to enter characters into the line, simply type them. The +typed character appears where the cursor was, and then the cursor moves +one space to the right. If you mistype a character, you can use your +erase character to back up and delete the mistyped character. + + Sometimes you may miss typing a character that you wanted to type, +and not notice your error until you have typed several other +characters. In that case, you can type C-b to move the cursor to the +left, and then correct your mistake. Afterwards, you can move the +cursor to the right with C-f. + + When you add text in the middle of a line, you will notice that +characters to the right of the cursor are `pushed over' to make room +for the text that you have inserted. Likewise, when you delete text +behind the cursor, characters to the right of the cursor are `pulled +back' to fill in the blank space created by the removal of the text. A +list of the basic bare essentials for editing the text of an input line +follows. + +C-b + Move back one character. + +C-f + Move forward one character. + +DEL + Delete the character to the left of the cursor. + +C-d + Delete the character underneath the cursor. + +Printing characters + Insert the character into the line at the cursor. + +C-_ + Undo the last thing that you did. You can undo all the way back + to an empty line. + + +File: bashref.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction + +Readline Movement Commands +-------------------------- + + The above table describes the most basic possible keystrokes that +you need in order to do editing of the input line. For your +convenience, many other commands have been added in addition to C-b, +C-f, C-d, and DEL. Here are some commands for moving more rapidly +about the line. + +C-a + Move to the start of the line. + +C-e + Move to the end of the line. + +M-f + Move forward a word. + +M-b + Move backward a word. + +C-l + Clear the screen, reprinting the current line at the top. + + Notice how C-f moves forward a character, while M-f moves forward a +word. It is a loose convention that control keystrokes operate on +characters while meta keystrokes operate on words. + + +File: bashref.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction + +Readline Killing Commands +------------------------- + + "Killing" text means to delete the text from the line, but to save +it away for later use, usually by "yanking" (re-inserting) it back into +the line. If the description for a command says that it `kills' text, +then you can be sure that you can get the text back in a different (or +the same) place later. + + When you use a kill command, the text is saved in a "kill-ring". +Any number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill ring is not line +specific; the text that you killed on a previously typed line is +available to be yanked back later, when you are typing another line. + + Here is the list of commands for killing text. + +C-k + Kill the text from the current cursor position to the end of the + line. + +M-d + Kill from the cursor to the end of the current word, or if between + words, to the end of the next word. + +M-DEL + Kill from the cursor the start of the previous word, or if between + words, to the start of the previous word. + +C-w + Kill from the cursor to the previous whitespace. This is + different than M-DEL because the word boundaries differ. + + And, here is how to "yank" the text back into the line. Yanking +means to copy the most-recently-killed text from the kill buffer. + +C-y + Yank the most recently killed text back into the buffer at the + cursor. + +M-y + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is C-y or M-y. + + +File: bashref.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction + +Readline Arguments +------------------ + + You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the sign of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type `M-- C-k'. + + The general way to pass numeric arguments to a command is to type +meta digits before the command. If the first `digit' you type is a +minus sign (-), then the sign of the argument will be negative. Once +you have typed one meta digit to get the argument started, you can type +the remainder of the digits, and then the command. For example, to give +the C-d command an argument of 10, you could type `M-1 0 C-d'. + + +File: bashref.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction + +Searching for Commands in the History +------------------------------------- + + Readline provides commands for searching through the command history +(*note Bash History Facilities::.) for lines containing a specified +string. There are two search modes: INCREMENTAL and NON-INCREMENTAL. + + Incremental searches begin before the user has finished typing the +search string. As each character of the search string is typed, +readline displays the next entry from the history matching the string +typed so far. An incremental search requires only as many characters +as needed to find the desired history entry. The Escape character is +used to terminate an incremental search. Control-J will also terminate +the search. Control-G will abort an incremental search and restore the +original line. When the search is terminated, the history entry +containing the search string becomes the current line. To find other +matching entries in the history list, type Control-S or Control-R as +appropriate. This will search backward or forward in the history for +the next entry matching the search string typed so far. Any other key +sequence bound to a readline command will terminate the search and +execute that command. For instance, a `newline' will terminate the +search and accept the line, thereby executing the command from the +history list. + + Non-incremental searches read the entire search string before +starting to search for matching history lines. The search string may be +typed by the user or part of the contents of the current line. + + +File: bashref.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing + +Readline Init File +================== + + Although the Readline library comes with a set of `emacs'-like +keybindings installed by default, it is possible that you would like to +use a different set of keybindings. You can customize programs that +use Readline by putting commands in an "inputrc" file in your home +directory. The name of this file is taken from the value of the shell +variable `INPUTRC'. If that variable is unset, the default is +`~/.inputrc'. + + When a program which uses the Readline library starts up, the init +file is read, and the key bindings are set. + + In addition, the `C-x C-r' command re-reads this init file, thus +incorporating any changes that you might have made to it. + +* Menu: + +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. + + +File: bashref.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File + +Readline Init File Syntax +------------------------- + + There are only a few basic constructs allowed in the Readline init +file. Blank lines are ignored. Lines beginning with a `#' are +comments. Lines beginning with a `$' indicate conditional constructs +(*note Conditional Init Constructs::.). Other lines denote variable +settings and key bindings. + +Variable Settings + You can change the state of a few variables in Readline by using + the `set' command within the init file. Here is how you would + specify that you wish to use `vi' line editing commands: + + set editing-mode vi + + Right now, there are only a few variables which can be set; so + few, in fact, that we just list them here: + + `bell-style' + Controls what happens when Readline wants to ring the + terminal bell. If set to `none', Readline never rings the + bell. If set to `visible', Readline uses a visible bell if + one is available. If set to `audible' (the default), + Readline attempts to ring the terminal's bell. + + `comment-begin' + The string to insert at the beginning of the line when the + `insert-comment' command is executed. The default value is + `"#"'. + + `completion-query-items' + The number of possible completions that determines when the + user is asked whether he wants to see the list of + possibilities. If the number of possible completions is + greater than this value, Readline will ask the user whether + or not he wishes to view them; otherwise, they are simply + listed. The default limit is `100'. + + `convert-meta' + If set to `on', Readline will convert characters with the + eigth bit set to an ASCII key sequence by stripping the eigth + bit and prepending an ESC character, converting them to a + meta-prefixed key sequence. The default value is `on'. + + `disable-completion' + If set to `On', readline will inhibit word completion. + Completion characters will be inserted into the line as if + they had been mapped to `self-insert'. The default is `off'. + + `editing-mode' + The `editing-mode' variable controls which editing mode you + are using. By default, Readline starts up in Emacs editing + mode, where the keystrokes are most similar to Emacs. This + variable can be set to either `emacs' or `vi'. + + `enable-keypad' + When set to `on', readline will try to enable the application + keypad when it is called. Some systems need this to enable + the arrow keys. The default is `off'. + + `expand-tilde' + If set to `on', tilde expansion is performed when Readline + attempts word completion. The default is `off'. + + `horizontal-scroll-mode' + This variable can be set to either `on' or `off'. Setting it + to `on' means that the text of the lines that you edit will + scroll horizontally on a single screen line when they are + longer than the width of the screen, instead of wrapping onto + a new screen line. By default, this variable is set to `off'. + + `keymap' + Sets Readline's idea of the current keymap for key binding + commands. Acceptable `keymap' names are `emacs', + `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', + `vi-command', and `vi-insert'. `vi' is equivalent to + `vi-command'; `emacs' is equivalent to `emacs-standard'. The + default value is `emacs'. The value of the `editing-mode' + variable also affects the default keymap. + + `mark-directories' + If set to `on', completed directory names have a slash + appended. The default is `on'. + + `mark-modified-lines' + This variable, when set to `on', says to display an asterisk + (`*') at the start of history lines which have been modified. + This variable is `off' by default. + + `input-meta' + If set to `on', Readline will enable eight-bit input (it will + not strip the eighth bit from the characters it reads), + regardless of what the terminal claims it can support. The + default value is `off'. The name `meta-flag' is a synonym + for this variable. + + `output-meta' + If set to `on', Readline will display characters with the + eighth bit set directly rather than as a meta-prefixed escape + sequence. The default is `off'. + + `show-all-if-ambiguous' + This alters the default behavior of the completion functions. + If set to `on', words which have more than one possible + completion cause the matches to be listed immediately instead + of ringing the bell. The default value is `off'. + + `visible-stats' + If set to `on', a character denoting a file's type is + appended to the filename when listing possible completions. + The default is `off'. + +Key Bindings + The syntax for controlling key bindings in the init file is + simple. First you have to know the name of the command that you + want to change. The following pages contain tables of the command + name, the default keybinding, and a short description of what the + command does. + + Once you know the name of the command, simply place the name of + the key you wish to bind the command to, a colon, and then the + name of the command on a line in the init file. The name of the + key can be expressed in different ways, depending on which is most + comfortable for you. + + KEYNAME: FUNCTION-NAME or MACRO + KEYNAME is the name of a key spelled out in English. For + example: + Control-u: universal-argument + Meta-Rubout: backward-kill-word + Control-o: "> output" + + In the above example, `C-u' is bound to the function + `universal-argument', and `C-o' is bound to run the macro + expressed on the right hand side (that is, to insert the text + `> output' into the line). + + "KEYSEQ": FUNCTION-NAME or MACRO + KEYSEQ differs from KEYNAME above in that strings denoting an + entire key sequence can be specified, by placing the key + sequence in double quotes. Some GNU Emacs style key escapes + can be used, as in the following example, but the special + character names are not recognized. + + "\C-u": universal-argument + "\C-x\C-r": re-read-init-file + "\e[11~": "Function Key 1" + + In the above example, `C-u' is bound to the function + `universal-argument' (just as it was in the first example), + `C-x C-r' is bound to the function `re-read-init-file', and + `ESC [ 1 1 ~' is bound to insert the text `Function Key 1'. + The following escape sequences are available when specifying + key sequences: + + ``\C-'' + control prefix + + ``\M-'' + meta prefix + + ``\e'' + an escape character + + ``\\'' + backslash + + ``\"'' + " + + ``\''' + ' + + When entering the text of a macro, single or double quotes + should be used to indicate a macro definition. Unquoted text + is assumed to be a function name. Backslash will quote any + character in the macro text, including `"' and `''. For + example, the following binding will make `C-x \' insert a + single `\' into the line: + "\C-x\\": "\\" + + +File: bashref.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File + +Conditional Init Constructs +--------------------------- + + Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key bindings +and variable settings to be performed as the result of tests. There +are three parser directives used. + +`$if' + The `$if' construct allows bindings to be made based on the + editing mode, the terminal being used, or the application using + Readline. The text of the test extends to the end of the line; no + characters are required to isolate it. + + `mode' + The `mode=' form of the `$if' directive is used to test + whether Readline is in `emacs' or `vi' mode. This may be + used in conjunction with the `set keymap' command, for + instance, to set bindings in the `emacs-standard' and + `emacs-ctlx' keymaps only if Readline is starting out in + `emacs' mode. + + `term' + The `term=' form may be used to include terminal-specific key + bindings, perhaps to bind the key sequences output by the + terminal's function keys. The word on the right side of the + `=' is tested against the full name of the terminal and the + portion of the terminal name before the first `-'. This + allows `sun' to match both `sun' and `sun-cmd', for instance. + + `application' + The APPLICATION construct is used to include + application-specific settings. Each program using the + Readline library sets the APPLICATION NAME, and you can test + for it. This could be used to bind key sequences to + functions useful for a specific program. For instance, the + following command adds a key sequence that quotes the current + or previous word in Bash: + $if Bash + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + $endif + +`$endif' + This command, as you saw in the previous example, terminates an + `$if' command. + +`$else' + Commands in this branch of the `$if' directive are executed if the + test fails. + + +File: bashref.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File + +Sample Init File +---------------- + + Here is an example of an inputrc file. This illustrates key +binding, variable assignment, and conditional syntax. + + + # This file controls the behaviour of line input editing for + # programs that use the Gnu Readline library. Existing programs + # include FTP, Bash, and Gdb. + # + # You can re-read the inputrc file with C-x C-r. + # Lines beginning with '#' are comments. + # + # Set various bindings for emacs mode. + + set editing-mode emacs + + $if mode=emacs + + Meta-Control-h: backward-kill-word Text after the function name is ignored + + # + # Arrow keys in keypad mode + # + #"\M-OD" backward-char + #"\M-OC" forward-char + #"\M-OA" previous-history + #"\M-OB" next-history + # + # Arrow keys in ANSI mode + # + "\M-[D" backward-char + "\M-[C" forward-char + "\M-[A" previous-history + "\M-[B" next-history + # + # Arrow keys in 8 bit keypad mode + # + #"\M-\C-OD" backward-char + #"\M-\C-OC" forward-char + #"\M-\C-OA" previous-history + #"\M-\C-OB" next-history + # + # Arrow keys in 8 bit ANSI mode + # + #"\M-\C-[D" backward-char + #"\M-\C-[C" forward-char + #"\M-\C-[A" previous-history + #"\M-\C-[B" next-history + + C-q: quoted-insert + + $endif + + # An old-style binding. This happens to be the default. + TAB: complete + + # Macros that are convenient for shell interaction + $if Bash + # edit the path + "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" + # prepare to type a quoted word -- insert open and close double quotes + # and move to just after the open quote + "\C-x\"": "\"\"\C-b" + # insert a backslash (testing backslash escapes in sequences and macros) + "\C-x\\": "\\" + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + # Add a binding to refresh the line, which is unbound + "\C-xr": redraw-current-line + # Edit variable on current line. + "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" + $endif + + # use a visible bell if one is available + set bell-style visible + + # don't strip characters to 7 bits when reading + set input-meta on + + # allow iso-latin1 characters to be inserted rather than converted to + # prefix-meta sequences + set convert-meta off + + # display characters with the eighth bit set directly rather than + # as meta-prefixed characters + set output-meta on + + # if there are more than 150 possible completions for a word, ask the + # user if he wants to see all of them + set completion-query-items 150 + + # For FTP + $if Ftp + "\C-xg": "get \M-?" + "\C-xt": "put \M-?" + "\M-.": yank-last-arg + $endif + + +File: bashref.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing + +Bindable Readline Commands +========================== + +* Menu: + +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. + + This section describes Readline commands that may be bound to key +sequences. + + +File: bashref.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands + +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. Words are composed of + letters and digits. + +`backward-word (M-b)' + Move back to the start of this, or the previous, word. Words are + composed of letters and digits. + +`clear-screen (C-l)' + Clear the screen and redraw the current line, leaving the current + line at the top of the screen. + +`redraw-current-line ()' + Refresh the current line. By default, this is unbound. + + +File: bashref.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands + +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 to the history list according to the setting of + the `HISTCONTROL' variable. 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. + +`forward-search-history (C-s)' + Search forward starting at the current line and moving `down' + through the the history as necessary. This is an incremental + search. + +`non-incremental-reverse-search-history (M-p)' + Search backward starting at the current line and moving `up' + through the history as necessary using a non-incremental search + for a string supplied by the user. + +`non-incremental-forward-search-history (M-n)' + Search forward starting at the current line and moving `down' + through the the history as necessary using a non-incremental search + for a string supplied by the user. + +`history-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the current cursor + position (the `point'). This is a non-incremental search. By + default, this command is unbound. + +`history-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. This is a + non-incremental search. By default, this command is unbound. + +`yank-nth-arg (M-C-y)' + Insert the first argument to the previous command (usually the + second word on the previous line). With an argument N, insert the + Nth word from the previous command (the words in the previous + command begin with word 0). A negative argument inserts the Nth + word from the end of the previous command. + +`yank-last-arg (M-., M-_)' + Insert last argument to the previous command (the last word of the + previous history entry). With an argument, behave exactly like + `yank-nth-arg'. + + +File: bashref.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands + +Commands For Changing Text +-------------------------- + +`delete-char (C-d)' + Delete the character under the cursor. If the cursor is at the + beginning of the line, 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 key sequences 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 the cursor forward over the character at + the cursor, moving the cursor forward as well. If the insertion + point is at the end of the line, then this transposes the last two + characters of the line. Negative argumentss 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 the cursor. + +`downcase-word (M-l)' + Lowercase the current (or following) word. With a negative + argument, do the previous word, but do not move the cursor. + +`capitalize-word (M-c)' + Capitalize the current (or following) word. With a negative + argument, do the previous word, but do not move the cursor. + + +File: bashref.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands + +Killing And Yanking +------------------- + +`kill-line (C-k)' + Kill the text from the current cursor position to the end of the + line. + +`backward-kill-line (C-x Rubout)' + Kill backward to the beginning of the line. + +`unix-line-discard (C-u)' + Kill backward from the cursor to the beginning of the current line. + Save the killed text on the kill-ring. + +`kill-whole-line ()' + Kill all characters on the current line, no matter where the + cursor is. By default, this is 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. Word boundaries are the same + as `forward-word'. + +`backward-kill-word (M-DEL)' + Kill the word behind the cursor. Word boundaries are the same as + `backward-word'. + +`unix-word-rubout (C-w)' + Kill the word behind the cursor, using white space as a word + boundary. The killed text is saved on the kill-ring. + +`delete-horizontal-space ()' + Delete all spaces and tabs around point. By default, this is + unbound. + +`kill-region ()' + Kill the text between the point and the *mark* (saved cursor + position. This text is referred to as the REGION. By default, + this command is unbound. + +`copy-region-as-kill ()' + Copy the text in the region to the kill buffer, so you can yank it + right away. By default, this command is unbound. + +`copy-backward-word ()' + Copy the word before point to the kill buffer. By default, this + command is unbound. + +`copy-forward-word ()' + Copy the word following point to the kill buffer. By default, + this command is unbound. + +`yank (C-y)' + Yank the top of the kill ring into the buffer at the current + cursor position. + +`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. + + +File: bashref.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands + +Specifying Numeric 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 ()' + Each time this is executed, the argument count is multiplied by + four. The argument count is initially one, so executing this + function the first time makes the argument count four. By + default, this is not bound to a key. + + +File: bashref.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands + +Letting Readline Type For You +----------------------------- + +`complete (TAB)' + Attempt to do completion on the text before the cursor. This is + application-specific. Generally, if you are typing a filename + argument, you can do filename completion; if you are typing a + command, you can do command completion, if you are typing in a + symbol to GDB, you can do symbol name completion, if you are + typing in a variable to Bash, you can do variable name completion, + and so on. Bash attempts completion treating the text as a + variable (if the text begins with `$'), username (if the text + begins with `~'), hostname (if the text begins with `@'), or + command (including aliases and functions) in turn. If none of + these produces a match, filename completion is attempted. + +`possible-completions (M-?)' + List the possible completions of the text before the cursor. + +`insert-completions (M-*)' + Insert all completions of the text before point that would have + been generated by `possible-completions'. + +`complete-filename (M-/)' + Attempt filename completion on the text before point. + +`possible-filename-completions (C-x /)' + List the possible completions of the text before point, treating + it as a filename. + +`complete-username (M-~)' + Attempt completion on the text before point, treating it as a + username. + +`possible-username-completions (C-x ~)' + List the possible completions of the text before point, treating + it as a username. + +`complete-variable (M-$)' + Attempt completion on the text before point, treating it as a + shell variable. + +`possible-variable-completions (C-x $)' + List the possible completions of the text before point, treating + it as a shell variable. + +`complete-hostname (M-@)' + Attempt completion on the text before point, treating it as a + hostname. + +`possible-hostname-completions (C-x @)' + List the possible completions of the text before point, treating + it as a hostname. + +`complete-command (M-!)' + Attempt completion on the text before point, treating it as a + command name. Command completion attempts to match the text + against aliases, reserved words, shell functions, builtins, and + finally executable filenames, in that order. + +`possible-command-completions (C-x !)' + List the possible completions of the text before point, treating + it as a command name. + +`dynamic-complete-history (M-TAB)' + Attempt completion on the text before point, comparing the text + against lines from the history list for possible completion + matches. + +`complete-into-braces (M-{)' + Perform filename completion and return the list of possible + completions enclosed within braces so the list is available to the + shell (*note Brace Expansion::.). + + +File: bashref.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands + +Keyboard Macros +--------------- + +`start-kbd-macro (C-x ()' + Begin saving the characters typed into the current keyboard macro. + +`end-kbd-macro (C-x ))' + Stop saving the characters typed into the current keyboard macro + and save the definition. + +`call-last-kbd-macro (C-x e)' + Re-execute the last keyboard macro defined, by making the + characters in the macro appear as if typed at the keyboard. + + +File: bashref.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands + +Some Miscellaneous Commands +--------------------------- + +`re-read-init-file (C-x C-r)' + Read in the contents of the inputrc file, and incorporate any + bindings or variable assignments found there. + +`abort (C-g)' + Abort the current editing command and ring the terminal's bell + (subject to the setting of `bell-style'). + +`do-uppercase-version (M-a, M-b, M-X, ...)' + If the metafied character X is lowercase, run the command that is + bound to the corresponding uppercase character. + +`prefix-meta (ESC)' + Make the next character that you type be metafied. This is for + people without a meta key. Typing `ESC f' is equivalent to typing + `M-f'. + +`undo (C-_, C-x C-u)' + 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. + +`tilde-expand (M-~)' + Perform tilde expansion on the current word. + +`set-mark (C-@)' + Set the mark to the current point. If a numeric argument is + supplied, the mark is set to that position. + +`exchange-point-and-mark (C-x C-x)' + Swap the point with the mark. The current cursor position is set + to the saved position, and the old cursor position is saved as the + mark. + +`character-search (C-])' + A character is read and point is moved to the next occurrence of + that character. A negative count searches for previous + occurrences. + +`character-search-backward (M-C-])' + A character is read and point is moved to the previous occurrence + of that character. A negative count searches for subsequent + occurrences. + +`insert-comment (M-#)' + The value of the `comment-begin' variable is inserted at the + beginning of the current line, and the line is accepted as if a + newline had been typed. This makes the current line a shell + comment. + +`dump-functions ()' + Print all of the functions and their key bindings to the readline + output stream. If a numeric argument is supplied, the output is + formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +`dump-variables ()' + Print all of the settable variables and their values to the + readline output stream. If a numeric argument is supplied, the + output is formatted in such a way that it can be made part of an + INPUTRC file. This command is unbound by default. + +`dump-macros ()' + Print all of the readline key sequences bound to macros and the + strings they ouput. If a numeric argument is supplied, the output + is formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +`glob-expand-word (C-x *)' + The word before point is treated as a pattern for pathname + expansion, and the list of matching file names is inserted, + replacing the word. + +`glob-list-expansions (C-x g)' + The list of expansions that would have been generated by + `glob-expand-word' is inserted into the line, replacing the word + before point. + +`display-shell-version (C-x C-v)' + Display version information about the current instance of Bash. + +`shell-expand-line (M-C-e)' + Expand the line the way the shell does when it reads it. This + performs alias and history expansion as well as all of the shell + word expansions. + +`history-expand-line (M-^)' + Perform history expansion on the current line. + +`insert-last-argument (M-., M-_)' + A synonym for `yank-last-arg'. + +`operate-and-get-next (C-o)' + Accept the current line for execution and fetch the next line + relative to the current line from the history for editing. Any + argument is ignored. + +`emacs-editing-mode (C-e)' + When in `vi' editing mode, this causes a switch back to `emacs' + editing mode, as if the command `set -o emacs' had been executed. + + +File: bashref.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing + +Readline vi Mode +================ + + While the Readline library does not have a full set of `vi' editing +functions, it does contain enough to allow simple editing of the line. +The Readline `vi' mode behaves as specified in the POSIX 1003.2 +standard. + + In order to switch interactively between `emacs' and `vi' editing +modes, use the `set -o emacs' and `set -o vi' commands (*note The Set +Builtin::.). The Readline default is `emacs' mode. + + When you enter a line in `vi' mode, you are already placed in +`insertion' mode, as if you had typed an `i'. Pressing ESC switches +you into `command' mode, where you can edit the text of the line with +the standard `vi' movement keys, move to previous history lines with +`k' and subsequent lines with `j', and so forth. + + +File: bashref.info, Node: Installing Bash, Next: Reporting Bugs, Prev: Command Line Editing, Up: Top + +Installing Bash +*************** + + This chapter provides basic instructions for installing Bash on the +various supported platforms. The distribution supports nearly every +version of Unix (and, someday, GNU). Other independent ports exist for +OS/2, Windows 95, and Windows NT. + +* Menu: + +* Basic Installation:: Generic installation instructions. + +* Compilers and Options:: How to set special options for various + systems. + +* Compiling For Multiple Architectures:: How to compile Bash for more + than one kind of system from + the same source tree. + +* Installation Names:: How to set the various paths used by the installation. + +* Specifying the System Type:: How to configure Bash for a particular system. + +* Sharing Defaults:: How to share default configuration values among GNU + programs. + +* Operation Controls:: Options recognized by the configuration program. + +* Optional Features:: How to enable and disable optional features when + building Bash. + + +File: bashref.info, Node: Basic Installation, Next: Compilers and Options, Up: Installing Bash + +Basic Installation +================== + + These are generic installation instructions for Bash. + + The `configure' shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a `Makefile' in each directory of the package +(the top directory, the `builtins' and `doc' directories, and the each +directory under `lib'). It also creates a `config.h' file containing +system-dependent definitions. Finally, it creates a shell script named +`config.status' that you can run in the future to recreate the current +configuration, a file `config.cache' that saves the results of its +tests to speed up reconfiguring, and a file `config.log' containing +compiler output (useful mainly for debugging `configure'). If at some +point `config.cache' contains results you don't want to keep, you may +remove or edit it. + + If you need to do unusual things to compile the package, please try +to figure out how `configure' could check whether or not to do them, +and mail diffs or instructions to `bash-maintainers@prep.ai.mit.edu' so +they can be considered for the next release. + + The file `configure.in' is used to create `configure' by a program +called Autoconf. You only need `configure.in' if you want to change it +or regenerate `configure' using a newer version of Autoconf. If you do +this, make sure you are using Autoconf version 2.9 or newer. + + The simplest way to compile Bash is: + + 1. `cd' to the directory containing the source code and type + `./configure' to configure Bash for your system. If you're using + `csh' on an old version of System V, you might need to type `sh + ./configure' instead to prevent `csh' from trying to execute + `configure' itself. + + Running `configure' takes awhile. While running, it prints some + messages telling which features it is checking for. + + 2. Type `make' to compile Bash and build the `bashbug' bug reporting + script. + + 3. Optionally, type `make tests' to run the Bash test suite. + + 4. Type `make install' to install `bash' and `bashbug'. This will + also install the manual pages and Info file. + + + You can remove the program binaries and object files from the source +code directory by typing `make clean'. To also remove the files that +`configure' created (so you can compile Bash for a different kind of +computer), type `make distclean'. + + +File: bashref.info, Node: Compilers and Options, Next: Compiling For Multiple Architectures, Prev: Basic Installation, Up: Installing Bash + +Compilers and Options +===================== + + Some systems require unusual options for compilation or linking that +the `configure' script does not know about. You can give `configure' +initial values for variables by setting them in the environment. Using +a Bourne-compatible shell, you can do that on the command line like +this: + + CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure + + On systems that have the `env' program, you can do it like this: + + env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure + + The configuration process uses GCC to build Bash if it is available. + + +File: bashref.info, Node: Compiling For Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Installing Bash + +Compiling For Multiple Architectures +==================================== + + You can compile Bash for more than one kind of computer at the same +time, by placing the object files for each architecture in their own +directory. To do this, you must use a version of `make' that supports +the `VPATH' variable, such as GNU `make'. `cd' to the directory where +you want the object files and executables to go and run the `configure' +script from the source directory. You may need to supply the +`--srcdir=PATH' argument to tell `configure' where the source files +are. `configure' automatically checks for the source code in the +directory that `configure' is in and in `..'. + + If you have to use a `make' that does not supports the `VPATH' +variable, you can compile Bash for one architecture at a time in the +source code directory. After you have installed Bash for one +architecture, use `make distclean' before reconfiguring for another +architecture. + + Alternatively, if your system supports symbolic links, you can use +the `support/mkclone' script to create a build tree which has symbolic +links back to each file in the source directory. Here's an example +that creates a build directory in the current directory from a source +directory `/usr/gnu/src/bash-2.0': + + bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . + +The `mkclone' script requires Bash, so you must have already built Bash +for at least one architecture before you can create build directories +for other architectures. + + +File: bashref.info, Node: Installation Names, Next: Specifying the System Type, Prev: Compiling For Multiple Architectures, Up: Installing Bash + +Installation Names +================== + + By default, `make install' will install into `/usr/local/bin', +`/usr/local/man', etc. You can specify an installation prefix other +than `/usr/local' by giving `configure' the option `--prefix=PATH'. + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +give `configure' the option `--exec-prefix=PATH', the package will use +`PATH' as the prefix for installing programs and libraries. +Documentation and other data files will still use the regular prefix. + + +File: bashref.info, Node: Specifying the System Type, Next: Sharing Defaults, Prev: Installation Names, Up: Installing Bash + +Specifying the System Type +========================== + + There may be some features `configure' can not figure out +automatically, but needs to determine by the type of host the package +will run on. Usually `configure' can figure that out, but if it prints +a message saying it can not guess the host type, give it the +`--host=TYPE' option. `TYPE' can either be a short name for the system +type, such as `sun4', or a canonical name with three fields: +`CPU-COMPANY-SYSTEM' (e.g., `sparc-sun-sunos4.1.2'). + +See the file `support/config.sub' for the possible values of each field. + + +File: bashref.info, Node: Sharing Defaults, Next: Operation Controls, Prev: Specifying the System Type, Up: Installing Bash + +Sharing Defaults +================ + + If you want to set default values for `configure' scripts to share, +you can create a site shell script called `config.site' that gives +default values for variables like `CC', `cache_file', and `prefix'. +`configure' looks for `PREFIX/share/config.site' if it exists, then +`PREFIX/etc/config.site' if it exists. Or, you can set the +`CONFIG_SITE' environment variable to the location of the site script. +A warning: the Bash `configure' looks for a site script, but not all +`configure' scripts do. + + +File: bashref.info, Node: Operation Controls, Next: Optional Features, Prev: Sharing Defaults, Up: Installing Bash + +Operation Controls +================== + + `configure' recognizes the following options to control how it +operates. + +`--cache-file=FILE' + Use and save the results of the tests in FILE instead of + `./config.cache'. Set FILE to `/dev/null' to disable caching, for + debugging `configure'. + +`--help' + Print a summary of the options to `configure', and exit. + +`--quiet' +`--silent' +`-q' + Do not print messages saying which checks are being made. + +`--srcdir=DIR' + Look for the Bash source code in directory DIR. Usually + `configure' can determine that directory automatically. + +`--version' + Print the version of Autoconf used to generate the `configure' + script, and exit. + + `configure' also accepts some other, not widely used, boilerplate +options. + + +File: bashref.info, Node: Optional Features, Prev: Operation Controls, Up: Installing Bash + +Optional Features +================= + + The Bash `configure' has a number of `--enable-FEATURE' options, +where FEATURE indicates an optional part of the package. There are +also several `--with-PACKAGE' options, where PACKAGE is something like +`gnu-malloc' or `purify' (for the Purify memory allocation checker). To +turn off the default use of a package, use `--without-PACKAGE'. To +configure Bash without a feature that is enabled by default, use +`--disable-FEATURE'. + + Here is a complete list of the `--enable-' and `--with-' options +that the Bash `configure' recognizes. + +`--with-gnu-malloc' + Use the GNU version of `malloc' in `lib/malloc/malloc.c'. This is + not the same `malloc' that appears in GNU libc, but an older + version derived from the 4.2 BSD `malloc'. This `malloc' is very + fast, but wastes a lot of space. This option is enabled by + default. The `NOTES' file contains a list of systems for which + this should be turned off. + +`--with-glibc-malloc' + Use the GNU libc version of `malloc' in `lib/malloc/gmalloc.c'. + This is somewhat slower than the default `malloc', but wastes + considerably less space. + +`--with-afs' + Define if you are using the Andrew File System from Transarc. + +`--with-purify' + Define this to use the Purify memory allocation checker from Pure + Software. + +`--enable-minimal-config' + This produces a shell with minimal features, close to the + historical Bourne shell. + +The `minimal-config' option can be used to disable all of the following +options, but it is processed first, so individual options may be +enabled using `enable-FEATURE'. + + All of the following options except for `disabled-builtins' and +`usg-echo-default' are enabled by default, unless the operating system +does not provide the necessary support. + +`--enable-job-control' + This enables job control features, if the OS supports them. + +`--enable-alias' + Allow alias expansion and include the `alias' and `unalias' + builtins. + +`--enable-readline' + Include support for command-line editing and history with the Bash + version of the Readline library. + +`--enable-history' + Include command history and the `fc' and `history' builtin + commands. + +`--enable-bang-history' + Include support for `csh'-like history substitution. + +`--enable-directory-stack' + Include support for a `csh'-like directory stack and the `pushd', + `popd', and `dirs' builtins. + +`--enable-restricted' + Include support for a "restricted shell". If this is enabled, + Bash, when called as `rbash', enters a restricted mode. See *Note + The Restricted Shell::, for a description of restricted mode. + +`--enable-process-substitution' + This enables process substitution (*note Process Substitution::.) + if the OS provides the necessary support. + +`--enable-prompt-string-decoding' + Turn on the interpretation of a number of backslash-escaped + characters in the `$PS1', `$PS2', `$PS3', and `$PS4' prompt + strings. + +`--enable-select' + Include the `ksh' `select' builtin, which allows the generation of + simple menus. + +`--enable-help-builtin' + Include the `help' builtin, which displays help on shell builtins + and variables. + +`--enable-array-variables' + Include support for one-dimensional array shell variables. + +`--enable-dparen-arithmetic' + Include support for the `ksh' `((...))' command. + +`--enable-brace-expansion' + Include `csh'-like brace expansion ( `b{a,b}c' ==> `bac bbc' ). + +`--enable-disabled-builtins' + Allow builtin commands to be invoked via `builtin xxx' even after + `xxx' has been disabled using `enable -n xxx'. See *Note Bash + Builtins::, for details of the `builtin' and `enable' builtin + commands. + +`--enable-command-timing' + Include support for recognizing `time' as a reserved word and for + displaying timing statistics for the pipeline following `time'. + This allows pipelines as well as shell builtins and functions to + be timed. + +`--enable-usg-echo-default' + Make the `echo' builtin expand backslash-escaped characters by + default, without requiring the `-e' option. This makes the Bash + `echo' behave more like the System V version. + + The file `config.h.top' contains C Preprocessor `#define' statements +for options which are not settable from `configure'. Some of these are +not meant to be changed; beware of the consequences if you do. Read +the comments associated with each definition for more information about +its effect. + + +File: bashref.info, Node: Reporting Bugs, Next: Builtin Index, Prev: Installing Bash, Up: Top + +Reporting Bugs +************** + + Please report all bugs you find in Bash. But first, you should make +sure that it really is a bug, and that it appears in the latest version +of Bash that you have. + + Once you have determined that a bug actually exists, use the +`bashbug' command to submit a bug report. If you have a fix, you are +welcome to mail that as well! Suggestions and `philosophical' bug +reports may be mailed to `bug-bash@prep.ai.MIT.Edu' or posted to the +Usenet newsgroup `gnu.bash.bug'. + + All bug reports should include: + * The version number of Bash. + + * The hardware and operating system. + + * The compiler used to compile Bash. + + * A description of the bug behaviour. + + * A short script or `recipe' which exercises the bug and may be used + to reproduce it. + +`bashbug' inserts the first three items automatically into the template +it provides for filing a bug report. + + Please send all reports concerning this manual to +`chet@ins.CWRU.Edu'. + + +File: bashref.info, Node: Builtin Index, Next: Reserved Word Index, Prev: Reporting Bugs, Up: Top + +Index of Shell Builtin Commands +******************************* + +* Menu: + +* .: Bourne Shell Builtins. +* :: Bourne Shell Builtins. +* [: Bourne Shell Builtins. +* alias: Alias Builtins. +* bg: Job Control Builtins. +* bind: Bash Builtins. +* break: Bourne Shell Builtins. +* builtin: Bash Builtins. +* cd: Bourne Shell Builtins. +* command: Bash Builtins. +* continue: Bourne Shell Builtins. +* declare: Bash Builtins. +* dirs: C Shell Builtins. +* disown: Job Control Builtins. +* echo: Bash Builtins. +* enable: Bash Builtins. +* eval: Bourne Shell Builtins. +* exec: Bourne Shell Builtins. +* exit: Bourne Shell Builtins. +* export: Bourne Shell Builtins. +* fc: Korn Shell Builtins. +* fg: Job Control Builtins. +* getopts: Bourne Shell Builtins. +* hash: Bourne Shell Builtins. +* help: Bash Builtins. +* history: C Shell Builtins. +* jobs: Job Control Builtins. +* kill: Job Control Builtins. +* let <1>: Arithmetic Builtins. +* let: Korn Shell Builtins. +* local: Bash Builtins. +* logout <1>: Bash Builtins. +* logout: C Shell Builtins. +* popd: C Shell Builtins. +* pushd: C Shell Builtins. +* pwd: Bourne Shell Builtins. +* read: Bash Builtins. +* readonly: Bourne Shell Builtins. +* return: Bourne Shell Builtins. +* set: The Set Builtin. +* shift: Bourne Shell Builtins. +* shopt: Bash Builtins. +* source: C Shell Builtins. +* suspend: Job Control Builtins. +* test: Bourne Shell Builtins. +* times: Bourne Shell Builtins. +* trap: Bourne Shell Builtins. +* type: Bash Builtins. +* typeset: Korn Shell Builtins. +* ulimit: Bash Builtins. +* umask: Bourne Shell Builtins. +* unalias: Alias Builtins. +* unset: Bourne Shell Builtins. +* wait: Job Control Builtins. + + +File: bashref.info, Node: Reserved Word Index, Next: Variable Index, Prev: Builtin Index, Up: Top + +Shell Reserved Words +******************** + +* Menu: + +* !: Pipelines. +* {: Command Grouping. +* }: Command Grouping. +* case: Conditional Constructs. +* do: Looping Constructs. +* done: Looping Constructs. +* elif: Conditional Constructs. +* else: Conditional Constructs. +* esac: Conditional Constructs. +* fi: Conditional Constructs. +* for: Looping Constructs. +* function: Shell Functions. +* if: Conditional Constructs. +* in: Conditional Constructs. +* select: Korn Shell Constructs. +* then: Conditional Constructs. +* time: Pipelines. +* until: Looping Constructs. +* while: Looping Constructs. + + +File: bashref.info, Node: Variable Index, Next: Function Index, Prev: Reserved Word Index, Up: Top + +Parameter and Variable Index +**************************** + +* Menu: + +* !: Special Parameters. +* #: Special Parameters. +* $: Special Parameters. +* *: Special Parameters. +* -: Special Parameters. +* 0: Special Parameters. +* ?: Special Parameters. +* @: Special Parameters. +* _: Special Parameters. +* auto_resume: Job Control Variables. +* BASH: Bash Variables. +* BASH_VERSINFO: Bash Variables. +* BASH_VERSION: Bash Variables. +* bell-style: Readline Init File Syntax. +* CDPATH: Bourne Shell Variables. +* comment-begin: Readline Init File Syntax. +* completion-query-items: Readline Init File Syntax. +* convert-meta: Readline Init File Syntax. +* DIRSTACK: Bash Variables. +* disable-completion: Readline Init File Syntax. +* editing-mode: Readline Init File Syntax. +* enable-keypad: Readline Init File Syntax. +* ENV: Korn Shell Variables. +* EUID: Bash Variables. +* expand-tilde: Readline Init File Syntax. +* FCEDIT: Korn Shell Variables. +* FIGNORE: Bash Variables. +* GLOBIGNORE: Bash Variables. +* histchars: Bash Variables. +* HISTCMD: Bash Variables. +* HISTCONTROL: Bash Variables. +* HISTFILE: Bash Variables. +* HISTFILESIZE: Bash Variables. +* HISTIGNORE: Bash Variables. +* HISTSIZE: Bash Variables. +* HOME: Bourne Shell Variables. +* horizontal-scroll-mode: Readline Init File Syntax. +* HOSTFILE: Bash Variables. +* HOSTNAME: Bash Variables. +* HOSTTYPE: Bash Variables. +* IFS: Bourne Shell Variables. +* IGNOREEOF <1>: Bash Variables. +* IGNOREEOF: C Shell Variables. +* input-meta: Readline Init File Syntax. +* INPUTRC: Bash Variables. +* keymap: Readline Init File Syntax. +* LANG: Bash Variables. +* LC_ALL: Bash Variables. +* LC_MESSAGES: Bash Variables. +* LINENO: Korn Shell Variables. +* MACHTYPE: Bash Variables. +* MAIL: Bourne Shell Variables. +* MAILCHECK: Bash Variables. +* MAILPATH: Bourne Shell Variables. +* mark-modified-lines: Readline Init File Syntax. +* meta-flag: Readline Init File Syntax. +* OLDPWD: Korn Shell Variables. +* OPTARG: Bourne Shell Variables. +* OPTERR: Bash Variables. +* OPTIND: Bourne Shell Variables. +* OSTYPE: Bash Variables. +* output-meta: Readline Init File Syntax. +* PATH: Bourne Shell Variables. +* PIPESTATUS: Bash Variables. +* PPID: Bash Variables. +* PROMPT_COMMAND: Bash Variables. +* PS1: Bourne Shell Variables. +* PS2: Bourne Shell Variables. +* PS3: Korn Shell Variables. +* PS4: Korn Shell Variables. +* PWD: Korn Shell Variables. +* RANDOM: Korn Shell Variables. +* REPLY: Korn Shell Variables. +* SECONDS: Korn Shell Variables. +* SHELLOPTS: Bash Variables. +* SHLVL: Bash Variables. +* show-all-if-ambiguous: Readline Init File Syntax. +* TIMEFORMAT: Bash Variables. +* TMOUT: Korn Shell Variables. +* UID: Bash Variables. +* visible-stats: Readline Init File Syntax. + + +File: bashref.info, Node: Function Index, Next: Concept Index, Prev: Variable Index, Up: Top + +Function Index +************** + +* Menu: + +* abort (C-g): Miscellaneous Commands. +* accept-line (Newline, Return): Commands For History. +* backward-char (C-b): Commands For Moving. +* backward-delete-char (Rubout): Commands For Text. +* backward-kill-line (C-x Rubout): Commands For Killing. +* backward-kill-word (M-DEL): Commands For Killing. +* backward-word (M-b): Commands For Moving. +* beginning-of-history (M-<): Commands For History. +* beginning-of-line (C-a): Commands For Moving. +* call-last-kbd-macro (C-x e): Keyboard Macros. +* capitalize-word (M-c): Commands For Text. +* character-search (C-]): Miscellaneous Commands. +* character-search-backward (M-C-]): Miscellaneous Commands. +* clear-screen (C-l): Commands For Moving. +* complete (TAB): Commands For Completion. +* copy-backward-word (): Commands For Killing. +* copy-forward-word (): Commands For Killing. +* copy-region-as-kill (): Commands For Killing. +* delete-char (C-d): Commands For Text. +* delete-horizontal-space (): Commands For Killing. +* digit-argument (M-0, M-1, ... M-): Numeric Arguments. +* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. +* downcase-word (M-l): Commands For Text. +* dump-functions (): Miscellaneous Commands. +* dump-macros (): Miscellaneous Commands. +* dump-variables (): Miscellaneous Commands. +* end-kbd-macro (C-x )): Keyboard Macros. +* end-of-history (M->): Commands For History. +* end-of-line (C-e): Commands For Moving. +* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. +* forward-char (C-f): Commands For Moving. +* forward-search-history (C-s): Commands For History. +* forward-word (M-f): Commands For Moving. +* history-search-backward (): Commands For History. +* history-search-forward (): Commands For History. +* insert-comment (M-#): Miscellaneous Commands. +* insert-completions (M-*): Commands For Completion. +* kill-line (C-k): Commands For Killing. +* kill-region (): Commands For Killing. +* kill-whole-line (): Commands For Killing. +* kill-word (M-d): Commands For Killing. +* next-history (C-n): Commands For History. +* non-incremental-forward-search-history (M-n): Commands For History. +* non-incremental-reverse-search-history (M-p): Commands For History. +* possible-completions (M-?): Commands For Completion. +* prefix-meta (ESC): Miscellaneous Commands. +* previous-history (C-p): Commands For History. +* quoted-insert (C-q, C-v): Commands For Text. +* re-read-init-file (C-x C-r): Miscellaneous Commands. +* redraw-current-line (): Commands For Moving. +* reverse-search-history (C-r): Commands For History. +* revert-line (M-r): Miscellaneous Commands. +* self-insert (a, b, A, 1, !, ...): Commands For Text. +* set-mark (C-@): Miscellaneous Commands. +* start-kbd-macro (C-x (): Keyboard Macros. +* tab-insert (M-TAB): Commands For Text. +* tilde-expand (M-~): Miscellaneous Commands. +* transpose-chars (C-t): Commands For Text. +* transpose-words (M-t): Commands For Text. +* undo (C-_, C-x C-u): Miscellaneous Commands. +* universal-argument (): Numeric Arguments. +* unix-line-discard (C-u): Commands For Killing. +* unix-word-rubout (C-w): Commands For Killing. +* upcase-word (M-u): Commands For Text. +* yank (C-y): Commands For Killing. +* yank-last-arg (M-., M-_): Commands For History. +* yank-nth-arg (M-C-y): Commands For History. +* yank-pop (M-y): Commands For Killing. + + +File: bashref.info, Node: Concept Index, Prev: Function Index, Up: Top + +Concept Index +************* + +* Menu: + +* alias expansion: Aliases. +* arithmetic evaluation: Arithmetic Evaluation. +* arithmetic expansion: Arithmetic Expansion. +* arithmetic, shell: Shell Arithmetic. +* arrays: Arrays. +* background: Job Control Basics. +* Bash configuration: Basic Installation. +* Bash installation: Basic Installation. +* Bourne shell: Basic Shell Features. +* brace expansion: Brace Expansion. +* builtin: Definitions. +* command editing: Readline Bare Essentials. +* command execution: Command Search and Execution. +* command history: Bash History Facilities. +* command search: Command Search and Execution. +* command substitution: Command Substitution. +* command timing: Pipelines. +* commands, conditional: Conditional Constructs. +* commands, grouping: Command Grouping. +* commands, lists: Lists. +* commands, looping: Looping Constructs. +* commands, pipelines: Pipelines. +* commands, simple: Simple Commands. +* comments, shell: Comments. +* configuration: Basic Installation. +* control operator: Definitions. +* editing command lines: Readline Bare Essentials. +* environment: Environment. +* evaluation, arithmetic: Arithmetic Evaluation. +* event designators: Event Designators. +* exit status <1>: Definitions. +* exit status: Exit Status. +* expansion: Shell Expansions. +* expansion, arithmetic: Arithmetic Expansion. +* expansion, brace: Brace Expansion. +* expansion, filename: Filename Expansion. +* expansion, parameter: Shell Parameter Expansion. +* expansion, pathname: Filename Expansion. +* expansion, tilde: Tilde Expansion. +* expressions, arithmetic: Arithmetic Evaluation. +* expressions, conditional: Bash Conditional Expressions. +* field: Definitions. +* filename: Definitions. +* filename expansion: Filename Expansion. +* foreground: Job Control Basics. +* functions, shell: Shell Functions. +* history events: Event Designators. +* history expansion: History Interaction. +* history list: Bash History Facilities. +* History, how to use: Job Control Variables. +* identifier: Definitions. +* initialization file, readline: Readline Init File. +* installation: Basic Installation. +* interaction, readline: Readline Interaction. +* interactive shell <1>: Is This Shell Interactive?. +* interactive shell: Invoking Bash. +* job: Definitions. +* job control <1>: Definitions. +* job control: Job Control Basics. +* kill ring: Readline Killing Commands. +* killing text: Readline Killing Commands. +* localization: Locale Translation. +* metacharacter: Definitions. +* name: Definitions. +* notation, readline: Readline Bare Essentials. +* operator, shell: Definitions. +* parameter expansion: Shell Parameter Expansion. +* parameters: Shell Parameters. +* parameters, positional: Positional Parameters. +* parameters, special: Special Parameters. +* pathname expansion: Filename Expansion. +* pipeline: Pipelines. +* POSIX: Definitions. +* POSIX Mode: Bash POSIX Mode. +* process group: Definitions. +* process group ID: Definitions. +* process substitution: Process Substitution. +* prompting: Printing a Prompt. +* quoting: Quoting. +* quoting, ANSI: ANSI-C Quoting. +* Readline, how to use: Modifiers. +* redirection: Redirections. +* reserved word: Definitions. +* restricted shell: The Restricted Shell. +* return status: Definitions. +* shell function: Shell Functions. +* shell script: Shell Scripts. +* shell variable: Shell Parameters. +* signal: Definitions. +* signal handling: Signals. +* special builtin: Definitions. +* startup files: Bash Startup Files. +* suspending jobs: Job Control Basics. +* tilde expansion: Tilde Expansion. +* token: Definitions. +* variable, shell: Shell Parameters. +* word: Definitions. +* word splitting: Word Splitting. +* yanking text: Readline Killing Commands. + + + +Tag Table: +Node: Top1009 +Node: Introduction3117 +Node: What is Bash?3342 +Node: What is a shell?4426 +Node: Definitions6307 +Node: Basic Shell Features8947 +Node: Shell Syntax10468 +Node: Shell Operation10758 +Node: Quoting11992 +Node: Escape Character13027 +Node: Single Quotes13458 +Node: Double Quotes13787 +Node: ANSI-C Quoting14483 +Node: Locale Translation15215 +Node: Comments15636 +Node: Simple Commands16160 +Node: Pipelines16749 +Node: Lists17820 +Node: Looping Constructs19095 +Node: Conditional Constructs20272 +Node: Command Grouping22337 +Node: Shell Functions23721 +Node: Shell Parameters25489 +Node: Positional Parameters26812 +Node: Special Parameters27506 +Node: Shell Expansions29998 +Node: Shell Parameter Expansion31998 +Node: Command Substitution38003 +Node: Process Substitution39003 +Node: Word Splitting39909 +Node: Filename Expansion41361 +Node: Quote Removal43727 +Node: Redirections44013 +Node: Executing Commands49754 +Node: Command Search and Execution50209 +Node: Environment51943 +Node: Exit Status53579 +Node: Signals54596 +Node: Shell Scripts55807 +Node: Bourne Shell Features57676 +Node: Bourne Shell Builtins58346 +Node: Bourne Shell Variables66619 +Node: Other Bourne Shell Features68156 +Node: Major Differences From The Bourne Shell68913 +Node: Csh Features79111 +Node: Brace Expansion80029 +Node: Tilde Expansion81584 +Node: C Shell Builtins82216 +Node: C Shell Variables86732 +Node: Korn Shell Features87140 +Node: Korn Shell Constructs87868 +Node: Korn Shell Builtins89562 +Node: Korn Shell Variables91720 +Node: Aliases93505 +Node: Alias Builtins95969 +Node: Bash Features96585 +Node: Invoking Bash97576 +Node: Bash Startup Files101441 +Node: Is This Shell Interactive?105024 +Node: Bash Builtins105755 +Node: The Set Builtin121569 +Node: Bash Conditional Expressions126939 +Node: Bash Variables131590 +Node: Shell Arithmetic141103 +Node: Arithmetic Evaluation141571 +Node: Arithmetic Expansion143601 +Node: Arithmetic Builtins144405 +Node: Arrays144876 +Node: Printing a Prompt147903 +Node: The Restricted Shell149501 +Node: Bash POSIX Mode150731 +Node: Job Control154303 +Node: Job Control Basics154768 +Node: Job Control Builtins158911 +Node: Job Control Variables161794 +Node: Using History Interactively162955 +Node: Bash History Facilities163544 +Node: History Interaction165942 +Node: Event Designators168504 +Node: Word Designators169427 +Node: Modifiers170676 +Node: Command Line Editing171993 +Node: Introduction and Notation172653 +Node: Readline Interaction173661 +Node: Readline Bare Essentials174849 +Node: Readline Movement Commands176378 +Node: Readline Killing Commands177268 +Node: Readline Arguments178970 +Node: Searching179943 +Node: Readline Init File181579 +Node: Readline Init File Syntax182635 +Node: Conditional Init Constructs190424 +Node: Sample Init File192705 +Node: Bindable Readline Commands195722 +Node: Commands For Moving196472 +Node: Commands For History197319 +Node: Commands For Text199992 +Node: Commands For Killing201734 +Node: Numeric Arguments203760 +Node: Commands For Completion204386 +Node: Keyboard Macros207348 +Node: Miscellaneous Commands207906 +Node: Readline vi Mode211937 +Node: Installing Bash212813 +Node: Basic Installation213890 +Node: Compilers and Options216389 +Node: Compiling For Multiple Architectures217123 +Node: Installation Names218780 +Node: Specifying the System Type219502 +Node: Sharing Defaults220213 +Node: Operation Controls220878 +Node: Optional Features221783 +Node: Reporting Bugs226408 +Node: Builtin Index227485 +Node: Reserved Word Index230898 +Node: Variable Index232206 +Node: Function Index237285 +Node: Concept Index241643 + +End Tag Table diff --git a/doc/bashref.texi b/doc/bashref.texi new file mode 100644 index 00000000..fe871c35 --- /dev/null +++ b/doc/bashref.texi @@ -0,0 +1,5331 @@ +\input texinfo.tex @c -*- texinfo -*- +@c %**start of header +@setfilename bashref.info +@settitle Bash Reference Manual +@c %**end of header + +@ignore +last change: Mon Nov 25 11:47:06 EST 1996 +@end ignore + +@set EDITION 2.0 +@set VERSION 2.0 +@set UPDATED 25 November 1996 +@set UPDATE-MONTH November 1996 + +@iftex +@finalout +@end iftex + +@setchapternewpage odd +@defcodeindex bt +@defcodeindex rw +@set BashFeatures + +@ifinfo +@format +This text is a brief description of the features that are present in +the Bash shell. + +This is Edition @value{EDITION}, last updated @value{UPDATED}, +of @cite{The GNU Bash Reference Manual}, +for @code{Bash}, Version @value{VERSION}. + +Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end format +@end ifinfo + +@titlepage +@title Bash Reference Manual +@subtitle Reference Documentation for Bash +@subtitle Edition @value{EDITION}, for @code{bash} Version @value{VERSION}. +@subtitle @value{UPDATED} +@author Chet Ramey, Case Western Reserve University +@author Brian Fox, Free Software Foundation +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1991, 1993, 1996 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, Introduction, (dir), (dir) +@top Bash Features +@end ifinfo + +@ifinfo +This text is a brief description of the features that are present in +the Bash shell. + +This is Edition @value{EDITION}, last updated @value{UPDATED}, +of @cite{The GNU Bash Reference Manual}, +for @code{Bash}, Version @value{VERSION}. + +Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc. + +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. + +This manual is meant as a brief introduction to features found in +Bash. The Bash manual page should be used as the definitive +reference on shell behavior. + +@menu +* Introduction:: An introduction to the shell. + +* Definitions:: Some definitions used in the rest of this + manual. + +* Basic Shell Features:: The shell "building blocks". + +* Bourne Shell Features:: Features similar to those found in the + Bourne shell. + +* Csh Features:: Features originally found in the + Berkeley C-Shell. + +* Korn Shell Features:: Features originally found in the Korn + Shell. + +* Bash Features:: Features found only in Bash. + +* Job Control:: A chapter describing what job control is + and how Bash allows you to use it. + +* Using History Interactively:: Chapter dealing with history expansion + rules. + +* Command Line Editing:: Chapter describing the command line + editing features. + +* Installing Bash:: How to build and install Bash on your system. + +* Reporting Bugs:: How to report bugs in Bash. + +* Builtin Index:: Index of Bash builtin commands. + +* Reserved Word Index:: Index of Bash reserved words. + +* Variable Index:: Quick reference helps you find the + variable you want. + +* Function Index:: Index of bindable Readline functions. + +* Concept Index:: General index for concepts described in + this manual. +@end menu +@end ifinfo + +@node Introduction +@chapter Introduction +@menu +* What is Bash?:: A short description of Bash. + +* What is a shell?:: A brief introduction to shells. +@end menu + +@node What is Bash? +@section What is Bash? + +Bash is the shell, or command language interpreter, +that will appear in the @sc{GNU} operating system. +The name is an acronym for the @samp{Bourne-Again SHell}, +a pun on Steve Bourne, the author of the direct ancestor of the current +Unix shell @code{/bin/sh}, +which appeared in the Seventh Edition Bell Labs Research version +of Unix. + +Bash is an @code{sh}-compatible shell that incorporates useful +features from the Korn shell @code{ksh} and the C shell @code{csh}. +It is ultimately intended to be a +conformant implementation of the @sc{IEEE} @sc{POSIX} Shell and Tools +specification (@sc{IEEE} Working Group 1003.2). It offers functional +improvements over @code{sh} for both interactive and programming use. + +While the @sc{GNU} operating system will include a version +of @code{csh}, Bash will be the default shell. +Like other @sc{GNU} software, Bash is quite portable. It currently runs +on nearly every version of Unix and a few other operating systems @minus{} +independently-supported ports exist for @sc{OS/2} and Windows @sc{NT}. + +@node What is a shell? +@section What is a shell? + +At its base, a shell is simply a macro processor that executes +commands. A Unix shell is both a command interpreter, which +provides the user interface to the rich set of Unix utilities, +and a programming language, allowing these utilitites to be +combined. The shell reads commands either from a terminal or a +file. Files containing commands can be created, and become +commands themselves. These new commands have the same status as +system commands in directories like @file{/bin}, allowing users +or groups to establish custom environments. + +A shell allows execution of Unix commands, both synchronously and +asynchronously. The @dfn{redirection} constructs permit +fine-grained control of the input and output of those commands, +and the shell allows control over the contents of their +environment. Unix shells also provide a small set of built-in +commands (@dfn{builtins}) implementing functionality impossible +(e.g., @code{cd}, @code{break}, @code{continue}, and +@code{exec}), or inconvenient (@code{history}, @code{getopts}, +@code{kill}, or @code{pwd}, for example) to obtain via separate +utilities. Shells may be used interactively or +non-interactively: they accept input typed from the keyboard or +from a file. All of the shell builtins are described in +subsequent sections. + +While executing commands is essential, most of the power (and +complexity) of shells is due to their embedded programming +languages. Like any high-level language, the shell provides +variables, flow control constructs, quoting, and functions. + +Shells have begun offering features geared specifically for +interactive use rather than to augment the programming language. +These interactive features include job control, command line +editing, history and aliases. Each of these features is +described in this manual. + +@node Definitions +@chapter Definitions +These definitions are used throughout the remainder of this manual. + +@table @code + +@item POSIX +@cindex POSIX +A family of open system standards based on Unix. Bash +is concerned with @sc{POSIX} 1003.2, the Shell and Tools Standard. + +@item blank +A space or tab character. + +@item builtin +@cindex builtin +A command that is implemented internally by the shell itself, rather +than by an executable program somewhere in the file system. + +@item control operator +@cindex control operator +A @code{word} that performs a control function. It is a @code{newline} +or one of the following: +@samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, +@samp{|}, @samp{(}, or @samp{)}. + +@item exit status +@cindex exit status +The value returned by a command to its caller. + +@item field +@cindex field +A unit of text that is the result of one of the shell expansions. After +expansion, when executing a command, the resulting fields are used as +the command name and arguments. + +@item filename +@cindex filename +A string of characters used to identify a file. + +@item job +@cindex job +A set of processes comprising a pipeline, and any processes descended +from it, that are all in the same process group. + +@item job control +@cindex job control +A mechanism by which users can selectively start and stop execution +of processes. + +@item metacharacter +@cindex metacharacter +A character that, when unquoted, separates words. A metacharacter is +a @code{blank} or one of the following characters: +@samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or +@samp{>}. + +@item name +@cindex name +@cindex identifier +A @code{word} consisting solely of letters, numbers, and underscores, +and beginning with a letter or underscore. @code{Name}s are used as +shell variable and function names. +Also referred to as an @code{identifier}. + +@item operator +@cindex operator, shell +A @code{control operator} or a @code{redirection operator}. +@xref{Redirections}, for a list of redirection operators. + +@item process group +@cindex process group +A collection of related processes each having the same process +group @sc{ID}. + +@item process group ID +@cindex process group ID +A unique identifer that represents a @code{process group} +during its lifetime. + +@item reserved word +@cindex reserved word +A @code{word} that has a special meaning to the shell. Most reserved +words introduce shell flow control constructs, such as @code{for} and +@code{while}. + +@item return status +@cindex return status +A synonym for @code{exit status}. + +@item signal +@cindex signal +A mechanism by which a process may be notified by the kernal +of an event occurring in the system. + +@item special builtin +@cindex special builtin +A shell builtin command that has been classified as special by the +@sc{POSIX.2} standard. + +@item token +@cindex token +A sequence of characters considered a single unit by the shell. It is +either a @code{word} or an @code{operator}. + +@item word +@cindex word +A @code{token} that is not an @code{operator}. +@end table + +@node Basic Shell Features +@chapter Basic Shell Features +@cindex Bourne shell + +Bash is an acronym for @samp{Bourne-Again SHell}. +The Bourne shell is +the traditional Unix shell originally 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 @sc{POSIX} +1003.2 specification for the `standard' Unix shell. + +This chapter briefly summarizes the shell's "building blocks": +commands, control structures, shell functions, shell @i{parameters}, +shell expansions, +@i{redirections}, which are a way to direct input and output from +and to named files, and how the shell executes commands. + +@menu +* Shell Syntax:: What your input means to the shell. +* Simple Commands:: The most common type of command. +* Pipelines:: Connecting the input and output of several + commands. +* Lists:: How to execute commands sequentially. +* Looping Constructs:: Shell commands for iterative action. +* Conditional Constructs:: Shell commands for conditional execution. +* Command Grouping:: Ways to group commands. +* Shell Functions:: Grouping commands by name. +* Shell Parameters:: Special shell variables. +* Shell Expansions:: How Bash expands variables and the various + expansions available. +* Redirections:: A way to control where input and output go. +* Executing Commands:: What happens when you run a command. +* Shell Scripts:: Executing files of shell commands. +@end menu + +@node Shell Syntax +@section Shell Syntax +@menu +* Shell Operation:: The basic operation of the shell. + +* Quoting:: How to remove the special meaning from characters. + +* Comments:: How to specify comments. +@end menu + +@node Shell Operation +@subsection Shell Operation + +The following is a brief description of the shell's operation when it +reads and executes a command. Basically, the shell does the +following: + +@enumerate +@item +Reads its input from a file (@pxref{Shell Scripts}), from a string +supplied as an argument to the @samp{-c} invocation option +(@pxref{Invoking Bash}), or from the user's terminal. + +@item +Breaks the input into words and operators, obeying the quoting rules +described in @ref{Quoting}. Tokens are separated by +@code{metacharacters}. Alias expansion is performed by this step +(@pxref{Aliases}). + +@item +Parses the tokens into simple and compound commands. + +@item +Performs the various shell expansions (@pxref{Shell Expansions}), breaking +the expanded tokens into lists of filenames (@pxref{Filename Expansion}) +and commands and arguments. + +@item +Performs any necessary redirections (@pxref{Redirections}) and removes +the redirection operators and their operands from the argument list. + +@item +Executes the command (@pxref{Executing Commands}). + +@item +Optionally waits for the command to complete and collects its exit +status. + +@end enumerate + +@node Quoting +@subsection Quoting +@cindex quoting +@menu +* Escape Character:: How to remove the special meaning from a single + character. +* Single Quotes:: How to inhibit all interpretation of a sequence + of characters. +* Double Quotes:: How to suppress most of the interpretation of a + sequence of characters. +* ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. + +* Locale Translation:: How to translate strings into different languages. +@end menu + +Quoting is used to remove the special meaning of certain +characters or words to the shell. Quoting can be used to +disable special treatment for special characters, to prevent +reserved words from being recognized as such, and to prevent +parameter expansion. + +Each of the shell @code{metacharacters} (@pxref{Definitions}) +has special meaning to the shell and must be quoted if they are to +represent themselves. There are three quoting mechanisms: the +@var{escape character}, single quotes, and double quotes. + +@node Escape Character +@subsubsection Escape Character +A non-quoted backslash @samp{\} is the Bash escape character. +It preserves the literal value of the next character that follows, +with the exception of @code{newline}. If a @code{\newline} pair +appears, and the backslash is not quoted, the @code{\newline} +is treated as a line continuation (that is, it is effectively ignored). + +@node Single Quotes +@subsubsection Single Quotes + +Enclosing characters in single quotes preserves the literal value +of each character within the quotes. A single quote may not occur +between single quotes, even when preceded by a backslash. + +@node Double Quotes +@subsubsection Double Quotes + +Enclosing characters in double quotes preserves the literal value +of all characters within the quotes, with the exception of +@samp{$}, @samp{`}, and @samp{\}. +The characters @samp{$} and @samp{`} +retain their special meaning within double quotes. The backslash +retains its special meaning only when followed by one of the following +characters: +@samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}. +A double quote may be quoted within double quotes by preceding it with +a backslash. + +The special parameters @samp{*} and @samp{@@} have special meaning +when in double quotes (@pxref{Shell Parameter Expansion}). + +@node ANSI-C Quoting +@subsubsection ANSI-C Quoting +@cindex quoting, ANSI + +Words of the form @code{$'@var{string}'} are treated specially. The +word expands to @var{string}, with backslash-escaped characters replaced +as specifed by the ANSI C standard. Backslash escape sequences, if +present, are decoded as follows: + +@table @code +@item \a +alert (bell) +@item \b +backspace +@item \e +an escape character (not ANSI C) +@item \f +form feed +@item \n +newline +@item \r +carriage return +@item \t +horizontal tab +@item \v +vertical tab +@item \\ +backslash +@item \@var{nnn} +the character whose @code{ASCII} code is @var{nnn} in octal +@end table + +@noindent +The result is single-quoted, as if the dollar sign had not been present. + +@node Locale Translation +@subsubsection Locale-Specific Translation +@cindex localization + +A double-quoted string preceded by a dollar sign (@samp{$}) will cause +the string to be translated according to the current locale. +If the current locale is @code{C} or @code{POSIX}, the dollar sign +is ignored. +If the string is translated and replaced, the replacement is +double-quoted. + +@node Comments +@subsection Comments +@cindex comments, shell + +In a non-interactive shell, or an interactive shell in which the +@code{interactive_comments} option to the @code{shopt} +builtin is enabled (@pxref{Bash Builtins}), +a word beginning with @samp{#} +causes that word and all remaining characters on that line to +be ignored. An interactive shell without the @code{interactive_comments} +option enabled does not allow comments. The @code{interactive_comments} +option is on by default in interactive shells. + +@node Simple Commands +@section Simple Commands +@cindex commands, simple + +A simple command is the kind of command you'll encounter most often. +It's just a sequence of words separated by @code{blank}s, terminated +by one of the shell control operators (@pxref{Definitions}). The +first word generally specifies a command to be executed. + +The return status (@pxref{Exit Status}) of a simple command is +its exit status as provided +by the @sc{POSIX.1} @code{waitpid} function, or 128+@var{n} if the command +was terminated by signal @var{n}. + +@node Pipelines +@section Pipelines +@cindex pipeline +@cindex commands, pipelines + +A @code{pipeline} is a sequence of simple commands separated by +@samp{|}. + +@rwindex time +@rwindex ! +@cindex command timing +The format for a pipeline is +@example +[@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}] +@end example + +@noindent +The output of each command in the pipeline is connected to the input of +the next command. That is, each command reads the previous command's +output. + +The reserved word @code{time} causes timing statistics +to be printed for the pipeline once it finishes. +The @samp{-p} option changes the output format to that specified +by @sc{POSIX}. +The @code{TIMEFORMAT} variable may be set to a format string that +specifies how the timing information should be displayed. +@xref{Bash Variables}, for a description of the available formats. + +Each command in a pipeline is executed in its own subshell. The exit +status of a pipeline is the exit status of the last command in the +pipeline. If the reserved word @samp{!} precedes the pipeline, the +exit status is the logical @sc{NOT} of the exit status of the last command. + +@node Lists +@section Lists of Commands +@cindex commands, lists + +A @code{list} is a sequence of one or more pipelines separated by one +of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||}, +and optionally terminated by one of @samp{;}, @samp{&}, or a +@code{newline}. + +Of these list operators, @samp{&&} and @samp{||} +have equal precedence, followed by @samp{;} and @samp{&}, +which have equal precedence. + +If a command is terminated by the control operator @samp{&}, +the shell executes the command in the @var{background} +in a subshell. The shell does not wait for the command to +finish, and the return status is 0 (true). Commands separated by a +@samp{;} are executed sequentially; the shell waits for each +command to terminate in turn. The return status is the +exit status of the last command executed. + +The control operators @samp{&&} and @samp{||} +denote @sc{AND} lists and @sc{OR} lists, respectively. +An @sc{AND} list has the form +@example +@var{command} && @var{command2} +@end example + +@noindent +@var{command2} is executed if, and only if, @var{command} +returns an exit status of zero. + +An @sc{OR} list has the form +@example +@var{command} || @var{command2} +@end example + +@noindent +@var{command2} is executed if and only if @var{command} +returns a non-zero exit status. + +The return status of +@sc{AND} and @sc{OR} lists is the exit status of the last command +executed in the list. + +@node Looping Constructs +@section Looping Constructs +@cindex commands, looping + +Note that wherever you see a @samp{;} in the description of a +command's syntax, it may be replaced indiscriminately with +one or more newlines. + +Bash supports the following looping constructs. + +@table @code +@item until +@rwindex until +@rwindex do +@rwindex done +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 +@rwindex 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 +@rwindex for +The syntax of the @code{for} command is: + +@example +for @var{name} [in @var{words} @dots{}]; do @var{commands}; done +@end example +Execute @var{commands} for each member in @var{words}, with @var{name} +bound to the current member. If @samp{in @var{words}} is not +present, @samp{in "$@@"} is assumed. + +@end table + +The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins}) +may be used to control loop execution. + +@node Conditional Constructs +@section Conditional Constructs +@cindex commands, conditional + +@table @code +@item if +@rwindex if +@rwindex then +@rwindex else +@rwindex elif +@rwindex fi +The syntax of the @code{if} command is: + +@example +if @var{test-commands}; then + @var{consequent-commands}; +[elif @var{more-test-commands}; then + @var{more-consequents};] +[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. +Otherwise, each @code{elif} list is executed in turn, +and if its exit status is zero, +the corresponding @var{more-consequents} is executed and the +command completes. +If @samp{else @var{alternate-consequents}} is present, and +the final command in the final @code{if} or @code{elif} clause +has a non-zero exit status, then execute @var{alternate-consequents}. + +@item case +@rwindex case +@rwindex in +@rwindex esac +The syntax of the @code{case} command is: + +@example +@code{case @var{word} in [@var{pattern} [| @var{pattern}]@dots{}) @var{commands} ;;]@dots{} esac} +@end example + +Selectively execute @var{commands} based upon @var{word} matching +@var{pattern}. The @samp{|} is used to separate multiple patterns. + +Here is an example using @code{case} in a script that could be used to +describe one 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 + +@item ((@dots{})) +@example +(( @var{expression} )) +@end example + +The @var{expression} is evaluated according to the rules described +below ((@pxref{Arithmetic Evaluation}). +If the value of the expression is non-zero, the return status is 0; +otherwise the return status is 1. This is exactly equivalent to +@example +let "@var{expression}" +@end example + +@end table + +The @code{select} construct, which allows users to choose from a list +of items presented as a menu, is also available. +@xref{Korn Shell Constructs}, for a full description of @code{select}. + +@node Command Grouping +@section Grouping Commands +@cindex commands, grouping + +Bash provides two ways to group a list of commands to be executed +as a unit. When commands are grouped, redirections may be applied +to the entire command list. For example, the output of all the +commands in the list may be redirected to a single stream. + +@table @code +@item () +@example +( @var{list} ) +@end example + +Placing a list of commands between parentheses causes a subshell +to be created, and each of the commands to be executed in that +subshell. Since the @var{list} is executed in a subshell, variable +assignments do not remain in effect after the subshell completes. + +@item @{@} +@rwindex @{ +@rwindex @} +@example +@{ @var{list}; @} +@end example + +Placing a list of commands between curly braces causes the list to +be executed in the current shell context. No subshell is created. +The semicolon following @var{list} is required. +@end table + +In addition to the creation of a subshell, there is a subtle difference +between these two constructs due to historical reasons. The braces +are @code{reserved words}, so they must be separated from the @var{list} +by @code{blank}s. The parentheses are @code{operators}, and are +recognized as separate tokens by the shell even if they are not separated +from @code{list} by whitespace. + +The exit status of both of these constructs is the exit status of +@var{list}. + +@node Shell Functions +@section Shell Functions +@cindex shell function +@cindex functions, shell + +Shell functions are a way to group commands for later execution +using a single name for the group. They are executed just like +a "regular" command. Shell functions are executed in the current +shell context; no new process is created to interpret them. + +Functions are declared using this syntax: +@rwindex function +@example +[ @code{function} ] @var{name} () @{ @var{command-list}; @} +@end example + +This defines a shell function named @var{name}. The reserved +word @code{function} is optional. The @var{body} of the +function is the @var{command-list} between @{ and @}. This list +is executed whenever @var{name} is specified as the +name of a command. The exit status of a function is +the exit status of the last command executed in the body. + +When a function is executed, the arguments to the +function become the positional parameters +during its execution (@pxref{Positional Parameters}). +The special parameter +@samp{#} that gives the number of positional parameters +is updated to reflect the change. Positional parameter @code{0} +is unchanged. + +If the builtin command @code{return} +is executed in a function, the function completes and +execution resumes with the next command after the function +call. When a function completes, the values of the +positional parameters and the special parameter @samp{#} +are restored to the values they had prior to function +execution. If a numeric argument is given to @code{return}, +that is the function return status. + +Variables local to the function may be declared with the +@code{local} builtin. These variables are visible only to +the function and the commands it invokes. + +Functions may be recursive. No limit is placed on the number of +recursive calls. + +@node Shell Parameters +@section Shell Parameters +@cindex parameters +@cindex variable, shell +@cindex shell variable + +@menu +* Positional Parameters:: The shell's command-line arguments. +* Special Parameters:: Parameters with special meanings. +@end menu + +A @var{parameter} is an entity that stores values. +It can be a @code{name}, a number, or one of the special characters +listed below. +For the shell's purposes, a @var{variable} is a parameter denoted by a +@code{name}. + +A parameter is set if it has been assigned a value. The null string is +a valid value. Once a variable is set, it may be unset only by using +the @code{unset} builtin command. + +A variable may be assigned to by a statement of the form +@example +@var{name}=[@var{value}] +@end example +@noindent +If @var{value} +is not given, the variable is assigned the null string. All +@var{value}s undergo tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote +removal (detailed below). If the variable has its @samp{-i} attribute +set (see the description of the @code{declare} builtin in +@ref{Bash Builtins}), then @var{value} +is subject to arithmetic expansion even if the @code{$((@dots{}))} +syntax does not appear (@pxref{Arithmetic Expansion}). +Word splitting is not performed, with the exception +of @code{"$@@"} as explained below. +Filename expansion is not performed. + +@node Positional Parameters +@subsection Positional Parameters +@cindex parameters, positional + +A @var{positional parameter} +is a parameter denoted by one or more +digits, other than the single digit @code{0}. Positional parameters are +assigned from the shell's arguments when it is invoked, +and may be reassigned using the @code{set} +builtin command. Positional parameters may not be assigned to +with assignment statements. The positional parameters are +temporarily replaced when a shell function is executed +(@pxref{Shell Functions}). + +When a positional parameter consisting of more than a single +digit is expanded, it must be enclosed in braces. + +@node Special Parameters +@subsection Special Parameters +@cindex parameters, special + +The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. + +@vtable @code + +@item * +Expands to the positional parameters, starting from one. When the +expansion occurs within double quotes, it expands to a single word +with the value of each parameter separated by the first character +of the @code{IFS} +special variable. That is, @code{"$*"} is equivalent +to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c} +is the first character of the value of the @code{IFS} +variable. If @code{IFS} +is null or unset, the parameters are separated by spaces. + +@item @@ +Expands to the positional parameters, starting from one. When the +expansion occurs within double quotes, each parameter expands as a +separate word. That is, @code{"$@@"} is equivalent to +@code{"$1" "$2" @dots{}}. +When there are no positional parameters, @code{"$@@"} and +@code{$@@} +expand to nothing (i.e., they are removed). + +@item # +Expands to the number of positional parameters in decimal. + +@item ? +Expands to the exit status of the most recently executed foreground +pipeline. + +@item - +Expands to the current option flags as specified upon invocation, +by the @code{set} +builtin command, or those set by the shell itself +(such as the @samp{-i} option). + +@item $ +Expands to the process @sc{ID} of the shell. In a @code{()} subshell, it +expands to the process @sc{ID} of the current shell, not the +subshell. + +@item ! +Expands to the process @sc{ID} of the most recently executed background +(asynchronous) command. + +@item 0 +Expands to the name of the shell or shell script. This is set at +shell initialization. If Bash is invoked with a file of commands, +@code{$0} is set to the name of that file. If Bash +is started with the @samp{-c} option, then @code{$0} +is set to the first argument after the string to be +executed, if one is present. Otherwise, it is set +to the filename used to invoke Bash, as given by argument zero. + +@item _ +At shell startup, set to the absolute filename of the shell or shell +script being executed as passed in the argument list. +Subsequently, expands to the last argument to the previous command, +after expansion. +Also set to the full filename of each command executed and placed in +the environment exported to that command. +When checking mail, this parameter holds the name of the mail file. +@end vtable + +@node Shell Expansions +@section Shell Expansions +@cindex expansion + +Expansion is performed on the command line after it has been split into +@code{token}s. There are seven kinds of expansion performed: +@itemize @bullet +@item brace expansion +@item tilde expansion +@item parameter and variable expansion +@item command substitution +@item arithmetic expansion +@item word splitting +@item filename expansion +@end itemize + +@menu +* Shell Parameter Expansion:: How Bash expands variables to their values. +* Command Substitution:: Using the output of a command as an argument. +* Process Substitution:: A way to write and read to and from a + command. +* Word Splitting:: How the results of expansion are split into separate + arguments. +* Filename Expansion:: A shorthand for specifying filenames matching patterns. +* Quote Removal:: How and when quote characters are removed from + words. +@end menu + +Brace expansion, tilde expansion, and arithmetic expansion are described +in other sections. For brace expansion, see @ref{Brace Expansion}; for +tilde expansion, see @ref{Tilde Expansion}; and for arithmetic expansion, +see @ref{Arithmetic Expansion}. + +The order of expansions is: brace expansion, tilde expansion, +parameter, variable, and arithmetic expansion and +command substitution +(done in a left-to-right fashion), word splitting, and filename +expansion. + +On systems that can support it, there is an additional expansion +available: @var{process substitution}. This is performed at the +same time as parameter, variable, and arithemtic expansion and +command substitution. + +Only brace expansion, word splitting, and filename expansion +can change the number of words of the expansion; other expansions +expand a single word to a single word. +The only exceptions to this are the expansions of +@code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{[@@]@}"} +(@pxref{Arrays}). + +After all expansions, @code{quote removal} (@pxref{Quote Removal}) +is performed. + +@node Shell Parameter Expansion +@subsection Shell Parameter Expansion +@cindex parameter expansion +@cindex expansion, parameter + +The @samp{$} character introduces parameter expansion, +command substitution, or arithmetic expansion. The parameter name +or symbol to be expanded may be enclosed in braces, which +are optional but serve to protect the variable to be expanded from +characters immediately following it which could be +interpreted as part of the name. + +The basic form of parameter expansion is $@{@var{parameter}@}. +The value of @var{parameter} is substituted. The braces are required +when @var{parameter} +is a positional parameter with more than one digit, +or when @var{parameter} +is followed by a character that is not to be +interpreted as part of its name. + +If the first character of @var{parameter} is an exclamation point, +a level of variable indirection is introduced. +Bash uses the value of the variable formed from the rest of +@var{parameter} as the name of the variable; this variable is then +expanded and that value used in the rest of the substitution, rather +than the value of @var{parameter} itself. +This is known as @code{indirect expansion}. + +In each of the cases below, @var{word} is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +When not performing substring expansion, Bash tests for a parameter +that is unset or null; omitting the colon results in a test only for a +parameter that is unset. + +@table @code + +@item $@{@var{parameter}:@minus{}@var{word}@} +If @var{parameter} is unset or null, the expansion of +@var{word} is substituted. Otherwise, the value of +@var{parameter} is substituted. + +@item $@{@var{parameter}:=@var{word}@} +If @var{parameter} +is unset or null, the expansion of @var{word} +is assigned to @var{parameter}. +The value of @var{parameter} +is then substituted. Positional parameters and special parameters may +not be assigned to in this way. + +@item $@{@var{parameter}:?@var{word}@} +If @var{parameter} +is null or unset, the expansion of @var{word} (or a message +to that effect if @var{word} +is not present) is written to the standard error and the shell, if it +is not interactive, exits. Otherwise, the value of @var{parameter} is +substituted. + +@item $@{@var{parameter}:+@var{word}@} +If @var{parameter} +is null or unset, nothing is substituted, otherwise the expansion of +@var{word} is substituted. + +@item $@{@var{parameter}:@var{offset}@} +@itemx $@{@var{parameter}:@var{offset}:@var{length}@} +Expands to up to @var{length} characters of @var{parameter}, +starting at @var{offset}. +If @var{length} is omitted, expands to the substring of +@var{parameter}, starting at the character specified by @var{offset}. +@var{length} and @var{offset} are arithmetic expressions +(@pxref{Arithmetic Evaluation}). +This is referred to as Substring Expansion. + +@var{length} must evaluate to a number greater than or equal to zero. +If @var{offset} evaluates to a number less than zero, the value +is used as an offset from the end of the value of @var{parameter}. +If @var{parameter} is @samp{@@}, the result is @var{length} positional +parameters beginning at @var{offset}. +If @var{parameter} is an array name indexed by @samp{@@} or @samp{*}, +the result is the @var{length} +members of the array beginning with $@{@var{parameter}[@var{offset}]@}. +Substring indexing is zero-based unless the positional parameters are +used, in which case the indexing starts at 1. + +@item $@{#@var{parameter}@} +The length in characters of the value of @var{parameter} is substituted. +If @var{parameter} +is @samp{*} or @samp{@@}, +the length substituted is the number of positional parameters. +If @var{parameter} +is an array name subscripted +by @samp{*} or @samp{@@}, +the length substituted is the number of elements in the array. + +@item $@{@var{parameter}#@var{word}@} +@itemx $@{@var{parameter}##@var{word}@} +The @var{word} +is expanded to produce a pattern just as in filename +expansion (@pxref{Filename Expansion}). If the pattern matches +the beginning of the value of @var{parameter}, +then the expansion is the value of @var{parameter} +with the shortest matching pattern (the @samp{#} case) or the +longest matching pattern (the @samp{##} case) deleted. +If @var{parameter} is @samp{@@} or @samp{*}, +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If @var{parameter} is an array variable subscripted with +@samp{@@} or @samp{*}, +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. + +@item $@{@var{parameter}%@var{word}@} +@itemx $@{@var{parameter}%%@var{word}@} +The @var{word} is expanded to produce a pattern just as in +filename expansion. +If the pattern matches a trailing portion of the value of +@var{parameter}, then the expansion is the value of @var{parameter} +with the shortest matching pattern (the @samp{%} case) or the +longest matching pattern (the @samp{%%} case) deleted. +If @var{parameter} is @samp{@@} or @samp{*}, +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If @var{parameter} +is an array variable subscripted with @samp{@@} or @samp{*}, +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. + +@item $@{@var{parameter}/@var{pattern}/@var{string}@} +@itemx $@{@var{parameter}//@var{pattern}/@var{string}@} + +The @var{pattern} is expanded to produce a pattern just as in +filename expansion. +@var{Parameter} is expanded and the longest match of @var{pattern} +against its value is replaced with @var{string}. +In the first form, only the first match is replaced. +The second form causes all matches of @var{pattern} to be +replaced with @var{string}. +If @var{pattern} begins with @samp{#}, it must match at the beginning +of @var{string}. +If @var{pattern} begins with @samp{%}, it must match at the end +of @var{string}. +If @var{string} is null, matches of @var{pattern} are deleted +and the @code{/} following @var{pattern} may be omitted. +If @var{parameter} is @samp{@@} or @samp{*}, +the substitution operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If @var{parameter} +is an array variable subscripted with @samp{@@} or @samp{*}, +the substitution operation is applied to each member of the +array in turn, and the expansion is the resultant list. + +@end table + +@node Command Substitution +@subsection Command Substitution +@cindex command substitution + +Command substitution allows the output of a command to replace +the command name. There are two forms: +@example +$(@var{command}) +@end example +@noindent +or +@example +`@var{command}` +@end example + +@noindent +Bash performs the expansion by executing @var{command} and +replacing the command substitution with the standard output of the +command, with any trailing newlines deleted. + +When the old-style backquote form of substitution is used, +backslash retains its literal meaning except when followed by +@samp{$}, @samp{`}, or @samp{\}. +When using the @code{$(@var{command})} form, all characters between +the parentheses make up the command; none are treated specially. + +Command substitutions may be nested. To nest when using the old form, +escape the inner backquotes with backslashes. + +If the substitution appears within double quotes, word splitting and +filename expansion are not performed on the results. + +@node Process Substitution +@subsection Process Substitution +@cindex process substitution + +Process substitution is supported on systems that support named +pipes (@sc{FIFO}s) or the @file{/dev/fd} method of naming open files. +It takes the form of +@example +<(@var{list}) +@end example +@noindent +or +@example +>(@var{list}) +@end example +@noindent +The process @var{list} is run with its input or output connected to a +@sc{FIFO} or some file in @file{/dev/fd}. The name of this file is +passed as an argument to the current command as the result of the +expansion. If the @code{>(@var{list})} form is used, writing to +the file will provide input for @var{list}. If the +@code{<(@var{list})} form is used, the file passed as an +argument should be read to obtain the output of @var{list}. + +On systems that support it, process substitution is performed +simultaneously with parameter and variable expansion, +command substitution, and arithmetic expansion. + +@node Word Splitting +@subsection Word Splitting +@cindex word splitting + +The shell scans the results of parameter expansion, command substitution, +and arithmetic expansion that did not occur within double quotes for +word splitting. + +The shell treats each character of @code{$IFS} +as a delimiter, and splits the results of the other +expansions into words on these characters. If +@code{IFS} is unset, or its value is exactly @code{<space><tab><newline>}, +the default, then any sequence of @code{IFS} +characters serves to delimit words. If @code{IFS} +has a value other than the default, then sequences of +the whitespace characters @code{space} and @code{tab} +are ignored at the beginning and end of the +word, as long as the whitespace character is in the +value of @code{IFS} (an @code{IFS} whitespace character). +Any character in @code{IFS} that is not @code{IFS} +whitespace, along with any adjacent @code{IFS} +whitespace characters, delimits a field. A sequence of @code{IFS} +whitespace characters is also treated as a delimiter. +If the value of @code{IFS} is null, no word splitting occurs. + +Explicit null arguments (@code{""} or @code{''}) are retained. +Unquoted implicit null arguments, resulting from the expansion of +@var{parameter}s +that have no values, are removed. +If a parameter with no value is expanded within double quotes, a +null argument results and is retained. + +Note that if no expansion occurs, no splitting +is performed. + +@node Filename Expansion +@subsection Filename Expansion +@cindex expansion, filename +@cindex expansion, pathname +@cindex filename expansion +@cindex pathname expansion + +After word splitting, +unless the @samp{-f} +option has been set (@pxref{The Set Builtin}), +Bash scans each word for the characters +@samp{*}, @samp{?}, and @samp{[}. +If one of these characters appears, then the word is +regarded as a @var{pattern}, +and replaced with an alphabetically sorted list of +file names matching the pattern. If no matching file names are found, +and the shell option @code{nullglob} is disabled, the word is left +unchanged. If the option is set, and no matches are found, the word +is removed. When a pattern is used for filename generation, +the character @samp{.} +at the start of a filename or immediately following a slash +must be matched explicitly, unless the shell option @code{dotglob} +is set. The slash character must always be matched explicitly. +In other cases, the @samp{.} character is not treated specially. +See the description of @code{shopt} in @ref{Bash Builtins}, +for a description of the @code{nullglob} and @code{dotglob} options. + +The @code{GLOBIGNORE} +shell variable may be used to restrict the set of filenames matching a +@var{pattern}. If @code{GLOBIGNORE} +is set, each matching filename that also matches one of the patterns in +@code{GLOBIGNORE} is removed from the list of matches. The filenames +@file{.} and @file{..} +are always ignored, even when @code{GLOBIGNORE}. +is set. However, setting @code{GLOBIGNORE} has the effect of +enabling the @code{dotglob} +shell option, so all other filenames beginning with a +@samp{.} will match. +To get the old behavior of ignoring filenames beginning with a +@samp{.}, make @samp{.*} one of the patterns in @code{GLOBIGNORE}. +The @code{dotglob} option is disabled when @code{GLOBIGNORE} +is unset. + +The special pattern characters have the following meanings: +@table @code +@item * +Matches any string, including the null string. +@item ? +Matches any single character. +@item [@dots{}] +Matches any one of the enclosed characters. A pair of characters +separated by a minus sign denotes a @var{range}; +any character lexically between those two characters, inclusive, +is matched. If the first character following the +@samp{[} is a @samp{!} or a @samp{^} +then any character not enclosed is matched. A @samp{@minus{}} +may be matched by including it as the first or last character +in the set. A @samp{]} may be matched by including it as the first +character in the set. +@end table + +@node Quote Removal +@subsection Quote Removal + +After the preceding expansions, all unquoted occurrences of the +characters @samp{\}, @samp{'}, and @samp{"} that did not +result from one of the above expansions are removed. + +@node Redirections +@section Redirections +@cindex redirection + +Before a command is executed, its input and output +may be @var{redirected} +using a special notation interpreted by the shell. +Redirection may also be used to open and close files for the +current shell execution environment. The following redirection +operators may precede or appear anywhere within a +simple command or may follow a command. +Redirections are processed in the order they appear, from +left to right. + +In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is +@samp{<}, the redirection refers to the standard input (file +descriptor 0). If the first character of the redirection operator +is @samp{>}, the redirection refers to the standard output (file +descriptor 1). + +The word that follows the redirection operator in the following +descriptions is subjected to brace expansion, tilde expansion, +parameter expansion, command substitution, arithmetic expansion, +quote removal, and filename expansion. If it expands to more +than one word, Bash reports an error. + +Note that the order of redirections is significant. For example, +the command +@example +ls > @var{dirlist} 2>&1 +@end example +@noindent +directs both standard output and standard error to the file +@var{dirlist}, while the command +@example +ls 2>&1 > @var{dirlist} +@end example +@noindent +directs only the standard output to file @var{dirlist}, +because the standard error was duplicated as standard output +before the standard output was redirected to @var{dirlist}. + +@subsection Redirecting Input +Redirection of input causes the file whose name results from +the expansion of @var{word} +to be opened for reading on file descriptor @code{n}, +or the standard input (file descriptor 0) if @code{n} +is not specified. + +The general format for redirecting input is: +@example +[n]<@var{word} +@end example + +@subsection Redirecting Output +Redirection of output causes the file whose name results from +the expansion of @var{word} +to be opened for writing on file descriptor @code{n}, +or the standard output (file descriptor 1) if @code{n} +is not specified. If the file does not exist it is created; +if it does exist it is truncated to zero size. + +The general format for redirecting output is: +@example +[n]>[|]@var{word} +@end example + +If the redirection operator is @samp{>}, and the @samp{-C} option to the +@code{set} builtin has been enabled, the redirection will fail if the +filename whose name results from the expansion of @var{word} exists. +If the redirection operator is @samp{>|}, +then the value of the @samp{-C} option to the @code{set} +builtin command is not tested, and the redirection is attempted even +if the file named by @var{word} exists. + +@subsection Appending Redirected Output +Redirection of output in this fashion +causes the file whose name results from +the expansion of @var{word} +to be opened for appending on file descriptor @code{n}, +or the standard output (file descriptor 1) if @code{n} +is not specified. If the file does not exist it is created. + +The general format for appending output is: +@example +[n]>>@var{word} +@end example + +@subsection Redirecting Standard Output and Standard Error +Bash allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be redirected to the file whose name is the +expansion of @var{word} with this construct. + +There are two formats for redirecting standard output and +standard error: +@example +&>@var{word} +@end example +@noindent +and +@example +>&@var{word} +@end example +@noindent +Of the two forms, the first is preferred. +This is semantically equivalent to +@example +>@var{word} 2>&1 +@end example + +@subsection Here Documents +This type of redirection instructs the shell to read input from the +current source until a line containing only @var{word} +(with no trailing blanks) is seen. All of +the lines read up to that point are then used as the standard +input for a command. + +The format of here-documents is as follows: +@example +<<[@minus{}]@var{word} + @var{here-document} +@var{delimiter} +@end example + +No parameter expansion, command substitution, filename +expansion, or arithmetic expansion is performed on +@var{word}. If any characters in @var{word} are quoted, the +@var{delimiter} is the result of quote removal on @var{word}, +and the lines in the here-document are not expanded. Otherwise, +all lines of the here-document are subjected to parameter expansion, +command substitution, and arithmetic expansion. In the latter +case, the pair @code{\newline} is ignored, and @samp{\} +must be used to quote the characters +@samp{\}, @samp{$}, and @samp{`}. + +If the redirection operator is @samp{<<-}, +then all leading tab characters are stripped from input lines and the +line containing @var{delimiter}. +This allows here-documents within shell scripts to be indented in a +natural fashion. + +@subsection Duplicating File Descriptors +The redirection operator +@example +[n]<&@var{word} +@end example +@noindent +is used to duplicate input file descriptors. +If @var{word} +expands to one or more digits, the file descriptor denoted by @code{n} +is made to be a copy of that file descriptor. If @var{word} +evaluates to @samp{-}, file descriptor @code{n} is closed. If +@code{n} is not specified, the standard input (file descriptor 0) is used. + +The operator +@example +[n]>&@var{word} +@end example +@noindent +is used similarly to duplicate output file descriptors. If +@code{n} +is not specified, the standard output (file descriptor 1) is used. +As a special case, if @code{n} is omitted, and @var{word} does not +expand to one or more digits, the standard output and standard +error are redirected as described previously. + +@subsection Opening File Descriptors for Reading and Writing +The redirection operator +@example +[n]<>@var{word} +@end example +@noindent +causes the file whose name is the expansion of @var{word} +to be opened for both reading and writing on file descriptor +@code{n}, or on file descriptor 0 if @code{n} +is not specified. If the file does not exist, it is created. + +@node Executing Commands +@section Executing Commands + +@menu +* Command Search and Execution:: How Bash finds commands and runs them. + +* Environment:: The environment given to a command. + +* Exit Status:: The status returned by commands and how Bash + interprets it. + +* Signals:: What happens when Bash or a command it runs + receives a signal. +@end menu + +@node Command Search and Execution +@subsection Command Search and Execution +@cindex command execution +@cindex command search + +After a command has been split into words, if it results in a +simple command and an optional list of arguments, the following +actions are taken. + +@enumerate +@item +If the command name contains no slashes, the shell attempts to +locate it. If there exists a shell function by that name, that +function is invoked as described above in @ref{Shell Functions}. + +@item +If the name does not match a function, the shell searches for +it in the list of shell builtins. If a match is found, that +builtin is invoked. + +@item +If the name is neither a shell function nor a builtin, +and contains no slashes, Bash searches each element of +@code{$PATH} for a directory containing an executable file +by that name. Bash uses a hash table to remember the full +filenames of executable files (see the description of +@code{hash} in @ref{Bourne Shell Builtins}) to avoid multiple +@code{PATH} searches. +A full search of the directories in @code{$PATH} +is performed only if the command is not found in the hash table. +If the search is unsuccessful, the shell prints an error +message and returns a nonzero exit status. + +@item +If the search is successful, or if the command name contains +one or more slashes, the shell executes the named program. +Argument 0 is set to the name given, and the remaining arguments +to the command are set to the arguments supplied, if any. + +@item +If this execution fails because the file is not in executable +format, and the file is not a directory, it is assumed to be +@var{shell script} (@pxref{Shell Scripts}). +@end enumerate + +@node Environment +@subsection Environment +@cindex environment + +When a program is invoked it is given an array of strings +called the @var{environment}. +This is a list of name-value pairs, of the form @code{name=value}. + +Bash allows you to manipulate the environment in several +ways. On invocation, the shell scans its own environment and +creates a parameter for each name found, automatically marking +it for @var{export} +to child processes. Executed commands inherit the environment. +The @code{export} and @samp{declare -x} +commands allow parameters and functions to be added to and +deleted from the environment. If the value of a parameter +in the environment is modified, the new value becomes part +of the environment, replacing the old. The environment +inherited by any executed command consists of the shell's +initial environment, whose values may be modified in the shell, +less any pairs removed by the @code{unset} command, plus any +additions via the @code{export} and @samp{declare -x} commands. + +The environment for any simple command +or function may be augmented temporarily by prefixing it with +parameter assignments, as described in @ref{Shell Parameters}. +These assignment statements affect only the environment seen +by that command. + +If the @samp{-k} flag is set (@pxref{The Set Builtin}, then all +parameter assignments are placed in the environment for a command, +not just those that precede the command name. + +When Bash invokes an external command, the variable @samp{$_} +is set to the full path name of the command and passed to that +command in its environment. + +@node Exit Status +@subsection Exit Status +@cindex exit status + +For the purposes of the shell, a command which exits with a +zero exit status has succeeded. +A non-zero exit status indicates failure. +This seemingly counter-intuitive scheme is used so there +is one well-defined way to indicate success and a variety of +ways to indicate various failure modes. +When a command terminates on a fatal signal whose number is @var{n}, +Bash uses the value 128+@var{n} as the exit status. + +If a command is not found, the child process created to +execute it returns a status of 127. If a command is found +but is not executable, the return status is 126. + +The exit status is used by the Bash conditional commands +(@pxref{Conditional Constructs}) and some of the list +constructs (@pxref{Lists}). + +All of the Bash builtins return an exit status of zero if they succeed +and a non-zero status on failure, so they may be used by the +conditional and list constructs. + +@node Signals +@subsection Signals +@cindex signal handling + +When Bash is interactive, it ignores +@code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell), +and @code{SIGINT} +is caught and handled (so that the @code{wait} builtin is interruptible). +When Bash receives a @code{SIGINT}, it breaks out of any executing loops. +In all cases, Bash ignores @code{SIGQUIT}. +If job control is in effect (@pxref{Job Control}), Bash +ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. + +Synchronous jobs started by Bash have signals set to the +values inherited by the shell from its parent. When job control +is not in effect, background jobs (commands terminated with @samp{&}) +ignore @code{SIGINT} and @code{SIGQUIT}. +Commands run as a result of command substitution ignore the +keyboard-generated job control signals +@code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. + +The shell exits by default upon receipt of a @code{SIGHUP}. +Before exiting, it resends the @code{SIGHUP} +to all jobs, running or stopped. To prevent the shell from +sending the @code{SIGHUP} signal to a particular job, remove it +from the jobs table with the @code{disown} builtin +(@pxref{Job Control Builtins}) +or use @code{disown -h} to mark it to not receive @code{SIGHUP}. + +@node Shell Scripts +@section Shell Scripts +@cindex shell script + +A shell script is a text file containing shell commands. When such +a file is used as the first non-option argument when invoking Bash, +and neither the @samp{-c} nor @samp{-s} option is supplied +(@pxref{Invoking Bash}), +Bash reads and executes commands from the file, then exits. This +mode of operation creates a non-interactive shell. When Bash runs +a shell script, it sets the special parameter @code{0} to the name +of the file, rather than the name of the shell, and the positional +parameters are set to the remaining arguments, if any are given. +If no additional arguments are supplied, the positional parameters +are unset. + +A shell script may be made executable by using the @code{chmod} command +to turn on the execute bit. When Bash finds such a file while +searching the @code{$PATH} for a command, it spawns a subshell to +execute it. In other words, executing +@example +filename @var{arguments} +@end example +@noindent +is equivalent to executing +@example +bash filename @var{arguments} +@end example + +@noindent +if @code{filename} is an executable shell script. +This subshell reinitializes itself, so that the effect is as if a +new shell had been invoked to interpret the script. + +Most versions of Unix make this a part of the kernel's command +execution mechanism. If the first line of a script begins with +the two characters @samp{#!}, the remainder of the line specifies +an interpreter for the program. The arguments to the interpreter +consist of a single optional argument following the interpreter +name on the first line of the script file, followed by the name of +the script file, followed by the rest of the arguments. Bash +will perform this action on operating systems that do not handle it +themselves. Note that some older versions of Unix limit the interpreter +name and argument to a maximum of 32 characters. + +@node Bourne Shell Features +@chapter Bourne Shell Style Features + +@menu +* Bourne Shell Builtins:: Builtin commands inherited from the Bourne + Shell. +* Bourne Shell Variables:: Variables which Bash uses in the same way + as the Bourne Shell. +* Other Bourne Shell Features:: Addtional aspects of Bash which behave in + the same way as the Bourne Shell. +@end menu + +This section briefly summarizes things which Bash inherits from +the Bourne Shell: builtins, variables, +and other features. It also lists the significant differences +between Bash and the Bourne Shell. + +@node Bourne Shell Builtins +@section Bourne Shell Builtins + +The following shell builtin commands are inherited from the Bourne +Shell. These commands are implemented as specified by the @sc{POSIX} +1003.2 standard. + +@table @code +@item : +@btindex : +@example +: [@var{arguments}] +@end example +Do nothing beyond expanding @var{arguments} and performing redirections. + +@item . +@btindex . +@example +. @var{filename} +@end example +Read and execute commands from the @var{filename} argument in the +current shell context. + +@item break +@btindex break +@example +break [@var{n}] +@end example +Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop. +If @var{n} is supplied, the @var{n}th enclosing loop is exited. + +@item cd +@btindex cd +@example +cd [-LP] [@var{directory}] +@end example +Change the current working directory to @var{directory}. If @var{directory} +is not given, the value of the @code{HOME} shell variable is used. If the +shell variable @code{CDPATH} exists, it is used as a search path. If +@var{directory} begins with a slash, @code{CDPATH} is not used. +The @samp{-P} option means +to not follow symbolic links; symlinks are followed by default or with the +@samp{-L} option. + +@item continue +@btindex continue +@example +continue [@var{n}] +@end example +Resume the next iteration of an enclosing @code{for}, @code{while}, +@code{until}, or @code{select} loop. +If @var{n} is supplied, the execution of the +@var{n}th enclosing loop is resumed. + +@item eval +@btindex eval +@example +eval [@var{arguments}] +@end example +The arguments are concatenated together into a single +command, which is then read and executed. + +@item exec +@btindex exec +@example +exec [-cl] [-a @var{name}] [@var{command}] [@var{arguments}] +@end example +If @var{command} +is supplied, it replaces the shell. +If the @samp{-l} option is supplied, +the shell places a dash in the zeroth arg passed to @var{command}. +This is what the @code{login} program does. +The @samp{-c} option causes @var{command} +to be executed with an empty environment. +If @samp{-a} is supplied, the shell passes @var{name} +as the zeroth argument to @var{command}. +If no @var{command} is specified, redirections may be used to affect +the current shell environment. + +@item exit +@btindex exit +@example +exit [@var{n}] +@end example +Exit the shell, returning a status of @var{n} to the shell's parent. + +@item export +@btindex export +@example +export [-fn] [-p] [@var{name}[=@var{value}]] +@end example +Mark each @var{name} to be passed to child processes +in the environment. If the @samp{-f} option is supplied, the @var{name}s +refer to shell functions. The @samp{-n} option means to no longer mark +each @var{name} for export. +If no @var{names} are supplied, or if the @samp{-p} option is given, a +list of exported names is displayed. + +@item getopts +@btindex getopts +@example +getopts @var{optstring} @var{name} [@var{args}] +@end example +@code{getopts} is used by shell scripts to parse positional parameters. +@var{optstring} contains the option letters to be recognized; if a letter +is followed by a colon, the option is expected to have an +argument, which should be separated from it by white space. +Each time it is invoked, @code{getopts} +places the next option in the shell variable @var{name}, initializing +@var{name} if it does not exist, +and the index of the next argument to be processed into the +variable @code{OPTIND}. @code{OPTIND} +is initialized to 1 each time the shell or a shell script +is invoked. When an option requires an argument, +@code{getopts} places that argument into the variable @code{OPTARG}. +The shell does not reset @code{OPTIND} +automatically; it must be manually reset between multiple +calls to @code{getopts} +within the same shell invocation if a new set of parameters +is to be used. + +@code{getopts} can report errors in two ways. If the first character of +@var{optstring} is a colon, @var{silent} +error reporting is used. In normal operation diagnostic messages +are printed when illegal options or missing option arguments are +encountered. +If the variable @code{OPTERR} +is set to 0, no error message will be displayed, even if the first +character of @code{optstring} is not a colon. + +If an illegal option is seen, +@code{getopts} places @samp{?} into @var{name} and, if not silent, +prints an error message and unsets @code{OPTARG}. +If @code{getopts} is silent, the option character found is placed in +@code{OPTARG} and no diagnostic message is printed. + +If a required argument is not found, and @code{getopts} +is not silent, a question mark (@samp{?}) is placed in @var{name}, +@code{OPTARG} is unset, and a diagnostic message is printed. +If @code{getopts} is silent, then a colon (@samp{:}) is placed in +@var{name} and @code{OPTARG} is set to the option character found. + +@code{getopts} +normally parses the positional parameters, but if more arguments are +given in @var{args}, @code{getopts} parses those instead. + +@item hash +@btindex hash +@example +hash [-r] [-p @var{filename}] [@var{name}] +@end example +Remember the full filenames of commands specified as arguments, +so they need not be searched for on subsequent invocations. The +commands are found by searching through the directories listed in +@code{$PATH}. The @samp{-p} option inhibits the path search, and +@var{filename} is used as the location of @var{name}. +The @samp{-r} option causes the shell to forget +all remembered locations. If no arguments are given, information +about remembered commands is printed. + +@item pwd +@btindex pwd +@example +pwd [-LP] +@end example +Print the current working directory. If the @samp{-P} option is supplied, +the path printed will not contain symbolic links. If the @samp{-L} option +is supplied, the path printed may contain symbolic links. + +@item readonly +@btindex readonly +@example +readonly [-apf] [@var{name}] @dots{} +@end example +Mark each @var{name} as unchangable. The values of these names may not +be changed by subsequent assignment. If the @samp{-f} option is supplied, +each @var{name} refers to a shell function. The @samp{-a} option means +each @var{name} refers to an array variable. +If no @var{name} arguments are given, or if the @samp{-p} +option is supplied, a list of all readonly names is printed. + +@item return +@btindex return +@example +return [@var{n}] +@end example +Cause a shell function to exit with value @var{n}. This may also be used +to terminate execution of a script being executed with the @code{.} +builtin. + +@item shift +@btindex shift +@example +shift [@var{n}] +@end example +Shift positional parameters to the left by @var{n}. +The positional parameters from @var{n}+1 @dots{} +are renamed to +@code{$1} @dots{} . +Parameters represented by the numbers +@code{$#} to @var{n}+1 are unset. @var{n} +must be a non-negative number less than or equal to @code{$#}. + +@item test +@itemx [ +@btindex test +@btindex [ +Evaluate a conditional expression (@pxref{Bash Conditional Expressions}). + +@item times +@btindex times +@example +times +@end example +Print out the user and system times used by the shell and its children. + +@item trap +@btindex trap +@example +trap [-lp] [@var{arg}] [@var{sigspec}] +@end example +The commands in @var{arg} are to be read and executed when the +shell receives signal @var{sigspec}. If @var{arg} is absent or +equal to @samp{-}, all specified signals are reset to the values +they had when the shell was started. +If @var{arg} is the null string, then @var{sigspec} is ignored by +the shell and commands it invokes. +If @var{arg} is @samp{-p}, the shell displays the trap commands +associated with each @var{sigspec}. If no arguments are supplied, or +only @samp{-p} is given, @code{trap} prints the list of commands +associated with each signal number. @var{sigspec} is either a signal +name such as @code{SIGINT} or a signal number. If @var{sigspec} is +@code{0} or @code{EXIT}, @var{arg} is executed when the shell exits. +If @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed +after every simple command. +The @samp{-l} option causes the shell to print a list of signal names +and their corresponding numbers. + +Signals ignored upon entry to the shell cannot be trapped or reset. +Trapped signals are reset to their original values in a child +process when it is created. + +@item umask +@btindex umask +@example +umask [-S] [@var{mode}] +@end example +Set the shell process's file creation mask to @var{mode}. If +@var{mode} begins with a digit, it is interpreted as an octal number; +if not, it is interpreted as a symbolic mode mask similar +to that accepted by the @code{chmod} command. If @var{mode} is +omitted, the current value of the mask is printed. If the @samp{-S} +option is supplied without a @var{mode} argument, the mask is printed +in a symbolic format. + +@item unset +@btindex unset +@example +unset [-fv] [@var{name}] +@end example +Each variable or function @var{name} is removed. +If no options are supplied, or the @samp{-v} option is given, each +@var{name} refers to a shell variable. +If the @samp{-f} option is given, the @var{name}s refer to shell +functions, and the function definition is removed. +Read-only variables and functions may not be unset. + +@end table + +@node Bourne Shell Variables +@section Bourne Shell Variables + +Bash uses certain shell variables in the same way as the Bourne shell. +In some cases, Bash assigns a default value to the variable. + +@vtable @code + +@item IFS +A list of characters that separate fields; used when the shell splits +words as part of expansion. + +@item PATH +A colon-separated list of directories in which the shell looks for +commands. + +@item HOME +The current user's home directory; the default for the @code{cd} builtin +command. + +@item CDPATH +A colon-separated list of directories used as a search path for +the @code{cd} command. + +@item MAILPATH +A colon-separated list of files which the shell periodically checks +for new mail. You can +also specify what message is printed by separating the file name from +the message with a @samp{?}. When used in the text of the message, +@code{$_} stands for the name of the current mailfile. + +@item MAIL +If this parameter is set to a filename and the @code{MAILPATH} variable +is not set, Bash informs the user of the arrival of mail in +the specified file. + +@item PS1 +The primary prompt string. The default value is @samp{\s-\v\$ }. + +@item PS2 +The secondary prompt string. The default value is @samp{> }. + +@item OPTIND +The index of the last option processed by the +@code{getopts} builtin. + +@item OPTARG +The value of the last option argument processed by the +@code{getopts} builtin. + +@end vtable + +@node Other Bourne Shell Features +@section Other Bourne Shell Features + +@menu +* Major Differences From The Bourne Shell:: Major differences between + Bash and the Bourne shell. +@end menu + +Bash implements essentially the same grammar, parameter and variable +expansion, redirection, and quoting as the Bourne Shell. Bash uses the +@sc{POSIX} 1003.2 standard as the specification of how these features are to be +implemented. There are some differences between the traditional Bourne +shell and the @sc{POSIX} standard; this section quickly details the differences +of significance. A number of these differences are explained in greater +depth in subsequent sections. + +@node Major Differences From The Bourne Shell +@subsection Major Differences From The SVR4.2 Bourne Shell + +Bash is @sc{POSIX}-conformant, even where the @sc{POSIX} specification +differs from traditional @code{sh} behavior. + +Bash has multi-character invocation options (@pxref{Invoking Bash}). + +Bash has command-line editing (@pxref{Command Line Editing}) and +the @code{bind} builtin. + +Bash has command history (@pxref{Bash History Facilities}) and the +@code{history} and @code{fc} builtins to manipulate it. + +Bash implements @code{csh}-like history expansion (@pxref{History Interaction}). + +Bash has one-dimensional array variables (@pxref{Arrays}), and the +appropriate variable expansions and assignment syntax to use them. +Some of the Bash builtins take options to act on arrays. Bash provides +some built-in array variables. + +Bash implements the @code{!} keyword to negate the return value of +a pipeline (@pxref{Pipelines}). +Very useful when an @code{if} statement needs to act only if a test fails. + +Bash includes the @code{select} compound command, which allows the +generation of simple menus (@pxref{Korn Shell Constructs}). + +Bash includes brace expansion (@pxref{Brace Expansion}) and tilde +expansion (@pxref{Tilde Expansion}). + +Bash implements command aliases and the @code{alias} and @code{unalias} +builtins (@pxref{Aliases}). + +Bash provides shell arithmetic and arithmetic expansion +(@pxref{Shell Arithmetic}). + +The @sc{POSIX} and @code{ksh}-style @code{$()} form of command substitution +is implemented (@pxref{Command Substitution}), +and preferred to the Bourne shell's @code{``} (which +is also implemented for backwards compatibility). + +Variables present in the shell's initial environment are automatically +exported to child processes. The Bourne shell does not normally do +this unless the variables are explicitly marked using the @code{export} +command. + +Bash includes the @sc{POSIX} and @code{ksh}-style pattern removal +@samp{%}, @samp{#}, @samp{%%} and @samp{##} constructs to remove +leading or trailing substrings from variable values +(@pxref{Shell Parameter Expansion}). + +The expansion @code{$@{#xx@}}, which returns the length of @code{$xx}, +is supported (@pxref{Shell Parameter Expansion}). + +The @code{$'@dots{}'} quoting syntax, which expands ANSI-C +backslash-escaped characters in the text between the single quotes, +is supported (@pxref{ANSI-C Quoting}). + +Bash supports the @code{$"@dots{}"} quoting syntax to do +locale-specific translation of the characters between the double +quotes. The @samp{-D} and @samp{--dump-strings} invocation options +list the translatable strings found in a script +(@pxref{Locale Translation}). + +The expansion @code{$@{var:}@var{length}@code{[:}@var{offset}@code{]@}}, +which expands to the substring of @code{var}'s value of length +@var{length}, optionally beginning at @var{offset}, is present +(@pxref{Shell Parameter Expansion}). + +The expansion +@code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}}, +which matches @var{pattern} and replaces it with @var{replacement} in +the value of @code{var}, is available (@pxref{Shell Parameter Expansion}). + +Bash has @var{indirect} variable expansion using @code{$@{!word@}} +(@pxref{Shell Parameter Expansion}). + +Bash can expand positional parameters beyond @code{$9} using +@code{$@{@var{num}@}}. + +Bash has process substitution (@pxref{Process Substitution}). + +Bash automatically assigns variables that provide information about the +current user (@code{UID} and @code{EUID}), the current host +(@code{HOSTTYPE}, @code{OSTYPE}, @code{MACHTYPE}, and @code{HOSTNAME}), +and the instance of Bash that is running (@code{BASH}, +@code{BASH_VERSION}, and @code{BASH_VERSINFO}. @xref{Bash Variables}, +for details. + +The @code{IFS} variable is used to split only the results of expansion, +not all words (@pxref{Word Splitting}). +This closes a longstanding shell security hole. + +It is possible to have a variable and a function with the same name; +@code{sh} does not separate the two name spaces. + +Bash functions are permitted to have local variables using the +@code{local} builtin, and thus useful recursive functions may be written. + +Variable assignments preceding commands affect only that command, even +builtins and functions. In @code{sh}, all variable assignments +preceding commands are global unless the command is executed from the +file system. + +Bash performs filename expansion on filenames specified as operands +to output redirection operators. + +Bash contains the @samp{<>} redirection operator, allowing a file to be +opened for both reading and writing, and the @samp{&>} redirection +operator, for directing standard output and standard error to the same +file (@pxref{Redirections}). + +The @code{noclobber} option is available to avoid overwriting existing +files with output redirection (@pxref{The Set Builtin}). +The @samp{>|} redirection operator may be used to override @code{noclobber}. + +Bash interprets special backslash-escaped characters in the prompt +strings when interactive (@pxref{Printing a Prompt}). + +Bash allows you to write a function to override a builtin, and provides +access to that builtin's functionality within the function via the +@code{builtin} and @code{command} builtins (@pxref{Bash Builtins}). + +The @code{command} builtin allows selective disabling of functions +when command lookup is performed (@pxref{Bash Builtins}). + +Individual builtins may be enabled or disabled using the @code{enable} +builtin (@pxref{Bash Builtins}). + +The Bash @code{hash} builtin allows a name to be associated with +an arbitrary filename, even when that filename cannot be found by +searching the @code{$PATH}, using @samp{hash -p}. + +Shell functions may be exported to children via the environment +(@pxref{Shell Functions}). + +Bash includes a @code{help} builtin for quick reference to shell +facilities (@pxref{Bash Builtins}). + +The Bash @code{read} builtin (@pxref{Bash Builtins}) +will read a line ending in @samp{\} with +the @samp{-r} option, and will use the @code{REPLY} variable as a +default if no arguments are supplied. The Bash @code{read} builtin +also accepts a prompt string with the @samp{-p} option and will use +Readline to obtain the line when given the @samp{-e} option. + +Bash includes the @code{shopt} builtin, for finer control of shell +optional capabilities (@pxref{Bash Builtins}). + +Bash has much more optional behavior controllable with the @code{set} +builtin (@pxref{The Set Builtin}). + +The @code{disown} builtin can remove a job from the internal shell +job table (@pxref{Job Control Builtins}). + +The @code{return} builtin may be used to abort execution of scripts +executed with the @code{.} or @code{source} builtins +(@pxref{Bourne Shell Builtins}). + +The @code{test} builtin (@pxref{Bourne Shell Builtins}) +is slightly different, as it implements the +@sc{POSIX} 1003.2 algorithm, which specifies the behavior based on the +number of arguments. + +The @code{trap} builtin (@pxref{Bourne Shell Builtins}) +allows a @code{DEBUG} pseudo-signal specification, +similar to @code{EXIT}. Commands specified with a @code{DEBUG} trap are +executed after every simple command. The @code{DEBUG} trap is not +inherited by shell functions. + +The Bash @code{export}, @code{readonly}, and @code{declare} builtins can +take a @samp{-f} option to act on shell functions, a @samp{-p} option to +display variables with various attributes set in a format that can be +used as shell input, a @samp{-n} option to remove various variable +attributes, and @samp{name=value} arguments to set variable attributes +and values simultaneously. + +The Bash @code{cd} and @code{pwd} builtins each take @samp{-L} and +@samp{-P} builtins to switch between logical and physical modes. + +The Bash @code{type} builtin is more extensive and gives more information +about the names it finds. + +Bash implements a @code{csh}-like directory stack, and provides the +@code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it. +Bash also makes the directory stack visible as the value of the +@code{DIRSTACK} shell variable. + +The Bash restricted mode is more useful (@pxref{The Restricted Shell}); +the @sc{SVR4.2} shell restricted mode is too limited. + +Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}). +The display of the timing statistics may be controlled with the +@code{TIMEFORMAT} variable. + +The @sc{SVR4.2} shell has two privilege-related builtins +(@code{mldmode} and @code{priv}) not present in Bash. + +Bash does not have the @code{stop} or @code{newgrp} builtins. + +Bash does not use the @code{SHACCT} variable or perform shell accounting. + +The @sc{SVR4.2} @code{sh} uses a @code{TIMEOUT} variable like Bash uses +@code{TMOUT}. + +More features unique to Bash may be found in +@ref{Bash Features}. + +@subsection Implementation Differences From The SVR4.2 Shell + +Since Bash is a completely new implementation, it does not suffer from +many of the limitations of the @sc{SVR4.2} shell. For instance: + +@itemize @bullet + +@item +Bash does not fork a subshell when redirecting into or out of +a shell control structure such as an @code{if} or @code{while} +statement. + +@item +Bash does not allow unbalanced quotes. The @sc{SVR4.2} shell will silently +insert a needed closing quote at @code{EOF} under certain circumstances. +This can be the cause of some hard-to-find errors. + +@item +The @sc{SVR4.2} shell uses a baroque memory management scheme based on +trapping @code{SIGSEGV}. If the shell is started from a process with +@code{SIGSEGV} blocked (e.g., by using the @code{system()} C library +function call), the shell misbehaves badly. + +@item +In a questionable attempt at security, the @sc{SVR4.2} shell +will alter its real +and effective @sc{UID} and @sc{GID} if they are less than some +threshold value, commonly 100. This can lead to unexpected results. + +@item +The @sc{SVR4.2} shell does not allow users to trap @code{SIGALRM} or +@code{SIGCHLD}. + +@item +For some reason, the @sc{SVR4.2} shell does not allow the @code{MAILCHECK} +variable to be unset. + +@item +The @sc{SVR4.2} shell treats @samp{^} as the undocumented equivalent of +@samp{|}. + +@item +Bash allows multiple option arguments when it is invoked (@code{-x -v}); +the @sc{SVR4.2} shell allows only one option argument (@code{-xv}). In +fact, some versions of the shell dump core if the second argument begins +with a @samp{-}. + +@item +The @sc{SVR4.2} shell exits a script if any builtin fails; Bash exits +a script only if one of the @sc{POSIX.2} special builtins fails, and +only for certain failures, as enumerated in the @code{POSIX.2} standard. + +@item +The @sc{SVR4.2} shell behaves differently when invoked as @code{jsh} +(it turns on job control). +@end itemize + +@node Csh Features +@chapter C-Shell Style Features + +The C-Shell (@dfn{@code{csh}}) was created by Bill Joy at The +University of California at Berkeley. It +is generally considered to have better features for interactive use than +the original Bourne shell. Some of the @code{csh} features present in +Bash include job control, history expansion, `protected' redirection, and +several variables to control the interactive behaviour of the shell +(e.g., @code{IGNOREEOF}). + +@xref{Using History Interactively}, for details on history expansion. + +@menu +* Brace Expansion:: Expansion of expressions within braces. +* Tilde Expansion:: Expansion of the ~ character. +* C Shell Builtins:: Builtin commands adopted from the C Shell. +* C Shell Variables:: Variables which Bash uses in essentially + the same way as the C Shell. +@end menu + +@node Brace Expansion +@section Brace Expansion +@cindex brace expansion +@cindex expansion, brace + +Brace expansion +is a mechanism by which arbitrary strings +may be generated. This mechanism is similar to +@var{filename expansion} (@pxref{Filename Expansion}), +but the file names generated +need not exist. Patterns to be brace expanded take +the form of an optional @var{preamble}, +followed by a series of comma-separated strings +between a pair of braces, followed by an optional @var{postamble}. +The preamble is prepended to each string contained +within the braces, and the postamble is then appended +to each resulting string, expanding left to right. + +Brace expansions may be nested. The results of each expanded +string are not sorted; left to right order is preserved. +For example, +@example +bash$ echo a@{d,c,b@}e +ade ace abe +@end example + +Brace expansion is performed before any other expansions, +and any characters special to other expansions are preserved +in the result. It is strictly textual. Bash +does not apply any syntactic interpretation to the context of the +expansion or the text between the braces. + +A correctly-formed brace expansion must contain unquoted opening +and closing braces, and at least one unquoted comma. +Any incorrectly formed brace expansion is left unchanged. + +This construct is typically used as shorthand when the common +prefix of the strings to be generated is longer than in the +above example: +@example +mkdir /usr/local/src/bash/@{old,new,dist,bugs@} +@end example +or +@example +chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@} +@end example + +@node Tilde Expansion +@section Tilde Expansion +@cindex tilde expansion +@cindex expansion, tilde + +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 +@file{$HOME/foo} + +@item ~fred/foo +The subdirectory @code{foo} of the home directory of the user +@code{fred}. + +@item ~+/foo +@file{$PWD/foo} + +@item ~-/foo +@file{$OLDPWD/foo} +@end table + +Bash will also tilde expand words following redirection operators +and words following @samp{=} in assignment statements. + +@node C Shell Builtins +@section C Shell Builtins + +Bash has several builtin commands whose definition is very similar +to @code{csh}. + +@table @code +@btindex pushd +@item pushd +@example +pushd [@var{dir} | @var{+N} | @var{-N}] [-n] +@end example + +Save the current directory on a list and then @code{cd} to +@var{dir}. With no +arguments, exchanges the top two directories. + +@table @code +@item +@var{N} +Brings the @var{N}th directory (counting from the left of the +list printed by @code{dirs}) to the top of the list by rotating +the stack. +@item -@var{N} +Brings the @var{N}th directory (counting from the right of the +list printed by @code{dirs}) to the top of the list by rotating +the stack. +@item -n +Suppresses the normal change of directory when adding directories +to the stack, so that only the stack is manipulated. +@item @var{dir} +Makes the current working directory be the top of the stack, and then +@code{cd}s to @var{dir}. You can see the saved directory list +with the @code{dirs} command. +@end table + +@item popd +@btindex popd +@example +popd [+@var{N} | -@var{N}] [-n] +@end example + +Pop the directory stack, and @code{cd} to the new top directory. When +no arguments are given, @code{popd} +removes the top directory from the stack and +performs a @code{cd} 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}. +@table @code +@item +@var{N} +Removes the @var{N}th directory (counting from the left of the +list printed by @code{dirs}), starting with zero. +@item -@var{N} +Removes the @var{N}th directory (counting from the right of the +list printed by @code{dirs}), starting with zero. +@item -n +Suppresses the normal change of directory when removing directories +from the stack, so that only the stack is manipulated. +@end table + +@item dirs +@btindex dirs +@example +dirs [+@var{N} | -@var{N}] [-clvp] +@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. +@table @code +@item +@var{N} +Displays the @var{N}th directory (counting from the left of the +list printed by @code{dirs} when invoked without options), starting +with zero. +@item -@var{N} +Displays the @var{N}th directory (counting from the right of the +list printed by @code{dirs} when invoked without options), starting +with zero. +@item -c +Clears the directory stack by deleting all of the elements. +@item -l +Produces a longer listing; the default listing format uses a +tilde to denote the home directory. +@item -p +Causes @code{dirs} to print the directory stack with one entry per +line. +@item -v +Causes @code{dirs} to print the directory stack with one entry per +line, prepending each entry with its index in the stack. +@end table + +@item history +@btindex history +@example +history [-c] [@var{n}] +history [-anrw] [@var{filename}] +history -ps @var{arg} +@end example + +Display the history list with line numbers. Lines prefixed with +with a @samp{*} have been modified. An argument of @var{n} says +to list only the last @var{n} lines. Options, if supplied, have +the following meanings: + +@table @code +@item -w +Write out the current history to the history file. + +@item -r +Read the current history file and append its contents to +the history list. + +@item -a +Append the new +history lines (history lines entered since the beginning of the +current Bash session) to the history file. + +@item -n +Append the history lines not already read from the history file +to the current history list. These are lines appended to the history +file since the beginning of the current Bash session. + +@item -c +Clear the history list. This may be combined +with the other options to replace the history list completely. + +@item -s +The @var{arg}s are added to the end of +the history list as a single entry. + +@item -p +Perform history substitution on the @var{arg}s and display the result +on the standard output, without storing the results in the history list. +@end table + +When the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} option is +used, if @var{filename} +is given, then it is used as the history file. If not, then +the value of the @code{HISTFILE} variable is used. + +@item logout +@btindex logout +Exit a login shell. + +@item source +@btindex source +A synonym for @code{.} (@pxref{Bourne Shell Builtins}). + +@end table + +@node C Shell Variables +@section C Shell Variables + +@vtable @code + +@item IGNOREEOF +If this variable is set, its value is used the number of consecutive +@code{EOF}s Bash will read before exiting. By default, Bash will exit +upon reading a single @code{EOF}. If @code{IGNOREEOF} is not set to +a numeric value, Bash acts as if its value were 10. + +@end vtable + +@node Korn Shell Features +@chapter Korn Shell Style Features + +This section describes features primarily inspired by the +Korn Shell (@code{ksh}). In some cases, the @sc{POSIX} 1003.2 +standard has adopted these commands and variables from the +Korn Shell; Bash implements those features using the @sc{POSIX} +standard as a guide. + +@menu +* Korn Shell Constructs:: Shell grammar constructs adopted from the + Korn Shell +* Korn Shell Builtins:: Builtin commands adopted from the Korn Shell. +* Korn Shell Variables:: Variables which Bash uses in essentially + the same way as the Korn Shell. +* Aliases:: Substituting one command for another. +@end menu + +@node Korn Shell Constructs +@section Korn Shell Constructs + +Bash includes the Korn Shell @code{select} construct. This construct +allows the easy generation of menus. It has almost the same syntax as +the @code{for} command. + +The syntax of the @code{select} command is: +@rwindex select +@example +select @var{name} [in @var{words} @dots{}]; do @var{commands}; done +@end example + +The list of words following @code{in} is expanded, generating a list +of items. The set of expanded words is printed on the standard +error, each preceded by a number. If the @samp{in @var{words}} +is omitted, the positional parameters are printed. The +@code{PS3} prompt is then displayed and a line is read from the standard +input. If the line consists of a number corresponding to one of +the displayed words, then the value of @var{name} +is set to that word. If the line is empty, the words and prompt +are displayed again. If @code{EOF} is read, the @code{select} +command completes. Any other value read causes @var{name} +to be set to null. The line read is saved in the variable +@code{REPLY}. + +The @var{commands} are executed after each selection until a +@code{break} or @code{return} command is executed, at which +point the @code{select} command completes. + +Bash also has adopted command timing from the Korn shell. If the +@code{time} reserved word precedes a pipeline or simple command, +timing statistics for the pipeline are displayed when it completes. +The statistics currently consist of elapsed (wall-clock) time and +user and system time consumed by the command's execution. + +The use of @code{time} as a reserved word permits the timing of +shell builtins, shell functions, and pipelines. An external +@code{time} command cannot time these easily. + +@node Korn Shell Builtins +@section Korn Shell Builtins + +This section describes Bash builtin commands taken from @code{ksh}. + +@table @code + +@item fc +@btindex fc +@example +@code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]} +@code{fc -s [@var{pat}=@var{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. Both @var{first} and +@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 @minus{}16 for listing. If the @samp{-l} flag is +given, the commands are listed on standard output. The @samp{-n} flag +suppresses the command numbers when listing. The @samp{-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 each instance +of @var{pat} in the selected command is replaced by @var{rep}. + +A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so +that typing @samp{r cc} runs the last command beginning with @code{cc} +and typing @samp{r} re-executes the last command (@pxref{Aliases}). + +@item let +@btindex let +The @code{let} builtin allows arithmetic to be performed on shell variables. +For details, refer to @ref{Arithmetic Builtins}. + +@item typeset +@btindex typeset +The @code{typeset} command is supplied for compatibility with the Korn +shell; however, it has been deprecated in favor of the +@code{declare} command (@pxref{Bash Builtins}). + +@end table + +@node Korn Shell Variables +@section Korn Shell Variables + +@vtable @code + +@item REPLY +The default variable for the @code{read} builtin. + +@item RANDOM +Each time this parameter is referenced, a random integer +between 0 and 32767 is generated. Assigning a value to this +variable seeds the random number generator. + +@item SECONDS +This variable expands to the number of seconds since the +shell was started. Assignment to this variable resets +the count to the value assigned, and the expanded value +becomes the value assigned plus the number of seconds +since the assignment. + +@item PS3 +The value of this variable is used as the prompt for the +@code{select} command. If this variable is not set, the +@code{select} command prompts with @samp{#? } + +@item PS4 +This is the prompt printed before the command line is echoed +when the @samp{-x} option is set (@pxref{The Set Builtin}). +The default is @samp{+ }. + +@item PWD +The current working directory as set by the @code{cd} builtin. + +@item OLDPWD +The previous working directory as set by the @code{cd} builtin. + +@item TMOUT +If set to a value greater than zero, the value is interpreted as +the number of seconds to wait for input after issuing the primary +prompt. +Bash terminates after that number of seconds if input does +not arrive. + +@item LINENO +The line number in the script or shell function currently executing. + +@item ENV +If this variable is set when Bash is invoked to execute a shell +script, its value is expanded and used as the name of a startup file +to read before executing the script. @xref{Bash Startup Files}. + +@item FCEDIT +The editor used as a default by the @code{fc} builtin command. + +@end vtable + +@node Aliases +@section Aliases +@cindex alias expansion + +@menu +* Alias Builtins:: Builtins commands to maniuplate aliases. +@end menu + +The shell maintains a list of @var{aliases} +that may be set and unset with the @code{alias} and +@code{unalias} builtin commands. + +The first word of each command, if unquoted, +is checked to see if it has an +alias. If so, that word is replaced by the text of the alias. +The alias name and the replacement text may contain any valid +shell input, including shell metacharacters, with the exception +that the alias name may not contain @key{=}. +The first word of the replacement text is tested for +aliases, but a word that is identical to an alias being expanded +is not expanded a second time. This means that one may alias +@code{ls} to @code{"ls -F"}, +for instance, and Bash does not try to recursively expand the +replacement text. If the last character of the alias value is a +space or tab character, then the next command word following the +alias is also checked for alias expansion. + +Aliases are created and listed with the @code{alias} +command, and removed with the @code{unalias} command. + +There is no mechanism for using arguments in the replacement text, +as in @code{csh}. +If arguments are needed, a shell function should be used +(@pxref{Shell Functions}). + +Aliases are not expanded when the shell is not interactive, +unless the @code{expand_aliases} shell option is set using +@code{shopt} (@pxref{Bash Builtins}). + +The rules concerning the definition and use of aliases are +somewhat confusing. Bash +always reads at least one complete line +of input before executing any +of the commands on that line. Aliases are expanded when a +command is read, not when it is executed. Therefore, an +alias definition appearing on the same line as another +command does not take effect until the next line of input is read. +The commands following the alias definition +on that line are not affected by the new alias. +This behavior is also an issue when functions are executed. +Aliases are expanded when the function definition is read, +not when the function is executed, because a function definition +is itself a compound command. As a consequence, aliases +defined in a function are not available until after that +function is executed. To be safe, always put +alias definitions on a separate line, and do not use @code{alias} +in compound commands. + +Note that for almost every purpose, aliases are superseded by +shell functions. + +@node Alias Builtins +@subsection Alias Builtins + +@table @code + +@item alias +@btindex alias +@example +alias [@code{-p}] [@var{name}[=@var{value}] @dots{}] +@end example + +Without arguments or with the @samp{-p} option, @code{alias} prints +the list of aliases on the standard output in a form that allows +them to be reused as input. +If arguments are supplied, an alias is defined for each @var{name} +whose @var{value} is given. If no @var{value} is given, the name +and value of the alias is printed. + +@item unalias +@btindex unalias +@example +unalias [-a] [@var{name} @dots{} ] +@end example + +Remove each @var{name} from the list of aliases. If @samp{-a} is +supplied, all aliases are removed. +@end table + +@node Bash Features +@chapter Bash Features + +This section describes features unique to Bash. + +@menu +* Invoking Bash:: Command line options that you can give + to Bash. +* Bash Startup Files:: When and how Bash executes scripts. +* Is This Shell Interactive?:: Determining the state of a running Bash. +* Bash Builtins:: Table of builtins specific to Bash. +* The Set Builtin:: This builtin is so overloaded it + deserves its own section. +* Bash Conditional Expressions:: Primitives used in composing expressions for + the @code{test} builtin. +* Bash Variables:: List of variables that exist in Bash. +* Shell Arithmetic:: Arithmetic on shell variables. +* Arrays:: Array Variables +* Printing a Prompt:: Controlling the PS1 string. +* The Restricted Shell:: A more controlled mode of shell execution. +* Bash POSIX Mode:: Making Bash behave more closely to what + the POSIX standard specifies. +@end menu + +@node Invoking Bash +@section Invoking Bash + +@example +bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}] +bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] -c @var{string} [@var{argument} @dots{}] +bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}] +@end example + +In addition to the single-character shell command-line options +(@pxref{The Set Builtin}), there are several multi-character +options that you can use. These options must appear on the command +line before the single-character options in order for them +to be recognized. + +@table @code +@item --dump-strings +Equivalent to @samp{-D}. + +@item --help +Display a usage message on standard output and exit sucessfully. + +@item --login +Make this shell act as if it were directly invoked by login. +This is equivalent to @samp{exec -l bash} but can be issued from +another shell, such as @code{csh}. If you wanted to replace your +current login shell with a Bash login shell, you would say +@samp{exec bash --login}. + +@item --noediting +Do not use the @sc{GNU} Readline library (@pxref{Command Line Editing}) +to read interactive command lines. + +@item --noprofile +Don't load the system-wide startup file @file{/etc/profile} +or any of the personal initialization files +@file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile} +when Bash is invoked as a login shell. + +@item --norc +Don't read the @file{~/.bashrc} initialization file in an +interactive shell. This is on by default if the shell is +invoked as @code{sh}. + +@item --posix +Change the behavior of Bash where the default operation differs +from the @sc{POSIX} 1003.2 standard to match the standard. This +is intended to make Bash behave as a strict superset of that +standard. @xref{Bash POSIX Mode}, for a description of the Bash +@sc{POSIX} mode. + +@item --rcfile @var{filename} +Execute commands from @var{filename} (instead of @file{~/.bashrc}) +in an interactive shell. + +@item --restricted +Make the shell a restricted shell (@pxref{The Restricted Shell}). + +@item --verbose +Equivalent to @samp{-v}. + +@item --version +Show version information for this instance of +Bash on the standard output and exit successfully. + +@end table + +There are several single-character options you can give which are +not available with the @code{set} builtin. + +@table @code +@item -c @var{string} +Read and execute commands from @var{string} after processing the +options, then exit. Any remaining arguments are assigned to the +positional parameters, starting with @code{$0}. + +@item -i +Force the shell to run interactively. + +@item -r +Make the shell restricted. + +@item -s +If this flag is present, or if no arguments remain after option +processing, then commands are read from the standard input. +This option allows the positional parameters to be set +when invoking an interactive shell. + +@item -D +A list of all double-quoted strings preceded by @samp{$} +is printed on the standard ouput. +These are the strings that +are subject to language translation when the current locale +is not @code{C} or @code{POSIX} (@pxref{Locale Translation}). +This implies the @samp{-n} option; no commands will be executed. + +@end table + +@cindex interactive shell +An @emph{interactive} shell is one whose input and output are both +connected to terminals (as determined by @code{isatty()}), or one +started with the @samp{-i} option. + +If arguments remain after option processing, and neither the +@samp{-c} nor the @samp{-s} +option has been supplied, the first argument is assumed to +be the name of a file containing shell commands (@pxref{Shell Scripts}). +When Bash is invoked in this fashion, @code{$0} +is set to the name of the file, and the positional parameters +are set to the remaining arguments. +Bash reads and executes commands from this file, then exits. +Bash's exit status is the exit status of the last command executed +in the script. If no commands are executed, the exit status is 0. + +@node Bash Startup Files +@section Bash Startup Files +@cindex startup files + +This section describs how bash executes its startup files. +If any of the files exist but cannot be read, bash reports an error. +Tildes are expanded in file names as described above under +Tilde Expansion (@pxref{Tilde Expansion}). + +When Bash is invoked as a login shell, it first reads and +executes commands from the file @file{/etc/profile}, if that file exists. +After reading that file, it looks for @file{~/.bash_profile}, +@file{~/.bash_login}, and @file{~/.profile}, in that order, and reads +and executes commands from the first one that exists and is readable. +The @samp{--noprofile} option may be used when the shell is started to +inhibit this behavior. + +When a login shell exits, Bash reads and executes commands from +the file @file{~/.bash_logout}, if it exists. + +When an interactive shell that is not a login shell is started, Bash +reads and executes commands from @file{~/.bashrc}, if that file exists. +This may be inhibited by using the @samp{--norc} option. +The @samp{--rcfile @var{file}} option will force Bash to read and +execute commands from @var{file} instead of @file{~/.bashrc}. + +So, typically, your @file{~/.bash_profile} contains the line +@example +@code{if [ -f @file{~/.bashrc} ]; then . @file{~/.bashrc}; fi} +@end example +@noindent +after (or before) any login-specific initializations. + +When Bash is started non-interactively, to run a shell script, +for example, it looks for the variable @code{BASH_ENV} in the environment, +expands its value if it appears there, and uses the expanded value as +the name of a file to read and execute. Bash behaves as if the +following command were executed: +@example +@code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi} +@end example +@noindent +but the value of the @code{PATH} variable is not used to search for the +file name. + +If Bash is invoked with the name @code{sh}, it tries to mimic the +startup behavior of historical versions of @code{sh} as closely as +possible, while conforming to the @sc{POSIX} standard as well. + +When invoked as a login shell, it first attempts to read and execute +commands from @file{/etc/profile} and @file{~/.profile}, in that order. +The @samp{--noprofile} option may be used to inhibit this behavior. +When invoked as an interactive shell with the name @code{sh}, +@code{bash} looks for the variable @code{ENV}, +expands its value if it is defined, and uses the +expanded value as the name of a file to read and execute. +Since a shell invoked as @code{sh} does not attempt to read and execute +commands from any other startup files, the @samp{--rcfile} option has +no effect. +A non-interactive shell invoked with the name @code{sh} does not attempt +to read any startup files. + +When invoked as @code{sh}, Bash enters @sc{POSIX} mode after +the startup files are read. + +When Bash is started in @sc{POSIX} mode, as with the +@samp{--posix} command line option, it follows the @sc{POSIX} standard +for startup files. +In this mode, the @code{ENV} variable is expanded and commands are read +and executed from the file whose name is the expanded value. +No other startup files are read. +This is done by both interactive and non-interactive shells. + +Bash attempts to determine when it is being run by the remote shell +daemon, usually @code{rshd}. If Bash determines it is being run by +rshd, it reads and executes commands from @file{~/.bashrc}, if that +file exists and is readable. +It will not do this if invoked as @code{sh}. +The @samp{--norc} option may be used to inhibit this behavior, and the +@samp{--rcfile} option may be used to force another file to be read, but +rshd does not generally invoke the shell with those options or allow +them to be specified. + +@node Is This Shell Interactive? +@section Is This Shell Interactive? +@cindex interactive shell + +As defined in @ref{Invoking Bash}, an interactive shell +is one whose input and output are both +connected to terminals (as determined by @code{isatty(3)}), +or one started with the @samp{-i} option. + +You may wish to determine within a startup script whether Bash is +running interactively or not. To do this, examine the variable +@code{$PS1}; it is unset in non-interactive shells, and set in +interactive shells. Thus: + +@example +if [ -z "$PS1" ]; then + echo This shell is not interactive +else + echo This shell is interactive +fi +@end example + +@node Bash Builtins +@section Bash Builtin Commands + +This section describes builtin commands which are unique to +or have been extended in Bash. + +@table @code + +@item bind +@btindex bind +@example +bind [-m @var{keymap}] [-lpsvPSV] [-q @var{name}] [-r @var{keyseq}] +bind [-m @var{keymap}] -f @var{filename} +bind [-m @var{keymap}] @var{keyseq:function-name} +@end example + +Display current Readline (@pxref{Command Line Editing}) +key and function bindings, or +bind a key sequence to a Readline function or macro. The +binding syntax accepted is identical to that of +@file{.inputrc} (@pxref{Readline Init File}), +but each binding must be passed as a separate argument: e.g., +@samp{"\C-x\C-r":re-read-init-file}. +Options, if supplied, have the following meanings: + +@table @code +@item -m @var{keymap} +Use @var{keymap} as the keymap to be affected by +the subsequent bindings. Acceptable @var{keymap} +names are +@code{emacs}, +@code{emacs-standard}, +@code{emacs-meta}, +@code{emacs-ctlx}, +@code{vi}, +@code{vi-command}, and +@code{vi-insert}. +@code{vi} is equivalent to @code{vi-command}; +@code{emacs} is equivalent to @code{emacs-standard}. + +@item -l +List the names of all Readline functions + +@item -p +Display Readline function names and bindings in such a way that they +can be re-read + +@item -P +List current Readline function names and bindings + +@item -v +Display Readline variable names and values in such a way that they +can be re-read + +@item -V +List current Readline variable names and values + +@item -s +Display Readline key sequences bound to macros and the strings they output +in such a way that they can be re-read + +@item -S +Display Readline key sequences bound to macros and the strings they output + +@item -f @var{filename} +Read key bindings from @var{filename} + +@item -q +Query about which keys invoke the named @var{function} + +@item -r @var{keyseq} +Remove any current binding for @var{keyseq} + +@end table + +@item builtin +@btindex 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 command +@btindex command +@example +command [-pVv] @var{command} [@var{args} @dots{}] +@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 @samp{command ls}. The +@samp{-p} option means to use a default value for @code{$PATH} +that is guaranteed to find all of the standard utilities. + +If either the @samp{-V} or @samp{-v} option is supplied, a +description of @var{command} is printed. The @samp{-v} option +causes a single word indicating the command or file name used to +invoke @var{command} to be printed; the @samp{-V} option produces +a more verbose description. + +@item declare +@btindex declare +@example +declare [-afFrxi] [-p] [@var{name}[=@var{value}]] +@end example + +Declare variables and give them attributes. If no @var{name}s +are given, then display the values of variables instead. + +The @samp{-p} option will display the attributes and values of each +@var{name}. When @samp{-p} is used, additional options are ignored. +The @samp{-F} option inhibits the display of function definitions; +only the function name and attributes are printed. @samp{-F} implies +@samp{-f}. The following options can be used to restrict output +to variables with the specified attributes or to give variables +attributes: + +@table @code +@item -a +Each @var{name} is an array variable (@pxref{Arrays}). + +@item -f +Use function names only. + +@item -i +The variable is to be treated as +an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is +performed when the variable is assigned a value. + +@item -r +Make @var{name}s readonly. These names cannot then be assigned values +by subsequent assignment statements. + +@item -x +Mark each @var{name} for export to subsequent commands via +the environment. +@end table + +Using @samp{+} +instead of @samp{-} turns off the attribute instead. When used in +a function, @code{declare} makes each @var{name} local, as with the +@code{local} command. + +@item echo +@btindex echo +@example +echo [-neE] [arg @dots{}] +@end example +Output the @code{arg}s, separated by spaces, terminated with a +newline. The return status is always 0. If @samp{-n} is +specified, the trailing newline is suppressed. If the @samp{-e} +option is given, interpretation of the following backslash-escaped +characters is enabled. The @samp{-E} option disables the interpretation +of these escape characters, even on systems where they are interpreted +by default. +@code{echo} interprets the following escape sequences: +@table @code +@item \a +alert (bell) +@item \b +backspace +@item \c +suppress trailing newline +@item \e +escape +@item \f +form feed +@item \n +new line +@item \r +carriage return +@item \t +horizontal tab +@item \v +vertical tab +@item \\ +backslash +@item \nnn +the character whose ASCII code is @code{nnn} (octal) +@end table + +@item enable +@btindex enable +@example +enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}] +@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 @samp{-n} is used, the @var{name}s become disabled. Otherwise +@var{name}s are enabled. For example, to use the @code{test} binary +found via @code{$PATH} instead of the shell builtin version, type +@samp{enable -n test}. + +If the @samp{-p} option is supplied, or no @var{name} arguments appear, +a list of shell builtins is printed. With no other arguments, the list +consists of all enabled shell builtins. +The @samp{-a} option means to list +each builtin with an indication of whether or not it is enabled. + +The @samp{-f} option means to load the new builtin command @var{name} +from shared object @var{filename}, on systems that support dynamic loading. +The @samp{-d} option will delete a builtin loaded with @samp{-f}. +If there are no options, a list of the shell builtins is displayed. +The @samp{-s} option restricts @code{enable} to the @sc{POSIX.2} special +builtins. If @samp{-s} is used with @samp{-f}, the new builtin becomes +a special builtin. + +@item help +@btindex help +@example +help [@var{pattern}] +@end example +Display helpful information about builtin commands. If +@var{pattern} is specified, @code{help} gives detailed help +on all commands matching @var{pattern}, otherwise a list of +the builtins is printed. + +@item local +@btindex local +@example +local @var{name}[=@var{value}] +@end example +For each argument, 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 logout +@btindex logout +@example +logout [@var{n}] +@end example +Exit a login shell, returning a status of @var{n} to the shell's +parent. + +@item read +@btindex read +@example +read [-a @var{aname}] [-p @var{prompt}] [-er] [@var{name} @dots{}] +@end example +One line is read from the standard input, and the first word +is assigned to the first +@var{name}, the second word to the second @var{name}, +and so on, with leftover words assigned to the last @var{name}. +Only the characters in the value of the @code{IFS} variable +are recognized as word delimiters. If no names +are supplied, the line read is assigned to the variable @code{REPLY}. +The return code is zero, unless end-of-file is encountered. Options, +if supplied, have the following meanings: + +@table @code +@item -r +If this option is given, a backslash-newline pair is not ignored, and +the backslash is considered to be part of the line. + +@item -p @var{prompt} +Display @code{prompt}, without a +trailing newline, before attempting to read any input. The prompt +is displayed only if input is coming from a terminal. + +@item -a @var{aname} +The words are assigned to +sequential indices of the array variable @var{aname}, starting at 0. + +@item -e +Readline (@pxref{Command Line Editing}) +is used to obtain the line. +@end table + +@item shopt +@btindex shopt +@example +shopt [-pqsu] [-o] [@var{optname} @dots{}] +@end example +Toggle the values of variables controlling optional shell behavior. +With no options, or with the @samp{-p} +option, a list of all settable options is displayed, with +an indication of whether or not each is set. Other options have +the following meanings: + +@table @code +@item -s +Enable (set) each @var{optname} + +@item -u +Disable (unset) each @var{optname}. + +@item -q +Suppresses normal output; the return status +indicates whether the @var{optname} is set or unset. +If multiple @var{optname} arguments are given with @samp{-q}, +the return status is zero if all @var{optnames} are enabled; +non-zero otherwise. + +@item -o +Restricts the values of +@var{optname} to be those defined for the @samp{-o} option to the +@code{set} builtin (@pxref{The Set Builtin}). +@end table + +If either of +@samp{-s} or @samp{-u} +is used with no @var{optname} arguments, the display is limited to +those options which are set or unset, respectively. + +Unless otherwise noted, the @code{shopt} options are disabled (off) +by default. + +The return status when listing options is zero if all @var{optnames} +are enabled, non-zero otherwise. When setting or unsetting options, +the return status is zero unless an @var{optname} is not a legal shell +option. + +The list of @code{shopt} options is: +@table @code +@item cdable_vars +If this is set, an argument to the @code{cd} +builtin command that +is not a directory is assumed to be the name of a variable whose +value is the directory to change to. + +@item cdspell +If set, minor errors in the spelling of a directory component in a +@code{cd} command will be corrected. +The errors checked for are transposed characters, +a missing character, and a character too many. +If a correction is found, the corrected path is printed, +and the command proceeds. +This option is enabled by default, but is only used by interactive shells. + +@item checkhash +If this is set, Bash checks that a command found in the hash +table exists before trying to execute it. If a hashed command no +longer exists, a normal path search is performed. + +@item checkwinsize +If set, Bash checks the window size after each command +and, if necessary, updates the values of +@code{LINES} and @code{COLUMNS}. + +@item cmdhist +If set, Bash +attempts to save all lines of a multiple-line +command in the same history entry. This allows +easy re-editing of multi-line commands. + +@item dotglob +If set, Bash includes filenames beginning with a `.' in +the results of filename expansion. + +@item execfail +If this is set, a non-interactive shell will not exit if +it cannot execute the file specified as an argument to the @code{exec} +builtin command. An interactive shell does not exit if @code{exec} +fails. + +@item histappend +If set, the history list is appended to the file named by the value +of the @code{HISTFILE} +variable when the shell exits, rather than overwriting the file. + +@item histreedit +If set, and Readline +is being used, a user is given the opportunity to re-edit a +failed history substitution. + +@item histverify +If set, and Readline +is being used, the results of history substitution are not immediately +passed to the shell parser. Instead, the resulting line is loaded into +the Readline editing buffer, allowing further modification. + +@item hostcomplete +If set, and Readline is being used, Bash will attempt to perform +hostname completion when a word beginning with @samp{@@} is being +completed (@pxref{Commands For Completion}). + +@item interactive_comments +Allow a word beginning with @samp{#} +to cause that word and all remaining characters on that +line to be ignored in an interactive shell. +This option is enabled by default. + +@item lithist +If enabled, and the @code{cmdhist} +option is enabled, multi-line commands are saved to the history with +embedded newlines rather than using semicolon separators where possible. + +@item mailwarn +If set, and a file that Bash is checking for mail has been +accessed since the last time it was checked, the message +@code{"The mail in @var{mailfile} has been read"} is displayed. + +@item nullglob +If set, Bash allows filename patterns which match no +files to expand to a null string, rather than themselves. + +@item promptvars +If set, prompt strings undergo variable and parameter expansion after +being expanded (@pxref{Printing a Prompt}). +This option is enabled by default. + +@item shift_verbose +If this is set, the @code{shift} +builtin prints an error message when the shift count exceeds the +number of positional parameters. + +@item sourcepath +If set, the @code{source} builtin uses the value of @code{PATH} +to find the directory containing the file supplied as an argument. +This is enabled by default. +@end table + +@item type +@btindex type +@example +type [-all] [-type | -path] [@var{name} @dots{}] +@end example +For each @var{name}, indicate how it would be interpreted if used as a +command name. + +If the @samp{-type} flag is used, @code{type} returns a single word +which is one of @samp{alias}, @samp{function}, @samp{builtin}, +@samp{file} or @samp{keyword}, +if @var{name} is an alias, shell function, shell builtin, +disk file, or shell reserved word, respectively. +If the @var{name} is not found, then nothing is printed, and +@code{type} returns a failure status. + +If the @samp{-path} flag is used, @code{type} either returns the name +of the disk file that would be executed, or nothing if @samp{-type} +would not return @samp{file}. + +If the @samp{-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 @samp{-path} flag is not also used. + +@code{type} accepts @samp{-a}, @samp{-t}, and @samp{-p} as equivalent to +@samp{-all}, @samp{-type}, and @samp{-path}, respectively. + +@item ulimit +@btindex ulimit +@example +ulimit [-acdflmnpstuvSH] [@var{limit}] +@end example +@code{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 -S +change and report the soft limit associated with a resource. + +@item -H +change and report the hard limit associated with a resource. + +@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 -f +the maximum size of files created by the shell. + +@item -l +The maximum size that may be locked into memory. + +@item -m +the maximum resident set size. + +@item -n +the maximum number of open file descriptors. + +@item -p +the pipe buffer size. + +@item -s +the maximum stack size. + +@item -t +the maximum amount of cpu time in seconds. + +@item -u +the maximum number of processes available to a single user. + +@item -v +the maximum amount of virtual memory available to the process. + +@end table + +If @var{limit} is given, it is the new value of the specified resource. +Otherwise, the current value of the soft limit for the specified resource +is printed, unless the @samp{-H} option is supplied. +When setting new limits, if neither @samp{-H} nor @samp{-S} is supplied, +both the hard and soft limits are set. +If no option is given, then @samp{-f} is assumed. Values are in 1024-byte +increments, except for @samp{-t}, which is in seconds, @samp{-p}, +which is in units of 512-byte blocks, and @samp{-n} and @samp{-u}, which +are unscaled values. + +@end table + +@node The Set Builtin +@section The Set Builtin + +This builtin is so overloaded that it deserves its own section. + +@table @code +@item set +@btindex set +@example +set [-abefhkmnptuvxdBCHP] [-o @var{option}] [@var{argument} @dots{}] +@end example + +@table @code +@item -a +Mark variables which are modified or created for export. + +@item -b +Cause the status of terminated background jobs to be reported +immediately, rather than before printing the next primary prompt. + +@item -e +Exit immediately if a simple command exits with a non-zero status. + +@item -f +Disable file name generation (globbing). + +@item -h +Locate and remember (hash) commands as they are looked up for execution. + +@item -k +All arguments in the form of assignment statements are placed +in the environment for a command, not just those that precede +the command name. + +@item -m +Job control is enabled (@pxref{Job Control}). + +@item -n +Read commands but do not execute them. + +@item -o @var{option-name} + +Set the flag corresponding to @var{option-name}: + +@table @code +@item allexport +same as @code{-a}. + +@item braceexpand +same as @code{-B}. + +@item emacs +use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}). + +@item errexit +same as @code{-e}. + +@item hashall +same as @code{-h}. + +@item histexpand +same as @code{-H}. + +@item history +Enable command history, as described in @ref{Bash History Facilities}. +This option is on by default in interactive shells. + +@item ignoreeof +the shell will not exit upon reading EOF. + +@item keyword +same as @code{-k}. + +@item monitor +same as @code{-m}. + +@item noclobber +same as @code{-C}. + +@item noexec +same as @code{-n}. + +@item noglob +same as @code{-f}. + +@item notify +same as @code{-b}. + +@item nounset +same as @code{-u}. + +@item onecmd +same as @code{-t}. + +@item physical +same as @code{-P}. + +@item posix +change the behavior of Bash where the default operation differs +from the @sc{POSIX} 1003.2 standard to match the standard. This +is intended to make Bash behave as a strict superset of that +standard. + +@item privileged +same as @code{-p}. + +@item verbose +same as @code{-v}. + +@item vi +use a @code{vi}-style line editing interface. + +@item xtrace +same as @code{-x}. +@end table + +@item -p +Turn on privileged mode. +In this mode, the @code{$ENV} +file is not processed, and shell functions +are not inherited from the environment. This is enabled automatically +on startup if the effective user (group) id is not equal to the real +user (group) id. Turning this option off causes the effective user +and group ids to be set to the real user and group ids. + +@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 -B +The shell will perform brace expansion (@pxref{Brace Expansion}). +This option is on by default. + +@item -C +Disallow output redirection to existing files. + +@item -H +Enable @samp{!} style history substitution (@pxref{History Interaction}). +This flag is on by default for interactive shells. + +@item -P +If set, do not follow symbolic links when performing commands such as +@code{cd} which change the current directory. The physical directory +is used instead. By default, Bash follows +the logical chain of directories when performing commands +which change the current directory. + +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{set -P} is on, then: +@example +$ cd /usr/sys; echo $PWD +/usr/local/sys +$ cd ..; pwd +/usr/local +@end example + +@item -- +If no arguments follow this flag, then the positional parameters are +unset. Otherwise, the positional parameters are set to the +@var{arguments}, even if some of them begin with a @samp{-}. + +@item - +Signal the end of options, cause all remaining @var{arguments} +to be assigned to the positional parameters. The @samp{-x} +and @samp{-v} options are turned off. +If there are no arguments, the positional parameters remain unchanged. +@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 N @var{arguments} are positional parameters and are +assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. If +no arguments are given, all shell variables are printed. +@end table + +@node Bash Conditional Expressions +@section Bash Conditional Expressions +@cindex expressions, conditional + +Conditional expressions are used by the @code{test} and @code{[} builtins. + +Expressions may be unary or binary. Unary +expressions are often used to examine the status of a file. There +are string operators and numeric comparison operators as well. Each +operator and operand must be a separate argument. If @var{file} +is of the form @file{/dev/fd/@var{N}}, then file descriptor @var{N} is +checked. Expressions are composed of the following primaries: + +@table @code +@item -b @var{file} +True if @var{file} exists and is a block special file. + +@item -c @var{file} +True if @var{file} exists and is a character special file. + +@item -d @var{file} +True if @var{file} exists and is a directory. + +@item -e @var{file} +True if @var{file} exists. + +@item -f @var{file} +True if @var{file} exists and is a regular file. + +@item -g @var{file} +True if @var{file} exists and is set-group-id. + +@item -k @var{file} +True if @var{file} has its "sticky" bit set. + +@item -L @var{file} +True if @var{file} exists and is a symbolic link. + +@item -p @var{file} +True if @var{file} exists and is a named pipe. + +@item -r @var{file} +True if @var{file} exists and is readable. + +@item -s @var{file} +True if @var{file} exists and has a size greater than zero. + +@item -S @var{file} +True if @var{file} exists and is a socket. + +@item -t @var{fd} +True if @var{fd} is opened on a terminal. + +@item -u @var{file} +True if @var{file} exists and its set-user-id bit is set. + +@item -w @var{file} +True if @var{file} exists and is writable. + +@item -x @var{file} +True if @var{file} exists and is executable. + +@item -O @var{file} +True if @var{file} exists and is owned by the effective user id. + +@item -G @var{file} +True if @var{file} exists and is owned by the effective group id. + +@item @var{file1} -nt @var{file2} +True if @var{file1} is newer (according to +modification date) than @var{file2}. + +@item @var{file1} -ot @var{file2} +True if @var{file1} is older than @var{file2}. + +@item @var{file1} -ef @var{file2} +True if @var{file1} and @var{file2} have the same device and +inode numbers. + +@item -o @var{optname} +True if shell option @var{optname} is enabled. +The list of options appears in the description of the @samp{-o} +option to the @code{set} builtin (@pxref{The Set Builtin}). + +@item -z @var{string} +True if the length of @var{string} is zero. + +@item -n @var{string} +@itemx @var{string} +True if the length of @var{string} is non-zero. + +@item @var{string1} = @var{string2} +True if the strings are equal. @samp{==} may be used in place of +@samp{=}. + +@item @var{string1} != @var{string2} +True if the strings are not equal. + +@item @var{string1} < @var{string2} +True if @var{string1} sorts before @var{string2} lexicographically. + +@item @var{string1} > @var{string2} +True if @var{string1} sorts after @var{string2} lexicographically. + +@item ! @var{expr} +True if @var{expr} is false. + +@item @var{expr1} -a @var{expr2} +True if both @var{expr1} and @var{expr2} are true. + +@item @var{expr1} -o @var{expr2} +True if either @var{expr1} and @var{expr2} is true. + +@item @var{arg1} OP @var{arg2} +@code{OP} is one of +@samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}. +These arithmetic binary operators return true if @var{arg1} +is equal to, not equal to, less than, less than or equal to, +greater than, or greater than or equal to @var{arg2}, +respectively. @var{Arg1} and @var{arg2} +may be positive or negative integers. + +@end table + +The Bash @code{test} and @code{[} builtins evaluate conditional +expressions using a set of rules based on the number of arguments. +These are the rules: + +@table @asis +@item 0 arguments +The expression is false. +@item 1 argument +The expression is true if and only if the argument is not null. +@item 2 arguments +If the first argument is @samp{!}, the expression is true if and +only if the second argument is null. If the first argument is +one of the listed unary operators, the expression is true if the +unary test is true. If the first argument is not a legal unary +operator, the expression is false. +@item 3 arguments +If the first argument is @samp{!}, the value is the negation of +the two-argument test using the second and third arguments. +If the second argument is one of the binary operators, the result +of the expression is the result of the binary test using the first +and third arguments as operands. +If the first argument is exactly @samp{(} and the third argument is +exactly @samp{)}, the result is the one-argument test of the second +argument. +Otherwise, the expression is false. +The @samp{-a} and @samp{-o} operators are considered binary operators +in this case. +@item 4 arguments +If the first argument is @samp{!}, the result is the negation of +the three-argument expression composed of the remaining arguments. +Otherwise, the expression is parsed and evaluated according to +precedence. @samp{-a} has a higher precedence than @samp{-o}. +@item 5 or more arguments +The expression is parsed and evaluated according to precedence, +with @samp{-a} having a higher precedence than @samp{-o}. +@end table + +@node Bash Variables +@section Bash Variables + +These variables are set or used by Bash, but other shells +do not normally treat them specially. + +@vtable @code + +@item TIMEFORMAT +The value of this parameter is used as a format string specifying +how the timing information for pipelines prefixed with the @code{time} +reserved word should be displayed. +The @samp{%} character introduces an +escape sequence that is expanded to a time value or other +information. +The escape sequences and their meanings are as +follows; the braces denote optional portions. + +@table @code + +@item %% +A literal @samp{%}. + +@item %[@var{p}][l]R +The elapsed time in seconds. + +@item %[@var{p}][l]U +The number of CPU seconds spent in user mode. + +@item %[@var{p}][l]S +The number of CPU seconds spent in system mode. + +@item %P +The CPU percentage, computed as (%U + %S) / %R. +@end table + +The optional @var{p} is a digit specifying the precision, the number of +fractional digits after a decimal point. +A value of 0 causes no decimal point or fraction to be output. +At most three places after the decimal point may be specified; values +of @var{p} greater than 3 are changed to 3. +If @var{p} is not specified, the value 3 is used. + +The optional @code{l} specifies a longer format, including minutes, of +the form @var{MM}m@var{SS}.@var{FF}s. +The value of @var{p} determines whether or not the fraction is included. + +If this variable is not set, bash acts as if it had the value +@code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}. +If the value is null, no timing information is displayed. +A trailing newline is added when the format string is displayed. + +@item HISTCONTROL +Set to a value of @samp{ignorespace}, it means don't enter lines which +begin with a space or tab into the history list. Set to a value +of @samp{ignoredups}, it means don't enter lines which match the last +entered line. A value of @samp{ignoreboth} combines the two options. +Unset, or set to any other value than those above, means to save +all lines on the history list. + +@item HISTIGNORE +A colon-separated list of patterns used to decide which command +lines should be saved on the history list. Each pattern is +anchored at the beginning of the line and must fully specify the +line (no implicit @samp{*} is appended). Each pattern is tested +against the line after the checks specified by @code{HISTCONTROL} +are applied. In addition to the normal shell pattern matching +characters, @samp{&} matches the previous history line. @samp{&} +may be escaped using a backslash. The backslash is removed +before attempting a match. + +@code{HISTIGNORE} subsumes the function of @code{HISTCONTROL}. A +pattern of @samp{&} is identical to @code{ignoredups}, and a +pattern of @samp{[ ]*} is identical to @code{ignorespace}. +Combining these two patterns, separating them with a colon, +provides the functionality of @code{ignoreboth}. + +@item HISTFILE +The name of the file to which the command history is saved. The +default is @file{~/.bash_history}. + +@item HISTSIZE +If set, this is the maximum number of commands to remember in the +history. + +@item HISTFILESIZE +The maximum number of lines contained in the history file. When this +variable is assigned a value, the history file is truncated, if +necessary, to contain no more than that number of lines. The default +value is 500. The history file is also truncated to this size after +writing it when an interactive shell exits. + +@item histchars +Up to three characters which control history expansion, quick +substitution, and tokenization (@pxref{History Interaction}). +The first character is the +@dfn{history-expansion-char}, that is, the character which signifies the +start of a history expansion, normally @samp{!}. The second character is the +character which signifies `quick substitution' when seen as the first +character on a line, normally @samp{^}. 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 @samp{#}. The history +comment character causes history substitution to be skipped for the +remaining words on the line. It does not necessarily cause the shell +parser to treat the rest of the line as a comment. + +@item HISTCMD +The history number, or index in the history list, of the current +command. If @code{HISTCMD} is unset, it loses its special properties, +even if it is subsequently reset. + +@item HOSTFILE +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 attempt to complete a +hostname, Bash will add the contents of the new file to the already +existing database. + +@item MAILCHECK +How often (in seconds) that the shell should check for mail +in the files specified in @code{MAILPATH}. + +@item PROMPT_COMMAND +If present, this contains a string which is a command to execute +before the printing of each primary prompt (@code{$PS1}). + +@item UID +The numeric real user id of the current user. + +@item EUID +The numeric effective user id of the current user. + +@item PPID +The process id of the shell's parent process. + +@item HOSTNAME +The name of the current host. + +@item HOSTTYPE +A string describing the machine Bash is running on. + +@item OSTYPE +A string describing the operating system Bash is running on. + +@item MACHTYPE +A string that fully describes the system type on which Bash +is executing, in the standard GNU @var{cpu-company-system} format. + +@item SHELLOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the @samp{-o} option to the +@code{set} builtin command (@pxref{The Set Builtin}). +The options appearing in @code{SHELLOPTS} are those reported +as @samp{on} by @samp{set -o}. +If this variable is in the environment when Bash +starts up, each shell option in the list will be enabled before +reading any startup files. This variable is readonly. + +@item FIGNORE +A colon-separated list of suffixes to ignore when performing +filename completion. +A file name whose suffix matches one of the entries in +@code{FIGNORE} +is excluded from the list of matched file names. A sample +value is @samp{.o:~} + +@item GLOBIGNORE +A colon-separated list of patterns defining the set of filenames to +be ignored by filename expansion. +If a filename matched by a filename expansion pattern also matches one +of the patterns in @code{GLOBIGNORE}, it is removed from the list +of matches. + +@item DIRSTACK +An array variable (@pxref{Arrays}) +containing the current contents of the directory stack. +Directories appear in the stack in the order they are displayed by the +@code{dirs} builtin. +Assigning to members of this array variable may be used to modify +directories already in the stack, but the @code{pushd} and @code{popd} +builtins must be used to add and remove directories. +Assignment to this variable will not change the current directory. +If @code{DIRSTACK} is unset, it loses its special properties, even if +it is subsequently reset. + +@item PIPESTATUS +An array variable (@pxref{Arrays}) +containing a list of exit status values from the processes +in the most-recently-executed foreground pipeline (which may +contain only a single command). + +@item INPUTRC +The name of the Readline startup file, overriding the default +of @file{~/.inputrc}. + +@item BASH +The full filename used to execute the current instance of Bash. + +@item BASH_VERSION +The version number of the current instance of Bash. + +@item BASH_VERSINFO +An array variable whose members hold version information for this +instance of Bash. +The values assigned to the array members are as follows: + +@table @code + +@item BASH_VERSINFO[0] +The major version number (the @var{release}). + +@item BASH_VERSINFO[1] +The minor version number (the @var{version}). + +@item BASH_VERSINFO[2] +The patch level. + +@item BASH_VERSINFO[3] +The build version. + +@item BASH_VERSINFO[4] +The release status (e.g., @var{beta1}). + +@item BASH_VERSINFO[5] +The value of @code{MACHTYPE}. + +@end table + +@item SHLVL +Incremented by one each time a new instance of Bash is started. This is +intended to be an account of how deeply your Bash shells are nested. + +@item OPTERR +If set to the value 1, Bash displays error messages +generated by the @code{getopts} builtin command. + +@item LANG +Used to determine the locale category for any category not specifically +selected with a variable starting with @code{LC_}. + +@item LC_ALL +This variable overrides the value of @code{LANG} and any other +@code{LC_} variable specifying a locale category. + +@item LC_MESSAGES +This variable determines the locale used to translate double-quoted +strings preceded by a @samp{$}. + +@item 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 consecutive @code{EOF} characters that can be read as the +first character on an input line +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. + +@end vtable + +@node Shell Arithmetic +@section Shell Arithmetic +@cindex arithmetic, shell + +@menu +* Arithmetic Evaluation:: How shell arithmetic works. +* Arithmetic Expansion:: How to use arithmetic in shell expansions. +* Arithmetic Builtins:: Builtin commands that use shell arithmetic. +@end menu + +Bash includes several mechanisms to evaluate arithmetic expressions +and display the result or use it as part of a command. + +@node Arithmetic Evaluation +@subsection Arithmetic Evaluation +@cindex expressions, arithmetic +@cindex evaluation, arithmetic +@cindex arithmetic evaluation + +The shell allows arithmetic expressions to be evaluated, as one of +the shell expansions or by the @code{let} builtin. + +Evaluation is done in long integers with no check for overflow, +though division by 0 is trapped and flagged as an error. The +following list of operators is grouped into levels of +equal-precedence operators. The levels are listed in order of +decreasing precedence. + +@table @code +@item - + +unary minus and plus + +@item ! ~ +logical and bitwise negation + +@item * / % +multiplication, division, remainder + +@item + - +addition, subtraction + +@item << >> +left and right bitwise shifts + +@item <= >= < > +comparison + +@item == != +equality and inequality + +@item & +bitwise AND + +@item ^ +bitwise exclusive OR + +@item | +bitwise OR + +@item && +logical AND + +@item || +logical OR + +@item expr ? expr : expr +conditional evaluation + +@item = *= /= %= += -= <<= >>= &= ^= |= +assignment +@end table + +Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. +The value of a parameter is coerced to a long integer within +an expression. A shell variable need not have its integer attribute +turned on to be used in an expression. + +Constants with a leading 0 are interpreted as octal numbers. +A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise, +numbers take the form [@var{base}@code{#}]@var{n}, where @var{base} +is a decimal number between 2 and 64 representing the arithmetic +base, and @var{n} is a number in that base. If @var{base} is +omitted, then base 10 is used. +The digits greater than 9 are represented by the lowercase letters, +the uppercase letters, @samp{_}, and @samp{@@}, in that order. +If @var{base} is less than or equal to 36, lowercase and uppercase +letters may be used interchangably to represent numbers between 10 +and 35. + +Operators are evaluated in order of precedence. Sub-expressions in +parentheses are evaluated first and may override the precedence +rules above. + +@node Arithmetic Expansion +@subsection Arithmetic Expansion +@cindex expansion, arithmetic +@cindex arithmetic expansion + +Arithmetic expansion allows the evaluation of an arithmetic expression +and the substitution of the result. The format for arithmetic expansion is: + +@example +$(( @var{expression} )) +@end example + +The expression is treated as if it were within double quotes, but +a double quote inside the braces or parentheses is not treated +specially. All tokens in the expression undergo parameter +expansion, command substitution, and quote removal. Arithmetic +substitutions may be nested. + +The evaluation is performed according to the rules listed above. +If the expression is invalid, Bash +prints a message indicating failure and no substitution occurs. + +@node Arithmetic Builtins +@subsection Arithmetic Builtins + +@table @code + +@item let +@btindex let +@example +let @var{expression} [@var{expression}] +@end example +The @code{let} builtin allows arithmetic to be performed on shell +variables. Each @var{expression} is evaluated according to the +rules given previously (@pxref{Arithmetic Evaluation}). If the +last @var{expression} evaluates to 0, @code{let} returns 1; +otherwise 0 is returned. +@end table + +@node Arrays +@section Arrays +@cindex arrays + +Bash provides one-dimensional array variables. Any variable may be used as +an array; the @code{declare} builtin will explicitly declare an array. +There is no maximum +limit on the size of an array, nor any requirement that members +be indexed or assigned contiguously. Arrays are zero-based. + +An array is created automatically if any variable is assigned to using +the syntax +@example +name[@var{subscript}]=@var{value} +@end example + +@noindent +The @var{subscript} +is treated as an arithmetic expression that must evaluate to a number +greater than or equal to zero. To explicitly declare an array, use +@example +declare -a @var{name} +@end example +@noindent +The syntax +@example +declare -a @var{name}[@var{subscript}] +@end example +@noindent +is also accepted; the @var{subscript} is ignored. Attributes may be +specified for an array variable using the @code{declare} and +@code{readonly} builtins. Each attribute applies to all members of +an array. + +Arrays are assigned to using compound assignments of the form +@example +name=(value@var{1} @dots{} value@var{n}) +@end example +@noindent +where each +@var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If +the optional subscript is supplied, that index is assigned to; +otherwise the index of the element assigned is the last index assigned +to by the statement plus one. Indexing starts at zero. +This syntax is also accepted by the @code{declare} +builtin. Individual array elements may be assigned to using the +@code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above. + +Any element of an array may be referenced using +@code{$@{name[}@var{subscript}@code{]@}}. +The braces are required to avoid +conflicts with the shell's filename expansion operators. If the +@var{subscript} is @samp{@@} or @samp{*}, the word expands to all members +of the array @var{name}. These subscripts differ only when the word +appears within double quotes. If the word is double-quoted, +@code{$@{name[*]@}} expands to a single word with +the value of each array member separated by the first character of the +@code{IFS} variable, and @code{$@{name[@@]@}} expands each element of +@var{name} to a separate word. When there are no array members, +@code{$@{name[@@]@}} expands to nothing. This is analogous to the +expansion of the special parameters @samp{@@} and @samp{*}. +@code{$@{#name[}@var{subscript}@code{]@}} expands to the length of +@code{$@{name[}@var{subscript}@code{]@}}. +If @var{subscript} is @samp{@@} or +@samp{*}, the expansion is the number of elements in the array. +Referencing an array variable without a subscript is equivalent to +referencing element zero. + +The @code{unset} builtin is used to destroy arrays. +@code{unset} @var{name[subscript]} +destroys the array element at index @var{subscript}. +@code{unset} @var{name}, where @var{name} is an array, removes the +entire array. A subscript of @samp{*} or @samp{@@} also removes the +entire array. + +The @code{declare}, @code{local}, and @code{readonly} +builtins each accept a @samp{-a} +option to specify an array. The @code{read} +builtin accepts a @samp{-a} +option to assign a list of words read from the standard input +to an array, and can read values from the standard input into +individual array elements. The @code{set} and @code{declare} +builtins display array values in a way that allows them to be +reused as input. + +@node Printing a Prompt +@section Controlling the Prompt +@cindex prompting + +The value of the variable @code{PROMPT_COMMAND} is examined just before +Bash prints each primary 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 prompt variables: + +@table @code +@item \a +a bell character. +@item \d +the date, in "Weekday Month Date" format (e.g., "Tue May 26"). +@item \e +an escape character. +@item \h +the hostname, up to the first `.'. +@item \H +the hostname. +@item \n +newline. +@item \s +the name of the shell, the basename of @code{$0} (the portion +following the final slash). +@item \t +the time, in 24-hour HH:MM:SS format. +@item \T +the time, in 12-hour HH:MM:SS format. +@item \@@ +the time, in 12-hour am/pm format. +@item \v +the version of Bash (e.g., 2.00) +@item \V +the release of Bash, version + patchlevel (e.g., 2.00.0) +@item \w +the current working directory. +@item \W +the basename of @code{$PWD}. +@item \u +your username. +@item \! +the history number of this command. +@item \# +the command number of this command. +@item \$ +if the effective uid is 0, @code{#}, otherwise @code{$}. +@item \nnn +the character corresponding to the octal number @code{nnn}. +@item \\ +a backslash. +@item \[ +begin a sequence of non-printing characters. This could be used to +embed a terminal control sequence into the prompt. +@item \] +end a sequence of non-printing characters. +@end table + +@node The Restricted Shell +@section The Restricted Shell +@cindex restricted shell + +If Bash is started with the name @code{rbash}, or the +@samp{--restricted} +option is supplied at invocation, the shell becomes restricted. +A restricted shell is used to +set up an environment more controlled than the standard shell. +A restricted shell behaves identically to @code{bash} +with the exception that the following are disallowed: +@itemize @bullet +@item +Changing directories with the @code{cd} builtin. +@item +Setting or unsetting the values of the @code{SHELL} or @code{PATH} +variables. +@item +Specifying command names containing slashes. +@item +Specifying a filename containing a slash as an argument to the @code{.} +builtin command. +@item +Importing function definitions from the shell environment at startup. +@item +Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&}, +@samp{&>}, and @samp{>>} redirection operators. +@item +Using the @code{exec} builtin to replace the shell with another command. +@item +Adding or deleting builtin commands with the +@samp{-f} and @samp{-d} options to the @code{enable} builtin. +@item +Specifying the @samp{-p} option to the @code{command} builtin. +@item +Turning off restricted mode with @samp{set +r}. +@end itemize + +@node Bash POSIX Mode +@section Bash POSIX Mode +@cindex POSIX Mode + +Starting Bash with the @samp{--posix} command-line option or executing +@samp{set -o posix} while Bash is running will cause Bash to conform more +closely to the @sc{POSIX.2} standard by changing the behavior to match that +specified by @sc{POSIX.2} in areas where the Bash default differs. + +The following list is what's changed when `@sc{POSIX} mode' is in effect: + +@enumerate +@item +When a command in the hash table no longer exists, Bash will re-search +@code{$PATH} to find the new location. This is also available with +@samp{shopt -s checkhash}. + +@item +The @samp{>&} redirection does not redirect stdout and stderr. + +@item +The message printed by the job control code and builtins when a job +exits with a non-zero status is `Done(status)'. + +@item +Reserved words may not be aliased. + +@item +The @sc{POSIX.2} @code{PS1} and @code{PS2} expansions of @samp{!} to +the history number and @samp{!!} to @samp{!} are enabled, +and parameter expansion is performed on +the value regardless of the setting of the @code{promptvars} option. + +@item +Interactive comments are enabled by default. (Note that Bash has +them on by default anyway.) + +@item +The @sc{POSIX.2} startup files are executed (@code{$ENV}) rather than +the normal Bash files. + +@item +Tilde expansion is only performed on assignments preceding a command +name, rather than on all assignment statements on the line. + +@item +The default history file is @file{~/.sh_history} (this is the +default value of @code{$HISTFILE}). + +@item +The output of @samp{kill -l} prints all the signal names on a single line, +separated by spaces. + +@item +Non-interactive shells exit if @var{filename} in @code{.} @var{filename} +is not found. + +@item +Redirection operators do not perform filename expansion on the word +in the redirection unless the shell is interactive. + +@item +Function names must be valid shell @code{name}s. That is, they may not +contain characters other than letters, digits, and underscores, and +may not start with a digit. Declaring a function with an illegal name +causes a fatal syntax error in non-interactive shells. + +@item +@sc{POSIX.2} `special' builtins are found before shell functions +during command lookup. + +@item +If a @sc{POSIX.2} special builtin returns an error status, a +non-interactive shell exits. The fatal errors are those listed in +the POSIX.2 standard, and include things like passing incorrect options, +redirection errors, variable assignment errors for assignments preceding +the command name, and so on. + +@ignore +@item +The environment passed to executed commands is not sorted. Neither is +the output of @code{set}. This is not strictly Posix.2 behavior, but +@code{sh} does it this way. @code{ksh} does not. It's not necessary to +sort the environment; no program should rely on it being sorted. +@end ignore + +@item +If the @code{cd} builtin finds a directory to change to +using @code{$CDPATH}, the +value it assigns to the @code{PWD} variable does not contain any +symbolic links, as if @samp{cd -P} had been executed. + +@item +A non-interactive shell exits with an error status if a variable +assignment error occurs when no command name follows the assignment +statements. +A variable assignment error occurs, for example, when trying to assign +a value to a read-only variable. + +@item +A non-interactive shell exits with an error status if the iteration +variable in a @code{for} statement or the selection variable in a +@code{select} statement is a read-only variable. + +@item +Process substitution is not available. + +@item +Assignment statements preceding @sc{POSIX.2} @code{special} builtins +persist in the shell environment after the builtin completes. + +@end enumerate + +There is other @sc{POSIX.2} behavior that Bash does not implement. +Specifically: + +@enumerate +@item +Assignment statements affect the execution environment of all +builtins, not just special ones. +@end enumerate + +@node Job Control +@chapter Job Control + +This chapter disusses what job control is, how it works, and how +Bash allows you to access its facilities. + +@menu +* Job Control Basics:: How job control works. +* Job Control Builtins:: Bash builtin commands used to interact + with job control. +* Job Control Variables:: Variables Bash uses to customize job + control. +@end menu + +@node Job Control Basics +@section Job Control Basics +@cindex job control +@cindex foreground +@cindex background +@cindex suspending jobs + +Job control +refers to the ability to selectively stop (suspend) +the execution of processes and continue (resume) +their execution at a later point. A user typically employs +this facility via an interactive interface supplied jointly +by the system's terminal driver and Bash. + +The shell associates a @var{job} with each pipeline. It keeps a +table of currently executing jobs, which may be listed with the +@code{jobs} command. When Bash starts a job +asynchronously (in the background), it prints a line that looks +like: +@example +[1] 25647 +@end example +@noindent +indicating that this job is job number 1 and that the process @sc{ID} +of the last process in the pipeline associated with this job is +25647. All of the processes in a single pipeline are members of +the same job. Bash uses the @var{job} abstraction as the +basis for job control. + +To facilitate the implementation of the user interface to job +control, the system maintains the notion of a current terminal +process group @sc{ID}. Members of this process group (processes whose +process group @sc{ID} is equal to the current terminal process group +@sc{ID}) receive keyboard-generated signals such as @code{SIGINT}. +These processes are said to be in the foreground. Background +processes are those whose process group @sc{ID} differs from the +terminal's; such processes are immune to keyboard-generated +signals. Only foreground processes are allowed to read from or +write to the terminal. Background processes which attempt to +read from (write to) the terminal are sent a @code{SIGTTIN} +(@code{SIGTTOU}) signal by the terminal driver, which, unless +caught, suspends the process. + +If the operating system on which Bash is running supports +job control, Bash allows you to use it. Typing the +@var{suspend} character (typically @samp{^Z}, Control-Z) while a +process is running causes that process to be stopped and returns +you to Bash. Typing the @var{delayed suspend} character +(typically @samp{^Y}, Control-Y) causes the process to be stopped +when it attempts to read input from the terminal, and control to +be returned to Bash. You may then manipulate the state of +this job, using the @code{bg} command to continue it in the +background, the @code{fg} command to continue it in the +foreground, or the @code{kill} command to kill it. A @samp{^Z} +takes effect immediately, and has the additional side effect of +causing pending output and typeahead to be discarded. + +There are a number of ways to refer to a job in the shell. The +character @samp{%} introduces a job name. Job number @code{n} +may be referred to as @samp{%n}. A job may also be referred to +using a prefix of the name used to start it, or using a substring +that appears in its command line. For example, @samp{%ce} refers +to a stopped @code{ce} job. Using @samp{%?ce}, on the +other hand, refers to any job containing the string @samp{ce} in +its command line. If the prefix or substring matches more than one job, +Bash reports an error. The symbols @samp{%%} and +@samp{%+} refer to the shell's notion of the current job, which +is the last job stopped while it was in the foreground. The +previous job may be referenced using @samp{%-}. In output +pertaining to jobs (e.g., the output of the @code{jobs} command), +the current job is always flagged with a @samp{+}, and the +previous job with a @samp{-}. + +Simply naming a job can be used to bring it into the foreground: +@samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the +background into the foreground. Similarly, @samp{%1 &} resumes +job 1 in the background, equivalent to @samp{bg %1} + +The shell learns immediately whenever a job changes state. +Normally, Bash waits until it is about to print a prompt +before reporting changes in a job's status so as to not interrupt +any other output. If the +the @samp{-b} option to the @code{set} builtin is set, +Bash reports such changes immediately (@pxref{The Set Builtin}). + +If you attempt to exit Bash while jobs are stopped, the +shell prints a message warning you that you have stopped jobs. +You may then use the +@code{jobs} command to inspect their status. If you do this, or +try to exit again immediately, you are not warned again, and the +stopped jobs are terminated. + +@node Job Control Builtins +@section Job Control Builtins + +@table @code + +@item bg +@btindex bg +@example +bg [@var{jobspec}] +@end example +Place @var{jobspec} into the background, as if it had been started +with @samp{&}. If @var{jobspec} is not supplied, the current job +is used. + +@item fg +@btindex fg +@example +fg [@var{jobspec}] +@end example +Bring @var{jobspec} into the foreground and make it the current job. +If @var{jobspec} is not supplied, the current job is used. + +@item jobs +@btindex jobs +@example +jobs [-lpnrs] [@var{jobspec}] +jobs -x @var{command} [@var{jobspec}] +@end example + +The first form lists the active jobs. The options have the +following meanings: + +@table @code +@item -l +List process @sc{ID}s in addition to the normal information + +@item -n +Display information only about jobs that have changed status since +you were last notified of their status. + +@item -p +List only the process @sc{ID} of the job's process group +leader. + +@item -r +Restrict output to running jobs. + +@item -s +Restrict output to stopped jobs. +@end table + +If @var{jobspec} is given, +output is restricted to information about that job. +If @var{jobspec} is not supplied, the status of all jobs is +listed. + +If the @samp{-x} option is supplied, @code{jobs} replaces any +@var{jobspec} found in @var{command} or @var{arguments} with the +corresponding process group @sc{ID}, and executes @var{command}, +passing it @var{argument}s, returning its exit status. + +@item kill +@btindex kill +@example +kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} +kill -l [@var{sigspec}] +@end example +Send a signal specified by @var{sigspec} or @var{signum} to the process +named by @var{jobspec}. @var{sigspec} is either a signal name such as +@code{SIGINT} or a signal number; @var{signum} is a signal number. If +@var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used. +The @samp{-l} option lists the signal names, or the signal name +corresponding to @var{sigspec}. + +@item wait +@btindex wait +@example +wait [@var{jobspec}|@var{pid}] +@end example +Wait until the child process specified by process @sc{ID} @var{pid} or job +specification @var{jobspec} exits and report its exit status. If a job +spec is given, all processes in the job are waited for. If no arguments +are given, all currently active child processes are waited for. + +@item disown +@btindex disown +@example +disown [-h] [@var{jobspec} @dots{}] +@end example +Without options, each @var{jobspec} is removed from the table of +active jobs. +If the @samp{-h} option is given, the job is not removed from the table, +but is marked so that @code{SIGHUP} is not sent to the job if the shell +receives a @code{SIGHUP}. +If @var{jobspec} is not present, the current job is used. + +@item suspend +@btindex suspend +@example +suspend [-f] +@end example +Suspend the execution of this shell until it receives a +@code{SIGCONT} signal. The @samp{-f} option means to suspend +even if the shell is a login shell. + +@end table + +When job control is not active, the @code{kill} and @code{wait} +builtins do not accept @var{jobspec} arguments. They must be +supplied process @sc{ID}s. + +@node Job Control Variables +@section Job Control Variables + +@vtable @code + +@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. +The name of a stopped job, in this context, is the command line +used to start it. If this variable is set to the value @samp{exact}, +the string supplied must match the name of a stopped job exactly; +if set to @samp{substring}, +the string supplied needs to match a substring of the name of a +stopped job. The @samp{substring} value provides functionality +analogous to the @samp{%?} job @sc{ID} (@pxref{Job Control Basics}). +If set to any other value, the supplied string must +be a prefix of a stopped job's name; this provides functionality +analogous to the @samp{%} job @sc{ID}. + +@end vtable + +@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 Installing Bash +@chapter Installing Bash + +This chapter provides basic instructions for installing Bash on +the various supported platforms. The distribution supports nearly every +version of Unix (and, someday, @sc{GNU}). Other independent ports exist for +@sc{OS/2}, Windows 95, and Windows @sc{NT}. + +@menu +* Basic Installation:: Generic installation instructions. + +* Compilers and Options:: How to set special options for various + systems. + +* Compiling For Multiple Architectures:: How to compile Bash for more + than one kind of system from + the same source tree. + +* Installation Names:: How to set the various paths used by the installation. + +* Specifying the System Type:: How to configure Bash for a particular system. + +* Sharing Defaults:: How to share default configuration values among GNU + programs. + +* Operation Controls:: Options recognized by the configuration program. + +* Optional Features:: How to enable and disable optional features when + building Bash. +@end menu + +@node Basic Installation +@section Basic Installation +@cindex installation +@cindex configuration +@cindex Bash installation +@cindex Bash configuration + +These are generic installation instructions for Bash. + +The @code{configure} shell script attempts to guess correct +values for various system-dependent variables used during +compilation. It uses those values to create a @file{Makefile} in +each directory of the package (the top directory, the +@file{builtins} and @file{doc} directories, and the +each directory under @file{lib}). It also creates a +@file{config.h} file containing system-dependent definitions. +Finally, it creates a shell script named @code{config.status} that you +can run in the future to recreate the current configuration, a +file @file{config.cache} that saves the results of its tests to +speed up reconfiguring, and a file @file{config.log} containing +compiler output (useful mainly for debugging @code{configure}). +If at some point +@file{config.cache} contains results you don't want to keep, you +may remove or edit it. + +If you need to do unusual things to compile the package, please +try to figure out how @code{configure} could check whether or not +to do them, and mail diffs or instructions to +@code{bash-maintainers@@prep.ai.mit.edu} so they can be +considered for the next release. + +The file @file{configure.in} is used to create @code{configure} +by a program called Autoconf. You only need +@file{configure.in} if you want to change it or regenerate +@code{configure} using a newer version of Autoconf. If +you do this, make sure you are using Autoconf version 2.9 or +newer. + +The simplest way to compile Bash is: + +@enumerate +@item +@code{cd} to the directory containing the source code and type +@samp{./configure} to configure Bash for your system. If you're +using @code{csh} on an old version of System V, you might need to +type @samp{sh ./configure} instead to prevent @code{csh} from trying +to execute @code{configure} itself. + +Running @code{configure} takes awhile. While running, it prints some +messages telling which features it is checking for. + +@item +Type @samp{make} to compile Bash and build the @code{bashbug} bug +reporting script. + +@item +Optionally, type @samp{make tests} to run the Bash test suite. + +@item +Type @samp{make install} to install @code{bash} and @code{bashbug}. +This will also install the manual pages and Info file. + +@end enumerate + +You can remove the program binaries and object files from the +source code directory by typing @samp{make clean}. To also remove the +files that @code{configure} created (so you can compile Bash for +a different kind of computer), type @samp{make distclean}. + +@node Compilers and Options +@section Compilers and Options + +Some systems require unusual options for compilation or linking +that the @code{configure} script does not know about. You can +give @code{configure} initial values for variables by setting +them in the environment. Using a Bourne-compatible shell, you +can do that on the command line like this: + +@example +CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure +@end example + +On systems that have the @code{env} program, you can do it like this: + +@example +env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure +@end example + +The configuration process uses GCC to build Bash if it +is available. + +@node Compiling For Multiple Architectures +@section Compiling For Multiple Architectures + +You can compile Bash for more than one kind of computer at the +same time, by placing the object files for each architecture in their +own directory. To do this, you must use a version of @code{make} that +supports the @code{VPATH} variable, such as GNU @code{make}. +@code{cd} to the +directory where you want the object files and executables to go and run +the @code{configure} script from the source directory. You may need to +supply the @samp{--srcdir=PATH} argument to tell @code{configure} where the +source files are. @code{configure} automatically checks for the +source code in the directory that @code{configure} is in and in `..'. + +If you have to use a @code{make} that does not supports the @code{VPATH} +variable, you can compile Bash for one architecture at a +time in the source code directory. After you have installed +Bash for one architecture, use @samp{make distclean} before +reconfiguring for another architecture. + +Alternatively, if your system supports symbolic links, you can use the +@file{support/mkclone} script to create a build tree which has +symbolic links back to each file in the source directory. Here's an +example that creates a build directory in the current directory from a +source directory @file{/usr/gnu/src/bash-2.0}: + +@example +bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . +@end example + +@noindent +The @code{mkclone} script requires Bash, so you must have already built +Bash for at least one architecture before you can create build +directories for other architectures. + +@node Installation Names +@section Installation Names + +By default, @samp{make install} will install into +@file{/usr/local/bin}, @file{/usr/local/man}, etc. You can +specify an installation prefix other than @file{/usr/local} by +giving @code{configure} the option @samp{--prefix=PATH}. + +You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. +If you give @code{configure} the option +@samp{--exec-prefix=PATH}, the package will use @samp{PATH} as the +prefix for installing programs and libraries. Documentation and +other data files will still use the regular prefix. + +@node Specifying the System Type +@section Specifying the System Type + +There may be some features @code{configure} can not figure out +automatically, but needs to determine by the type of host the +package will run on. Usually @code{configure} can figure that +out, but if it prints a message saying it can not guess the host +type, give it the @samp{--host=TYPE} option. @samp{TYPE} can +either be a short name for the system type, such as @samp{sun4}, +or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM} +(e.g., @samp{sparc-sun-sunos4.1.2}). + +@noindent See the file @file{support/config.sub} for the possible +values of each field. + +@node Sharing Defaults +@section Sharing Defaults + +If you want to set default values for @code{configure} scripts to +share, you can create a site shell script called +@code{config.site} that gives default values for variables like +@code{CC}, @code{cache_file}, and @code{prefix}. @code{configure} +looks for @file{PREFIX/share/config.site} if it exists, then +@file{PREFIX/etc/config.site} if it exists. Or, you can set the +@code{CONFIG_SITE} environment variable to the location of the site +script. A warning: the Bash @code{configure} looks for a site script, +but not all @code{configure} scripts do. + +@node Operation Controls +@section Operation Controls + +@code{configure} recognizes the following options to control how it +operates. + +@table @code + +@item --cache-file=@var{FILE} +Use and save the results of the tests in +@var{FILE} instead of @file{./config.cache}. Set @var{FILE} to +@file{/dev/null} to disable caching, for debugging +@code{configure}. + +@item --help +Print a summary of the options to @code{configure}, and exit. + +@item --quiet +@itemx --silent +@itemx -q +Do not print messages saying which checks are being made. + +@item --srcdir=@var{DIR} +Look for the Bash source code in directory @var{DIR}. Usually +@code{configure} can determine that directory automatically. + +@item --version +Print the version of Autoconf used to generate the @code{configure} +script, and exit. +@end table + +@code{configure} also accepts some other, not widely used, boilerplate +options. + +@node Optional Features +@section Optional Features + +The Bash @code{configure} has a number of @samp{--enable-@var{FEATURE}} +options, where @var{FEATURE} indicates an optional part of the +package. There are also several @samp{--with-@var{PACKAGE}} options, +where @var{PACKAGE} is something like @samp{gnu-malloc} or +@samp{purify} (for the Purify memory allocation checker). To +turn off the default use of a package, use +@samp{--without-@var{PACKAGE}}. To configure Bash without a feature +that is enabled by default, use @samp{--disable-@var{FEATURE}}. + +Here is a complete list of the @samp{--enable-} and +@samp{--with-} options that the Bash @code{configure} recognizes. + +@table @code +@item --with-gnu-malloc +Use the @sc{GNU} version of +@code{malloc} in @file{lib/malloc/malloc.c}. This is not the same +@code{malloc} that appears in @sc{GNU} libc, but an older version +derived from the 4.2 @sc{BSD} @code{malloc}. This @code{malloc} is +very fast, but wastes a lot of space. This option is enabled by +default. The @file{NOTES} file contains a list of systems for +which this should be turned off. + +@item --with-glibc-malloc +Use the @sc{GNU} libc version of @code{malloc} in +@file{lib/malloc/gmalloc.c}. This is somewhat slower than the +default @code{malloc}, but wastes considerably less space. + +@item --with-afs +Define if you are using the Andrew File System from Transarc. + +@item --with-purify +Define this to use the Purify memory allocation checker from Pure +Software. + +@item --enable-minimal-config +This produces a shell with minimal features, close to the historical +Bourne shell. +@end table + +@noindent +The @samp{minimal-config} option can be used to disable all of +the following options, but it is processed first, so individual +options may be enabled using @samp{enable-@var{FEATURE}}. + +All of the following options except for @samp{disabled-builtins} and +@samp{usg-echo-default} are +enabled by default, unless the operating system does not provide the +necessary support. + +@table @code +@item --enable-job-control +This enables job control features, if the @sc{OS} supports them. + +@item --enable-alias +Allow alias expansion and include the @code{alias} and @code{unalias} +builtins. + +@item --enable-readline +Include support for command-line editing and history with the Bash +version of the Readline library. + +@item --enable-history +Include command history and the @code{fc} and @code{history} +builtin commands. + +@item --enable-bang-history +Include support for @code{csh}-like history substitution. + +@item --enable-directory-stack +Include support for a @code{csh}-like directory stack and the +@code{pushd}, @code{popd}, and @code{dirs} builtins. + +@item --enable-restricted +Include support for a @dfn{restricted shell}. If this is enabled, Bash, +when called as @code{rbash}, enters a restricted mode. See +@ref{The Restricted Shell}, for a description of restricted mode. + +@item --enable-process-substitution +This enables process substitution (@pxref{Process Substitution}) if +the @sc{OS} provides the necessary support. + +@item --enable-prompt-string-decoding +Turn on the interpretation of a number of backslash-escaped characters +in the @code{$PS1}, @code{$PS2}, @code{$PS3}, and @code{$PS4} prompt +strings. + +@item --enable-select +Include the @code{ksh} @code{select} builtin, which allows the +generation of simple menus. + +@item --enable-help-builtin +Include the @code{help} builtin, which displays help on shell builtins and +variables. + +@item --enable-array-variables +Include support for one-dimensional array shell variables. + +@item --enable-dparen-arithmetic +Include support for the @code{ksh} @code{((@dots{}))} command. + +@item --enable-brace-expansion +Include @code{csh}-like brace expansion +( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ). + +@item --enable-disabled-builtins +Allow builtin commands to be invoked via @samp{builtin xxx} +even after @code{xxx} has been disabled using @samp{enable -n xxx}. +See @ref{Bash Builtins}, for details of the @code{builtin} and +@code{enable} builtin commands. + +@item --enable-command-timing +Include support for recognizing @code{time} as a reserved word and for +displaying timing statistics for the pipeline following @code{time}. This +allows pipelines as well as shell builtins and functions to be timed. + +@item --enable-usg-echo-default +Make the @code{echo} builtin expand backslash-escaped characters by default, +without requiring the @samp{-e} option. This makes the Bash @code{echo} +behave more like the System V version. + +@end table + +The file @file{config.h.top} contains C Preprocessor +@samp{#define} statements for options which are not settable from +@code{configure}. +Some of these are not meant to be changed; beware of the consequences if +you do. +Read the comments associated with each definition for more +information about its effect. + +@node Reporting Bugs +@appendix Reporting Bugs + +Please report all bugs you find in Bash. +But first, you should +make sure that it really is a bug, and that it appears in the latest +version of Bash that you have. + +Once you have determined that a bug actually exists, use the +@code{bashbug} command to submit a bug report. +If you have a fix, you are welcome to mail that as well! +Suggestions and `philosophical' bug reports may be mailed +to @code{bug-bash@@prep.ai.MIT.Edu} or posted to the Usenet +newsgroup @code{gnu.bash.bug}. + +All bug reports should include: +@itemize @bullet +@item +The version number of Bash. +@item +The hardware and operating system. +@item +The compiler used to compile Bash. +@item +A description of the bug behaviour. +@item +A short script or `recipe' which exercises the bug and may be used +to reproduce it. +@end itemize + +@noindent +@code{bashbug} inserts the first three items automatically into +the template it provides for filing a bug report. + +Please send all reports concerning this manual to +@code{chet@@ins.CWRU.Edu}. + +@node Builtin Index +@appendix Index of Shell Builtin Commands +@printindex bt + +@node Reserved Word Index +@appendix Shell Reserved Words +@printindex rw + +@node Variable Index +@appendix Parameter and Variable Index +@printindex vr + +@node Function Index +@appendix Function Index +@printindex fn + +@node Concept Index +@appendix Concept Index +@printindex cp + +@contents +@bye diff --git a/doc/builtins.1 b/doc/builtins.1 new file mode 100644 index 00000000..d0aa6312 --- /dev/null +++ b/doc/builtins.1 @@ -0,0 +1,15 @@ +.\" This is a hack to force bash builtins into the whatis database +.\" and to get the list of builtins to come up with the man command. +.TH BASH_BUILTINS 1 "1996 March 20" GNU +.SH NAME +bash, :, ., alias, bg, bind, break, builtin, case, cd, command, +continue, declare, dirs, disown, echo, enable, eval, exec, exit, +export, fc, fg, for, getopts, hash, help, history, if, jobs, kill, +let, local, logout, popd, pushd, pwd, read, readonly, return, set, +shift, shopt, source, suspend, test, times, trap, type, typeset, +ulimit, umask, unalias, unset, until, wait, while \- bash built-in commands, see \fBbash\fR(1) +.SH BASH BUILTIN COMMANDS +.nr zZ 1 +.so bash.1 +.SH SEE ALSO +bash(1), sh(1) diff --git a/doc/readline.3 b/doc/readline.3 new file mode 100644 index 00000000..e122cb7a --- /dev/null +++ b/doc/readline.3 @@ -0,0 +1,1103 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Information Network Services +.\" Case Western Reserve University +.\" chet@ins.CWRU.Edu +.\" +.\" Last Change: Mon Jul 8 13:07:48 EDT 1996 +.\" +.TH READLINE 3 "1996 July 8" GNU +.\" +.\" File Name macro. This used to be `.PN', for Path Name, +.\" but Sun doesn't seem to like that very much. +.\" +.de FN +\fI\|\\$1\|\fP +.. +.SH NAME +readline \- get a line from a user with editing +.SH SYNOPSIS +.LP +.nf +.ft B +#include <readline.h> +#include <history.h> +.ft +.fi +.LP +.nf +.ft B +char *readline (prompt) +char *prompt; +.ft +.fi +.SH COPYRIGHT +.if n Readline is Copyright (C) 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc. +.if t Readline is Copyright \(co 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc. +.SH DESCRIPTION +.LP +.B readline +will read a line from the terminal +and return it, using +.B prompt +as a prompt. If +.B prompt +is null, no prompt is issued. The line returned is allocated with +.IR malloc (3), +so the caller must free it when finished. The line returned +has the final newline removed, so only the text of the line +remains. +.LP +.B readline +offers editing capabilities while the user is entering the +line. +By default, the line editing commands +are similar to those of emacs. +A vi\-style line editing interface is also available. +.SH RETURN VALUE +.LP +.B readline +returns the text of the line read. A blank line +returns the empty string. If +.B EOF +is encountered while reading a line, and the line is empty, +.B NULL +is returned. If an +.B EOF +is read with a non\-empty line, it is +treated as a newline. +.SH NOTATION +.LP +An emacs-style notation is used to denote +keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n +means Control\-N. Similarly, +.I meta +keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards +without a +.I meta +key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key +then the +.I x +key. This makes ESC the \fImeta prefix\fP. +The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP, +or press the Escape key +then hold the Control key while pressing the +.I x +key.) +.PP +Readline commands may be given numeric +.IR arguments , +which normally act as a repeat count. Sometimes, however, it is the +sign of the argument that is significant. Passing a negative argument +to a command that acts in the forward direction (e.g., \fBkill\-line\fP) +causes that command to act in a backward direction. Commands whose +behavior with arguments deviates from this are noted. +.PP +When a command is described as \fIkilling\fP text, the text +deleted is saved for possible future retrieval +(\fIyanking\fP). The killed text is saved in a +\fIkill ring\fP. Consecutive kills cause the text to be +accumulated into one unit, which can be yanked all at once. +Commands which do not kill text separate the chunks of text +on the kill ring. +.SH INITIALIZATION FILE +.LP +Readline is customized by putting commands in an initialization +file (the \fIinputrc\fP file). +The name of this file is taken from the value of the +.B INPUTRC +environment variable. If that variable is unset, the default is +.IR ~/.inputrc . +When a program which uses the readline library starts up, the +init file is read, and the key bindings and variables are set. +There are only a few basic constructs allowed in the +readline init file. Blank lines are ignored. +Lines beginning with a \fB#\fP are comments. +Lines beginning with a \fB$\fP indicate conditional constructs. +Other lines denote key bindings and variable settings. +Each program using this library may add its own commands +and bindings. +.PP +For example, placing +.RS +.PP +M\-Control\-u: universal\-argument +.RE +or +.RS +C\-Meta\-u: universal\-argument +.RE +into the +.I inputrc +would make M\-C\-u execute the readline command +.IR universal\-argument . +.PP +The following symbolic character names are recognized while +processing key bindings: +.IR RUBOUT , +.IR DEL , +.IR ESC , +.IR LFD , +.IR NEWLINE , +.IR RET , +.IR RETURN , +.IR SPC , +.IR SPACE , +and +.IR TAB . +In addition to command names, readline allows keys to be bound +to a string that is inserted when the key is pressed (a \fImacro\fP). +.PP +.SS Key Bindings +.PP +The syntax for controlling key bindings in the +.I inputrc +file is simple. All that is required is the name of the +command or the text of a macro and a key sequence to which +it should be bound. The name may be specified in one of two ways: +as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP +prefixes, or as a key sequence. +When using the form \fBkeyname\fP:\fIfunction-name\fP or \fImacro\fP, +.I keyname +is the name of a key spelled out in English. For example: +.sp +.RS +Control\-u: universal\-argument +.br +Meta\-Rubout: backward\-kill\-word +.br +Control\-o: ">&output" +.RE +.LP +In the above example, +.I C\-u +is bound to the function +.BR universal\-argument , +.I M-DEL +is bound to the function +.BR backward\-kill\-word , +and +.I C\-o +is bound to run the macro +expressed on the right hand side (that is, to insert the text +.I >&output +into the line). +.PP +In the second form, \fB"keyseq"\fP:\fIfunction\-name\fP or \fImacro\fP, +.B keyseq +differs from +.B keyname +above in that strings denoting +an entire key sequence may be specified by placing the sequence +within double quotes. Some GNU Emacs style key escapes can be +used, as in the following example. +.sp +.RS +"\eC\-u": universal\-argument +.br +"\eC\-x\eC\-r": re\-read\-init\-file +.br +"\ee[11~": "Function Key 1" +.RE +.PP +In this example, +.I C-u +is again bound to the function +.BR universal\-argument . +.I "C-x C-r" +is bound to the function +.BR re\-read\-init\-file , +and +.I "ESC [ 1 1 ~" +is bound to insert the text +.BR "Function Key 1" . +The full set of escape sequences is +.RS +.TP +.B \eC\- +control prefix +.TP +.B \eM\- +meta prefix +.TP +.B \ee +an escape character +.TP +.B \e\e +backslash +.TP +.B \e" +literal " +.TP +.B \e' +literal ' +.RE +.PP +When entering the text of a macro, single or double quotes should +be used to indicate a macro definition. Unquoted text +is assumed to be a function name. Backslash +will quote any character in the macro text, including " and '. +.PP +.B Bash +allows the current readline key bindings to be displayed or modified +with the +.B bind +builtin command. The editing mode may be switched during interactive +use by using the +.B \-o +option to the +.B set +builtin command. Other programs using this library provide +similar mechanisms. The +.I inputrc +file may be edited and re-read if a program does not provide +any other means to incorporate new bindings. +.SS Variables +.PP +Readline has variables that can be used to further customize its +behavior. A variable may be set in the +.I inputrc +file with a statement of the form +.RS +.PP +\fBset\fP \fIvariable\-name\fP \fIvalue\fP +.RE +.PP +Except where noted, readline variables can take the values +.B On +or +.BR Off . +The variables and their default values are: +.PP +.PD 0 +.TP +.B bell\-style (audible) +Controls what happens when readline wants to ring the terminal bell. +If set to \fBnone\fP, readline never rings the bell. If set to +\fBvisible\fP, readline uses a visible bell if one is available. +If set to \fBaudible\fP, readline attempts to ring the terminal's bell. +.TP +.B comment\-begin (``#'') +The string that is inserted in \fBvi\fP mode when the +.B insert\-comment +command is executed. +This command is bound to +.B M\-# +in emacs mode and to +.B # +in vi command mode. +.TP +.B completion\-query\-items (100) +This determines when the user is queried about viewing +the number of possible completions +generated by the \fBpossible\-completions\fP command. +It may be set to any integer value greater than or equal to +zero. If the number of possible completions is greater than +or equal to the value of this variable, the user is asked whether +or not he wishes to view them; otherwise they are simply listed +on the terminal. +.TP +.B convert\-meta (On) +If set to \fBOn\fP, readline will convert characters with the +eighth bit set to an ASCII key sequence +by stripping the eighth bit and prepending an +escape character (in effect, using escape as the \fImeta prefix\fP). +.TP +.B disable\-completion (Off) +If set to \fBOn\fP, readline will inhibit word completion. Completion +characters will be inserted into the line as if they had been +mapped to \fBself-insert\fP. +.TP +.B editing\-mode (emacs) +Controls whether readline begins with a set of key bindings similar +to \fIemacs\fP or \fIvi\fP. +.B editing\-mode +can be set to either +.B emacs +or +.BR vi . +.TP +.B enable\-keypad (Off) +When set to \fBOn\fP, readline will try to enable the application +keypad when it is called. Some systems need this to enable the +arrow keys. +.TP +.B expand\-tilde (Off) +If set to \fBon\fP, tilde expansion is performed when readline +attempts word completion. +.TP +.B horizontal\-scroll\-mode (Off) +When set to \fBOn\fP, makes readline use a single line for display, +scrolling the input horizontally on a single screen line when it +becomes longer than the screen width rather than wrapping to a new line. +.TP +.B keymap (emacs) +Set the current readline keymap. The set of legal keymap names is +\fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move, +vi-command\fP, and +.IR vi-insert . +\fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is +equivalent to \fIemacs-standard\fP. The default value is +.IR emacs ; +the value of +.B editing\-mode +also affects the default keymap. +.TP +.B mark\-directories (On) +If set to \fBOn\fP, completed directory names have a slash +appended. +.TP +.B mark\-modified\-lines (Off) +If set to \fBOn\fP, history lines that have been modified are displayed +with a preceding asterisk (\fB*\fP). +.TP +.B meta\-flag (Off) +If set to \fBOn\fP, readline will enable eight-bit input (that is, +it will not strip the high bit from the characters it reads), +regardless of what the terminal claims it can support. +.TP +.B output\-meta (Off) +If set to \fBOn\fP, readline will display characters with the +eighth bit set directly rather than as a meta-prefixed escape +sequence. +.TP +.B show\-all\-if\-ambiguous (Off) +This alters the default behavior of the completion functions. If +set to +.BR on , +words which have more than one possible completion cause the +matches to be listed immediately instead of ringing the bell. +.TP +.B visible\-stats (Off) +If set to \fBOn\fP, a character denoting a file's type as reported +by \fBstat\fP(2) is appended to the filename when listing possible +completions. +.PD +.SS Conditional Constructs +.PP +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are three parser directives used. +.IP \fB$if\fP +The +.B $if +construct allows bindings to be made based on the +editing mode, the terminal being used, or the application using +readline. The text of the test extends to the end of the line; +no characters are required to isolate it. +.RS +.IP \fBmode\fP +The \fBmode=\fP form of the \fB$if\fP directive is used to test +whether readline is in emacs or vi mode. +This may be used in conjunction +with the \fBset keymap\fP command, for instance, to set bindings in +the \fIemacs-standard\fP and \fIemacs-ctlx\fP keymaps only if +readline is starting out in emacs mode. +.IP \fBterm\fP +The \fBterm=\fP form may be used to include terminal-specific +key bindings, perhaps to bind the key sequences output by the +terminal's function keys. The word on the right side of the +.B = +is tested against the full name of the terminal and the portion +of the terminal name before the first \fB\-\fP. This allows +.I sun +to match both +.I sun +and +.IR sun\-cmd , +for instance. +.IP \fBapplication\fP +The \fBapplication\fP construct is used to include +application-specific settings. Each program using the readline +library sets the \fIapplication name\fP, and an initialization +file can test for a particular value. +This could be used to bind key sequences to functions useful for +a specific program. For instance, the following command adds a +key sequence that quotes the current or previous word in Bash: +.RS +.nf +\fB$if\fP bash +# Quote the current or previous word +"\eC-xq": "\eeb\e"\eef\e"" +\fB$endif\fP +.fi +.RE +.RE +.IP \fB$endif\fP +This command, as you saw in the previous example, terminates an +\fB$if\fP command. +.IP \fB$else\fP +Commands in this branch of the \fB$if\fP directive are executed if +the test fails. +.SH SEARCHING +.PP +Readline provides commands for searching through the command history +for lines containing a specified string. +There are two search modes: +.I incremental +and +.IR non-incremental . +.PP +Incremental searches begin before the user has finished typing the +search string. +As each character of the search string is typed, readline displays +the next entry from the history matching the string typed so far. +An incremental search requires only as many characters as needed to +find the desired history entry. +The Escape character is used to terminate an incremental search. +Control-J will also terminate the search. +Control-G will abort an incremental search and restore the original +line. +When the search is terminated, the history entry containing the +search string becomes the current line. +To find other matching entries in the history list, type Control-S or +Control-R as appropriate. +This will search backward or forward in the history for the next +line matching the search string typed so far. +Any other key sequence bound to a readline command will terminate +the search and execute that command. +For instance, a \fInewline\fP will terminate the search and accept +the line, thereby executing the command from the history list. +.PP +Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or part of the contents of the current line. +.SH EDITING COMMANDS +.PP +The following is a list of the names of the commands and the default +key sequences to which they are bound. +Command names without an accompanying key sequence are unbound by default. +.SS Commands for Moving +.PP +.PD 0 +.TP +.B beginning\-of\-line (C\-a) +Move to the start of the current line. +.TP +.B end\-of\-line (C\-e) +Move to the end of the line. +.TP +.B forward\-char (C\-f) +Move forward a character. +.TP +.B backward\-char (C\-b) +Move back a character. +.TP +.B forward\-word (M\-f) +Move forward to the end of the next word. Words are composed of +alphanumeric characters (letters and digits). +.TP +.B backward\-word (M\-b) +Move back to the start of this, or the previous, word. Words are +composed of alphanumeric characters (letters and digits). +.TP +.B clear\-screen (C\-l) +Clear the screen leaving the current line at the top of the screen. +With an argument, refresh the current line without clearing the +screen. +.TP +.B redraw\-current\-line +Refresh the current line. +.PD +.SS Commands for Manipulating the History +.PP +.PD 0 +.TP +.B accept\-line (Newline, Return) +Accept the line regardless of where the cursor is. If this line is +non-empty, add it to the history list. If the line is a modified +history line, then restore the history line to its original state. +.TP +.B previous\-history (C\-p) +Fetch the previous command from the history list, moving back in +the list. +.TP +.B next\-history (C\-n) +Fetch the next command from the history list, moving forward in the +list. +.TP +.B beginning\-of\-history (M\-<) +Move to the first line in the history. +.TP +.B end\-of\-history (M\->) +Move to the end of the input history, i.e., the line currently being +entered. +.TP +.B 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. +.TP +.B forward\-search\-history (C\-s) +Search forward starting at the current line and moving `down' through +the history as necessary. This is an incremental search. +.TP +.B non\-incremental\-reverse\-search\-history (M\-p) +Search backward through the history starting at the current line +using a non-incremental search for a string supplied by the user. +.TP +.B non\-incremental\-forward\-search\-history (M\-n) +Search forward through the history using a non-incremental search +for a string supplied by the user. +.TP +.B history\-search\-forward +Search forward through the history for the string of characters +between the start of the current line and the current cursor +position (the \fIpoint\fP). +This is a non-incremental search. +.TP +.B history\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the point. +This is a non-incremental search. +.TP +.B yank\-nth\-arg (M\-C\-y) +Insert the first argument to the previous command (usually +the second word on the previous line) at point (the current +cursor position). With an argument +.IR n , +insert the \fIn\fPth word from the previous command (the words +in the previous command begin with word 0). A negative argument +inserts the \fIn\fPth word from the end of the previous command. +.TP +.B +yank\-last\-arg (M\-.\^, M\-_\^) +Insert the last argument to the previous command (the last word of +the previous history entry). With an argument, +behave exactly like \fByank\-nth\-arg\fP. +.PD +.SS Commands for Changing Text +.PP +.PD 0 +.TP +.B delete\-char (C\-d) +Delete the character under the cursor. If point is at the +beginning of the line, there are no characters in the line, and +the last character typed was not +.BR C\-d , +then return +.SM +.BR EOF . +.TP +.B backward\-delete\-char (Rubout) +Delete the character behind the cursor. When given a numeric argument, +save the deleted text on the kill ring. +.TP +.B quoted\-insert (C\-q, C\-v) +Add the next character that you type to the line verbatim. This is +how to insert characters like \fBC\-q\fP, for example. +.TP +.B tab\-insert (M-TAB) +Insert a tab character. +.TP +.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...) +Insert the character typed. +.TP +.B 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 arguments don't work. +.TP +.B 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. +.TP +.B upcase\-word (M\-u) +Uppercase the current (or following) word. With a negative argument, +do the previous word, but do not move point. +.TP +.B downcase\-word (M\-l) +Lowercase the current (or following) word. With a negative argument, +do the previous word, but do not move point. +.TP +.B capitalize\-word (M\-c) +Capitalize the current (or following) word. With a negative argument, +do the previous word, but do not move point. +.PD +.SS Killing and Yanking +.PP +.PD 0 +.TP +.B kill\-line (C\-k) +Kill the text from the current cursor position to the end of the line. +.TP +.B backward\-kill\-line (C\-x Rubout) +Kill backward to the beginning of the line. +.TP +.B unix\-line\-discard (C\-u) +Kill backward from point to the beginning of the line. +.\" There is no real difference between this and backward-kill-line +.TP +.B kill\-whole\-line +Kill all characters on the current line, no matter where the +cursor is. +.TP +.B 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. Word boundaries are the same as +those used by \fBforward\-word\fP. +.TP +.B backward\-kill\-word (M\-Rubout) +Kill the word behind the cursor. Word boundaries are the same as +those used by \fBbackward\-word\fP. +.TP +.B unix\-word\-rubout (C\-w) +Kill the word behind the cursor, using white space as a word boundary. +The word boundaries are different from +.BR backward\-kill\-word . +.TP +.B delete\-horizontal\-space (M\-\e) +Delete all spaces and tabs around point. +.TP +.B kill\-region +Kill the text between the point and \fImark\fP (saved cursor position). +This text is referred to as the \fIregion\fP. +.TP +.B copy\-region\-as\-kill +Copy the text in the region to the kill buffer. +.TP +.B copy\-backward\-word +Copy the word before point to the kill buffer. +.TP +.B copy\-forward\-word +Copy the word following point to the kill buffer. +.TP +.B yank (C\-y) +Yank the top of the kill ring into the buffer at the cursor. +.TP +.B yank\-pop (M\-y) +Rotate the kill ring, and yank the new top. Only works following +.B yank +or +.BR yank\-pop . +.PD +.SS Numeric Arguments +.PP +.PD 0 +.TP +.B 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. +.TP +.B universal\-argument +Each time this is executed, the argument count is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four. +.PD +.SS Completing +.PP +.PD 0 +.TP +.B complete (TAB) +Attempt to perform completion on the text before point. +The actual completion performed is application-specific. +.BR Bash , +for instance, attempts completion treating the text as a variable +(if the text begins with \fB$\fP), username (if the text begins with +\fB~\fP), hostname (if the text begins with \fB@\fP), or +command (including aliases and functions) in turn. If none +of these produces a match, filename completion is attempted. +.BR Gdb , +on the other hand, +allows completion of program functions and variables, and +only attempts filename completion under certain circumstances. +.TP +.B possible\-completions (M\-?) +List the possible completions of the text before point. +.TP +.B insert\-completions (M\-*) +Insert all completions of the text before point +that would have been generated by +\fBpossible\-completions\fP. +.PD +.SS Keyboard Macros +.PP +.PD 0 +.TP +.B start\-kbd\-macro (C\-x (\^) +Begin saving the characters typed into the current keyboard macro. +.TP +.B end\-kbd\-macro (C\-x )\^) +Stop saving the characters typed into the current keyboard macro +and store the definition. +.TP +.B call\-last\-kbd\-macro (C\-x e) +Re-execute the last keyboard macro defined, by making the characters +in the macro appear as if typed at the keyboard. +.PD +.SS Miscellaneous +.PP +.PD 0 +.TP +.B re\-read\-init\-file (C\-x C\-r) +Read in the contents of the \fIinputrc\fP file, and incorporate +any bindings or variable assignments found there. +.TP +.B abort (C\-g) +Abort the current editing command and +ring the terminal's bell (subject to the setting of +.BR bell\-style ). +.TP +.B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...) +If the metafied character \fIx\fP is lowercase, run the command +that is bound to the corresponding uppercase character. +.TP +.B prefix\-meta (ESC) +Metafy the next character typed. +.SM +.B ESC +.B f +is equivalent to +.BR Meta\-f . +.TP +.B undo (C\-_, C\-x C\-u) +Incremental undo, separately remembered for each line. +.TP +.B revert\-line (M\-r) +Undo all changes made to this line. This is like typing the +.B undo +command enough times to return the line to its initial state. +.TP +.B tilde\-expand (M\-~) +Perform tilde expansion on the current word. +.TP +.B set\-mark (C\-@, M-<space>) +Set the mark to the current point. If a +numeric argument is supplied, the mark is set to that position. +.TP +.B exchange\-point\-and\-mark (C\-x C\-x) +Swap the point with the mark. The current cursor position is set to +the saved position, and the old cursor position is saved as the mark. +.TP +.B character\-search (C\-]) +A character is read and point is moved to the next occurrence of that +character. A negative count searches for previous occurrences. +.TP +.B character\-search\-backward (M\-C\-]) +A character is read and point is moved to the previous occurrence of that +character. A negative count searches for subsequent occurrences. +.TP +.B insert\-comment (M\-#) +The value of the readline +.B comment\-begin +variable is inserted at the beginning of the current line, and the line +is accepted as if a newline had been typed. This makes the current line +a shell comment. +.TP +.B glob\-expand\-word (C\-x *) +The word before point is treated as a pattern for pathname expansion, +and the list of matching file names is inserted, replacing the word. +.TP +.B glob\-list\-expansions (C\-x g) +The list of expansions that would have been generated by +.B glob\-expand\-word +is inserted into the line, replacing the word before point. +.TP +.B dump\-functions +Print all of the functions and their key bindings to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-variables +Print all of the settable variables and their values to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-macros +Print all of the readline key sequences bound to macros and the +strings they ouput. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B emacs\-editing\-mode (C\-e) +When in +.B vi +editing mode, this causes a switch to +.B emacs +editing mode. +.TP +.B vi\-editing\-mode (M\-C\-j) +When in +.B emacs +editing mode, this causes a switch to +.B vi +editing mode. +.PD +.SH DEFAULT KEY BINDINGS +.LP +The following is a list of the default emacs and vi bindings. +Characters with the 8th bit set are written as M\-<character>, and +are referred to as +.I metafied +characters. +The printable ASCII characters not mentioned in the list of emacs +standard bindings are bound to the +.I self\-insert +function, which just inserts the given character into the input line. +In vi insertion mode, all characters not specifically mentioned are +bound to +.IR self\-insert . +Characters assigned to signal generation by +.IR stty (1) +or the terminal driver, such as C-Z or C-C, +retain that function. +Upper and lower case +.I metafied +characters are bound to the same function in the emacs mode +meta keymap. +The remaining characters are unbound, which causes readline +to ring the bell (subject to the setting of the +.B bell\-style +variable). +.SS Emacs Mode +.RS +.6i +.nf +.ta 2.5i +.sp +Emacs Standard bindings +.sp +"C-@" set-mark +"C-A" beginning-of-line +"C-B" backward-char +"C-D" delete-char +"C-E" end-of-line +"C-F" forward-char +"C-G" abort +"C-H" backward-delete-char +"C-I" complete +"C-J" accept-line +"C-K" kill-line +"C-L" clear-screen +"C-M" accept-line +"C-N" next-history +"C-P" previous-history +"C-Q" quoted-insert +"C-R" reverse-search-history +"C-S" forward-search-history +"C-T" transpose-chars +"C-U" unix-line-discard +"C-V" quoted-insert +"C-W" unix-word-rubout +"C-Y" yank +"C-]" character-search +"C-_" undo +"\^ " to "/" self-insert +"0" to "9" self-insert +":" to "~" self-insert +"C-?" backward-delete-char +.PP +Emacs Meta bindings +.sp +"M-C-G" abort +"M-C-H" backward-kill-word +"M-C-I" tab-insert +"M-C-J" vi-editing-mode +"M-C-M" vi-editing-mode +"M-C-R" revert-line +"M-C-Y" yank-nth-arg +"M-C-[" complete +"M-C-]" character-search-backward +"M-space" set-mark +"M-#" insert-comment +"M-&" tilde-expand +"M-*" insert-completions +"M--" digit-argument +"M-." yank-last-arg +"M-0" digit-argument +"M-1" digit-argument +"M-2" digit-argument +"M-3" digit-argument +"M-4" digit-argument +"M-5" digit-argument +"M-6" digit-argument +"M-7" digit-argument +"M-8" digit-argument +"M-9" digit-argument +"M-<" beginning-of-history +"M-=" possible-completions +"M->" end-of-history +"M-?" possible-completions +"M-B" backward-word +"M-C" capitalize-word +"M-D" kill-word +"M-F" forward-word +"M-L" downcase-word +"M-N" non-incremental-forward-search-history +"M-P" non-incremental-reverse-search-history +"M-R" revert-line +"M-T" transpose-words +"M-U" upcase-word +"M-Y" yank-pop +"M-\e" delete-horizontal-space +"M-~" tilde-expand +"M-C-?" backward-delete-word +"M-_" yank-last-arg +.PP +Emacs Control-X bindings +.sp +"C-XC-G" abort +"C-XC-R" re-read-init-file +"C-XC-U" undo +"C-XC-X" exchange-point-and-mark +"C-X(" start-kbd-macro +"C-X)" end-kbd-macro +"C-XE" call-last-kbd-macro +"C-XC-?" backward-kill-line +.sp +.RE +.SS VI Mode bindings +.RS +.6i +.nf +.ta 2.5i +.sp +.PP +VI Insert Mode functions +.sp +"C-D" vi-eof-maybe +"C-H" backward-delete-char +"C-I" complete +"C-J" accept-line +"C-M" accept-line +"C-R" reverse-search-history +"C-S" forward-search-history +"C-T" transpose-chars +"C-U" unix-line-discard +"C-V" quoted-insert +"C-W" unix-word-rubout +"C-Y" yank +"C-[" vi-movement-mode +"C-_" undo +"\^ " to "~" self-insert +"C-?" backward-delete-char +.PP +VI Command Mode functions +.sp +"C-D" vi-eof-maybe +"C-E" emacs-editing-mode +"C-G" abort +"C-H" backward-char +"C-J" accept-line +"C-K" kill-line +"C-L" clear-screen +"C-M" accept-line +"C-N" next-history +"C-P" previous-history +"C-Q" quoted-insert +"C-R" reverse-search-history +"C-S" forward-search-history +"C-T" transpose-chars +"C-U" unix-line-discard +"C-V" quoted-insert +"C-W" unix-word-rubout +"C-Y" yank +"\^ " forward-char +"#" insert-comment +"$" end-of-line +"%" vi-match +"&" vi-tilde-expand +"*" vi-complete +"+" next-history +"," vi-char-search +"-" previous-history +"." vi-redo +"/" vi-search +"0" beginning-of-line +"1" to "9" vi-arg-digit +";" vi-char-search +"=" vi-complete +"?" vi-search +"A" vi-append-eol +"B" vi-prev-word +"C" vi-change-to +"D" vi-delete-to +"E" vi-end-word +"F" vi-char-search +"G" vi-fetch-history +"I" vi-insert-beg +"N" vi-search-again +"P" vi-put +"R" vi-replace +"S" vi-subst +"T" vi-char-search +"U" revert-line +"W" vi-next-word +"X" backward-delete-char +"Y" vi-yank-to +"\e" vi-complete +"^" vi-first-print +"_" vi-yank-arg +"`" vi-goto-mark +"a" vi-append-mode +"b" vi-prev-word +"c" vi-change-to +"d" vi-delete-to +"e" vi-end-word +"f" vi-char-search +"h" backward-char +"i" vi-insertion-mode +"j" next-history +"k" prev-history +"l" forward-char +"m" vi-set-mark +"n" vi-search-again +"p" vi-put +"r" vi-change-char +"s" vi-subst +"t" vi-char-search +"u" undo +"w" vi-next-word +"x" vi-delete +"y" vi-yank-to +"|" vi-column +"~" vi-change-case +.RE +.SH "SEE ALSO" +.PD 0 +.TP +\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey +.TP +\fIbash\fP(1) +.PD +.SH FILES +.PD 0 +.TP +.FN ~/.inputrc +Individual \fBreadline\fP initialization file +.PD +.SH AUTHORS +Brian Fox, Free Software Foundation (primary author) +.br +bfox@ai.MIT.Edu +.PP +Chet Ramey, Case Western Reserve University +.br +chet@ins.CWRU.Edu +.SH BUG REPORTS +If you find a bug in +.B readline, +you should report it. But first, you should +make sure that it really is a bug, and that it appears in the latest +version of the +.B readline +library that you have. +.PP +Once you have determined that a bug actually exists, mail a +bug report to \fIbug\-readline\fP@\fIprep.ai.MIT.Edu\fP. +If you have a fix, you are welcome to mail that +as well! Suggestions and `philosophical' bug reports may be mailed +to \fPbug-readline\fP@\fIprep.ai.MIT.Edu\fP or posted to the Usenet +newsgroup +.BR gnu.bash.bug . +.PP +Comments and bug reports concerning +this manual page should be directed to +.IR chet@ins.CWRU.Edu . +.SH BUGS +.PP +It's too big and too slow. diff --git a/doc/texinfo.tex b/doc/texinfo.tex new file mode 100644 index 00000000..fb7cfe5a --- /dev/null +++ b/doc/texinfo.tex @@ -0,0 +1,4421 @@ +%% TeX macros to handle texinfo files + +% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 1994 Free Software Foundation, Inc. + +%This texinfo.tex file 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 2, or (at +%your option) any later version. + +%This texinfo.tex file 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 this texinfo.tex file; see the file COPYING. If not, write +%to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, +%USA. + + +%In other words, you are welcome to use, share and improve this program. +%You are forbidden to forbid anyone else to use, share and improve +%what you give them. Help stamp out software-hoarding! + + +% Send bug reports to bug-texinfo@prep.ai.mit.edu. +% Please include a *precise* test case in each bug report. + + +% Make it possible to create a .fmt file just by loading this file: +% if the underlying format is not loaded, start by loading it now. +% Added by gildea November 1993. +\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi + +% This automatically updates the version number based on RCS. +\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} +\deftexinfoversion$Revision: 2.145 $ +\message{Loading texinfo package [Version \texinfoversion]:} + +% If in a .fmt file, print the version number +% and turn on active characters that we couldn't do earlier because +% they might have appeared in the input file name. +\everyjob{\message{[Texinfo version \texinfoversion]}\message{} + \catcode`+=\active \catcode`\_=\active} + +% Save some parts of plain tex whose names we will redefine. + +\let\ptextilde=\~ +\let\ptexlbrace=\{ +\let\ptexrbrace=\} +\let\ptexdots=\dots +\let\ptexdot=\. +\let\ptexstar=\* +\let\ptexend=\end +\let\ptexbullet=\bullet +\let\ptexb=\b +\let\ptexc=\c +\let\ptexi=\i +\let\ptext=\t +\let\ptexl=\l +\let\ptexL=\L + +% Be sure we're in horizontal mode when doing a tie, since we make space +% equivalent to this in @example-like environments. Otherwise, a space +% at the beginning of a line will start with \penalty -- and +% since \penalty is valid in vertical mode, we'd end up putting the +% penalty on the vertical list instead of in the new paragraph. +{\catcode`@ = 11 + \gdef\tie{\leavevmode\penalty\@M\ } +} +\let\~ = \tie % And make it available as @~. + +\message{Basics,} +\chardef\other=12 + +% If this character appears in an error message or help string, it +% starts a new line in the output. +\newlinechar = `^^J + +% Set up fixed words for English. +\ifx\putwordChapter\undefined{\gdef\putwordChapter{Chapter}}\fi% +\def\putwordInfo{Info}% +\ifx\putwordSee\undefined{\gdef\putwordSee{See}}\fi% +\ifx\putwordsee\undefined{\gdef\putwordsee{see}}\fi% +\ifx\putwordfile\undefined{\gdef\putwordfile{file}}\fi% +\ifx\putwordpage\undefined{\gdef\putwordpage{page}}\fi% +\ifx\putwordsection\undefined{\gdef\putwordsection{section}}\fi% +\ifx\putwordSection\undefined{\gdef\putwordSection{Section}}\fi% +\ifx\putwordTableofContents\undefined{\gdef\putwordTableofContents{Table of Contents}}\fi% +\ifx\putwordShortContents\undefined{\gdef\putwordShortContents{Short Contents}}\fi% +\ifx\putwordAppendix\undefined{\gdef\putwordAppendix{Appendix}}\fi% + +% Ignore a token. +% +\def\gobble#1{} + +\hyphenation{ap-pen-dix} +\hyphenation{mini-buf-fer mini-buf-fers} +\hyphenation{eshell} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen \bindingoffset \bindingoffset=0pt +\newdimen \normaloffset \normaloffset=\hoffset +\newdimen\pagewidth \newdimen\pageheight +\pagewidth=\hsize \pageheight=\vsize + +% Sometimes it is convenient to have everything in the transcript file +% and nothing on the terminal. We don't just call \tracingall here, +% since that produces some useless output on the terminal. +% +\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% +\def\loggingall{\tracingcommands2 \tracingstats2 + \tracingpages1 \tracingoutput1 \tracinglostchars1 + \tracingmacros2 \tracingparagraphs1 \tracingrestores1 + \showboxbreadth\maxdimen\showboxdepth\maxdimen +}% + +%---------------------Begin change----------------------- +% +%%%% For @cropmarks command. +% Dimensions to add cropmarks at corners Added by P. A. MacKay, 12 Nov. 1986 +% +\newdimen\cornerlong \newdimen\cornerthick +\newdimen \topandbottommargin +\newdimen \outerhsize \newdimen \outervsize +\cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks +\outerhsize=7in +%\outervsize=9.5in +% Alternative @smallbook page size is 9.25in +\outervsize=9.25in +\topandbottommargin=.75in +% +%---------------------End change----------------------- + +% \onepageout takes a vbox as an argument. Note that \pagecontents +% does insertions itself, but you have to call it yourself. +\chardef\PAGE=255 \output={\onepageout{\pagecontents\PAGE}} +\def\onepageout#1{\hoffset=\normaloffset +\ifodd\pageno \advance\hoffset by \bindingoffset +\else \advance\hoffset by -\bindingoffset\fi +{\escapechar=`\\\relax % makes sure backslash is used in output files. +\shipout\vbox{{\let\hsize=\pagewidth \makeheadline} \pagebody{#1}% +{\let\hsize=\pagewidth \makefootline}}}% +\advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi} + +%%%% For @cropmarks command %%%% + +% Here is a modification of the main output routine for Near East Publications +% This provides right-angle cropmarks at all four corners. +% The contents of the page are centerlined into the cropmarks, +% and any desired binding offset is added as an \hskip on either +% site of the centerlined box. (P. A. MacKay, 12 November, 1986) +% +\def\croppageout#1{\hoffset=0pt % make sure this doesn't mess things up +{\escapechar=`\\\relax % makes sure backslash is used in output files. + \shipout + \vbox to \outervsize{\hsize=\outerhsize + \vbox{\line{\ewtop\hfill\ewtop}} + \nointerlineskip + \line{\vbox{\moveleft\cornerthick\nstop} + \hfill + \vbox{\moveright\cornerthick\nstop}} + \vskip \topandbottommargin + \centerline{\ifodd\pageno\hskip\bindingoffset\fi + \vbox{ + {\let\hsize=\pagewidth \makeheadline} + \pagebody{#1} + {\let\hsize=\pagewidth \makefootline}} + \ifodd\pageno\else\hskip\bindingoffset\fi} + \vskip \topandbottommargin plus1fill minus1fill + \boxmaxdepth\cornerthick + \line{\vbox{\moveleft\cornerthick\nsbot} + \hfill + \vbox{\moveright\cornerthick\nsbot}} + \nointerlineskip + \vbox{\line{\ewbot\hfill\ewbot}} + }} + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi} +% +% Do @cropmarks to get crop marks +\def\cropmarks{\let\onepageout=\croppageout } + +\newinsert\margin \dimen\margin=\maxdimen + +\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} +{\catcode`\@ =11 +\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi +% marginal hacks, juha@viisa.uucp (Juha Takala) +\ifvoid\margin\else % marginal info is present + \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi +\dimen@=\dp#1 \unvbox#1 +\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi +\ifr@ggedbottom \kern-\dimen@ \vfil \fi} +} + +% +% Here are the rules for the cropmarks. Note that they are +% offset so that the space between them is truly \outerhsize or \outervsize +% (P. A. MacKay, 12 November, 1986) +% +\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} +\def\nstop{\vbox + {\hrule height\cornerthick depth\cornerlong width\cornerthick}} +\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} +\def\nsbot{\vbox + {\hrule height\cornerlong depth\cornerthick width\cornerthick}} + +% Parse an argument, then pass it to #1. The argument is the rest of +% the input line (except we remove a trailing comment). #1 should be a +% macro which expects an ordinary undelimited TeX argument. +% +\def\parsearg#1{% + \let\next = #1% + \begingroup + \obeylines + \futurelet\temp\parseargx +} + +% If the next token is an obeyed space (from an @example environment or +% the like), remove it and recurse. Otherwise, we're done. +\def\parseargx{% + % \obeyedspace is defined far below, after the definition of \sepspaces. + \ifx\obeyedspace\temp + \expandafter\parseargdiscardspace + \else + \expandafter\parseargline + \fi +} + +% Remove a single space (as the delimiter token to the macro call). +{\obeyspaces % + \gdef\parseargdiscardspace {\futurelet\temp\parseargx}} + +{\obeylines % + \gdef\parseargline#1^^M{% + \endgroup % End of the group started in \parsearg. + % + % First remove any @c comment, then any @comment. + % Result of each macro is put in \toks0. + \argremovec #1\c\relax % + \expandafter\argremovecomment \the\toks0 \comment\relax % + % + % Call the caller's macro, saved as \next in \parsearg. + \expandafter\next\expandafter{\the\toks0}% + }% +} + +% Since all \c{,omment} does is throw away the argument, we can let TeX +% do that for us. The \relax here is matched by the \relax in the call +% in \parseargline; it could be more or less anything, its purpose is +% just to delimit the argument to the \c. +\def\argremovec#1\c#2\relax{\toks0 = {#1}} +\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}} + +% \argremovec{,omment} might leave us with trailing spaces, though; e.g., +% @end itemize @c foo +% will have two active spaces as part of the argument with the +% `itemize'. Here we remove all active spaces from #1, and assign the +% result to \toks0. +% +% This loses if there are any *other* active characters besides spaces +% in the argument -- _ ^ +, for example -- since they get expanded. +% Fortunately, Texinfo does not define any such commands. (If it ever +% does, the catcode of the characters in questionwill have to be changed +% here.) But this means we cannot call \removeactivespaces as part of +% \argremovec{,omment}, since @c uses \parsearg, and thus the argument +% that \parsearg gets might well have any character at all in it. +% +\def\removeactivespaces#1{% + \begingroup + \ignoreactivespaces + \edef\temp{#1}% + \global\toks0 = \expandafter{\temp}% + \endgroup +} + +% Change the active space to expand to nothing. +% +\begingroup + \obeyspaces + \gdef\ignoreactivespaces{\obeyspaces\let =\empty} +\endgroup + + +\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} + +%% These are used to keep @begin/@end levels from running away +%% Call \inENV within environments (after a \begingroup) +\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi} +\def\ENVcheck{% +\ifENV\errmessage{Still within an environment. Type Return to continue.} +\endgroup\fi} % This is not perfect, but it should reduce lossage + +% @begin foo is the same as @foo, for now. +\newhelp\EMsimple{Type <Return> to continue.} + +\outer\def\begin{\parsearg\beginxxx} + +\def\beginxxx #1{% +\expandafter\ifx\csname #1\endcsname\relax +{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else +\csname #1\endcsname\fi} + +% @end foo executes the definition of \Efoo. +% +\def\end{\parsearg\endxxx} +\def\endxxx #1{% + \removeactivespaces{#1}% + \edef\endthing{\the\toks0}% + % + \expandafter\ifx\csname E\endthing\endcsname\relax + \expandafter\ifx\csname \endthing\endcsname\relax + % There's no \foo, i.e., no ``environment'' foo. + \errhelp = \EMsimple + \errmessage{Undefined command `@end \endthing'}% + \else + \unmatchedenderror\endthing + \fi + \else + % Everything's ok; the right environment has been started. + \csname E\endthing\endcsname + \fi +} + +% There is an environment #1, but it hasn't been started. Give an error. +% +\def\unmatchedenderror#1{% + \errhelp = \EMsimple + \errmessage{This `@end #1' doesn't have a matching `@#1'}% +} + +% Define the control sequence \E#1 to give an unmatched @end error. +% +\def\defineunmatchedend#1{% + \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}% +} + + +% Single-spacing is done by various environments (specifically, in +% \nonfillstart and \quotations). +\newskip\singlespaceskip \singlespaceskip = 12.5pt +\def\singlespace{% + % Why was this kern here? It messes up equalizing space above and below + % environments. --karl, 6may93 + %{\advance \baselineskip by -\singlespaceskip + %\kern \baselineskip}% + \setleading \singlespaceskip +} + +%% Simple single-character @ commands + +% @@ prints an @ +% Kludge this until the fonts are right (grr). +\def\@{{\tt \char '100}} + +% This is turned off because it was never documented +% and you can use @w{...} around a quote to suppress ligatures. +%% Define @` and @' to be the same as ` and ' +%% but suppressing ligatures. +%\def\`{{`}} +%\def\'{{'}} + +% Used to generate quoted braces. + +\def\mylbrace {{\tt \char '173}} +\def\myrbrace {{\tt \char '175}} +\let\{=\mylbrace +\let\}=\myrbrace + +% @: forces normal size whitespace following. +\def\:{\spacefactor=1000 } + +% @* forces a line break. +\def\*{\hfil\break\hbox{}\ignorespaces} + +% @. is an end-of-sentence period. +\def\.{.\spacefactor=3000 } + +% @enddots{} is an end-of-sentence ellipsis. +\gdef\enddots{$\mathinner{\ldotp\ldotp\ldotp\ldotp}$\spacefactor=3000} + +% @! is an end-of-sentence bang. +\gdef\!{!\spacefactor=3000 } + +% @? is an end-of-sentence query. +\gdef\?{?\spacefactor=3000 } + +% @w prevents a word break. Without the \leavevmode, @w at the +% beginning of a paragraph, when TeX is still in vertical mode, would +% produce a whole line of output instead of starting the paragraph. +\def\w#1{\leavevmode\hbox{#1}} + +% @group ... @end group forces ... to be all on one page, by enclosing +% it in a TeX vbox. We use \vtop instead of \vbox to construct the box +% to keep its height that of a normal line. According to the rules for +% \topskip (p.114 of the TeXbook), the glue inserted is +% max (\topskip - \ht (first item), 0). If that height is large, +% therefore, no glue is inserted, and the space between the headline and +% the text is small, which looks bad. +% +\def\group{\begingroup + \ifnum\catcode13=\active \else + \errhelp = \groupinvalidhelp + \errmessage{@group invalid in context where filling is enabled}% + \fi + % + % The \vtop we start below produces a box with normal height and large + % depth; thus, TeX puts \baselineskip glue before it, and (when the + % next line of text is done) \lineskip glue after it. (See p.82 of + % the TeXbook.) Thus, space below is not quite equal to space + % above. But it's pretty close. + \def\Egroup{% + \egroup % End the \vtop. + \endgroup % End the \group. + }% + % + \vtop\bgroup + % We have to put a strut on the last line in case the @group is in + % the midst of an example, rather than completely enclosing it. + % Otherwise, the interline space between the last line of the group + % and the first line afterwards is too small. But we can't put the + % strut in \Egroup, since there it would be on a line by itself. + % Hence this just inserts a strut at the beginning of each line. + \everypar = {\strut}% + % + % Since we have a strut on every line, we don't need any of TeX's + % normal interline spacing. + \offinterlineskip + % + % OK, but now we have to do something about blank + % lines in the input in @example-like environments, which normally + % just turn into \lisppar, which will insert no space now that we've + % turned off the interline space. Simplest is to make them be an + % empty paragraph. + \ifx\par\lisppar + \edef\par{\leavevmode \par}% + % + % Reset ^^M's definition to new definition of \par. + \obeylines + \fi + % + % Do @comment since we are called inside an environment such as + % @example, where each end-of-line in the input causes an + % end-of-line in the output. We don't want the end-of-line after + % the `@group' to put extra space in the output. Since @group + % should appear on a line by itself (according to the Texinfo + % manual), we don't worry about eating any user text. + \comment +} +% +% TeX puts in an \escapechar (i.e., `@') at the beginning of the help +% message, so this ends up printing `@group can only ...'. +% +\newhelp\groupinvalidhelp{% +group can only be used in environments such as @example,^^J% +where each line of input produces a line of output.} + +% @need space-in-mils +% forces a page break if there is not space-in-mils remaining. + +\newdimen\mil \mil=0.001in + +\def\need{\parsearg\needx} + +% Old definition--didn't work. +%\def\needx #1{\par % +%% This method tries to make TeX break the page naturally +%% if the depth of the box does not fit. +%{\baselineskip=0pt% +%\vtop to #1\mil{\vfil}\kern -#1\mil\penalty 10000 +%\prevdepth=-1000pt +%}} + +\def\needx#1{% + % Go into vertical mode, so we don't make a big box in the middle of a + % paragraph. + \par + % + % Don't add any leading before our big empty box, but allow a page + % break, since the best break might be right here. + \allowbreak + \nointerlineskip + \vtop to #1\mil{\vfil}% + % + % TeX does not even consider page breaks if a penalty added to the + % main vertical list is 10000 or more. But in order to see if the + % empty box we just added fits on the page, we must make it consider + % page breaks. On the other hand, we don't want to actually break the + % page after the empty box. So we use a penalty of 9999. + % + % There is an extremely small chance that TeX will actually break the + % page at this \penalty, if there are no other feasible breakpoints in + % sight. (If the user is using lots of big @group commands, which + % almost-but-not-quite fill up a page, TeX will have a hard time doing + % good page breaking, for example.) However, I could not construct an + % example where a page broke at this \penalty; if it happens in a real + % document, then we can reconsider our strategy. + \penalty9999 + % + % Back up by the size of the box, whether we did a page break or not. + \kern -#1\mil + % + % Do not allow a page break right after this kern. + \nobreak +} + +% @br forces paragraph break + +\let\br = \par + +% @dots{} output some dots + +\def\dots{$\ldots$} + +% @page forces the start of a new page + +\def\page{\par\vfill\supereject} + +% @exdent text.... +% outputs text on separate line in roman font, starting at standard page margin + +% This records the amount of indent in the innermost environment. +% That's how much \exdent should take out. +\newskip\exdentamount + +% This defn is used inside fill environments such as @defun. +\def\exdent{\parsearg\exdentyyy} +\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}} + +% This defn is used inside nofill environments such as @example. +\def\nofillexdent{\parsearg\nofillexdentyyy} +\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount +\leftline{\hskip\leftskip{\rm#1}}}} + +%\hbox{{\rm#1}}\hfil\break}} + +% @include file insert text of that file as input. + +\def\include{\parsearg\includezzz} +%Use \input\thisfile to avoid blank after \input, which may be an active +%char (in which case the blank would become the \input argument). +%The grouping keeps the value of \thisfile correct even when @include +%is nested. +\def\includezzz #1{\begingroup +\def\thisfile{#1}\input\thisfile +\endgroup} + +\def\thisfile{} + +% @center line outputs that line, centered + +\def\center{\parsearg\centerzzz} +\def\centerzzz #1{{\advance\hsize by -\leftskip +\advance\hsize by -\rightskip +\centerline{#1}}} + +% @sp n outputs n lines of vertical space + +\def\sp{\parsearg\spxxx} +\def\spxxx #1{\par \vskip #1\baselineskip} + +% @comment ...line which is ignored... +% @c is the same as @comment +% @ignore ... @end ignore is another way to write a comment + +\def\comment{\catcode 64=\other \catcode 123=\other \catcode 125=\other% +\parsearg \commentxxx} + +\def\commentxxx #1{\catcode 64=0 \catcode 123=1 \catcode 125=2 } + +\let\c=\comment + +% Prevent errors for section commands. +% Used in @ignore and in failing conditionals. +\def\ignoresections{% +\let\chapter=\relax +\let\unnumbered=\relax +\let\top=\relax +\let\unnumberedsec=\relax +\let\unnumberedsection=\relax +\let\unnumberedsubsec=\relax +\let\unnumberedsubsection=\relax +\let\unnumberedsubsubsec=\relax +\let\unnumberedsubsubsection=\relax +\let\section=\relax +\let\subsec=\relax +\let\subsubsec=\relax +\let\subsection=\relax +\let\subsubsection=\relax +\let\appendix=\relax +\let\appendixsec=\relax +\let\appendixsection=\relax +\let\appendixsubsec=\relax +\let\appendixsubsection=\relax +\let\appendixsubsubsec=\relax +\let\appendixsubsubsection=\relax +\let\contents=\relax +\let\smallbook=\relax +\let\titlepage=\relax +} + +% Used in nested conditionals, where we have to parse the Texinfo source +% and so want to turn off most commands, in case they are used +% incorrectly. +% +\def\ignoremorecommands{% + \let\defcv = \relax + \let\deffn = \relax + \let\deffnx = \relax + \let\defindex = \relax + \let\defivar = \relax + \let\defmac = \relax + \let\defmethod = \relax + \let\defop = \relax + \let\defopt = \relax + \let\defspec = \relax + \let\deftp = \relax + \let\deftypefn = \relax + \let\deftypefun = \relax + \let\deftypevar = \relax + \let\deftypevr = \relax + \let\defun = \relax + \let\defvar = \relax + \let\defvr = \relax + \let\ref = \relax + \let\xref = \relax + \let\printindex = \relax + \let\pxref = \relax + \let\settitle = \relax + \let\include = \relax + \let\lowersections = \relax + \let\down = \relax + \let\raisesections = \relax + \let\up = \relax + \let\set = \relax + \let\clear = \relax + \let\item = \relax + \let\message = \relax +} + +% Ignore @ignore ... @end ignore. +% +\def\ignore{\doignore{ignore}} + +% Also ignore @ifinfo, @ifhtml, @html, @menu, and @direntry text. +% +\def\ifinfo{\doignore{ifinfo}} +\def\ifhtml{\doignore{ifhtml}} +\def\html{\doignore{html}} +\def\menu{\doignore{menu}} +\def\direntry{\doignore{direntry}} + +% Ignore text until a line `@end #1'. +% +\def\doignore#1{\begingroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define a command to swallow text until we reach `@end #1'. + \long\def\doignoretext##1\end #1{\enddoignore}% + % + % Make sure that spaces turn into tokens that match what \doignoretext wants. + \catcode32 = 10 + % + % And now expand that command. + \doignoretext +} + +% What we do to finish off ignored text. +% +\def\enddoignore{\endgroup\ignorespaces}% + +\newif\ifwarnedobs\warnedobsfalse +\def\obstexwarn{% + \ifwarnedobs\relax\else + % We need to warn folks that they may have trouble with TeX 3.0. + % This uses \immediate\write16 rather than \message to get newlines. + \immediate\write16{} + \immediate\write16{***WARNING*** for users of Unix TeX 3.0!} + \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).} + \immediate\write16{If you are running another version of TeX, relax.} + \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} + \immediate\write16{ Then upgrade your TeX installation if you can.} + \immediate\write16{If you are stuck with version 3.0, run the} + \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} + \immediate\write16{ to use a workaround.} + \immediate\write16{} + \warnedobstrue + \fi +} + +% **In TeX 3.0, setting text in \nullfont hangs tex. For a +% workaround (which requires the file ``dummy.tfm'' to be installed), +% uncomment the following line: +%%%%%\font\nullfont=dummy\let\obstexwarn=\relax + +% Ignore text, except that we keep track of conditional commands for +% purposes of nesting, up to an `@end #1' command. +% +\def\nestedignore#1{% + \obstexwarn + % We must actually expand the ignored text to look for the @end + % command, so that nested ignore constructs work. Thus, we put the + % text into a \vbox and then do nothing with the result. To minimize + % the change of memory overflow, we follow the approach outlined on + % page 401 of the TeXbook: make the current font be a dummy font. + % + \setbox0 = \vbox\bgroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define `@end #1' to end the box, which will in turn undefine the + % @end command again. + \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}% + % + % We are going to be parsing Texinfo commands. Most cause no + % trouble when they are used incorrectly, but some commands do + % complicated argument parsing or otherwise get confused, so we + % undefine them. + % + % We can't do anything about stray @-signs, unfortunately; + % they'll produce `undefined control sequence' errors. + \ignoremorecommands + % + % Set the current font to be \nullfont, a TeX primitive, and define + % all the font commands to also use \nullfont. We don't use + % dummy.tfm, as suggested in the TeXbook, because not all sites + % might have that installed. Therefore, math mode will still + % produce output, but that should be an extremely small amount of + % stuff compared to the main input. + % + \nullfont + \let\tenrm = \nullfont \let\tenit = \nullfont \let\tensl = \nullfont + \let\tenbf = \nullfont \let\tentt = \nullfont \let\smallcaps = \nullfont + \let\tensf = \nullfont + % Similarly for index fonts (mostly for their use in + % smallexample) + \let\indrm = \nullfont \let\indit = \nullfont \let\indsl = \nullfont + \let\indbf = \nullfont \let\indtt = \nullfont \let\indsc = \nullfont + \let\indsf = \nullfont + % + % Don't complain when characters are missing from the fonts. + \tracinglostchars = 0 + % + % Don't bother to do space factor calculations. + \frenchspacing + % + % Don't report underfull hboxes. + \hbadness = 10000 + % + % Do minimal line-breaking. + \pretolerance = 10000 + % + % Do not execute instructions in @tex + \def\tex{\doignore{tex}} +} + +% @set VAR sets the variable VAR to an empty value. +% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. +% +% Since we want to separate VAR from REST-OF-LINE (which might be +% empty), we can't just use \parsearg; we have to insert a space of our +% own to delimit the rest of the line, and then take it out again if we +% didn't need it. +% +\def\set{\parsearg\setxxx} +\def\setxxx#1{\setyyy#1 \endsetyyy} +\def\setyyy#1 #2\endsetyyy{% + \def\temp{#2}% + \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty + \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. + \fi +} +% Can't use \xdef to pre-expand #2 and save some time, since \temp or +% \next or other control sequences that we've defined might get us into +% an infinite loop. Consider `@set foo @cite{bar}'. +\def\setzzz#1#2 \endsetzzz{\expandafter\gdef\csname SET#1\endcsname{#2}} + +% @clear VAR clears (i.e., unsets) the variable VAR. +% +\def\clear{\parsearg\clearxxx} +\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax} + +% @value{foo} gets the text saved in variable foo. +% +\def\value#1{\expandafter + \ifx\csname SET#1\endcsname\relax + {\{No value for ``#1''\}} + \else \csname SET#1\endcsname \fi} + +% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined +% with @set. +% +\def\ifset{\parsearg\ifsetxxx} +\def\ifsetxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifsetfail + \else + \expandafter\ifsetsucceed + \fi +} +\def\ifsetsucceed{\conditionalsucceed{ifset}} +\def\ifsetfail{\nestedignore{ifset}} +\defineunmatchedend{ifset} + +% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been +% defined with @set, or has been undefined with @clear. +% +\def\ifclear{\parsearg\ifclearxxx} +\def\ifclearxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifclearsucceed + \else + \expandafter\ifclearfail + \fi +} +\def\ifclearsucceed{\conditionalsucceed{ifclear}} +\def\ifclearfail{\nestedignore{ifclear}} +\defineunmatchedend{ifclear} + +% @iftex always succeeds; we read the text following, through @end +% iftex). But `@end iftex' should be valid only after an @iftex. +% +\def\iftex{\conditionalsucceed{iftex}} +\defineunmatchedend{iftex} + +% We can't just want to start a group at @iftex (for example) and end it +% at @end iftex, since then @set commands inside the conditional have no +% effect (they'd get reverted at the end of the group). So we must +% define \Eiftex to redefine itself to be its previous value. (We can't +% just define it to fail again with an ``unmatched end'' error, since +% the @ifset might be nested.) +% +\def\conditionalsucceed#1{% + \edef\temp{% + % Remember the current value of \E#1. + \let\nece{prevE#1} = \nece{E#1}% + % + % At the `@end #1', redefine \E#1 to be its previous value. + \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}% + }% + \temp +} + +% We need to expand lots of \csname's, but we don't want to expand the +% control sequences after we've constructed them. +% +\def\nece#1{\expandafter\noexpand\csname#1\endcsname} + +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math means output in math mode. +% We don't use $'s directly in the definition of \math because control +% sequences like \math are expanded when the toc file is written. Then, +% we read the toc file back, the $'s will be normal characters (as they +% should be, according to the definition of Texinfo). So we must use a +% control sequence to switch into and out of math mode. +% +% This isn't quite enough for @math to work properly in indices, but it +% seems unlikely it will ever be needed there. +% +\let\implicitmath = $ +\def\math#1{\implicitmath #1\implicitmath} + +% @bullet and @minus need the same treatment as @math, just above. +\def\bullet{\implicitmath\ptexbullet\implicitmath} +\def\minus{\implicitmath-\implicitmath} + +\def\node{\ENVcheck\parsearg\nodezzz} +\def\nodezzz#1{\nodexxx [#1,]} +\def\nodexxx[#1,#2]{\gdef\lastnode{#1}} +\let\nwnode=\node +\let\lastnode=\relax + +\def\donoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\setref{\lastnode}\fi +\global\let\lastnode=\relax} + +\def\unnumbnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\unnumbsetref{\lastnode}\fi +\global\let\lastnode=\relax} + +\def\appendixnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\appendixsetref{\lastnode}\fi +\global\let\lastnode=\relax} + +\let\refill=\relax + +% @setfilename is done at the beginning of every texinfo file. +% So open here the files we need to have open while reading the input. +% This makes it possible to make a .fmt file for texinfo. +\def\setfilename{% + \readauxfile + \opencontents + \openindices + \fixbackslash % Turn off hack to swallow `\input texinfo'. + \global\let\setfilename=\comment % Ignore extra @setfilename cmds. + \comment % Ignore the actual filename. +} + +\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} + +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + +\message{fonts,} + +% Font-change commands. + +% Texinfo supports the sans serif font style, which plain TeX does not. +% So we set up a \sf analogous to plain's \rm, etc. +\newfam\sffam +\def\sf{\fam=\sffam \tensf} +\let\li = \sf % Sometimes we call it \li, not \sf. + +%% Try out Computer Modern fonts at \magstephalf +\let\mainmagstep=\magstephalf + +% Set the font macro #1 to the font named #2, adding on the +% specified font prefix (normally `cm'). +\def\setfont#1#2{\font#1=\fontprefix#2} + +% Use cm as the default font prefix. +% To specify the font prefix, you must define \fontprefix +% before you read in texinfo.tex. +\ifx\fontprefix\undefined +\def\fontprefix{cm} +\fi + +\ifx\bigger\relax +\let\mainmagstep=\magstep1 +\setfont\textrm{r12} +\setfont\texttt{tt12} +\else +\setfont\textrm{r10 scaled \mainmagstep} +\setfont\texttt{tt10 scaled \mainmagstep} +\fi +% Instead of cmb10, you many want to use cmbx10. +% cmbx10 is a prettier font on its own, but cmb10 +% looks better when embedded in a line with cmr10. +\setfont\textbf{b10 scaled \mainmagstep} +\setfont\textit{ti10 scaled \mainmagstep} +\setfont\textsl{sl10 scaled \mainmagstep} +\setfont\textsf{ss10 scaled \mainmagstep} +\setfont\textsc{csc10 scaled \mainmagstep} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep + +% A few fonts for @defun, etc. +\setfont\defbf{bx10 scaled \magstep1} %was 1314 +\setfont\deftt{tt10 scaled \magstep1} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} + +% Fonts for indices and small examples. +% We actually use the slanted font rather than the italic, +% because texinfo normally uses the slanted fonts for that. +% Do not make many font distinctions in general in the index, since they +% aren't very useful. +\setfont\ninett{tt9} +\setfont\indrm{r9} +\setfont\indit{sl9} +\let\indsl=\indit +\let\indtt=\ninett +\let\indsf=\indrm +\let\indbf=\indrm +\setfont\indsc{csc10 at 9pt} +\font\indi=cmmi9 +\font\indsy=cmsy9 + +% Fonts for headings +\setfont\chaprm{bx12 scaled \magstep2} +\setfont\chapit{ti12 scaled \magstep2} +\setfont\chapsl{sl12 scaled \magstep2} +\setfont\chaptt{tt12 scaled \magstep2} +\setfont\chapsf{ss12 scaled \magstep2} +\let\chapbf=\chaprm +\setfont\chapsc{csc10 scaled\magstep3} +\font\chapi=cmmi12 scaled \magstep2 +\font\chapsy=cmsy10 scaled \magstep3 + +\setfont\secrm{bx12 scaled \magstep1} +\setfont\secit{ti12 scaled \magstep1} +\setfont\secsl{sl12 scaled \magstep1} +\setfont\sectt{tt12 scaled \magstep1} +\setfont\secsf{ss12 scaled \magstep1} +\setfont\secbf{bx12 scaled \magstep1} +\setfont\secsc{csc10 scaled\magstep2} +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 + +% \setfont\ssecrm{bx10 scaled \magstep1} % This size an font looked bad. +% \setfont\ssecit{cmti10 scaled \magstep1} % The letters were too crowded. +% \setfont\ssecsl{sl10 scaled \magstep1} +% \setfont\ssectt{tt10 scaled \magstep1} +% \setfont\ssecsf{ss10 scaled \magstep1} + +%\setfont\ssecrm{b10 scaled 1315} % Note the use of cmb rather than cmbx. +%\setfont\ssecit{ti10 scaled 1315} % Also, the size is a little larger than +%\setfont\ssecsl{sl10 scaled 1315} % being scaled magstep1. +%\setfont\ssectt{tt10 scaled 1315} +%\setfont\ssecsf{ss10 scaled 1315} + +%\let\ssecbf=\ssecrm + +\setfont\ssecrm{bx12 scaled \magstephalf} +\setfont\ssecit{ti12 scaled \magstephalf} +\setfont\ssecsl{sl12 scaled \magstephalf} +\setfont\ssectt{tt12 scaled \magstephalf} +\setfont\ssecsf{ss12 scaled \magstephalf} +\setfont\ssecbf{bx12 scaled \magstephalf} +\setfont\ssecsc{csc10 scaled \magstep1} +\font\sseci=cmmi12 scaled \magstephalf +\font\ssecsy=cmsy10 scaled \magstep1 +% The smallcaps and symbol fonts should actually be scaled \magstep1.5, +% but that is not a standard magnification. + +% Fonts for title page: +\setfont\titlerm{bx12 scaled \magstep3} +\let\authorrm = \secrm + +% In order for the font changes to affect most math symbols and letters, +% we have to define the \textfont of the standard families. Since +% texinfo doesn't allow for producing subscripts and superscripts, we +% don't bother to reset \scriptfont and \scriptscriptfont (which would +% also require loading a lot more fonts). +% +\def\resetmathfonts{% + \textfont0 = \tenrm \textfont1 = \teni \textfont2 = \tensy + \textfont\itfam = \tenit \textfont\slfam = \tensl \textfont\bffam = \tenbf + \textfont\ttfam = \tentt \textfont\sffam = \tensf +} + + +% The font-changing commands redefine the meanings of \tenSTYLE, instead +% of just \STYLE. We do this so that font changes will continue to work +% in math mode, where it is the current \fam that is relevant in most +% cases, not the current. Plain TeX does, for example, +% \def\bf{\fam=\bffam \tenbf} By redefining \tenbf, we obviate the need +% to redefine \bf itself. +\def\textfonts{% + \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl + \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \resetmathfonts} +\def\chapfonts{% + \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl + \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc + \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy + \resetmathfonts} +\def\secfonts{% + \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl + \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy + \resetmathfonts} +\def\subsecfonts{% + \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl + \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy + \resetmathfonts} +\def\indexfonts{% + \let\tenrm=\indrm \let\tenit=\indit \let\tensl=\indsl + \let\tenbf=\indbf \let\tentt=\indtt \let\smallcaps=\indsc + \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy + \resetmathfonts} + +% Set up the default fonts, so we can use them for creating boxes. +% +\textfonts + +% Count depth in font-changes, for error checks +\newcount\fontdepth \fontdepth=0 + +% Fonts for short table of contents. +\setfont\shortcontrm{r12} +\setfont\shortcontbf{bx12} +\setfont\shortcontsl{sl12} + +%% Add scribe-like font environments, plus @l for inline lisp (usually sans +%% serif) and @ii for TeX italic + +% \smartitalic{ARG} outputs arg in italics, followed by an italic correction +% unless the following character is such as not to need one. +\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi} +\def\smartitalic#1{{\sl #1}\futurelet\next\smartitalicx} + +\let\i=\smartitalic +\let\var=\smartitalic +\let\dfn=\smartitalic +\let\emph=\smartitalic +\let\cite=\smartitalic + +\def\b#1{{\bf #1}} +\let\strong=\b + +% We can't just use \exhyphenpenalty, because that only has effect at +% the end of a paragraph. Restore normal hyphenation at the end of the +% group within which \nohyphenation is presumably called. +% +\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} +\def\restorehyphenation{\hyphenchar\font = `- } + +\def\t#1{% + {\tt \nohyphenation \rawbackslash \frenchspacing #1}% + \null +} +\let\ttfont = \t +%\def\samp #1{`{\tt \rawbackslash \frenchspacing #1}'\null} +\def\samp #1{`\tclose{#1}'\null} +\def\key #1{{\tt \nohyphenation \uppercase{#1}}\null} +\def\ctrl #1{{\tt \rawbackslash \hat}#1} + +\let\file=\samp + +% @code is a modification of @t, +% which makes spaces the same size as normal in the surrounding text. +\def\tclose#1{% + {% + % Change normal interword space to be same as for the current font. + \spaceskip = \fontdimen2\font + % + % Switch to typewriter. + \tt + % + % But `\ ' produces the large typewriter interword space. + \def\ {{\spaceskip = 0pt{} }}% + % + % Turn off hyphenation. + \nohyphenation + % + \rawbackslash + \frenchspacing + #1% + }% + \null +} + +% We *must* turn on hyphenation at `-' and `_' in \code. +% Otherwise, it is too hard to avoid overful hboxes +% in the Emacs manual, the Library manual, etc. + +% Unfortunately, TeX uses one parameter (\hyphenchar) to control +% both hyphenation at - and hyphenation within words. +% We must therefore turn them both off (\tclose does that) +% and arrange explicitly to hyphenate an a dash. +% -- rms. +{ +\catcode`\-=\active +\catcode`\_=\active +\global\def\code{\begingroup \catcode`\-=\active \let-\codedash \catcode`\_=\active \let_\codeunder \codex} +% The following is used by \doprintindex to insure that long function names +% wrap around. It is necessary for - and _ to be active before the index is +% read from the file, as \entry parses the arguments long before \code is +% ever called. -- mycroft +\global\def\indexbreaks{\catcode`\-=\active \let-\realdash \catcode`\_=\active \let_\realunder} +} +\def\realdash{-} +\def\realunder{_} +\def\codedash{-\discretionary{}{}{}} +\def\codeunder{\normalunderscore\discretionary{}{}{}} +\def\codex #1{\tclose{#1}\endgroup} + +%\let\exp=\tclose %Was temporary + +% @kbd is like @code, except that if the argument is just one @key command, +% then @kbd has no effect. + +\def\xkey{\key} +\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% +\ifx\one\xkey\ifx\threex\three \key{#2}% +\else\tclose{\look}\fi +\else\tclose{\look}\fi} + +% Typeset a dimension, e.g., `in' or `pt'. The only reason for the +% argument is to make the input look right: @dmn{pt} instead of +% @dmn{}pt. +% +\def\dmn#1{\thinspace #1} + +\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} + +\def\l#1{{\li #1}\null} % + +\def\r#1{{\rm #1}} % roman font +% Use of \lowercase was suggested. +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +\message{page headings,} + +\newskip\titlepagetopglue \titlepagetopglue = 1.5in +\newskip\titlepagebottomglue \titlepagebottomglue = 2pc + +% First the title page. Must do @settitle before @titlepage. +\def\titlefont#1{{\titlerm #1}} + +\newif\ifseenauthor +\newif\iffinishedtitlepage + +\def\shorttitlepage{\parsearg\shorttitlepagezzz} +\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% + \endgroup\page\hbox{}\page} + +\def\titlepage{\begingroup \parindent=0pt \textfonts + \let\subtitlerm=\tenrm +% I deinstalled the following change because \cmr12 is undefined. +% This change was not in the ChangeLog anyway. --rms. +% \let\subtitlerm=\cmr12 + \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% + % + \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}% + % + % Leave some space at the very top of the page. + \vglue\titlepagetopglue + % + % Now you can print the title using @title. + \def\title{\parsearg\titlezzz}% + \def\titlezzz##1{\leftline{\titlefont{##1}} + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% + % No rule at page bottom unless we print one at the top with @title. + \finishedtitlepagetrue + % + % Now you can put text using @subtitle. + \def\subtitle{\parsearg\subtitlezzz}% + \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}% + % + % @author should come last, but may come many times. + \def\author{\parsearg\authorzzz}% + \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi + {\authorfont \leftline{##1}}}% + % + % Most title ``pages'' are actually two pages long, with space + % at the top of the second. We don't want the ragged left on the second. + \let\oldpage = \page + \def\page{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + \oldpage + \let\page = \oldpage + \hbox{}}% +% \def\page{\oldpage \hbox{}} +} + +\def\Etitlepage{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + % It is important to do the page break before ending the group, + % because the headline and footline are only empty inside the group. + % If we use the new definition of \page, we always get a blank page + % after the title page, which we certainly don't want. + \oldpage + \endgroup + \HEADINGSon +} + +\def\finishtitlepage{% + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue +} + +%%% Set up page headings and footings. + +\let\thispage=\folio + +\newtoks \evenheadline % Token sequence for heading line of even pages +\newtoks \oddheadline % Token sequence for heading line of odd pages +\newtoks \evenfootline % Token sequence for footing line of even pages +\newtoks \oddfootline % Token sequence for footing line of odd pages + +% Now make Tex use those variables +\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline + \else \the\evenheadline \fi}} +\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline + \else \the\evenfootline \fi}\HEADINGShook} +\let\HEADINGShook=\relax + +% Commands to set those variables. +% For example, this is what @headings on does +% @evenheading @thistitle|@thispage|@thischapter +% @oddheading @thischapter|@thispage|@thistitle +% @evenfooting @thisfile|| +% @oddfooting ||@thisfile + +\def\evenheading{\parsearg\evenheadingxxx} +\def\oddheading{\parsearg\oddheadingxxx} +\def\everyheading{\parsearg\everyheadingxxx} + +\def\evenfooting{\parsearg\evenfootingxxx} +\def\oddfooting{\parsearg\oddfootingxxx} +\def\everyfooting{\parsearg\everyfootingxxx} + +{\catcode`\@=0 % + +\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish} +\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish} +\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{% +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyheadingxxx #1{\everyheadingyyy #1@|@|@|@|\finish} +\gdef\everyheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}} +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish} +\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish} +\gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{% +\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyfootingxxx #1{\everyfootingyyy #1@|@|@|@|\finish} +\gdef\everyfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}} +\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} +% +}% unbind the catcode of @. + +% @headings double turns headings on for double-sided printing. +% @headings single turns headings on for single-sided printing. +% @headings off turns them off. +% @headings on same as @headings double, retained for compatibility. +% @headings after turns on double-sided headings after this page. +% @headings doubleafter turns on double-sided headings after this page. +% @headings singleafter turns on single-sided headings after this page. +% By default, they are off. + +\def\headings #1 {\csname HEADINGS#1\endcsname} + +\def\HEADINGSoff{ +\global\evenheadline={\hfil} \global\evenfootline={\hfil} +\global\oddheadline={\hfil} \global\oddfootline={\hfil}} +\HEADINGSoff +% When we turn headings on, set the page number to 1. +% For double-sided printing, put current file name in lower left corner, +% chapter name on inside top of right hand pages, document +% title on inside top of left hand pages, and page numbers on outside top +% edge of all pages. +\def\HEADINGSdouble{ +%\pagealignmacro +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} +% For single-sided printing, chapter title goes across top left of page, +% page number on top right. +\def\HEADINGSsingle{ +%\pagealignmacro +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} +\def\HEADINGSon{\HEADINGSdouble} + +\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} +\let\HEADINGSdoubleafter=\HEADINGSafter +\def\HEADINGSdoublex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} + +\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} +\def\HEADINGSsinglex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} + +% Subroutines used in generating headings +% Produces Day Month Year style of output. +\def\today{\number\day\space +\ifcase\month\or +January\or February\or March\or April\or May\or June\or +July\or August\or September\or October\or November\or December\fi +\space\number\year} + +% Use this if you want the Month Day, Year style of output. +%\def\today{\ifcase\month\or +%January\or February\or March\or April\or May\or June\or +%July\or August\or September\or October\or November\or December\fi +%\space\number\day, \number\year} + +% @settitle line... specifies the title of the document, for headings +% It generates no output of its own + +\def\thistitle{No Title} +\def\settitle{\parsearg\settitlezzz} +\def\settitlezzz #1{\gdef\thistitle{#1}} + +\message{tables,} + +% @tabs -- simple alignment + +% These don't work. For one thing, \+ is defined as outer. +% So these macros cannot even be defined. + +%\def\tabs{\parsearg\tabszzz} +%\def\tabszzz #1{\settabs\+#1\cr} +%\def\tabline{\parsearg\tablinezzz} +%\def\tablinezzz #1{\+#1\cr} +%\def\&{&} + +% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(x). + +% default indentation of table text +\newdimen\tableindent \tableindent=.8in +% default indentation of @itemize and @enumerate text +\newdimen\itemindent \itemindent=.3in +% margin between end of table item and start of table text. +\newdimen\itemmargin \itemmargin=.1in + +% used internally for \itemindent minus \itemmargin +\newdimen\itemmax + +% Note @table, @vtable, and @vtable define @item, @itemx, etc., with +% these defs. +% They also define \itemindex +% to index the item name in whatever manner is desired (perhaps none). + +\newif\ifitemxneedsnegativevskip + +\def\itemxpar{\par\ifitemxneedsnegativevskip\vskip-\parskip\nobreak\fi} + +\def\internalBitem{\smallbreak \parsearg\itemzzz} +\def\internalBitemx{\itemxpar \parsearg\itemzzz} + +\def\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz} +\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz} + +\def\internalBkitem{\smallbreak \parsearg\kitemzzz} +\def\internalBkitemx{\itemxpar \parsearg\kitemzzz} + +\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}% + \itemzzz {#1}} + +\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}% + \itemzzz {#1}} + +\def\itemzzz #1{\begingroup % + \advance\hsize by -\rightskip + \advance\hsize by -\tableindent + \setbox0=\hbox{\itemfont{#1}}% + \itemindex{#1}% + \nobreak % This prevents a break before @itemx. + % + % Be sure we are not still in the middle of a paragraph. + %{\parskip = 0in + %\par + %}% + % + % If the item text does not fit in the space we have, put it on a line + % by itself, and do not allow a page break either before or after that + % line. We do not start a paragraph here because then if the next + % command is, e.g., @kindex, the whatsit would get put into the + % horizontal list on a line by itself, resulting in extra blank space. + \ifdim \wd0>\itemmax + % + % Make this a paragraph so we get the \parskip glue and wrapping, + % but leave it ragged-right. + \begingroup + \advance\leftskip by-\tableindent + \advance\hsize by\tableindent + \advance\rightskip by0pt plus1fil + \leavevmode\unhbox0\par + \endgroup + % + % We're going to be starting a paragraph, but we don't want the + % \parskip glue -- logically it's part of the @item we just started. + \nobreak \vskip-\parskip + % + % Stop a page break at the \parskip glue coming up. Unfortunately + % we can't prevent a possible page break at the following + % \baselineskip glue. + \nobreak + \endgroup + \itemxneedsnegativevskipfalse + \else + % The item text fits into the space. Start a paragraph, so that the + % following text (if any) will end up on the same line. Since that + % text will be indented by \tableindent, we make the item text be in + % a zero-width box. + \noindent + \rlap{\hskip -\tableindent\box0}\ignorespaces% + \endgroup% + \itemxneedsnegativevskiptrue% + \fi +} + +\def\item{\errmessage{@item while not in a table}} +\def\itemx{\errmessage{@itemx while not in a table}} +\def\kitem{\errmessage{@kitem while not in a table}} +\def\kitemx{\errmessage{@kitemx while not in a table}} +\def\xitem{\errmessage{@xitem while not in a table}} +\def\xitemx{\errmessage{@xitemx while not in a table}} + +%% Contains a kludge to get @end[description] to work +\def\description{\tablez{\dontindex}{1}{}{}{}{}} + +\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex} +{\obeylines\obeyspaces% +\gdef\tablex #1^^M{% +\tabley\dontindex#1 \endtabley}} + +\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex} +{\obeylines\obeyspaces% +\gdef\ftablex #1^^M{% +\tabley\fnitemindex#1 \endtabley +\def\Eftable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex} +{\obeylines\obeyspaces% +\gdef\vtablex #1^^M{% +\tabley\vritemindex#1 \endtabley +\def\Evtable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\dontindex #1{} +\def\fnitemindex #1{\doind {fn}{\code{#1}}}% +\def\vritemindex #1{\doind {vr}{\code{#1}}}% + +{\obeyspaces % +\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup% +\tablez{#1}{#2}{#3}{#4}{#5}{#6}}} + +\def\tablez #1#2#3#4#5#6{% +\aboveenvbreak % +\begingroup % +\def\Edescription{\Etable}% Neccessary kludge. +\let\itemindex=#1% +\ifnum 0#3>0 \advance \leftskip by #3\mil \fi % +\ifnum 0#4>0 \tableindent=#4\mil \fi % +\ifnum 0#5>0 \advance \rightskip by #5\mil \fi % +\def\itemfont{#2}% +\itemmax=\tableindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \tableindent % +\exdentamount=\tableindent +\parindent = 0pt +\parskip = \smallskipamount +\ifdim \parskip=0pt \parskip=2pt \fi% +\def\Etable{\endgraf\afterenvbreak\endgroup}% +\let\item = \internalBitem % +\let\itemx = \internalBitemx % +\let\kitem = \internalBkitem % +\let\kitemx = \internalBkitemx % +\let\xitem = \internalBxitem % +\let\xitemx = \internalBxitemx % +} + +% This is the counter used by @enumerate, which is really @itemize + +\newcount \itemno + +\def\itemize{\parsearg\itemizezzz} + +\def\itemizezzz #1{% + \begingroup % ended by the @end itemsize + \itemizey {#1}{\Eitemize} +} + +\def\itemizey #1#2{% +\aboveenvbreak % +\itemmax=\itemindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \itemindent % +\exdentamount=\itemindent +\parindent = 0pt % +\parskip = \smallskipamount % +\ifdim \parskip=0pt \parskip=2pt \fi% +\def#2{\endgraf\afterenvbreak\endgroup}% +\def\itemcontents{#1}% +\let\item=\itemizeitem} + +% Set sfcode to normal for the chars that usually have another value. +% These are `.?!:;,' +\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000 + \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 } + +% \splitoff TOKENS\endmark defines \first to be the first token in +% TOKENS, and \rest to be the remainder. +% +\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% + +% Allow an optional argument of an uppercase letter, lowercase letter, +% or number, to specify the first label in the enumerated list. No +% argument is the same as `1'. +% +\def\enumerate{\parsearg\enumeratezzz} +\def\enumeratezzz #1{\enumeratey #1 \endenumeratey} +\def\enumeratey #1 #2\endenumeratey{% + \begingroup % ended by the @end enumerate + % + % If we were given no argument, pretend we were given `1'. + \def\thearg{#1}% + \ifx\thearg\empty \def\thearg{1}\fi + % + % Detect if the argument is a single token. If so, it might be a + % letter. Otherwise, the only valid thing it can be is a number. + % (We will always have one token, because of the test we just made. + % This is a good thing, since \splitoff doesn't work given nothing at + % all -- the first parameter is undelimited.) + \expandafter\splitoff\thearg\endmark + \ifx\rest\empty + % Only one token in the argument. It could still be anything. + % A ``lowercase letter'' is one whose \lccode is nonzero. + % An ``uppercase letter'' is one whose \lccode is both nonzero, and + % not equal to itself. + % Otherwise, we assume it's a number. + % + % We need the \relax at the end of the \ifnum lines to stop TeX from + % continuing to look for a <number>. + % + \ifnum\lccode\expandafter`\thearg=0\relax + \numericenumerate % a number (we hope) + \else + % It's a letter. + \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax + \lowercaseenumerate % lowercase letter + \else + \uppercaseenumerate % uppercase letter + \fi + \fi + \else + % Multiple tokens in the argument. We hope it's a number. + \numericenumerate + \fi +} + +% An @enumerate whose labels are integers. The starting integer is +% given in \thearg. +% +\def\numericenumerate{% + \itemno = \thearg + \startenumeration{\the\itemno}% +} + +% The starting (lowercase) letter is in \thearg. +\def\lowercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more lowercase letters in @enumerate; get a bigger + alphabet}% + \fi + \char\lccode\itemno + }% +} + +% The starting (uppercase) letter is in \thearg. +\def\uppercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more uppercase letters in @enumerate; get a bigger + alphabet} + \fi + \char\uccode\itemno + }% +} + +% Call itemizey, adding a period to the first argument and supplying the +% common last two arguments. Also subtract one from the initial value in +% \itemno, since @item increments \itemno. +% +\def\startenumeration#1{% + \advance\itemno by -1 + \itemizey{#1.}\Eenumerate\flushcr +} + +% @alphaenumerate and @capsenumerate are abbreviations for giving an arg +% to @enumerate. +% +\def\alphaenumerate{\enumerate{a}} +\def\capsenumerate{\enumerate{A}} +\def\Ealphaenumerate{\Eenumerate} +\def\Ecapsenumerate{\Eenumerate} + +% Definition of @item while inside @itemize. + +\def\itemizeitem{% +\advance\itemno by 1 +{\let\par=\endgraf \smallbreak}% +\ifhmode \errmessage{\in hmode at itemizeitem}\fi +{\parskip=0in \hskip 0pt +\hbox to 0pt{\hss \itemcontents\hskip \itemmargin}% +\vadjust{\penalty 1200}}% +\flushcr} + +% @multitable macros +% Amy Hendrickson, 8/18/94 +% +% @multitable ... @endmultitable will make as many columns as desired. +% Contents of each column will wrap at width given in preamble. Width +% can be specified either with sample text given in a template line, +% or in percent of \hsize, the current width of text on page. + +% Table can continue over pages but will only break between lines. + +% To make preamble: +% +% Either define widths of columns in terms of percent of \hsize: +% @multitable @percentofhsize .2 .3 .5 +% @item ... +% +% Numbers following @percentofhsize are the percent of the total +% current hsize to be used for each column. You may use as many +% columns as desired. + +% Or use a template: +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item ... +% using the widest term desired in each column. + + +% Each new table line starts with @item, each subsequent new column +% starts with @tab. Empty columns may be produced by supplying @tab's +% with nothing between them for as many times as empty columns are needed, +% ie, @tab@tab@tab will produce two empty columns. + +% @item, @tab, @multicolumn or @endmulticolumn do not need to be on their +% own lines, but it will not hurt if they are. + +% Sample multitable: + +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item first col stuff @tab second col stuff @tab third col +% @item +% first col stuff +% @tab +% second col stuff +% @tab +% third col +% @item first col stuff @tab second col stuff +% @tab Many paragraphs of text may be used in any column. +% +% They will wrap at the width determined by the template. +% @item@tab@tab This will be in third column. +% @endmultitable + +% Default dimensions may be reset by user. +% @intableparskip will set vertical space between paragraphs in table. +% @intableparindent will set paragraph indent in table. +% @spacebetweencols will set horizontal space to be left between columns. +% @spacebetweenlines will set vertical space to be left between lines. + +%%%% +% Dimensions + +\newdimen\intableparskip +\newdimen\intableparindent +\newdimen\spacebetweencols +\newdimen\spacebetweenlines +\intableparskip=0pt +\intableparindent=6pt +\spacebetweencols=12pt +\spacebetweenlines=12pt + +%%%% +% Macros used to set up halign preamble: +\let\endsetuptable\relax +\def\xendsetuptable{\endsetuptable} +\let\percentofhsize\relax +\def\xpercentofhsize{\percentofhsize} +\newif\ifsetpercent + +\newcount\colcount +\def\setuptable#1{\def\firstarg{#1}% +\ifx\firstarg\xendsetuptable\let\go\relax% +\else + \ifx\firstarg\xpercentofhsize\global\setpercenttrue% + \else + \ifsetpercent + \if#1.\else% + \global\advance\colcount by1 % + \expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% + \fi + \else + \global\advance\colcount by1 + \setbox0=\hbox{#1}% + \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% + \fi% + \fi% + \let\go\setuptable% +\fi\go} +%%%% +% multitable syntax +\def\tab{&} + +%%%% +% @multitable ... @endmultitable definitions: + +\def\multitable#1\item{\bgroup +\let\item\cr +\tolerance=9500 +\hbadness=9500 +\parskip=\intableparskip +\parindent=\intableparindent +\overfullrule=0pt +\global\colcount=0\relax% +\def\Emultitable{\global\setpercentfalse\global\everycr{}\cr\egroup\egroup}% + % To parse everything between @multitable and @item : +\def\one{#1}\expandafter\setuptable\one\endsetuptable + % Need to reset this to 0 after \setuptable. +\global\colcount=0\relax% + % + % This preamble sets up a generic column definition, which will + % be used as many times as user calls for columns. + % \vtop will set a single line and will also let text wrap and + % continue for many paragraphs if desired. +\halign\bgroup&\global\advance\colcount by 1\relax% +\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname + % In order to keep entries from bumping into each other + % we will add a \leftskip of \spacebetweencols to all columns after + % the first one. + % If a template has been used, we will add \spacebetweencols + % to the width of each template entry. + % If user has set preamble in terms of percent of \hsize + % we will use that dimension as the width of the column, and + % the \leftskip will keep entries from bumping into each other. + % Table will start at left margin and final column will justify at + % right margin. +\ifnum\colcount=1 +\else + \ifsetpercent + \else + % If user has <not> set preamble in terms of percent of \hsize + % we will advance \hsize by \spacebetweencols + \advance\hsize by \spacebetweencols + \fi + % In either case we will make \leftskip=\spacebetweencols: +\leftskip=\spacebetweencols +\fi +\noindent##}\cr% + % \everycr will reset column counter, \colcount, at the end of + % each line. Every column entry will cause \colcount to advance by one. + % The table preamble + % looks at the current \colcount to find the correct column width. +\global\everycr{\noalign{\nointerlineskip\vskip\spacebetweenlines +\filbreak%% keeps underfull box messages off when table breaks over pages. +\global\colcount=0\relax}}} + +\message{indexing,} +% Index generation facilities + +% Define \newwrite to be identical to plain tex's \newwrite +% except not \outer, so it can be used within \newindex. +{\catcode`\@=11 +\gdef\newwrite{\alloc@7\write\chardef\sixt@@n}} + +% \newindex {foo} defines an index named foo. +% It automatically defines \fooindex such that +% \fooindex ...rest of line... puts an entry in the index foo. +% It also defines \fooindfile to be the number of the output channel for +% the file that accumulates this index. The file's extension is foo. +% The name of an index should be no more than 2 characters long +% for the sake of vms. + +\def\newindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#1}} +} + +% @defindex foo == \newindex{foo} + +\def\defindex{\parsearg\newindex} + +% Define @defcodeindex, like @defindex except put all entries in @code. + +\def\newcodeindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#1}} +} + +\def\defcodeindex{\parsearg\newcodeindex} + +% @synindex foo bar makes index foo feed into index bar. +% Do this instead of @defindex foo if you don't want it as a separate index. +\def\synindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#2}}% +} + +% @syncodeindex foo bar similar, but put all entries made for index foo +% inside @code. +\def\syncodeindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#2}}% +} + +% Define \doindex, the driver for all \fooindex macros. +% Argument #1 is generated by the calling \fooindex macro, +% and it is "foo", the name of the index. + +% \doindex just uses \parsearg; it calls \doind for the actual work. +% This is because \doind is more useful to call from other macros. + +% There is also \dosubind {index}{topic}{subtopic} +% which makes an entry in a two-level index such as the operation index. + +\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} +\def\singleindexer #1{\doind{\indexname}{#1}} + +% like the previous two, but they put @code around the argument. +\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} +\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} + +\def\indexdummies{% +% Take care of the plain tex accent commands. +\def\"{\realbackslash "}% +\def\`{\realbackslash `}% +\def\'{\realbackslash '}% +\def\^{\realbackslash ^}% +\def\~{\realbackslash ~}% +\def\={\realbackslash =}% +\def\b{\realbackslash b}% +\def\c{\realbackslash c}% +\def\d{\realbackslash d}% +\def\u{\realbackslash u}% +\def\v{\realbackslash v}% +\def\H{\realbackslash H}% +% Take care of the plain tex special European modified letters. +\def\oe{\realbackslash oe}% +\def\ae{\realbackslash ae}% +\def\aa{\realbackslash aa}% +\def\OE{\realbackslash OE}% +\def\AE{\realbackslash AE}% +\def\AA{\realbackslash AA}% +\def\o{\realbackslash o}% +\def\O{\realbackslash O}% +\def\l{\realbackslash l}% +\def\L{\realbackslash L}% +\def\ss{\realbackslash ss}% +% Take care of texinfo commands likely to appear in an index entry. +\def\_{{\realbackslash _}}% +\def\w{\realbackslash w }% +\def\bf{\realbackslash bf }% +\def\rm{\realbackslash rm }% +\def\sl{\realbackslash sl }% +\def\sf{\realbackslash sf}% +\def\tt{\realbackslash tt}% +\def\gtr{\realbackslash gtr}% +\def\less{\realbackslash less}% +\def\hat{\realbackslash hat}% +\def\char{\realbackslash char}% +\def\TeX{\realbackslash TeX}% +\def\dots{\realbackslash dots }% +\def\copyright{\realbackslash copyright }% +\def\tclose##1{\realbackslash tclose {##1}}% +\def\code##1{\realbackslash code {##1}}% +\def\samp##1{\realbackslash samp {##1}}% +\def\t##1{\realbackslash r {##1}}% +\def\r##1{\realbackslash r {##1}}% +\def\i##1{\realbackslash i {##1}}% +\def\b##1{\realbackslash b {##1}}% +\def\cite##1{\realbackslash cite {##1}}% +\def\key##1{\realbackslash key {##1}}% +\def\file##1{\realbackslash file {##1}}% +\def\var##1{\realbackslash var {##1}}% +\def\kbd##1{\realbackslash kbd {##1}}% +\def\dfn##1{\realbackslash dfn {##1}}% +\def\emph##1{\realbackslash emph {##1}}% +} + +% \indexnofonts no-ops all font-change commands. +% This is used when outputting the strings to sort the index by. +\def\indexdummyfont#1{#1} +\def\indexdummytex{TeX} +\def\indexdummydots{...} + +\def\indexnofonts{% +% Just ignore accents. +\let\"=\indexdummyfont +\let\`=\indexdummyfont +\let\'=\indexdummyfont +\let\^=\indexdummyfont +\let\~=\indexdummyfont +\let\==\indexdummyfont +\let\b=\indexdummyfont +\let\c=\indexdummyfont +\let\d=\indexdummyfont +\let\u=\indexdummyfont +\let\v=\indexdummyfont +\let\H=\indexdummyfont +% Take care of the plain tex special European modified letters. +\def\oe{oe}% +\def\ae{ae}% +\def\aa{aa}% +\def\OE{OE}% +\def\AE{AE}% +\def\AA{AA}% +\def\o{o}% +\def\O{O}% +\def\l{l}% +\def\L{L}% +\def\ss{ss}% +\let\w=\indexdummyfont +\let\t=\indexdummyfont +\let\r=\indexdummyfont +\let\i=\indexdummyfont +\let\b=\indexdummyfont +\let\emph=\indexdummyfont +\let\strong=\indexdummyfont +\let\cite=\indexdummyfont +\let\sc=\indexdummyfont +%Don't no-op \tt, since it isn't a user-level command +% and is used in the definitions of the active chars like <, >, |... +%\let\tt=\indexdummyfont +\let\tclose=\indexdummyfont +\let\code=\indexdummyfont +\let\file=\indexdummyfont +\let\samp=\indexdummyfont +\let\kbd=\indexdummyfont +\let\key=\indexdummyfont +\let\var=\indexdummyfont +\let\TeX=\indexdummytex +\let\dots=\indexdummydots +} + +% To define \realbackslash, we must make \ not be an escape. +% We must first make another character (@) an escape +% so we do not become unable to do a definition. + +{\catcode`\@=0 \catcode`\\=\other +@gdef@realbackslash{\}} + +\let\indexbackslash=0 %overridden during \printindex. + +\let\SETmarginindex=\relax %initialize! +% workhorse for all \fooindexes +% #1 is name of index, #2 is stuff to put there +\def\doind #1#2{% +% Put the index entry in the margin if desired. +\ifx\SETmarginindex\relax\else% +\insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% +\fi% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% Expand all macros now EXCEPT \folio +\def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now +% so it will be output as is; and it will print as backslash in the indx. +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}}}% +\temp }% +}\penalty\count10}} + +\def\dosubind #1#2#3{% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% +\def\rawbackslashxx{\indexbackslash}% +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2 #3}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}{#3}}}% +\temp }% +}\penalty\count10}} + +% The index entry written in the file actually looks like +% \entry {sortstring}{page}{topic} +% or +% \entry {sortstring}{page}{topic}{subtopic} +% The texindex program reads in these files and writes files +% containing these kinds of lines: +% \initial {c} +% before the first topic whose initial is c +% \entry {topic}{pagelist} +% for a topic that is used without subtopics +% \primary {topic} +% for the beginning of a topic that is used with subtopics +% \secondary {subtopic}{pagelist} +% for each subtopic. + +% Define the user-accessible indexing commands +% @findex, @vindex, @kindex, @cindex. + +\def\findex {\fnindex} +\def\kindex {\kyindex} +\def\cindex {\cpindex} +\def\vindex {\vrindex} +\def\tindex {\tpindex} +\def\pindex {\pgindex} + +\def\cindexsub {\begingroup\obeylines\cindexsub} +{\obeylines % +\gdef\cindexsub "#1" #2^^M{\endgroup % +\dosubind{cp}{#2}{#1}}} + +% Define the macros used in formatting output of the sorted index material. + +% This is what you call to cause a particular index to get printed. +% Write +% @unnumbered Function Index +% @printindex fn + +\def\printindex{\parsearg\doprintindex} + +\def\doprintindex#1{% + \tex + \dobreak \chapheadingskip {10000} + \catcode`\%=\other\catcode`\&=\other\catcode`\#=\other + \catcode`\$=\other + \catcode`\~=\other + \indexbreaks + % + % The following don't help, since the chars were translated + % when the raw index was written, and their fonts were discarded + % due to \indexnofonts. + %\catcode`\"=\active + %\catcode`\^=\active + %\catcode`\_=\active + %\catcode`\|=\active + %\catcode`\<=\active + %\catcode`\>=\active + % % + \def\indexbackslash{\rawbackslashxx} + \indexfonts\rm \tolerance=9500 \advance\baselineskip -1pt + \begindoublecolumns + % + % See if the index file exists and is nonempty. + \openin 1 \jobname.#1s + \ifeof 1 + % \enddoublecolumns gets confused if there is no text in the index, + % and it loses the chapter title and the aux file entries for the + % index. The easiest way to prevent this problem is to make sure + % there is some text. + (Index is nonexistent) + \else + % + % If the index file exists but is empty, then \openin leaves \ifeof + % false. We have to make TeX try to read something from the file, so + % it can discover if there is anything in it. + \read 1 to \temp + \ifeof 1 + (Index is empty) + \else + \input \jobname.#1s + \fi + \fi + \closein 1 + \enddoublecolumns + \Etex +} + +% These macros are used by the sorted index file itself. +% Change them to control the appearance of the index. + +% Same as \bigskipamount except no shrink. +% \balancecolumns gets confused if there is any shrink. +\newskip\initialskipamount \initialskipamount 12pt plus4pt + +\def\initial #1{% +{\let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt +\ifdim\lastskip<\initialskipamount +\removelastskip \penalty-200 \vskip \initialskipamount\fi +\line{\secbf#1\hfill}\kern 2pt\penalty10000}} + +% This typesets a paragraph consisting of #1, dot leaders, and then #2 +% flush to the right margin. It is used for index and table of contents +% entries. The paragraph is indented by \leftskip. +% +\def\entry #1#2{\begingroup + % + % Start a new paragraph if necessary, so our assignments below can't + % affect previous text. + \par + % + % Do not fill out the last line with white space. + \parfillskip = 0in + % + % No extra space above this paragraph. + \parskip = 0in + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 + % + % \hangindent is only relevant when the entry text and page number + % don't both fit on one line. In that case, bob suggests starting the + % dots pretty far over on the line. Unfortunately, a large + % indentation looks wrong when the entry text itself is broken across + % lines. So we use a small indentation and put up with long leaders. + % + % \hangafter is reset to 1 (which is the value we want) at the start + % of each paragraph, so we need not do anything with that. + \hangindent=2em + % + % When the entry text needs to be broken, just fill out the first line + % with blank space. + \rightskip = 0pt plus1fil + % + % Start a ``paragraph'' for the index entry so the line breaking + % parameters we've set above will have an effect. + \noindent + % + % Insert the text of the index entry. TeX will do line-breaking on it. + #1% + % The following is kluged to not output a line of dots in the index if + % there are no page numbers. The next person who breaks this will be + % cursed by a Unix daemon. + \def\tempa{{\rm }}% + \def\tempb{#2}% + \edef\tempc{\tempa}% + \edef\tempd{\tempb}% + \ifx\tempc\tempd\ \else% + % + % If we must, put the page number on a line of its own, and fill out + % this line with blank space. (The \hfil is overwhelmed with the + % fill leaders glue in \indexdotfill if the page number does fit.) + \hfil\penalty50 + \null\nobreak\indexdotfill % Have leaders before the page number. + % + % The `\ ' here is removed by the implicit \unskip that TeX does as + % part of (the primitive) \par. Without it, a spurious underfull + % \hbox ensues. + \ #2% The page number ends the paragraph. + \fi% + \par +\endgroup} + +% Like \dotfill except takes at least 1 em. +\def\indexdotfill{\cleaders + \hbox{$\mathsurround=0pt \mkern1.5mu ${\it .}$ \mkern1.5mu$}\hskip 1em plus 1fill} + +\def\primary #1{\line{#1\hfil}} + +\newskip\secondaryindent \secondaryindent=0.5cm + +\def\secondary #1#2{ +{\parfillskip=0in \parskip=0in +\hangindent =1in \hangafter=1 +\noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par +}} + +%% Define two-column mode, which is used in indexes. +%% Adapted from the TeXbook, page 416. +\catcode `\@=11 + +\newbox\partialpage + +\newdimen\doublecolumnhsize + +\def\begindoublecolumns{\begingroup + % Grab any single-column material above us. + \output = {\global\setbox\partialpage + =\vbox{\unvbox255\kern -\topskip \kern \baselineskip}}% + \eject + % + % Now switch to the double-column output routine. + \output={\doublecolumnout}% + % + % Change the page size parameters. We could do this once outside this + % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 + % format, but then we repeat the same computation. Repeating a couple + % of assignments once per index is clearly meaningless for the + % execution time, so we may as well do it once. + % + % First we halve the line length, less a little for the gutter between + % the columns. We compute the gutter based on the line length, so it + % changes automatically with the paper format. The magic constant + % below is chosen so that the gutter has the same value (well, +- < + % 1pt) as it did when we hard-coded it. + % + % We put the result in a separate register, \doublecolumhsize, so we + % can restore it in \pagesofar, after \hsize itself has (potentially) + % been clobbered. + % + \doublecolumnhsize = \hsize + \advance\doublecolumnhsize by -.04154\hsize + \divide\doublecolumnhsize by 2 + \hsize = \doublecolumnhsize + % + % Double the \vsize as well. (We don't need a separate register here, + % since nobody clobbers \vsize.) + \vsize = 2\vsize + \doublecolumnpagegoal +} + +\def\enddoublecolumns{\eject \endgroup \pagegoal=\vsize \unvbox\partialpage} + +\def\doublecolumnsplit{\splittopskip=\topskip \splitmaxdepth=\maxdepth + \global\dimen@=\pageheight \global\advance\dimen@ by-\ht\partialpage + \global\setbox1=\vsplit255 to\dimen@ \global\setbox0=\vbox{\unvbox1} + \global\setbox3=\vsplit255 to\dimen@ \global\setbox2=\vbox{\unvbox3} + \ifdim\ht0>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi + \ifdim\ht2>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi +} +\def\doublecolumnpagegoal{% + \dimen@=\vsize \advance\dimen@ by-2\ht\partialpage \global\pagegoal=\dimen@ +} +\def\pagesofar{\unvbox\partialpage % + \hsize=\doublecolumnhsize % have to restore this since output routine + \wd0=\hsize \wd2=\hsize \hbox to\pagewidth{\box0\hfil\box2}} +\def\doublecolumnout{% + \setbox5=\copy255 + {\vbadness=10000 \doublecolumnsplit} + \ifvbox255 + \setbox0=\vtop to\dimen@{\unvbox0} + \setbox2=\vtop to\dimen@{\unvbox2} + \onepageout\pagesofar \unvbox255 \penalty\outputpenalty + \else + \setbox0=\vbox{\unvbox5} + \ifvbox0 + \dimen@=\ht0 \advance\dimen@ by\topskip \advance\dimen@ by-\baselineskip + \divide\dimen@ by2 \splittopskip=\topskip \splitmaxdepth=\maxdepth + {\vbadness=10000 + \loop \global\setbox5=\copy0 + \setbox1=\vsplit5 to\dimen@ + \setbox3=\vsplit5 to\dimen@ + \ifvbox5 \global\advance\dimen@ by1pt \repeat + \setbox0=\vbox to\dimen@{\unvbox1} + \setbox2=\vbox to\dimen@{\unvbox3} + \global\setbox\partialpage=\vbox{\pagesofar} + \doublecolumnpagegoal + } + \fi + \fi +} + +\catcode `\@=\other +\message{sectioning,} +% Define chapters, sections, etc. + +\newcount \chapno +\newcount \secno \secno=0 +\newcount \subsecno \subsecno=0 +\newcount \subsubsecno \subsubsecno=0 + +% This counter is funny since it counts through charcodes of letters A, B, ... +\newcount \appendixno \appendixno = `\@ +\def\appendixletter{\char\the\appendixno} + +\newwrite \contentsfile +% This is called from \setfilename. +\def\opencontents{\openout \contentsfile = \jobname.toc} + +% Each @chapter defines this as the name of the chapter. +% page headings and footings can use it. @section does likewise + +\def\thischapter{} \def\thissection{} +\def\seccheck#1{\if \pageno<0 % +\errmessage{@#1 not allowed after generating table of contents}\fi +% +} + +\def\chapternofonts{% +\let\rawbackslash=\relax% +\let\frenchspacing=\relax% +\def\result{\realbackslash result} +\def\equiv{\realbackslash equiv} +\def\expansion{\realbackslash expansion} +\def\print{\realbackslash print} +\def\TeX{\realbackslash TeX} +\def\dots{\realbackslash dots} +\def\copyright{\realbackslash copyright} +\def\tt{\realbackslash tt} +\def\bf{\realbackslash bf } +\def\w{\realbackslash w} +\def\less{\realbackslash less} +\def\gtr{\realbackslash gtr} +\def\hat{\realbackslash hat} +\def\char{\realbackslash char} +\def\tclose##1{\realbackslash tclose {##1}} +\def\code##1{\realbackslash code {##1}} +\def\samp##1{\realbackslash samp {##1}} +\def\r##1{\realbackslash r {##1}} +\def\b##1{\realbackslash b {##1}} +\def\key##1{\realbackslash key {##1}} +\def\file##1{\realbackslash file {##1}} +\def\kbd##1{\realbackslash kbd {##1}} +% These are redefined because @smartitalic wouldn't work inside xdef. +\def\i##1{\realbackslash i {##1}} +\def\cite##1{\realbackslash cite {##1}} +\def\var##1{\realbackslash var {##1}} +\def\emph##1{\realbackslash emph {##1}} +\def\dfn##1{\realbackslash dfn {##1}} +} + +\newcount\absseclevel % used to calculate proper heading level +\newcount\secbase\secbase=0 % @raise/lowersections modify this count + +% @raisesections: treat @section as chapter, @subsection as section, etc. +\def\raisesections{\global\advance\secbase by -1} +\let\up=\raisesections % original BFox name + +% @lowersections: treat @chapter as section, @section as subsection, etc. +\def\lowersections{\global\advance\secbase by 1} +\let\down=\lowersections % original BFox name + +% Choose a numbered-heading macro +% #1 is heading level if unmodified by @raisesections or @lowersections +% #2 is text for heading +\def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \chapterzzz{#2} +\or + \seczzz{#2} +\or + \numberedsubseczzz{#2} +\or + \numberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \chapterzzz{#2} + \else + \numberedsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses appendix heading levels +\def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \appendixzzz{#2} +\or + \appendixsectionzzz{#2} +\or + \appendixsubseczzz{#2} +\or + \appendixsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \appendixzzz{#2} + \else + \appendixsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses numberless heading levels +\def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \unnumberedzzz{#2} +\or + \unnumberedseczzz{#2} +\or + \unnumberedsubseczzz{#2} +\or + \unnumberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \unnumberedzzz{#2} + \else + \unnumberedsubsubseczzz{#2} + \fi +\fi +} + + +\def\thischaptername{No Chapter Title} +\outer\def\chapter{\parsearg\chapteryyy} +\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz #1{\seccheck{chapter}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \chapno by 1 \message{\putwordChapter \the\chapno}% +\chapmacro {#1}{\the\chapno}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +% We don't substitute the actual chapter name into \thischapter +% because we don't want its macros evaluated now. +\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% +{\chapternofonts% +\edef\temp{{\realbackslash chapentry {#1}{\the\chapno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec +}} + +\outer\def\appendix{\parsearg\appendixyyy} +\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz +\def\appendixzzz #1{\seccheck{appendix}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \appendixno by 1 \message{Appendix \appendixletter}% +\chapmacro {#1}{\putwordAppendix{} \appendixletter}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% +{\chapternofonts% +\edef\temp{{\realbackslash chapentry + {#1}{\putwordAppendix{} \appendixletter}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\global\let\section = \appendixsec +\global\let\subsection = \appendixsubsec +\global\let\subsubsection = \appendixsubsubsec +}} + +\outer\def\top{\parsearg\unnumberedyyy} +\outer\def\unnumbered{\parsearg\unnumberedyyy} +\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +\def\unnumberedzzz #1{\seccheck{unnumbered}% +\secno=0 \subsecno=0 \subsubsecno=0 +% +% This used to be simply \message{#1}, but TeX fully expands the +% argument to \message. Therefore, if #1 contained @-commands, TeX +% expanded them. For example, in `@unnumbered The @cite{Book}', TeX +% expanded @cite (which turns out to cause errors because \cite is meant +% to be executed, not expanded). +% +% Anyway, we don't want the fully-expanded definition of @cite to appear +% as a result of the \message, we just want `@cite' itself. We use +% \the<toks register> to achieve this: TeX expands \the<toks> only once, +% simply yielding the contents of the <toks register>. +\toks0 = {#1}\message{(\the\toks0)}% +% +\unnumbchapmacro {#1}% +\gdef\thischapter{#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbchapentry {#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\global\let\section = \unnumberedsec +\global\let\subsection = \unnumberedsubsec +\global\let\subsubsection = \unnumberedsubsubsec +}} + +\outer\def\numberedsec{\parsearg\secyyy} +\def\secyyy #1{\numhead1{#1}} % normally calls seczzz +\def\seczzz #1{\seccheck{section}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% +{\chapternofonts% +\edef\temp{{\realbackslash secentry % +{#1}{\the\chapno}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appenixsection{\parsearg\appendixsecyyy} +\outer\def\appendixsec{\parsearg\appendixsecyyy} +\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz +\def\appendixsectionzzz #1{\seccheck{appendixsection}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% +{\chapternofonts% +\edef\temp{{\realbackslash secentry % +{#1}{\appendixletter}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} +\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz +\def\unnumberedseczzz #1{\seccheck{unnumberedsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} +\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz +\def\numberedsubseczzz #1{\seccheck{subsection}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsecentry % +{#1}{\the\chapno}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} +\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz +\def\appendixsubseczzz #1{\seccheck{appendixsubsec}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsecentry % +{#1}{\appendixletter}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} +\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +\def\unnumberedsubseczzz #1{\seccheck{unnumberedsubsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsubsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} +\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz +\def\numberedsubsubseczzz #1{\seccheck{subsubsection}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsubsecentry % + {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno} + {\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} +\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz +\def\appendixsubsubseczzz #1{\seccheck{appendixsubsubsec}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsubsecentry{#1}% + {\appendixletter} + {\the\secno}{\the\subsecno}{\the\subsubsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} +\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +\def\unnumberedsubsubseczzz #1{\seccheck{unnumberedsubsubsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsubsubsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +% These are variants which are not "outer", so they can appear in @ifinfo. +% Actually, they should now be obsolete; ordinary section commands should work. +\def\infotop{\parsearg\unnumberedzzz} +\def\infounnumbered{\parsearg\unnumberedzzz} +\def\infounnumberedsec{\parsearg\unnumberedseczzz} +\def\infounnumberedsubsec{\parsearg\unnumberedsubseczzz} +\def\infounnumberedsubsubsec{\parsearg\unnumberedsubsubseczzz} + +\def\infoappendix{\parsearg\appendixzzz} +\def\infoappendixsec{\parsearg\appendixseczzz} +\def\infoappendixsubsec{\parsearg\appendixsubseczzz} +\def\infoappendixsubsubsec{\parsearg\appendixsubsubseczzz} + +\def\infochapter{\parsearg\chapterzzz} +\def\infosection{\parsearg\sectionzzz} +\def\infosubsection{\parsearg\subsectionzzz} +\def\infosubsubsection{\parsearg\subsubsectionzzz} + +% These macros control what the section commands do, according +% to what kind of chapter we are in (ordinary, appendix, or unnumbered). +% Define them by default for a numbered chapter. +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec + +% Define @majorheading, @heading and @subheading + +% NOTE on use of \vbox for chapter headings, section headings, and +% such: +% 1) We use \vbox rather than the earlier \line to permit +% overlong headings to fold. +% 2) \hyphenpenalty is set to 10000 because hyphenation in a +% heading is obnoxious; this forbids it. +% 3) Likewise, headings look best if no \parindent is used, and +% if justification is not attempted. Hence \raggedright. + + +\def\majorheading{\parsearg\majorheadingzzz} +\def\majorheadingzzz #1{% +{\advance\chapheadingskip by 10pt \chapbreak }% +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\chapheading{\parsearg\chapheadingzzz} +\def\chapheadingzzz #1{\chapbreak % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\heading{\parsearg\secheadingi} + +\def\subheading{\parsearg\subsecheadingi} + +\def\subsubheading{\parsearg\subsubsecheadingi} + +% These macros generate a chapter, section, etc. heading only +% (including whitespace, linebreaking, etc. around it), +% given all the information in convenient, parsed form. + +%%% Args are the skip and penalty (usually negative) +\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} + +\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} + +%%% Define plain chapter starts, and page on/off switching for it +% Parameter controlling skip before chapter headings (if needed) + +\newskip \chapheadingskip \chapheadingskip = 30pt plus 8pt minus 4pt + +\def\chapbreak{\dobreak \chapheadingskip {-4000}} +\def\chappager{\par\vfill\supereject} +\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi} + +\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} + +\def\CHAPPAGoff{ +\global\let\pchapsepmacro=\chapbreak +\global\let\pagealignmacro=\chappager} + +\def\CHAPPAGon{ +\global\let\pchapsepmacro=\chappager +\global\let\pagealignmacro=\chappager +\global\def\HEADINGSon{\HEADINGSsingle}} + +\def\CHAPPAGodd{ +\global\let\pchapsepmacro=\chapoddpage +\global\let\pagealignmacro=\chapoddpage +\global\def\HEADINGSon{\HEADINGSdouble}} + +\CHAPPAGon + +\def\CHAPFplain{ +\global\let\chapmacro=\chfplain +\global\let\unnumbchapmacro=\unnchfplain} + +\def\chfplain #1#2{% + \pchapsepmacro + {% + \chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #2\enspace #1}% + }% + \bigskip + \penalty5000 +} + +\def\unnchfplain #1{% +\pchapsepmacro % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} +\CHAPFplain % The default + +\def\unnchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} + +\def\chfopen #1#2{\chapoddpage {\chapfonts +\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% +\par\penalty 5000 % +} + +\def\CHAPFopen{ +\global\let\chapmacro=\chfopen +\global\let\unnumbchapmacro=\unnchfopen} + +% Parameter controlling skip before section headings. + +\newskip \subsecheadingskip \subsecheadingskip = 17pt plus 8pt minus 4pt +\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} + +\newskip \secheadingskip \secheadingskip = 21pt plus 8pt minus 4pt +\def\secheadingbreak{\dobreak \secheadingskip {-1000}} + +% @paragraphindent is defined for the Info formatting commands only. +\let\paragraphindent=\comment + +% Section fonts are the base font at magstep2, which produces +% a size a bit more than 14 points in the default situation. + +\def\secheading #1#2#3{\secheadingi {#2.#3\enspace #1}} +\def\plainsecheading #1{\secheadingi {#1}} +\def\secheadingi #1{{\advance \secheadingskip by \parskip % +\secheadingbreak}% +{\secfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } + + +% Subsection fonts are the base font at magstep1, +% which produces a size of 12 points. + +\def\subsecheading #1#2#3#4{\subsecheadingi {#2.#3.#4\enspace #1}} +\def\subsecheadingi #1{{\advance \subsecheadingskip by \parskip % +\subsecheadingbreak}% +{\subsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } + +\def\subsubsecfonts{\subsecfonts} % Maybe this should change: + % Perhaps make sssec fonts scaled + % magstep half +\def\subsubsecheading #1#2#3#4#5{\subsubsecheadingi {#2.#3.#4.#5\enspace #1}} +\def\subsubsecheadingi #1{{\advance \subsecheadingskip by \parskip % +\subsecheadingbreak}% +{\subsubsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000} + + +\message{toc printing,} + +% Finish up the main text and prepare to read what we've written +% to \contentsfile. + +\newskip\contentsrightmargin \contentsrightmargin=1in +\def\startcontents#1{% + \pagealignmacro + \immediate\closeout \contentsfile + \ifnum \pageno>0 + \pageno = -1 % Request roman numbered pages. + \fi + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \unnumbchapmacro{#1}\def\thischapter{}% + \begingroup % Set up to handle contents files properly. + \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 + \catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi + \raggedbottom % Worry more about breakpoints than the bottom. + \advance\hsize by -\contentsrightmargin % Don't use the full line length. +} + + +% Normal (long) toc. +\outer\def\contents{% + \startcontents{\putwordTableofContents}% + \input \jobname.toc + \endgroup + \vfill \eject +} + +% And just the chapters. +\outer\def\summarycontents{% + \startcontents{\putwordShortContents}% + % + \let\chapentry = \shortchapentry + \let\unnumbchapentry = \shortunnumberedentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl + \rm + \advance\baselineskip by 1pt % Open it up a little. + \def\secentry ##1##2##3##4{} + \def\unnumbsecentry ##1##2{} + \def\subsecentry ##1##2##3##4##5{} + \def\unnumbsubsecentry ##1##2{} + \def\subsubsecentry ##1##2##3##4##5##6{} + \def\unnumbsubsubsecentry ##1##2{} + \input \jobname.toc + \endgroup + \vfill \eject +} +\let\shortcontents = \summarycontents + +% These macros generate individual entries in the table of contents. +% The first argument is the chapter or section name. +% The last argument is the page number. +% The arguments in between are the chapter number, section number, ... + +% Chapter-level things, for both the long and short contents. +\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}} + +% See comments in \dochapentry re vbox and related settings +\def\shortchapentry#1#2#3{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno{#3}}% +} + +% Typeset the label for a chapter or appendix for the short contents. +% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter. +% We could simplify the code here by writing out an \appendixentry +% command in the toc file for appendices, instead of using \chapentry +% for both, but it doesn't seem worth it. +\setbox0 = \hbox{\shortcontrm \putwordAppendix } +\newdimen\shortappendixwidth \shortappendixwidth = \wd0 + +\def\shortchaplabel#1{% + % We typeset #1 in a box of constant width, regardless of the text of + % #1, so the chapter titles will come out aligned. + \setbox0 = \hbox{#1}% + \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi + % + % This space should be plenty, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in in \shortchapentry above.) + \advance\dimen0 by 1.1em + \hbox to \dimen0{#1\hfil}% +} + +\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}} +\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno{#2}}} + +% Sections. +\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} +\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}} + +% Subsections. +\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} +\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}} + +% And subsubsections. +\def\subsubsecentry#1#2#3#4#5#6{% + \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} +\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}} + + +% This parameter controls the indentation of the various levels. +\newdimen\tocindent \tocindent = 3pc + +% Now for the actual typesetting. In all these, #1 is the text and #2 is the +% page number. +% +% If the toc has to be broken over pages, we would want to be at chapters +% if at all possible; hence the \penalty. +\def\dochapentry#1#2{% + \penalty-300 \vskip\baselineskip + \begingroup + \chapentryfonts + \tocentry{#1}{\dopageno{#2}}% + \endgroup + \nobreak\vskip .25\baselineskip +} + +\def\dosecentry#1#2{\begingroup + \secentryfonts \leftskip=\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsecentry#1#2{\begingroup + \subsecentryfonts \leftskip=2\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsubsecentry#1#2{\begingroup + \subsubsecentryfonts \leftskip=3\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +% Final typesetting of a toc entry; we use the same \entry macro as for +% the index entries, but we want to suppress hyphenation here. (We +% can't do that in the \entry macro, since index entries might consist +% of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.) +% +\def\tocentry#1#2{\begingroup + \hyphenpenalty = 10000 + \entry{#1}{#2}% +\endgroup} + +% Space between chapter (or whatever) number and the title. +\def\labelspace{\hskip1em \relax} + +\def\dopageno#1{{\rm #1}} +\def\doshortpageno#1{{\rm #1}} + +\def\chapentryfonts{\secfonts \rm} +\def\secentryfonts{\textfonts} +\let\subsecentryfonts = \textfonts +\let\subsubsecentryfonts = \textfonts + + +\message{environments,} + +% Since these characters are used in examples, it should be an even number of +% \tt widths. Each \tt character is 1en, so two makes it 1em. +% Furthermore, these definitions must come after we define our fonts. +\newbox\dblarrowbox \newbox\longdblarrowbox +\newbox\pushcharbox \newbox\bullbox +\newbox\equivbox \newbox\errorbox + +\let\ptexequiv = \equiv + +%{\tentt +%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil} +%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil} +%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil} +%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil} +% Adapted from the manmac format (p.420 of TeXbook) +%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex +% depth .1ex\hfil} +%} + +\def\point{$\star$} + +\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} +\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} +\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} + +\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} + +% Adapted from the TeXbook's \boxit. +{\tentt \global\dimen0 = 3em}% Width of the box. +\dimen2 = .55pt % Thickness of rules +% The text. (`r' is open on the right, `e' somewhat less so on the left.) +\setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt} + +\global\setbox\errorbox=\hbox to \dimen0{\hfil + \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. + \advance\hsize by -2\dimen2 % Rules. + \vbox{ + \hrule height\dimen2 + \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. + \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. + \kern3pt\vrule width\dimen2}% Space to right. + \hrule height\dimen2} + \hfil} + +% The @error{} command. +\def\error{\leavevmode\lower.7ex\copy\errorbox} + +% @tex ... @end tex escapes into raw Tex temporarily. +% One exception: @ is still an escape character, so that @end tex works. +% But \@ or @@ will get a plain tex @ character. + +\def\tex{\begingroup +\catcode `\\=0 \catcode `\{=1 \catcode `\}=2 +\catcode `\$=3 \catcode `\&=4 \catcode `\#=6 +\catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie +\catcode `\%=14 +\catcode 43=12 +\catcode`\"=12 +\catcode`\==12 +\catcode`\|=12 +\catcode`\<=12 +\catcode`\>=12 +\escapechar=`\\ +% +\let\~=\ptextilde +\let\{=\ptexlbrace +\let\}=\ptexrbrace +\let\.=\ptexdot +\let\*=\ptexstar +\let\dots=\ptexdots +\def\@{@}% +\let\bullet=\ptexbullet +\let\b=\ptexb \let\c=\ptexc \let\i=\ptexi \let\t=\ptext \let\l=\ptexl +\let\L=\ptexL +% +\let\Etex=\endgroup} + +% Define @lisp ... @endlisp. +% @lisp does a \begingroup so it can rebind things, +% including the definition of @endlisp (which normally is erroneous). + +% Amount to narrow the margins by for @lisp. +\newskip\lispnarrowing \lispnarrowing=0.4in + +% This is the definition that ^^M gets inside @lisp, @example, and other +% such environments. \null is better than a space, since it doesn't +% have any width. +\def\lisppar{\null\endgraf} + +% Make each space character in the input produce a normal interword +% space in the output. Don't allow a line break at this space, as this +% is used only in environments like @example, where each line of input +% should produce a line of output anyway. +% +{\obeyspaces % +\gdef\sepspaces{\obeyspaces\let =\tie}} + +% Define \obeyedspace to be our active space, whatever it is. This is +% for use in \parsearg. +{\sepspaces% +\global\let\obeyedspace= } + +% This space is always present above and below environments. +\newskip\envskipamount \envskipamount = 0pt + +% Make spacing and below environment symmetrical. We use \parskip here +% to help in doing that, since in @example-like environments \parskip +% is reset to zero; thus the \afterenvbreak inserts no space -- but the +% start of the next paragraph will insert \parskip +% +\def\aboveenvbreak{{\advance\envskipamount by \parskip +\endgraf \ifdim\lastskip<\envskipamount +\removelastskip \penalty-50 \vskip\envskipamount \fi}} + +\let\afterenvbreak = \aboveenvbreak + +% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins. +\let\nonarrowing=\relax + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \cartouche: draw rectangle w/rounded corners around argument +\font\circle=lcircle10 +\newdimen\circthick +\newdimen\cartouter\newdimen\cartinner +\newskip\normbskip\newskip\normpskip\newskip\normlskip +\circthick=\fontdimen8\circle +% +\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth +\def\ctr{{\hskip 6pt\circle\char'010}} +\def\cbl{{\circle\char'012\hskip -6pt}} +\def\cbr{{\hskip 6pt\circle\char'011}} +\def\carttop{\hbox to \cartouter{\hskip\lskip + \ctl\leaders\hrule height\circthick\hfil\ctr + \hskip\rskip}} +\def\cartbot{\hbox to \cartouter{\hskip\lskip + \cbl\leaders\hrule height\circthick\hfil\cbr + \hskip\rskip}} +% +\newskip\lskip\newskip\rskip + +\long\def\cartouche{% +\begingroup + \lskip=\leftskip \rskip=\rightskip + \leftskip=0pt\rightskip=0pt %we want these *outside*. + \cartinner=\hsize \advance\cartinner by-\lskip + \advance\cartinner by-\rskip + \cartouter=\hsize + \advance\cartouter by 18pt % allow for 3pt kerns on either +% side, and for 6pt waste from +% each corner char + \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip + % Flag to tell @lisp, etc., not to narrow margin. + \let\nonarrowing=\comment + \vbox\bgroup + \baselineskip=0pt\parskip=0pt\lineskip=0pt + \carttop + \hbox\bgroup + \hskip\lskip + \vrule\kern3pt + \vbox\bgroup + \hsize=\cartinner + \kern3pt + \begingroup + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip +\def\Ecartouche{% + \endgroup + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup +\endgroup +}} + + +% This macro is called at the beginning of all the @example variants, +% inside a group. +\def\nonfillstart{% + \aboveenvbreak + \inENV % This group ends at the end of the body + \hfuzz = 12pt % Don't be fussy + \sepspaces % Make spaces be word-separators rather than space tokens. + \singlespace + \let\par = \lisppar % don't ignore blank lines + \obeylines % each line of input is a line of output + \parskip = 0pt + \parindent = 0pt + \emergencystretch = 0pt % don't try to avoid overfull boxes + % @cartouche defines \nonarrowing to inhibit narrowing + % at next level down. + \ifx\nonarrowing\relax + \advance \leftskip by \lispnarrowing + \exdentamount=\lispnarrowing + \let\exdent=\nofillexdent + \let\nonarrowing=\relax + \fi +} + +% To ending an @example-like environment, we first end the paragraph +% (via \afterenvbreak's vertical glue), and then the group. That way we +% keep the zero \parskip that the environments set -- \parskip glue +% will be inserted at the beginning of the next paragraph in the +% document, after the environment. +% +\def\nonfillfinish{\afterenvbreak\endgroup}% + +% This macro is +\def\lisp{\begingroup + \nonfillstart + \let\Elisp = \nonfillfinish + \tt + \rawbackslash % have \ input char produce \ char from current font + \gobble +} + +% Define the \E... control sequence only if we are inside the +% environment, so the error checking in \end will work. +% +% We must call \lisp last in the definition, since it reads the +% return following the @example (or whatever) command. +% +\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} +\def\smallexample{\begingroup \def\Esmallexample{\nonfillfinish\endgroup}\lisp} +\def\smalllisp{\begingroup \def\Esmalllisp{\nonfillfinish\endgroup}\lisp} + +% @smallexample and @smalllisp. This is not used unless the @smallbook +% command is given. Originally contributed by Pavel@xerox. +% +\def\smalllispx{\begingroup + \nonfillstart + \let\Esmalllisp = \nonfillfinish + \let\Esmallexample = \nonfillfinish + % + % Smaller interline space and fonts for small examples. + \setleading{10pt}% + \indexfonts \tt + \rawbackslash % make \ output the \ character from the current font (tt) + \gobble +} + +% This is @display; same as @lisp except use roman font. +% +\def\display{\begingroup + \nonfillstart + \let\Edisplay = \nonfillfinish + \gobble +} + +% This is @format; same as @display except don't narrow margins. +% +\def\format{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eformat = \nonfillfinish + \gobble +} + +% @flushleft (same as @format) and @flushright. +% +\def\flushleft{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushleft = \nonfillfinish + \gobble +} +\def\flushright{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushright = \nonfillfinish + \advance\leftskip by 0pt plus 1fill + \gobble} + +% @quotation does normal linebreaking (hence we can't use \nonfillstart) +% and narrows the margins. +% +\def\quotation{% + \begingroup\inENV %This group ends at the end of the @quotation body + {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip + \singlespace + \parindent=0pt + % We have retained a nonzero parskip for the environment, since we're + % doing normal filling. So to avoid extra space below the environment... + \def\Equotation{\parskip = 0pt \nonfillfinish}% + % + % @cartouche defines \nonarrowing to inhibit narrowing at next level down. + \ifx\nonarrowing\relax + \advance\leftskip by \lispnarrowing + \advance\rightskip by \lispnarrowing + \exdentamount = \lispnarrowing + \let\nonarrowing = \relax + \fi +} + +\message{defuns,} +% Define formatter for defuns +% First, allow user to change definition object font (\df) internally +\def\setdeffont #1 {\csname DEF#1\endcsname} + +\newskip\defbodyindent \defbodyindent=.4in +\newskip\defargsindent \defargsindent=50pt +\newskip\deftypemargin \deftypemargin=12pt +\newskip\deflastargmargin \deflastargmargin=18pt + +\newcount\parencount +% define \functionparens, which makes ( and ) and & do special things. +% \functionparens affects the group it is contained in. +\def\activeparens{% +\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active +\catcode`\[=\active \catcode`\]=\active} + +% Make control sequences which act like normal parenthesis chars. +\let\lparen = ( \let\rparen = ) + +{\activeparens % Now, smart parens don't turn on until &foo (see \amprm) + +% Be sure that we always have a definition for `(', etc. For example, +% if the fn name has parens in it, \boldbrax will not be in effect yet, +% so TeX would otherwise complain about undefined control sequence. +\global\let(=\lparen \global\let)=\rparen +\global\let[=\lbrack \global\let]=\rbrack + +\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 } +\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} +% This is used to turn on special parens +% but make & act ordinary (given that it's active). +\gdef\boldbraxnoamp{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb\let&=\ampnr} + +% Definitions of (, ) and & used in args for functions. +% This is the definition of ( outside of all parentheses. +\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested % +\global\advance\parencount by 1 } +% +% This is the definition of ( when already inside a level of parens. +\gdef\opnested{\char`\(\global\advance\parencount by 1 } +% +\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0. +% also in that case restore the outer-level definition of (. +\ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi +\global\advance \parencount by -1 } +% If we encounter &foo, then turn on ()-hacking afterwards +\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ } +% +\gdef\normalparens{\boldbrax\let&=\ampnr} +} % End of definition inside \activeparens +%% These parens (in \boldbrax) actually are a little bolder than the +%% contained text. This is especially needed for [ and ] +\def\opnr{{\sf\char`\(}} \def\clnr{{\sf\char`\)}} \def\ampnr{\&} +\def\lbrb{{\bf\char`\[}} \def\rbrb{{\bf\char`\]}} + +% First, defname, which formats the header line itself. +% #1 should be the function name. +% #2 should be the type of definition, such as "Function". + +\def\defname #1#2{% +% Get the values of \leftskip and \rightskip as they were +% outside the @def... +\dimen2=\leftskip +\advance\dimen2 by -\defbodyindent +\dimen3=\rightskip +\advance\dimen3 by -\defbodyindent +\noindent % +\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}% +\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line +\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations +\parshape 2 0in \dimen0 \defargsindent \dimen1 % +% Now output arg 2 ("Function" or some such) +% ending at \deftypemargin from the right margin, +% but stuck inside a box of width 0 so it does not interfere with linebreaking +{% Adjust \hsize to exclude the ambient margins, +% so that \rightline will obey them. +\advance \hsize by -\dimen2 \advance \hsize by -\dimen3 +\rlap{\rightline{{\rm #2}\hskip \deftypemargin}}}% +% Make all lines underfull and no complaints: +\tolerance=10000 \hbadness=10000 +\advance\leftskip by -\defbodyindent +\exdentamount=\defbodyindent +{\df #1}\enskip % Generate function name +} + +% Actually process the body of a definition +% #1 should be the terminating control sequence, such as \Edefun. +% #2 should be the "another name" control sequence, such as \defunx. +% #3 should be the control sequence that actually processes the header, +% such as \defunheader. + +\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\activeparens\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % 61 is `=' +\obeylines\activeparens\spacesplit#3} + +\def\defmethparsebody #1#2#3#4 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#4}}} + +\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#5}}} + +% These parsing functions are similar to the preceding ones +% except that they do not make parens into active characters. +% These are used for "variables" since they have no arguments. + +\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % +\obeylines\spacesplit#3} + +% This is used for \def{tp,vr}parsebody. It could probably be used for +% some of the others, too, with some judicious conditionals. +% +\def\parsebodycommon#1#2#3{% + \begingroup\inENV % + \medbreak % + % Define the end token that this defining construct specifies + % so that it will exit this group. + \def#1{\endgraf\endgroup\medbreak}% + \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}% + \parindent=0in + \advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent + \exdentamount=\defbodyindent + \begingroup\obeylines +} + +\def\defvrparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{#3{#4}}% +} + +% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the +% type is just `struct', because we lose the braces in `{struct +% termios}' when \spacesplit reads its undelimited argument. Sigh. +% \let\deftpparsebody=\defvrparsebody +% +% So, to get around this, we put \empty in with the type name. That +% way, TeX won't find exactly `{...}' as an undelimited argument, and +% won't strip off the braces. +% +\def\deftpparsebody #1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{\parsetpheaderline{#3{#4}}}\empty +} + +% Fine, but then we have to eventually remove the \empty *and* the +% braces (if any). That's what this does, putting the result in \tptemp. +% +\def\removeemptybraces\empty#1\relax{\def\tptemp{#1}}% + +% After \spacesplit has done its work, this is called -- #1 is the final +% thing to call, #2 the type name (which starts with \empty), and #3 +% (which might be empty) the arguments. +% +\def\parsetpheaderline#1#2#3{% + \removeemptybraces#2\relax + #1{\tptemp}{#3}% +}% + +\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\spacesplit{#3{#5}}} + +% Split up #2 at the first space token. +% call #1 with two arguments: +% the first is all of #2 before the space token, +% the second is all of #2 after that space token. +% If #2 contains no space token, all of it is passed as the first arg +% and the second is passed as empty. + +{\obeylines +\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}% +\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{% +\ifx\relax #3% +#1{#2}{}\else #1{#2}{#3#4}\fi}} + +% So much for the things common to all kinds of definitions. + +% Define @defun. + +% First, define the processing that is wanted for arguments of \defun +% Use this to expand the args and terminate the paragraph they make up + +\def\defunargs #1{\functionparens \sl +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +\hyphenchar\tensl=0 +#1% +\hyphenchar\tensl=45 +\ifnum\parencount=0 \else \errmessage{unbalanced parens in @def arguments}\fi% +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +\def\deftypefunargs #1{% +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +% Use \boldbraxnoamp, not \functionparens, so that & is not special. +\boldbraxnoamp +\tclose{#1}% avoid \code because of side effects on active chars +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +% Do complete processing of one @defun or @defunx line already parsed. + +% @deffn Command forward-char nchars + +\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader} + +\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}% +\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defun == @deffn Function + +\def\defun{\defparsebody\Edefun\defunx\defunheader} + +\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Function}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefun int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader} + +% #1 is the data type. #2 is the name and args. +\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax} +% #1 is the data type, #2 the name, #3 the args. +\def\deftypefunheaderx #1#2 #3\relax{% +\doind {fn}{\code{#2}}% Make entry in function index +\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Function}% +\deftypefunargs {#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader} + +% \defheaderxcond#1\relax$$$ +% puts #1 in @code, followed by a space, but does nothing if #1 is null. +\def\defheaderxcond#1#2$$${\ifx#1\relax\else\code{#1#2} \fi} + +% #1 is the classification. #2 is the data type. #3 is the name and args. +\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax} +% #1 is the classification, #2 the data type, #3 the name, #4 the args. +\def\deftypefnheaderx #1#2#3 #4\relax{% +\doind {fn}{\code{#3}}% Make entry in function index +\begingroup +\normalparens % notably, turn off `&' magic, which prevents +% at least some C++ text from working +\defname {\defheaderxcond#2\relax$$$#3}{#1}% +\deftypefunargs {#4}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defmac == @deffn Macro + +\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader} + +\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Macro}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defspec == @deffn Special Form + +\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader} + +\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Special Form}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% This definition is run if you use @defunx +% anywhere other than immediately after a @defun or @defunx. + +\def\deffnx #1 {\errmessage{@deffnx in invalid context}} +\def\defunx #1 {\errmessage{@defunx in invalid context}} +\def\defmacx #1 {\errmessage{@defmacx in invalid context}} +\def\defspecx #1 {\errmessage{@defspecx in invalid context}} +\def\deftypefnx #1 {\errmessage{@deftypefnx in invalid context}} +\def\deftypeunx #1 {\errmessage{@deftypeunx in invalid context}} + +% @defmethod, and so on + +% @defop {Funny Method} foo-class frobnicate argument + +\def\defop #1 {\def\defoptype{#1}% +\defopparsebody\Edefop\defopx\defopheader\defoptype} + +\def\defopheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% Make entry in function index +\begingroup\defname {#2}{\defoptype{} on #1}% +\defunargs {#3}\endgroup % +} + +% @defmethod == @defop Method + +\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} + +\def\defmethodheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% entry in function index +\begingroup\defname {#2}{Method on #1}% +\defunargs {#3}\endgroup % +} + +% @defcv {Class Option} foo-class foo-flag + +\def\defcv #1 {\def\defcvtype{#1}% +\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype} + +\def\defcvarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{\defcvtype{} of #1}% +\defvarargs {#3}\endgroup % +} + +% @defivar == @defcv {Instance Variable} + +\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} + +\def\defivarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{Instance Variable of #1}% +\defvarargs {#3}\endgroup % +} + +% These definitions are run if you use @defmethodx, etc., +% anywhere other than immediately after a @defmethod, etc. + +\def\defopx #1 {\errmessage{@defopx in invalid context}} +\def\defmethodx #1 {\errmessage{@defmethodx in invalid context}} +\def\defcvx #1 {\errmessage{@defcvx in invalid context}} +\def\defivarx #1 {\errmessage{@defivarx in invalid context}} + +% Now @defvar + +% First, define the processing that is wanted for arguments of @defvar. +% This is actually simple: just print them in roman. +% This must expand the args and terminate the paragraph they make up +\def\defvarargs #1{\normalparens #1% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000} + +% @defvr Counter foo-count + +\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader} + +\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}% +\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup} + +% @defvar == @defvr Variable + +\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader} + +\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{Variable}% +\defvarargs {#2}\endgroup % +} + +% @defopt == @defvr {User Option} + +\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader} + +\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{User Option}% +\defvarargs {#2}\endgroup % +} + +% @deftypevar int foobar + +\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} + +% #1 is the data type. #2 is the name. +\def\deftypevarheader #1#2{% +\doind {vr}{\code{#2}}% Make entry in variables index +\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Variable}% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% @deftypevr {Global Flag} int enable + +\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} + +\def\deftypevrheader #1#2#3{\doind {vr}{\code{#3}}% +\begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1} +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% This definition is run if you use @defvarx +% anywhere other than immediately after a @defvar or @defvarx. + +\def\defvrx #1 {\errmessage{@defvrx in invalid context}} +\def\defvarx #1 {\errmessage{@defvarx in invalid context}} +\def\defoptx #1 {\errmessage{@defoptx in invalid context}} +\def\deftypevarx #1 {\errmessage{@deftypevarx in invalid context}} +\def\deftypevrx #1 {\errmessage{@deftypevrx in invalid context}} + +% Now define @deftp +% Args are printed in bold, a slight difference from @defvar. + +\def\deftpargs #1{\bf \defvarargs{#1}} + +% @deftp Class window height width ... + +\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader} + +\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}% +\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup} + +% This definition is run if you use @deftpx, etc +% anywhere other than immediately after a @deftp, etc. + +\def\deftpx #1 {\errmessage{@deftpx in invalid context}} + +\message{cross reference,} +% Define cross-reference macros +\newwrite \auxfile + +\newif\ifhavexrefs % True if xref values are known. +\newif\ifwarnedxrefs % True if we warned once that they aren't known. + +% \setref{foo} defines a cross-reference point named foo. + +\def\setref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ysectionnumberandtype}} + +\def\unnumbsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ynothing}} + +\def\appendixsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Yappendixletterandtype}} + +% \xref, \pxref, and \ref generate cross-references to specified points. +% For \xrefX, #1 is the node name, #2 the name of the Info +% cross-reference, #3 the printed node name, #4 the name of the Info +% file, #5 the name of the printed manual. All but the node name can be +% omitted. +% +\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} +\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} +\def\ref#1{\xrefX[#1,,,,,,,]} +\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup + \def\printedmanual{\ignorespaces #5}% + \def\printednodename{\ignorespaces #3}% + \setbox1=\hbox{\printedmanual}% + \setbox0=\hbox{\printednodename}% + \ifdim \wd0 = 0pt + % No printed node name was explicitly given. + \ifx\SETxref-automatic-section-title\relax % + % Use the actual chapter/section title appear inside + % the square brackets. Use the real section title if we have it. + \ifdim \wd1>0pt% + % It is in another manual, so we don't have it. + \def\printednodename{\ignorespaces #1}% + \else + \ifhavexrefs + % We know the real title if we have the xref values. + \def\printednodename{\refx{#1-title}}% + \else + % Otherwise just copy the Info node name. + \def\printednodename{\ignorespaces #1}% + \fi% + \fi + \def\printednodename{#1-title}% + \else + % Use the node name inside the square brackets. + \def\printednodename{\ignorespaces #1}% + \fi + \fi + % + % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not + % insert empty discretionaries after hyphens, which means that it will + % not find a line break at a hyphen in a node names. Since some manuals + % are best written with fairly long node names, containing hyphens, this + % is a loss. Therefore, we give the text of the node name again, so it + % is as if TeX is seeing it for the first time. + \ifdim \wd1 > 0pt + \putwordsection{} ``\printednodename'' in \cite{\printedmanual}% + \else + % _ (for example) has to be the character _ for the purposes of the + % control sequence corresponding to the node, but it has to expand + % into the usual \leavevmode...\vrule stuff for purposes of + % printing. So we \turnoffactive for the \refx-snt, back on for the + % printing, back off for the \refx-pg. + {\turnoffactive \refx{#1-snt}{}}% + \space [\printednodename],\space + \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \fi +\endgroup} + +% \dosetq is the interface for calls from other macros + +% Use \turnoffactive so that punctuation chars such as underscore +% work in node names. +\def\dosetq #1#2{{\let\folio=0 \turnoffactive \auxhat% +\edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% +\next}} + +% \internalsetq {foo}{page} expands into +% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...} +% When the aux file is read, ' is the escape character + +\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}} + +% Things to be expanded by \internalsetq + +\def\Ypagenumber{\folio} + +\def\Ytitle{\thissection} + +\def\Ynothing{} + +\def\Ysectionnumberandtype{% +\ifnum\secno=0 \putwordChapter\xreftie\the\chapno % +\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\def\Yappendixletterandtype{% +\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}% +\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\gdef\xreftie{'tie} + +% Use TeX 3.0's \inputlineno to get the line number, for better error +% messages, but if we're using an old version of TeX, don't do anything. +% +\ifx\inputlineno\thisisundefined + \let\linenumber = \empty % Non-3.0. +\else + \def\linenumber{\the\inputlineno:\space} +\fi + +% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. +% If its value is nonempty, SUFFIX is output afterward. + +\def\refx#1#2{% + \expandafter\ifx\csname X#1\endcsname\relax + % If not defined, say something at least. + $\langle$un\-de\-fined$\rangle$% + \ifhavexrefs + \message{\linenumber Undefined cross reference `#1'.}% + \else + \ifwarnedxrefs\else + \global\warnedxrefstrue + \message{Cross reference values unknown; you must run TeX again.}% + \fi + \fi + \else + % It's defined, so just use it. + \csname X#1\endcsname + \fi + #2% Output the suffix in any case. +} + +% Read the last existing aux file, if any. No error if none exists. + +% This is the macro invoked by entries in the aux file. +\def\xrdef #1#2{ +{\catcode`\'=\other\expandafter \gdef \csname X#1\endcsname {#2}}} + +\def\readauxfile{% +\begingroup +\catcode `\^^@=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\^^C=\other +\catcode `\^^D=\other +\catcode `\^^E=\other +\catcode `\^^F=\other +\catcode `\^^G=\other +\catcode `\^^H=\other +\catcode `\=\other +\catcode `\^^L=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode 26=\other +\catcode `\^^[=\other +\catcode `\^^\=\other +\catcode `\^^]=\other +\catcode `\^^^=\other +\catcode `\^^_=\other +\catcode `\@=\other +\catcode `\^=\other +\catcode `\~=\other +\catcode `\[=\other +\catcode `\]=\other +\catcode`\"=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode `\$=\other +\catcode `\#=\other +\catcode `\&=\other +% `\+ does not work, so use 43. +\catcode 43=\other +% Make the characters 128-255 be printing characters +{% + \count 1=128 + \def\loop{% + \catcode\count 1=\other + \advance\count 1 by 1 + \ifnum \count 1<256 \loop \fi + }% +}% +% the aux file uses ' as the escape. +% Turn off \ as an escape so we do not lose on +% entries which were dumped with control sequences in their names. +% For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^ +% Reference to such entries still does not work the way one would wish, +% but at least they do not bomb out when the aux file is read in. +\catcode `\{=1 \catcode `\}=2 +\catcode `\%=\other +\catcode `\'=0 +\catcode`\^=7 % to make ^^e4 etc usable in xref tags +\catcode `\\=\other +\openin 1 \jobname.aux +\ifeof 1 \else \closein 1 \input \jobname.aux \global\havexrefstrue +\global\warnedobstrue +\fi +% Open the new aux file. Tex will close it automatically at exit. +\openout \auxfile=\jobname.aux +\endgroup} + + +% Footnotes. + +\newcount \footnoteno + +% The trailing space in the following definition for supereject is +% vital for proper filling; pages come out unaligned when you do a +% pagealignmacro call if that space before the closing brace is +% removed. +\def\supereject{\par\penalty -20000\footnoteno =0 } + +% @footnotestyle is meaningful for info output only.. +\let\footnotestyle=\comment + +\let\ptexfootnote=\footnote + +{\catcode `\@=11 +% +% Auto-number footnotes. Otherwise like plain. +\gdef\footnote{% + \global\advance\footnoteno by \@ne + \edef\thisfootno{$^{\the\footnoteno}$}% + % + % In case the footnote comes at the end of a sentence, preserve the + % extra spacing after we do the footnote number. + \let\@sf\empty + \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi + % + % Remove inadvertent blank space before typesetting the footnote number. + \unskip + \thisfootno\@sf + \footnotezzz +}% + +% Don't bother with the trickery in plain.tex to not require the +% footnote text as a parameter. Our footnotes don't need to be so general. +% +\long\gdef\footnotezzz#1{\insert\footins{% + % We want to typeset this text as a normal paragraph, even if the + % footnote reference occurs in (for example) a display environment. + % So reset some parameters. + \interlinepenalty\interfootnotelinepenalty + \splittopskip\ht\strutbox % top baseline for broken footnotes + \splitmaxdepth\dp\strutbox + \floatingpenalty\@MM + \leftskip\z@skip + \rightskip\z@skip + \spaceskip\z@skip + \xspaceskip\z@skip + \parindent\defaultparindent + % + % Hang the footnote text off the number. + \hang + \textindent{\thisfootno}% + % + % Don't crash into the line above the footnote text. Since this + % expands into a box, it must come within the paragraph, lest it + % provide a place where TeX can split the footnote. + \footstrut + #1\strut}% +} + +}%end \catcode `\@=11 + +% Set the baselineskip to #1, and the lineskip and strut size +% correspondingly. There is no deep meaning behind these magic numbers +% used as factors; they just match (closely enough) what Knuth defined. +% +\def\lineskipfactor{.08333} +\def\strutheightpercent{.70833} +\def\strutdepthpercent {.29167} +% +\def\setleading#1{% + \normalbaselineskip = #1\relax + \normallineskip = \lineskipfactor\normalbaselineskip + \normalbaselines + \setbox\strutbox =\hbox{% + \vrule width0pt height\strutheightpercent\baselineskip + depth \strutdepthpercent \baselineskip + }% +} + +% @| inserts a changebar to the left of the current line. It should +% surround any changed text. This approach does *not* work if the +% change spans more than two lines of output. To handle that, we would +% have adopt a much more difficult approach (putting marks into the main +% vertical list for the beginning and end of each change). +% +\def\|{% + % \vadjust can only be used in horizontal mode. + \leavevmode + % + % Append this vertical mode material after the current line in the output. + \vadjust{% + % We want to insert a rule with the height and depth of the current + % leading; that is exactly what \strutbox is supposed to record. + \vskip-\baselineskip + % + % \vadjust-items are inserted at the left edge of the type. So + % the \llap here moves out into the left-hand margin. + \llap{% + % + % For a thicker or thinner bar, change the `1pt'. + \vrule height\baselineskip width1pt + % + % This is the space between the bar and the text. + \hskip 12pt + }% + }% +} + +% For a final copy, take out the rectangles +% that mark overfull boxes (in case you have decided +% that the text looks ok even though it passes the margin). +% +\def\finalout{\overfullrule=0pt} + + +% End of control word definitions. + +\message{and turning on texinfo input format.} + +\def\openindices{% + \newindex{cp}% + \newcodeindex{fn}% + \newcodeindex{vr}% + \newcodeindex{tp}% + \newcodeindex{ky}% + \newcodeindex{pg}% +} + +% Set some numeric style parameters, for 8.5 x 11 format. + +%\hsize = 6.5in +\newdimen\defaultparindent \defaultparindent = 15pt +\parindent = \defaultparindent +\parskip 18pt plus 1pt +\setleading{15pt} +\advance\topskip by 1.2cm + +% Prevent underfull vbox error messages. +\vbadness=10000 + +% Following George Bush, just get rid of widows and orphans. +\widowpenalty=10000 +\clubpenalty=10000 + +% Use TeX 3.0's \emergencystretch to help line breaking, but if we're +% using an old version of TeX, don't do anything. We want the amount of +% stretch added to depend on the line length, hence the dependence on +% \hsize. This makes it come to about 9pt for the 8.5x11 format. +% +\ifx\emergencystretch\thisisundefined + % Allow us to assign to \emergencystretch anyway. + \def\emergencystretch{\dimen0}% +\else + \emergencystretch = \hsize + \divide\emergencystretch by 45 +\fi + +% Use @smallbook to reset parameters for 7x9.5 format (or else 7x9.25) +\def\smallbook{ + +% These values for secheadingskip and subsecheadingskip are +% experiments. RJC 7 Aug 1992 +\global\secheadingskip = 17pt plus 6pt minus 3pt +\global\subsecheadingskip = 14pt plus 6pt minus 3pt + +\global\lispnarrowing = 0.3in +\setleading{12pt} +\advance\topskip by -1cm +\global\parskip 3pt plus 1pt +\global\hsize = 5in +\global\vsize=7.5in +\global\tolerance=700 +\global\hfuzz=1pt +\global\contentsrightmargin=0pt +\global\deftypemargin=0pt +\global\defbodyindent=.5cm + +\global\pagewidth=\hsize +\global\pageheight=\vsize + +\global\let\smalllisp=\smalllispx +\global\let\smallexample=\smalllispx +\global\def\Esmallexample{\Esmalllisp} +} + +% Use @afourpaper to print on European A4 paper. +\def\afourpaper{ +\global\tolerance=700 +\global\hfuzz=1pt +\setleading{12pt} +\global\parskip 15pt plus 1pt + +\global\vsize= 53\baselineskip +\advance\vsize by \topskip +%\global\hsize= 5.85in % A4 wide 10pt +\global\hsize= 6.5in +\global\outerhsize=\hsize +\global\advance\outerhsize by 0.5in +\global\outervsize=\vsize +\global\advance\outervsize by 0.6in + +\global\pagewidth=\hsize +\global\pageheight=\vsize +} + +% Allow control of the text dimensions. Parameters in order: textheight; +% textwidth; \voffset; \hoffset (!); binding offset. All require a dimension; +% header is additional; added length extends the bottom of the page. + +\def\changepagesizes#1#2#3#4#5{ + \global\vsize= #1 + \advance\vsize by \topskip + \global\voffset= #3 + \global\hsize= #2 + \global\outerhsize=\hsize + \global\advance\outerhsize by 0.5in + \global\outervsize=\vsize + \global\advance\outervsize by 0.6in + \global\pagewidth=\hsize + \global\pageheight=\vsize + \global\normaloffset= #4 + \global\bindingoffset= #5} + +% This layout is compatible with Latex on A4 paper. + +\def\afourlatex{\changepagesizes{22cm}{15cm}{7mm}{4.6mm}{5mm}} + +% Use @afourwide to print on European A4 paper in wide format. +\def\afourwide{\afourpaper +\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}} + +% Define macros to output various characters with catcode for normal text. +\catcode`\"=\other +\catcode`\~=\other +\catcode`\^=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode`\+=\other +\def\normaldoublequote{"} +\def\normaltilde{~} +\def\normalcaret{^} +\def\normalunderscore{_} +\def\normalverticalbar{|} +\def\normalless{<} +\def\normalgreater{>} +\def\normalplus{+} + +% This macro is used to make a character print one way in ttfont +% where it can probably just be output, and another way in other fonts, +% where something hairier probably needs to be done. +% +% #1 is what to print if we are indeed using \tt; #2 is what to print +% otherwise. Since all the Computer Modern typewriter fonts have zero +% interword stretch (and shrink), and it is reasonable to expect all +% typewriter fonts to have this, we can check that font parameter. +% +\def\ifusingtt#1#2{\ifdim \fontdimen3\the\font=0pt #1\else #2\fi} + +% Turn off all special characters except @ +% (and those which the user can use as if they were ordinary). +% Most of these we simply print from the \tt font, but for some, we can +% use math or other variants that look better in normal text. + +\catcode`\"=\active +\def\activedoublequote{{\tt \char '042}} +\let"=\activedoublequote +\catcode`\~=\active +\def~{{\tt \char '176}} +\chardef\hat=`\^ +\catcode`\^=\active +\def\auxhat{\def^{'hat}} +\def^{{\tt \hat}} + +\catcode`\_=\active +\def_{\ifusingtt\normalunderscore\_} +% Subroutine for the previous macro. +\def\_{\lvvmode \kern.06em \vbox{\hrule width.3em height.1ex}} + +% \lvvmode is equivalent in function to \leavevmode. +% Using \leavevmode runs into trouble when written out to +% an index file due to the expansion of \leavevmode into ``\unhbox +% \voidb@x'' ---which looks to TeX like ``\unhbox \voidb\x'' due to our +% magic tricks with @. +\def\lvvmode{\vbox to 0pt{}} + +\catcode`\|=\active +\def|{{\tt \char '174}} +\chardef \less=`\< +\catcode`\<=\active +\def<{{\tt \less}} +\chardef \gtr=`\> +\catcode`\>=\active +\def>{{\tt \gtr}} +\catcode`\+=\active +\def+{{\tt \char 43}} +%\catcode 27=\active +%\def^^[{$\diamondsuit$} + +% Set up an active definition for =, but don't enable it most of the time. +{\catcode`\==\active +\global\def={{\tt \char 61}}} + +\catcode`+=\active +\catcode`\_=\active + +% If a .fmt file is being used, characters that might appear in a file +% name cannot be active until we have parsed the command line. +% So turn them off again, and have \everyjob (or @setfilename) turn them on. +% \otherifyactive is called near the end of this file. +\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} + +\catcode`\@=0 + +% \rawbackslashxx output one backslash character in current font +\global\chardef\rawbackslashxx=`\\ +%{\catcode`\\=\other +%@gdef@rawbackslashxx{\}} + +% \rawbackslash redefines \ as input to do \rawbackslashxx. +{\catcode`\\=\active +@gdef@rawbackslash{@let\=@rawbackslashxx }} + +% \normalbackslash outputs one backslash in fixed width font. +\def\normalbackslash{{\tt\rawbackslashxx}} + +% Say @foo, not \foo, in error messages. +\escapechar=`\@ + +% \catcode 17=0 % Define control-q +\catcode`\\=\active + +% Used sometimes to turn off (effectively) the active characters +% even after parsing them. +@def@turnoffactive{@let"=@normaldoublequote +@let\=@realbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +@def@normalturnoffactive{@let"=@normaldoublequote +@let\=@normalbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +% Make _ and + \other characters, temporarily. +% This is canceled by @fixbackslash. +@otherifyactive + +% If a .fmt file is being used, we don't want the `\input texinfo' to show up. +% That is what \eatinput is for; after that, the `\' should revert to printing +% a backslash. +% +@gdef@eatinput input texinfo{@fixbackslash} +@global@let\ = @eatinput + +% On the other hand, perhaps the file did not have a `\input texinfo'. Then +% the first `\{ in the file would cause an error. This macro tries to fix +% that, assuming it is called before the first `\' could plausibly occur. +% Also back turn on active characters that might appear in the input +% file name, in case not using a pre-dumped format. +% +@gdef@fixbackslash{@ifx\@eatinput @let\ = @normalbackslash @fi + @catcode`+=@active @catcode`@_=@active} + +%% These look ok in all fonts, so just make them not special. The @rm below +%% makes sure that the current font starts out as the newly loaded cmr10 +@catcode`@$=@other @catcode`@%=@other @catcode`@&=@other @catcode`@#=@other + +@textfonts +@rm + +@c Local variables: +@c page-delimiter: "^\\\\message" +@c End: |