From b7fc9e0f6d6105ba2203f219743d4b269415e84b Mon Sep 17 00:00:00 2001 From: An-Cheng Huang Date: Mon, 12 Nov 2007 13:06:02 -0800 Subject: initial import from bash_3.1dfsg.orig.tar.gz --- doc/FAQ | 0 doc/INTRO | 187 ++ doc/Makefile.in | 291 ++ doc/README | 36 + doc/article.ms | 1114 +++++++ doc/article.ps | 1418 +++++++++ doc/bash.1 | 8866 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/bashbug.1 | 41 + doc/bashref.texi | 14 + doc/builtins.1 | 15 + doc/fdl.texi | 452 +++ doc/fdl.txt | 397 +++ doc/htmlpost.sh | 19 + doc/infopost.sh | 8 + doc/rbash.1 | 8 + doc/rose94.ps | 1581 ++++++++++ doc/texinfo.tex | 6688 ++++++++++++++++++++++++++++++++++++++++ doc/version.texi | 10 + 18 files changed, 21145 insertions(+) create mode 100644 doc/FAQ create mode 100644 doc/INTRO create mode 100644 doc/Makefile.in create mode 100644 doc/README create mode 100644 doc/article.ms create mode 100644 doc/article.ps create mode 100644 doc/bash.1 create mode 100644 doc/bashbug.1 create mode 100644 doc/bashref.texi create mode 100644 doc/builtins.1 create mode 100644 doc/fdl.texi create mode 100644 doc/fdl.txt create mode 100755 doc/htmlpost.sh create mode 100755 doc/infopost.sh create mode 100644 doc/rbash.1 create mode 100644 doc/rose94.ps create mode 100644 doc/texinfo.tex create mode 100644 doc/version.texi (limited to 'doc') diff --git a/doc/FAQ b/doc/FAQ new file mode 100644 index 0000000..e69de29 diff --git a/doc/INTRO b/doc/INTRO new file mode 100644 index 0000000..29f208a --- /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 facility. + +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 0000000..270ddfd --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,291 @@ +# This Makefile is for the Bash/documentation directory -*- text -*-. +# +# Copyright (C) 2003 Free Software Foundation, Inc. + +# This program 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 program 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 program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +PACKAGE = @PACKAGE_NAME@ +VERSION = @PACKAGE_VERSION@ + +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_VERSION = @PACKAGE_VERSION@ + +# +SHELL = @MAKE_SHELL@ +RM = rm -f + +topdir = @top_srcdir@ +srcdir = @srcdir@ +VPATH = .:@srcdir@ + +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +infodir = @infodir@ + +# set this to a directory name to have the HTML files installed +htmldir = @htmldir@ + +# Support an alternate destination root directory for package building +DESTDIR = + +mandir = @mandir@ +manpfx = man + +man1ext = .1 +man1dir = $(mandir)/$(manpfx)1 +man3ext = .3 +man3dir = $(mandir)/$(manpfx)3 + +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +BUILD_DIR = @BUILD_DIR@ + +SUPPORT_SRCDIR = $(topdir)/support + +# bad style +RL_LIBDIR = $(topdir)/lib/readline + +# unused +TEXINDEX = texindex +TEX = tex + +MAKEINFO = makeinfo +TEXI2DVI = ${SUPPORT_SRCDIR}/texi2dvi +TEXI2HTML = ${SUPPORT_SRCDIR}/texi2html +MAN2HTML = ${BUILD_DIR}/support/man2html +HTMLPOST = ${srcdir}/htmlpost.sh +INFOPOST = ${srcdir}/infopost.sh +QUIETPS = #set this to -q to shut up dvips +PAPERSIZE = letter # change to a4 for A4-size paper +PSDPI = 600 # could be 300 if you like +DVIPS = dvips -D ${PSDPI} $(QUIETPS) -t ${PAPERSIZE} -o $@ # tricky + +TEXINPUTDIR = $(RL_LIBDIR)/doc +SET_TEXINPUTS = TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS + +# These tools might not be available; they're not required +DVIPDF = dvipdfm -o $@ -p ${PAPERSIZE} +PSPDF = gs -sPAPERSIZE=${PAPERSIZE} -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=$@ + +MKDIRS = ${SUPPORT_SRCDIR}/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.texi +RLUSER = $(RL_LIBDIR)/doc/rluser.texi + +BASHREF_FILES = $(srcdir)/bashref.texi $(srcdir)/version.texi + +.SUFFIXES: .0 .1 .3 .ms .ps .txt .dvi .html .pdf + +.1.ps: + $(RM) $@ + -${GROFF} -man $< > $@ + +.1.0: + $(RM) $@ + -${NROFF} -man $< > $@ + +.1.html: + $(RM) $@ + -${MAN2HTML} $< | ${HTMLPOST} > $@ + +.ms.ps: + $(RM) $@ + -${GROFF} -ms $< > $@ + +.ms.txt: + $(RM) $@ + -${NROFF} -ms $< > $@ + +.3.ps: + $(RM) $@ + -${GROFF} -man $< > $@ + +.3.0: + $(RM) $@ + -${NROFF} -man $< > $@ + +.3.html: + $(RM) $@ + -${MAN2HTML} $< > $@ + +.ps.pdf: + $(RM) $@ + -${PSPDF} $< + +.dvi.pdf: + $(RM) $@ + -${DVIPDF} $< + +.dvi.ps: + ${RM} $@ + -${DVIPS} $< + +all: ps info dvi text html +nodvi: ps info text html + +PSFILES = bash.ps bashbug.ps article.ps builtins.ps rbash.ps +DVIFILES = bashref.dvi bashref.ps +INFOFILES = bashref.info +MAN0FILES = bash.0 bashbug.0 builtins.0 rbash.0 +HTMLFILES = bashref.html bash.html +PDFFILES = bash.pdf bashref.pdf article.pdf rose94.pdf + +ps: ${PSFILES} +dvi: ${DVIFILES} +info: ${INFOFILES} +text: ${MAN0FILES} +html: ${HTMLFILES} +pdf: ${PDFFILES} + +bashref.dvi: $(BASHREF_FILES) $(HSUSER) $(RLUSER) + ${SET_TEXINPUTS} $(TEXI2DVI) $(srcdir)/bashref.texi + +bashref.info: $(BASHREF_FILES) $(HSUSER) $(RLUSER) + $(MAKEINFO) --no-split -I$(TEXINPUTDIR) $(srcdir)/bashref.texi + +bashref.html: $(BASHREF_FILES) $(HSUSER) $(RLUSER) + $(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/bashref.texi + +bash.info: bashref.info + ${SHELL} ${INFOPOST} < $(srcdir)/bashref.info > $@ ; \ + +bash.txt: bash.1 +bash.ps: bash.1 +bash.html: bash.1 $(MAN2HTML) +bashbug.ps: bashbug.1 +builtins.ps: builtins.1 bash.1 +rbash.ps: rbash.1 bash.1 +bash.0: bash.1 +bashbug.0: bashbug.1 +builtins.0: builtins.1 bash.1 +rbash.0: rbash.1 bash.1 +article.ps: article.ms + +bashref.ps: bashref.dvi + +article.pdf: article.ps +bashref.pdf: bashref.dvi +bash.pdf: bash.ps +rose94.pdf: rose94.ps + +$(MAN2HTML): ${topdir}/support/man2html.c + -( cd ${BUILD_DIR}/support ; ${MAKE} ${MFLAGS} man2html) + +clean: + $(RM) *.aux *.bak *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.cps \ + *.pgs *.bt *.bts *.rw *.rws *.fns *.kys *.tps *.vrs *.o + ${RM} core *.core + +mostlyclean: clean + $(RM) Makefile + +distclean: clean maybe-clean + $(RM) Makefile + +maintainer-clean: clean + ${RM} ${PSFILES} ${DVIFILES} ${INFOFILES} ${MAN0FILES} ${HTMLFILES} + ${RM} ${CREATED_FAQ} + $(RM) Makefile + +maybe-clean: + -if test "X$(topdir)" != "X$(BUILD_DIR)"; then \ + $(RM) ${PSFILES} ${DVIFILES} ${INFOFILES} ${MAN0FILES} ${HTMLFILES}; \ + fi + +installdirs: + -$(SHELL) $(SUPPORT_SRCDIR)/mkinstalldirs $(DESTDIR)$(man1dir) + -$(SHELL) $(SUPPORT_SRCDIR)/mkinstalldirs $(DESTDIR)$(infodir) + -if test -n "$(htmldir)" ; then \ + $(SHELL) $(SUPPORT_SRCDIR)/mkinstalldirs $(DESTDIR)$(htmldir) ; \ + fi + +install: info installdirs bash.info + -$(INSTALL_DATA) $(srcdir)/bash.1 $(DESTDIR)$(man1dir)/bash${man1ext} + -$(INSTALL_DATA) $(srcdir)/bashbug.1 $(DESTDIR)$(man1dir)/bashbug${man1ext} +# uncomment the next line to install the builtins man page +# -$(INSTALL_DATA) $(srcdir)/builtins.1 $(DESTDIR)$(man1dir)/bash_builtins${man1ext} + -$(INSTALL_DATA) $(srcdir)/bash.info $(DESTDIR)$(infodir)/bash.info +# run install-info if it is present to update the info directory + if $(SHELL) -c 'install-info --version' >/dev/null 2>&1; then \ + install-info --dir-file=$(DESTDIR)$(infodir)/dir $(DESTDIR)$(infodir)/bash.info; \ + else true; fi +# if htmldir is set, install the html files into that directory + -if test -n "${htmldir}" ; then \ + $(INSTALL_DATA) $(srcdir)/bash.html $(DESTDIR)$(htmldir) ; \ + $(INSTALL_DATA) $(srcdir)/bashref.html $(DESTDIR)$(htmldir) ; \ + fi + +uninstall: + -$(RM) $(DESTDIR)$(man1dir)/bash${man1ext} $(DESTDIR)$(man1dir)/bashbug${man1ext} + $(RM) $(DESTDIR)$(infodir)/bash.info + -if test -n "$(htmldir)" ; then \ + $(RM) $(DESTDIR)$(htmldir)/bash.html ; \ + $(RM) $(DESTDIR)$(htmldir)/bashref.html ; \ + fi + +# for use by chet +CREATED_FAQ = faq.news faq.news2 faq.mail faq.version + +faq: ${CREATED_FAQ} + +faq.version: FAQ.version FAQ + sh mkfaqvers FAQ.version > $@ + +faq.headers.mail: FAQ.headers.mail FAQ + sh mkfaqvers FAQ.headers.mail > $@ + +faq.headers.news: FAQ.headers.news FAQ + sh mkfaqvers FAQ.headers.news > $@ + +faq.headers.news2: FAQ.headers.news2 FAQ + sh mkfaqvers FAQ.headers.news2 > $@ + +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 > $@ + +inst: bashref.texi + $(SHELL) ./mkinstall + cmp -s INSTALL ../INSTALL || mv INSTALL ../INSTALL + $(RM) INSTALL + +posix: bashref.texi + $(SHELL) ./mkposix + cmp -s POSIX ../POSIX || mv POSIX ../POSIX + $(RM) POSIX + +rbash: bashref.texi + $(SH) ./mkrbash + cmp -s RBASH ../RBASH || mv RBASH ../RBASH + $(RM) RBASH + +xdist: pdf inst posix rbash diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..e3a1d24 --- /dev/null +++ b/doc/README @@ -0,0 +1,36 @@ +This directory contains the bash documentation. + +FAQ - a set of frequently-asked questions about Bash with answers +INTRO - a short introduction to bash +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 +bashref.texi - the `bash reference manual' +bashref.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 0000000..517155a --- /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/article.ps b/doc/article.ps new file mode 100644 index 0000000..3aadf2f --- /dev/null +++ b/doc/article.ps @@ -0,0 +1,1418 @@ +%!PS-Adobe-3.0 +%%Creator: groff version 1.16.1 +%%CreationDate: Mon Nov 19 13:06:55 2001 +%%DocumentNeededResources: font Times-Bold +%%+ font Times-Italic +%%+ font Times-Roman +%%+ font Courier +%%DocumentSuppliedResources: procset grops 1.16 1 +%%Pages: 11 +%%PageOrder: Ascend +%%Orientation: Portrait +%%EndComments +%%BeginProlog +%%BeginResource: procset grops 1.16 1 +/setpacking where{ +pop +currentpacking +true setpacking +}if +/grops 120 dict dup begin +/SC 32 def +/A/show load def +/B{0 SC 3 -1 roll widthshow}bind def +/C{0 exch ashow}bind def +/D{0 exch 0 SC 5 2 roll awidthshow}bind def +/E{0 rmoveto show}bind def +/F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def +/G{0 rmoveto 0 exch ashow}bind def +/H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/I{0 exch rmoveto show}bind def +/J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def +/K{0 exch rmoveto 0 exch ashow}bind def +/L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/M{rmoveto show}bind def +/N{rmoveto 0 SC 3 -1 roll widthshow}bind def +/O{rmoveto 0 exch ashow}bind def +/P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/Q{moveto show}bind def +/R{moveto 0 SC 3 -1 roll widthshow}bind def +/S{moveto 0 exch ashow}bind def +/T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/SF{ +findfont exch +[exch dup 0 exch 0 exch neg 0 0]makefont +dup setfont +[exch/setfont cvx]cvx bind def +}bind def +/MF{ +findfont +[5 2 roll +0 3 1 roll +neg 0 0]makefont +dup setfont +[exch/setfont cvx]cvx bind def +}bind def +/level0 0 def +/RES 0 def +/PL 0 def +/LS 0 def +/MANUAL{ +statusdict begin/manualfeed true store end +}bind def +/PLG{ +gsave newpath clippath pathbbox grestore +exch pop add exch pop +}bind def +/BP{ +/level0 save def +1 setlinecap +1 setlinejoin +72 RES div dup scale +LS{ +90 rotate +}{ +0 PL translate +}ifelse +1 -1 scale +}bind def +/EP{ +level0 restore +showpage +}bind def +/DA{ +newpath arcn stroke +}bind def +/SN{ +transform +.25 sub exch .25 sub exch +round .25 add exch round .25 add exch +itransform +}bind def +/DL{ +SN +moveto +SN +lineto stroke +}bind def +/DC{ +newpath 0 360 arc closepath +}bind def +/TM matrix def +/DE{ +TM currentmatrix pop +translate scale newpath 0 0 .5 0 360 arc closepath +TM setmatrix +}bind def +/RC/rcurveto load def +/RL/rlineto load def +/ST/stroke load def +/MT/moveto load def +/CL/closepath load def +/FL{ +currentgray exch setgray fill setgray +}bind def +/BL/fill load def +/LW/setlinewidth load def +/RE{ +findfont +dup maxlength 1 index/FontName known not{1 add}if dict begin +{ +1 index/FID ne{def}{pop pop}ifelse +}forall +/Encoding exch def +dup/FontName exch def +currentdict end definefont pop +}bind def +/DEFS 0 def +/EBEGIN{ +moveto +DEFS begin +}bind def +/EEND/end load def +/CNT 0 def +/level1 0 def +/PBEGIN{ +/level1 save def +translate +div 3 1 roll div exch scale +neg exch neg exch translate +0 setgray +0 setlinecap +1 setlinewidth +0 setlinejoin +10 setmiterlimit +[]0 setdash +/setstrokeadjust where{ +pop +false setstrokeadjust +}if +/setoverprint where{ +pop +false setoverprint +}if +newpath +/CNT countdictstack def +userdict begin +/showpage{}def +}bind def +/PEND{ +clear +countdictstack CNT sub{end}repeat +level1 restore +}bind def +end def +/setpacking where{ +pop +setpacking +}if +%%EndResource +%%IncludeResource: font Times-Bold +%%IncludeResource: font Times-Italic +%%IncludeResource: font Times-Roman +%%IncludeResource: font Courier +grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72 +def/PL 792 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron/Zcaron +/scaron/zcaron/Ydieresis/trademark/quotesingle/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent +/ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen +/period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon +/semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O +/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/circumflex +/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y +/z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase/guillemotleft +/guillemotright/bullet/florin/fraction/perthousand/dagger/daggerdbl +/endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut +/dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash +/quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen +/brokenbar/section/dieresis/copyright/ordfeminine/guilsinglleft +/logicalnot/minus/registered/macron/degree/plusminus/twosuperior +/threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior +/ordmasculine/guilsinglright/onequarter/onehalf/threequarters +/questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE +/Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex +/Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis +/multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn +/germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla +/egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis +/eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash +/ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def +/Courier@0 ENC0/Courier RE/Times-Roman@0 ENC0/Times-Roman RE +/Times-Italic@0 ENC0/Times-Italic RE/Times-Bold@0 ENC0/Times-Bold RE +%%EndProlog +%%Page: 1 1 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 12/Times-Bold@0 SF(Bash \255 The GNU shell*)227.904 123 Q/F1 10 +/Times-Italic@0 SF(Chet Rame)263.85 147 Q(y)-.3 E(Case W)221.72 159 Q +(estern Reserve Univer)-.92 E(sity)-.1 E -.15(ch)250.425 171 S +(et@po.cwru.edu).15 E/F2 10/Times-Bold@0 SF 2.5(1. Intr)72 207 R +(oduction)-.18 E(Bash)97 222.6 Q/F3 10/Times-Roman@0 SF .904 +(is the shell, or command language interpreter)3.404 F 3.404(,t)-.4 G +.904(hat will appear in the GNU operating system.)-3.404 F 1.075 +(The name is an acron)72 234.6 R 1.075(ym for the \231Bourne-Ag)-.15 F +1.075(ain SHell\232, a pun on Ste)-.05 F 1.375 -.15(ve B)-.25 H 1.075 +(ourne, the author of the direct).15 F .206(ancestor of the current)72 +246.6 R/F4 8/Times-Roman@0 SF(UNIX)2.706 E F3 2.706C(hell)-2.706 E +F1(/bin/sh)2.706 E F3 2.706(,w)C .205(hich appeared in the Se)-2.706 F +-.15(ve)-.25 G .205(nth Edition Bell Labs Research v).15 F(er)-.15 E(-) +-.2 E(sion of)72 258.6 Q/F5 9/Times-Roman@0 SF(UNIX)2.5 E F3(.)A .387 +(Bash is an)97 274.2 R F2(sh)2.887 E F3 .387 +(\255compatible shell that incorporates useful features from the K)B +.388(orn shell \()-.35 F F2(ksh)A F3 2.888(\)a)C .388(nd the C)-2.888 F +.023(shell \()72 286.2 R F2(csh)A F3 .023 +(\), described later in this article.)B .022 +(It is ultimately intended to be a conformant implementation of the) +5.022 F 3.568(IEEE POSIX Shell and Utilities speci\214cation \(IEEE W)72 +298.2 R 3.568(orking Group 1003.2\).)-.8 F 3.569(It of)8.569 F 3.569 +(fers functional)-.25 F(impro)72 310.2 Q -.15(ve)-.15 G(ments o).15 E +-.15(ve)-.15 G 2.5(rs).15 G 2.5(hf)-2.5 G(or both interacti)-2.5 E .3 +-.15(ve a)-.25 H(nd programming use.).15 E .697 +(While the GNU operating system will most lik)97 325.8 R .697 +(ely include a v)-.1 F .697(ersion of the Berk)-.15 F(ele)-.1 E 3.197 +(ys)-.15 G .696(hell csh, Bash)-3.197 F .015(will be the def)72 337.8 R +.015(ault shell.)-.1 F(Lik)5.015 E 2.515(eo)-.1 G .015(ther GNU softw) +-2.515 F .016(are, Bash is quite portable.)-.1 F .016 +(It currently runs on nearly e)5.016 F -.15(ve)-.25 G(ry).15 E -.15(ve) +72 349.8 S .523(rsion of).15 F F4(UNIX)3.023 E F3 .523(and a fe)3.023 F +3.023(wo)-.25 G .523 +(ther operating systems \255 an independently-supported port e)-3.023 F +.523(xists for OS/2, and)-.15 F .706 +(there are rumors of ports to DOS and W)72 361.8 R(indo)-.4 E .706 +(ws NT)-.25 F 5.706(.P)-.74 G .706(orts to)-5.706 F F5(UNIX)3.206 E F3 +(-lik)A 3.206(es)-.1 G .706(ystems such as QNX and Minix)-3.206 F +(are part of the distrib)72 373.8 Q(ution.)-.2 E .405 +(The original author of Bash w)97 389.4 R .405(as Brian F)-.1 F .405 +(ox, an emplo)-.15 F .405(yee of the Free Softw)-.1 F .405(are F)-.1 F +2.905(oundation. The)-.15 F(cur)2.905 E(-)-.2 E(rent de)72 401.4 Q -.15 +(ve)-.25 G(loper and maintainer is Chet Rame).15 E 1.3 -.65(y, a v)-.15 +H(olunteer who w).45 E(orks at Case W)-.1 E(estern Reserv)-.8 E 2.5(eU) +-.15 G(ni)-2.5 E -.15(ve)-.25 G(rsity).15 E(.)-.65 E F2 2.5(2. What')72 +425.4 R 2.5(sP)-.37 G(OSIX, anyway?)-2.5 E F1(POSIX)97 441 Q F3 .343 +(is a name originally coined by Richard Stallman for a f)2.843 F .343 +(amily of open system standards based)-.1 F(on)72 453 Q F5(UNIX)3.24 E +F3 5.74(.T)C .74(here are a number of aspects of)-5.74 F F5(UNIX)3.24 E +F3 .74(under consideration for standardization, from the basic)3.24 F +.192(system services at the system call and C library le)72 465 R -.15 +(ve)-.25 G 2.692(lt).15 G 2.692(oa)-2.692 G .192 +(pplications and tools to system administration and)-2.692 F 2.5 +(management. Each)72 477 R(area of standardization is assigned to a w) +2.5 E(orking group in the 1003 series.)-.1 E 2.814 +(The POSIX Shell and Utilities standard has been de)97 492.6 R -.15(ve) +-.25 G 2.814(loped by IEEE W).15 F 2.813(orking Group 1003.2)-.8 F .254 +(\(POSIX.2\).\210 It concentrates on the command interpreter interf)72 +504.6 R .253(ace and utility programs commonly e)-.1 F -.15(xe)-.15 G +(cuted).15 E 1.112(from the command line or by other programs.)72 516.6 +R 1.112(An initial v)6.112 F 1.113 +(ersion of the standard has been appro)-.15 F -.15(ve)-.15 G 3.613(da) +.15 G(nd)-3.613 E .365(published by the IEEE, and w)72 528.6 R .365 +(ork is currently underw)-.1 F .365(ay to update it.)-.1 F .365 +(There are four primary areas of w)5.365 F(ork)-.1 E +(in the 1003.2 standard:)72 540.6 Q 21.5<8341>72 556.2 S .835 +(spects of the shell')-21.5 F 3.335(ss)-.55 G .835 +(yntax and command language.)-3.335 F 3.335(An)5.835 G .835 +(umber of special b)-3.335 F .835(uiltins such as)-.2 F F2(cd)3.335 E F3 +(and)3.335 E F2(exec)97 568.2 Q F3 .545(are being speci\214ed as part o\ +f the shell, since their functionality usually cannot be implemented) +3.046 F(by a separate e)97 580.2 Q -.15(xe)-.15 G(cutable;).15 E 21.5 +<8341>72 595.8 S .926 +(set of utilities to be called by shell scripts and applications.) +-18.074 F .927(Examples are programs lik)5.927 F(e)-.1 E F1 .927 +(sed, tr)3.427 F(,)-1.11 E F3(and)97 607.8 Q F1(awk.)2.797 E F3 .297 +(Utilities commonly implemented as shell b)5.297 F .296 +(uiltins are described in this section, such as)-.2 F F2(test)2.796 E F3 +(and)97 619.8 Q F2(kill)3.422 E F3 5.922(.A)C 3.422(ne)-5.922 G .922 +(xpansion of this section')-3.572 F 3.423(ss)-.55 G .923 +(cope, termed the User Portability Extension, or UPE, has)-3.423 F +(standardized interacti)97 631.8 Q .3 -.15(ve p)-.25 H(rograms such as) +.15 E F1(vi)2.5 E F3(and)2.5 E F1(mailx;)2.5 E F3 21.5<8341>72 647.4 S +.288(group of functional interf)-18.712 F .287(aces to services pro)-.1 +F .287(vided by the shell, such as the traditional)-.15 F/F6 10 +/Courier@0 SF(system\(\))2.787 E F3 3.289(Cl)97 659.4 S .789 +(ibrary function.)-3.289 F .789(There are functions to perform shell w) +5.789 F .789(ord e)-.1 F .79(xpansions, perform \214lename e)-.15 F +(xpan-)-.15 E .324(sion \()97 671.4 R F1(globbing)A F3 .324 +(\), obtain v)B .323(alues of POSIX.2 system con\214guration v)-.25 F +.323(ariables, retrie)-.25 F .623 -.15(ve v)-.25 H .323(alues of en)-.1 +F(viron-)-.4 E(ment v)97 683.4 Q(ariables \()-.25 E F6(getenv\(\))A F3 +(\), and other services;).833 E .32 LW 144 691.4 72 691.4 DL F4 +(*An earlier v)72 703.2 Q +(ersion of this article appeared in The Linux Journal.)-.12 E(\210IEEE,) +72 715 Q/F7 8/Times-Italic@0 SF 1.231(IEEE Standar)3.231 F 3.231(df) +-.296 G 1.231(or Information T)-3.231 F(ec)-.736 E(hnolo)-.12 E 1.231 +(gy -- P)-.08 F 1.231(ortable Oper)-.64 F 1.232 +(ating System Interface \(POSIX\) P)-.12 F 1.232(art 2:)-.64 F +(Shell and Utilities)72 725 Q F4 2(,1)C(992.)-2 E EP +%%Page: 2 2 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-2-)282.17 48 Q 21.5<8341>72 84 S +(suite of \231de)-19 E -.15(ve)-.25 G(lopment\232 utilities such as).15 +E/F1 10/Times-Italic@0 SF(c89)2.5 E F0(\(the POSIX.2 v)2.5 E(ersion of) +-.15 E F1(cc)2.5 E F0(\), and)A F1(yacc.)2.5 E F0 .483 +(Bash is concerned with the aspects of the shell')97 99.6 R 2.983(sb) +-.55 G(eha)-2.983 E .484(vior de\214ned by POSIX.2.)-.2 F .484 +(The shell command)5.484 F 1.439 +(language has of course been standardized, including the basic \215o)72 +111.6 R 3.938(wc)-.25 G 1.438(ontrol and program e)-3.938 F -.15(xe)-.15 +G 1.438(cution con-).15 F 1.284 +(structs, I/O redirection and pipelining, ar)72 123.6 R 1.284 +(gument handling, v)-.18 F 1.284(ariable e)-.25 F 1.284 +(xpansion, and quoting.)-.15 F(The)6.285 E F1(special)3.785 E F0 -.2(bu) +72 135.6 S .676 +(iltins, which must be implemented as part of the shell to pro).2 F .676 +(vide the desired functionality)-.15 F 3.176(,a)-.65 G .676 +(re speci\214ed)-3.176 F .7(as being part of the shell; e)72 147.6 R .7 +(xamples of these are)-.15 F/F2 10/Times-Bold@0 SF -2.3 -.15(ev a)3.201 +H(l).15 E F0(and)3.201 E F2(export)3.201 E F0 5.701(.O)C .701 +(ther utilities appear in the sections of)-5.701 F .256(POSIX.2 not de) +72 159.6 R -.2(vo)-.25 G .256(ted to the shell which are commonly \(and\ + in some cases must be\) implemented as b).2 F(uiltin)-.2 E .213 +(commands, such as)72 171.6 R F2 -.18(re)2.713 G(ad).18 E F0(and)2.713 E +F2(test)2.713 E F0 5.213(.P)C .213 +(OSIX.2 also speci\214es aspects of the shell')-5.213 F 2.713(si)-.55 G +(nteracti)-2.713 E .513 -.15(ve b)-.25 H(eha).15 E .214(vior as part)-.2 +F .598(of the UPE, including job control and command line editing.)72 +183.6 R .598(Interestingly enough, only)5.598 F F1(vi)3.098 E F0 .598 +(-style line edit-)B(ing commands ha)72 195.6 Q .3 -.15(ve b)-.2 H +(een standardized;).15 E F1(emacs)2.5 E F0 +(editing commands were left out due to objections.)2.5 E 1.128 +(While POSIX.2 includes much of what the shell has traditionally pro)97 +211.2 R 1.129(vided, some important things)-.15 F(ha)72 223.2 Q .344 +-.15(ve b)-.2 H .044(een omitted as being \231be).15 F .044 +(yond its scope.)-.15 F 5.043<9a54>-.7 G .043 +(here is, for instance, no mention of a dif)-5.043 F .043 +(ference between a)-.25 F F1(lo)72 235.2 Q(gin)-.1 E F0 1.445 +(shell and an)3.945 F 3.945(yo)-.15 G 1.445(ther interacti)-3.945 F +1.745 -.15(ve s)-.25 H 1.446 +(hell \(since POSIX.2 does not specify a login program\).).15 F 1.446 +(No \214x)6.446 F(ed)-.15 E(startup \214les are de\214ned, either \255 \ +the standard does not mention)72 247.2 Q F1(.pr)2.5 E(o\214le)-.45 E F0 +(.)A F2 2.5(3. Basic)72 271.2 R(Bash featur)2.5 E(es)-.18 E F0 1.448 +(Since the Bourne shell pro)97 286.8 R 1.448 +(vides Bash with most of its philosophical underpinnings, Bash inherits) +-.15 F .64(most of its features and functionality from sh.)72 298.8 R +.641(Bash implements all of the traditional sh \215o)5.641 F 3.141(wc) +-.25 G .641(ontrol con-)-3.141 F .8(structs \()72 310.8 R F1(for)A F0(,) +A F1(if)3.3 E F0(,)A F1(while)3.3 E F0 3.3(,e)C 3.3(tc.\). All)-3.3 F +.799(of the Bourne shell b)3.3 F .799 +(uiltins, including those not speci\214ed in the POSIX.2)-.2 F .536 +(standard, appear in Bash.)72 322.8 R(Shell)5.536 E F1(functions)3.036 E +F0 3.036(,i)C .536(ntroduced in the SVR2 v)-3.036 F .537 +(ersion of the Bourne shell, are similar)-.15 F .779 +(to shell scripts, b)72 334.8 R .779 +(ut are de\214ned using a special syntax and are e)-.2 F -.15(xe)-.15 G +.779(cuted in the same process as the calling).15 F 2.841(shell. Bash)72 +346.8 R .341(has shell functions which beha)2.841 F .641 -.15(ve i)-.2 H +2.841(naf).15 G .341(ashion upw)-2.941 F .342 +(ard-compatible with sh functions.)-.1 F .342(There are)5.342 F 1.447 +(certain shell v)72 358.8 R 1.446 +(ariables that Bash interprets in the same w)-.25 F 1.446 +(ay as sh, such as)-.1 F F2(PS1)3.946 E F0(,)A F2(IFS)3.946 E F0 3.946 +(,a)C(nd)-3.946 E F2 -.74(PA)3.946 G(TH)-.21 E F0 6.446(.B)C(ash)-6.446 +E 1.423(implements essentially the same grammar)72 370.8 R 3.924(,p)-.4 +G 1.424(arameter and v)-3.924 F 1.424(ariable e)-.25 F 1.424 +(xpansion semantics, redirection, and)-.15 F 1.06 +(quoting as the Bourne shell.)72 382.8 R 1.06(Where dif)6.06 F 1.06 +(ferences appear between the POSIX.2 standard and traditional sh)-.25 F +(beha)72 394.8 Q(vior)-.2 E 2.5(,B)-.4 G(ash follo)-2.5 E(ws POSIX.)-.25 +E 1.608(The K)97 410.4 R 1.608(orn Shell \()-.35 F F2(ksh)A F0 4.108 +(\)i)C 4.108(sad)-4.108 G 1.608 +(escendent of the Bourne shell written at A)-4.108 F 1.609 +(T&T Bell Laboratories by)-1.11 F(Da)72 422.4 Q 1.059(vid K)-.2 F 3.559 +(orn\207. It)-.35 F(pro)3.559 E 1.059 +(vides a number of useful features that POSIX and Bash ha)-.15 F 1.359 +-.15(ve a)-.2 H 3.558(dopted. Man).15 F 3.558(yo)-.15 G 3.558(ft)-3.558 +G(he)-3.558 E(interacti)72 434.4 Q 1.312 -.15(ve f)-.25 H 1.012 +(acilities in POSIX.2 ha).05 F 1.312 -.15(ve t)-.2 H 1.012 +(heir roots in the ksh: for e).15 F 1.013 +(xample, the POSIX and ksh job control)-.15 F -.1(fa)72 446.4 S .513 +(cilities are nearly identical. Bash includes features from the K).1 F +.513(orn Shell for both interacti)-.35 F .813 -.15(ve u)-.25 H .513 +(se and shell).15 F 3.905(programming. F)72 458.4 R 1.405 +(or programming, Bash pro)-.15 F 1.405(vides v)-.15 F 1.405 +(ariables such as)-.25 F F2(RANDOM)3.905 E F0(and)3.905 E F2(REPL)3.905 +E(Y)-.92 E F0 3.905(,t)C(he)-3.905 E F2(typeset)3.905 E F0 -.2(bu)72 +470.4 S .398(iltin, the ability to remo).2 F .698 -.15(ve s)-.15 H .398 +(ubstrings from v).15 F .398 +(ariables based on patterns, and shell arithmetic.)-.25 F F2(RANDOM) +5.397 E F0 -.15(ex)72 482.4 S .489 +(pands to a random number each time it is referenced; assigning a v).15 +F .49(alue to)-.25 F F2(RANDOM)2.99 E F0 .49(seeds the random)2.99 F +.055(number generator)72 494.4 R(.)-.55 E F2(REPL)5.055 E(Y)-.92 E F0 +.054(is the def)2.554 F .054(ault v)-.1 F .054(ariable used by the)-.25 +F F2 -.18(re)2.554 G(ad).18 E F0 -.2(bu)2.554 G .054(iltin when no v).2 +F .054(ariable names are sup-)-.25 F .742(plied as ar)72 506.4 R 3.243 +(guments. The)-.18 F F2(typeset)3.243 E F0 -.2(bu)3.243 G .743 +(iltin is used to de\214ne v).2 F .743(ariables and gi)-.25 F 1.043 -.15 +(ve t)-.25 H .743(hem attrib).15 F .743(utes such as)-.2 F F2 -.18(re) +3.243 G(ad-).18 E(only)72 518.4 Q F0 5.512(.B)C .512 +(ash arithmetic allo)-5.512 F .512(ws the e)-.25 F -.25(va)-.25 G .511 +(luation of an e).25 F .511 +(xpression and the substitution of the result.)-.15 F .511(Shell v)5.511 +F(ari-)-.25 E .222 +(ables may be used as operands, and the result of an e)72 530.4 R .222 +(xpression may be assigned to a v)-.15 F 2.722(ariable. Nearly)-.25 F +.222(all of)2.722 F(the operators from the C language are a)72 542.4 Q +-.25(va)-.2 G(ilable, with the same precedence rules:).25 E/F3 10 +/Courier@0 SF 6($e)97 560.4 S(cho $\(\(3 + 5 * 32\)\))-6 E(163)97 572.4 +Q F0 -.15(Fo)72 594 S 3.24(ri).15 G(nteracti)-3.24 E 1.04 -.15(ve u)-.25 +H .74(se, Bash implements ksh-style aliases and b).15 F .74 +(uiltins such as)-.2 F F2(fc)3.24 E F0 .74(\(discussed belo)3.24 F .74 +(w\) and)-.25 F F2(jobs)3.24 E F0(.)A .291(Bash aliases allo)72 606 R +2.791(was)-.25 G .291(tring to be substituted for a command name.)-2.791 +F(The)5.291 E 2.791(yc)-.15 G .291(an be used to create a mnemonic) +-2.791 F .568(for a)72 618 R/F4 9/Times-Roman@0 SF(UNIX)3.068 E F0 .568 +(command name \()3.068 F F3 .568(alias del=rm)B F0 .568(\), to e)B .567 +(xpand a single w)-.15 F .567(ord to a comple)-.1 F 3.067(xc)-.15 G .567 +(ommand \()-3.067 F F3(alias)A .255 +(news='xterm -g 80x45 -title trn -e trn -e -S1 -N &')72 630 R F0 .255 +(\), or to ensure that a command)B(is in)72 642 Q -.2(vo)-.4 G -.1(ke).2 +G 2.5(dw).1 G(ith a basic set of options \()-2.5 E F3 +(alias ls="/bin/ls -F")A F0(\).)A .293(The C shell \()97 657.6 R F2(csh) +A F0 .293(\)\207, originally written by Bill Jo)B 2.792(yw)-.1 G .292 +(hile at Berk)-2.792 F(ele)-.1 E 1.592 -.65(y, i)-.15 H 2.792(sw).65 G +.292(idely used and quite popular)-2.792 F 1.499(for its interacti)72 +669.6 R 1.799 -.15(ve f)-.25 H 3.999(acilities. Bash).05 F 1.499 +(includes a csh-compatible history e)3.999 F 1.5 +(xpansion mechanism \(\231! history\232\),)-.15 F .019(brace e)72 681.6 +R .018(xpansion, access to a stack of directories via the)-.15 F F2 +(pushd)2.518 E F0(,)A F2(popd)2.518 E F0 2.518(,a)C(nd)-2.518 E F2(dirs) +2.518 E F0 -.2(bu)2.518 G .018(iltins, and tilde e).2 F(xpansion,)-.15 E +1.293(to generate users' home directories.)72 693.6 R -.35(Ti)6.294 G +1.294(lde e).35 F 1.294(xpansion has also been adopted by both the K) +-.15 F 1.294(orn Shell and)-.35 F .32 LW 144 708.2 72 708.2 DL/F5 8 +/Times-Roman@0 SF(\207Morris Bolsk)72 720 Q 2(ya)-.12 G(nd Da)-2 E +(vid K)-.16 E(orn,)-.28 E/F6 8/Times-Italic@0 SF(The K)2 E +(ornShell Command and Pr)-.32 E -.08(og)-.36 G -.12(ra).08 G +(mming Langua).12 E -.08(ge)-.08 G F5 2(,P).08 G(rentice Hall, 1989.)-2 +E EP +%%Page: 3 3 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-3-)282.17 48 Q(POSIX.2.)72 84 Q .148 +(There were certain areas in which POSIX.2 felt standardization w)97 +99.6 R .149(as necessary)-.1 F 2.649(,b)-.65 G .149(ut no e)-2.849 F +.149(xisting imple-)-.15 F 1.598(mentation pro)72 111.6 R 1.598 +(vided the proper beha)-.15 F(vior)-.2 E 6.598(.T)-.55 G 1.598(he w) +-6.598 F 1.597(orking group in)-.1 F -.15(ve)-.4 G 1.597 +(nted and standardized functionality in).15 F .674 +(these areas, which Bash implements.)72 123.6 R(The)5.674 E/F1 10 +/Times-Bold@0 SF(command)3.174 E F0 -.2(bu)3.174 G .674(iltin w).2 F +.674(as in)-.1 F -.15(ve)-.4 G .674 +(nted so that shell functions could be).15 F .996(written to replace b) +72 135.6 R .996(uiltins; it mak)-.2 F .996(es the capabilities of the b) +-.1 F .995(uiltin a)-.2 F -.25(va)-.2 G .995(ilable to the function.).25 +F .995(The reserv)5.995 F(ed)-.15 E -.1(wo)72 147.6 S 1.731 +(rd \231!\232 w).1 F 1.731(as added to ne)-.1 F -.05(ga)-.15 G 1.731 +(te the return v).05 F 1.731(alue of a command or pipeline; it w)-.25 F +1.732(as nearly impossible to)-.1 F -.15(ex)72 159.6 S .286 +(press \231if not x\232 cleanly using the sh language.).15 F .286 +(There e)5.286 F .286(xist multiple incompatible implementations of the) +-.15 F F1(test)72 171.6 Q F0 -.2(bu)3.163 G .663 +(iltin, which tests \214les for type and other attrib).2 F .664 +(utes and performs arithmetic and string comparisons.)-.2 F .5 +(POSIX considered none of these correct, so the standard beha)72 183.6 R +.5(vior w)-.2 F .5(as speci\214ed in terms of the number of)-.1 F(ar)72 +195.6 Q .412(guments to the command.)-.18 F .412(POSIX.2 dictates e) +5.412 F .412(xactly what will happen when four or fe)-.15 F .412(wer ar) +-.25 F .412(guments are)-.18 F(gi)72 207.6 Q -.15(ve)-.25 G 5.01(nt).15 +G(o)-5.01 E F1(test)5.01 E F0 5.01(,a)C 2.51(nd lea)-5.01 F -.15(ve)-.2 +G 5.01(st).15 G 2.51(he beha)-5.01 F 2.51(vior unde\214ned when more ar) +-.2 F 2.51(guments are supplied.)-.18 F 2.51(Bash uses the)7.51 F +(POSIX.2 algorithm, which w)72 219.6 Q(as concei)-.1 E -.15(ve)-.25 G +2.5(db).15 G 2.5(yD)-2.5 G -.2(av)-2.5 G(id K).2 E(orn.)-.35 E F1 2.5 +(3.1. F)72 243.6 R(eatur)-.25 E(es not in the Bour)-.18 E(ne Shell)-.15 +E F0 .718(There are a number of minor dif)97 259.2 R .719 +(ferences between Bash and the v)-.25 F .719 +(ersion of sh present on most other)-.15 F -.15(ve)72 271.2 S .874 +(rsions of).15 F/F2 9/Times-Roman@0 SF(UNIX)3.374 E F0 5.873(.T)C .873 +(he majority of these are due to the POSIX standard, b)-5.873 F .873 +(ut some are the result of Bash)-.2 F .386 +(adopting features from other shells.)72 283.2 R -.15(Fo)5.386 G 2.886 +(ri).15 G .386(nstance, Bash includes the ne)-2.886 F 2.886<7799>-.25 G +.386(!\232 reserv)-2.886 F .386(ed w)-.15 F .386(ord, the)-.1 F F1 +(command)2.886 E F0 -.2(bu)72 295.2 S .116(iltin, the ability of the).2 +F F1 -.18(re)2.616 G(ad).18 E F0 -.2(bu)2.615 G .115 +(iltin to correctly return a line ending with a backslash, symbolic ar) +.2 F(guments)-.18 E .798(to the)72 307.2 R F1(umask)3.298 E F0 -.2(bu) +3.298 G .798(iltin, v).2 F .798(ariable substring remo)-.25 F -.25(va) +-.15 G .798(l, a w).25 F .799(ay to get the length of a v)-.1 F .799 +(ariable, and the ne)-.25 F 3.299(wa)-.25 G(lgo-)-3.299 E(rithm for the) +72 319.2 Q F1(test)2.5 E F0 -.2(bu)2.5 G +(iltin from the POSIX.2 standard, none of which appear in sh.).2 E 1.225 +(Bash also implements the \231$\(...\)\232 command substitution syntax,\ + which supersedes the sh `...` con-)97 334.8 R 2.851(struct. The)72 +346.8 R .351(\231$\(...\)\232 construct e)2.851 F .351(xpands to the ou\ +tput of the command contained within the parentheses, with)-.15 F .664 +(trailing ne)72 358.8 R .664(wlines remo)-.25 F -.15(ve)-.15 G 3.164 +(d. The).15 F .664(sh syntax is accepted for backw)3.164 F .664 +(ards compatibility)-.1 F 3.164(,b)-.65 G .664 +(ut the \231$\(...\)\232 form is)-3.364 F(preferred because its quoting\ + rules are much simpler and it is easier to nest.)72 370.8 Q .772 +(The Bourne shell does not pro)97 386.4 R .772 +(vide such features as brace e)-.15 F .772 +(xpansion, the ability to de\214ne a v)-.15 F(ariable)-.25 E .283 +(and a function with the same name, local v)72 398.4 R .282 +(ariables in shell functions, the ability to enable and disable indi-) +-.25 F .547(vidual b)72 410.4 R .547 +(uiltins or write a function to replace a b)-.2 F .547 +(uiltin, or a means to e)-.2 F .547 +(xport a shell function to a child pro-)-.15 F(cess.)72 422.4 Q .32 +(Bash has closed a long-standing shell security hole by not using the)97 +438 R F1($IFS)2.82 E F0 -.25(va)2.82 G .32(riable to split each w).25 F +(ord)-.1 E 1.254(read by the shell, b)72 450 R 1.254 +(ut splitting only the results of e)-.2 F 1.255 +(xpansion \(ksh and the 4.4 BSD sh ha)-.15 F 1.555 -.15(ve \214)-.2 H +-.15(xe).15 G 3.755(dt).15 G 1.255(his as)-3.755 F 2.907(well\). Useful) +72 462 R(beha)2.907 E .407(vior such as a means to abort e)-.2 F -.15 +(xe)-.15 G .407(cution of a script read with the \231.).15 F 2.906<9a63> +-.7 G .406(ommand using the)-2.906 F F1 -.18(re)72 474 S(tur).18 E(n) +-.15 E F0 -.2(bu)2.742 G .242(iltin or automatically e).2 F .242 +(xporting v)-.15 F .243(ariables in the shell')-.25 F 2.743(se)-.55 G +-.4(nv)-2.743 G .243(ironment to children is also not present).4 F .969 +(in the Bourne shell.)72 486 R .968(Bash pro)5.968 F .968 +(vides a much more po)-.15 F .968(werful en)-.25 F .968 +(vironment for both interacti)-.4 F 1.268 -.15(ve u)-.25 H .968 +(se and pro-).15 F(gramming.)72 498 Q F1 2.5(4. Bash-speci\214c)72 522 R +-.25(Fe)2.5 G(atur).25 E(es)-.18 E F0 .491(This section details a fe)97 +537.6 R 2.991(wo)-.25 G 2.991(ft)-2.991 G .491(he features which mak) +-2.991 F 2.991(eB)-.1 G .491(ash unique.)-2.991 F .492(Most of them pro) +5.491 F .492(vide impro)-.15 F -.15(ve)-.15 G(d).15 E(interacti)72 549.6 +Q 1.182 -.15(ve u)-.25 H .882(se, b).15 F .882(ut a fe)-.2 F 3.382(wp) +-.25 G .882(rogramming impro)-3.382 F -.15(ve)-.15 G .882 +(ments are present as well.).15 F .882(Full descriptions of these fea-) +5.882 F(tures can be found in the Bash documentation.)72 561.6 Q F1 2.5 +(4.1. Startup)72 585.6 R(Files)2.5 E F0 .161(Bash e)97 601.2 R -.15(xe) +-.15 G .161(cutes startup \214les dif).15 F .161 +(ferently than other shells.)-.25 F .162(The Bash beha)5.161 F .162 +(vior is a compromise between)-.2 F .29 +(the csh principle of startup \214les with \214x)72 613.2 R .29 +(ed names e)-.15 F -.15(xe)-.15 G .29 +(cuted for each shell and the sh \231minimalist\232 beha).15 F(vior)-.2 +E(.)-.55 E 2.955(An interacti)72 625.2 R 3.255 -.15(ve i)-.25 H 2.955 +(nstance of Bash started as a login shell reads and e).15 F -.15(xe)-.15 +G(cutes).15 E/F3 10/Times-Italic@0 SF(~/.bash_pr)5.456 E(o\214le)-.45 E +F0 2.956(\(the \214le)5.456 F .954(.bash_pro\214le in the user')72 637.2 +R 3.454(sh)-.55 G .953(ome directory\), if it e)-3.454 F 3.453 +(xists. An)-.15 F(interacti)3.453 E 1.253 -.15(ve n)-.25 H .953 +(on-login shell reads and e).15 F -.15(xe)-.15 G(cutes).15 E F3 +(~/.bashr)72 649.2 Q(c)-.37 E F0 5.641(.A)C(non-interacti)-2.5 E .942 +-.15(ve s)-.25 H .642(hell \(one be).15 F .642(gun to e)-.15 F -.15(xe) +-.15 G .642(cute a shell script, for e).15 F .642 +(xample\) reads no \214x)-.15 F .642(ed startup)-.15 F .342(\214le, b)72 +661.2 R .342(ut uses the v)-.2 F .342(alue of the v)-.25 F(ariable)-.25 +E F1($ENV)2.842 E F0 2.841(,i)C 2.841(fs)-2.841 G .341 +(et, as the name of a startup \214le.)-2.841 F .341 +(The ksh practice of read-)5.341 F(ing)72 673.2 Q F1($ENV)3.114 E F0 +.614(for e)3.114 F -.15(ve)-.25 G .614(ry shell, with the accompan).15 F +.615(ying dif)-.15 F .615(\214culty of de\214ning the proper v)-.25 F +.615(ariables and functions)-.25 F .721(for interacti)72 685.2 R 1.021 +-.15(ve a)-.25 H .721(nd non-interacti).15 F 1.021 -.15(ve s)-.25 H .721 +(hells or ha).15 F .721(ving the \214le read only for interacti)-.2 F +1.02 -.15(ve s)-.25 H .72(hells, w).15 F .72(as considered)-.1 F .158 +(too comple)72 697.2 R 2.658(x. Ease)-.15 F .158(of use w)2.658 F .158 +(on out here.)-.1 F(Interestingly)5.158 E 2.658(,t)-.65 G .158(he ne) +-2.658 F .159(xt release of ksh will change to reading)-.15 F F1($ENV) +2.659 E .32 LW 144 705.2 72 705.2 DL/F4 8/Times-Roman@0 SF .559 +(\207Bill Jo)72 717 R 1.599 -.52(y, A)-.08 H 2.559(nI).52 G .559 +(ntroduction to the C Shell,)-2.559 F/F5 8/Times-Italic@0 SF .558 +(UNIX User')2.558 F 2.558(sS)-.32 G .558(upplementary Documents)-2.558 F +F4 2.558(,U)C(ni)-2.558 E -.12(ve)-.2 G .558(rsity of California at).12 +F(Berk)72 727 Q(ele)-.08 E 1.04 -.52(y, 1)-.12 H(986.).52 E EP +%%Page: 4 4 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-4-)282.17 48 Q(only for interacti)72 84 Q .3 +-.15(ve s)-.25 H(hells.).15 E/F1 10/Times-Bold@0 SF 2.5(4.2. New)72 108 +R(Builtin Commands)2.5 E F0 1.02(There are a fe)97 123.6 R 3.52(wb)-.25 +G 1.02(uiltins which are ne)-3.72 F 3.52(wo)-.25 G 3.52(rh)-3.52 G -2.25 +-.2(av e)-3.52 H 1.02(been e)3.72 F 1.02(xtended in Bash.)-.15 F(The) +6.02 E F1(enable)3.52 E F0 -.2(bu)3.52 G 1.02(iltin allo).2 F(ws)-.25 E +-.2(bu)72 135.6 S .824(iltin commands to be turned on and of).2 F 3.324 +(fa)-.25 G(rbitrarily)-3.324 E 5.824(.T)-.65 G 3.324(ou)-6.624 G .824 +(se the v)-3.324 F .824(ersion of)-.15 F/F2 10/Times-Italic@0 SF(ec) +3.324 E(ho)-.15 E F0 .825(found in a user')3.324 F 3.325(ss)-.55 G +(earch)-3.325 E .625(path rather than the Bash b)72 147.6 R(uiltin,)-.2 +E/F3 10/Courier@0 SF .625(enable -n echo)3.125 F F0(suf)3.125 E 3.125 +(\214ces. The)-.25 F F1(help)3.124 E F0 -.2(bu)3.124 G .624(iltin pro).2 +F .624(vides quick synopses)-.15 F .703(of the shell f)72 159.6 R .704 +(acilities without requiring access to a manual page.)-.1 F F1(Builtin) +5.704 E F0 .704(is similar to)3.204 F F1(command)3.204 E F0 .704 +(in that it)3.204 F .342(bypasses shell functions and directly e)72 +171.6 R -.15(xe)-.15 G .342(cutes b).15 F .342(uiltin commands.)-.2 F +.342(Access to a csh-style stack of directories)5.342 F .072(is pro)72 +183.6 R .073(vided via the)-.15 F F1(pushd)2.573 E F0(,)A F1(popd)2.573 +E F0 2.573(,a)C(nd)-2.573 E F1(dirs)2.573 E F0 -.2(bu)2.573 G(iltins.).2 +E F1(Pushd)5.073 E F0(and)2.573 E F1(popd)2.573 E F0 .073 +(insert and remo)2.573 F .373 -.15(ve d)-.15 H .073(irectories from the) +.15 F 2.858(stack, respecti)72 195.6 R -.15(ve)-.25 G(ly).15 E 5.358(,a) +-.65 G(nd)-5.358 E F1(dirs)5.358 E F0 2.858(lists the stack contents.) +5.358 F 2.858(On systems that allo)7.858 F 5.358<778c>-.25 G 2.857 +(ne-grained control of)-5.358 F 1.339(resources, the)72 207.6 R F1 +(ulimit)3.839 E F0 -.2(bu)3.839 G 1.339 +(iltin can be used to tune these settings.).2 F F1(Ulimit)6.34 E F0 +(allo)3.84 E 1.34(ws a user to control, among)-.25 F 1.086 +(other things, whether core dumps are to be generated, ho)72 219.6 R +3.586(wm)-.25 G 1.086(uch memory the shell or a child process is)-3.586 +F(allo)72 231.6 Q .496(wed to allocate, and ho)-.25 F 2.996(wl)-.25 G +(ar)-2.996 E .496(ge a \214le created by a child process can gro)-.18 F +4.296 -.65(w. T)-.25 H(he).65 E F1(suspend)2.996 E F0 .497(command will) +2.997 F .744(stop the shell process when job control is acti)72 243.6 R +-.15(ve)-.25 G 3.243(;m).15 G .743(ost other shells do not allo)-3.243 F +3.243(wt)-.25 G(hemselv)-3.243 E .743(es to be stopped)-.15 F(lik)72 +255.6 Q 2.717(et)-.1 G(hat.)-2.717 E F1 -.74(Ty)5.217 G(pe,).74 E F0 +.217(the Bash answer to)2.717 F F1(which)2.717 E F0(and)2.717 E F1 +(whence,)2.717 E F0(sho)2.717 E .218(ws what will happen when a w)-.25 F +.218(ord is typed as a)-.1 F(command:)72 267.6 Q F3 6($t)97 285.6 S +(ype export)-6 E(export is a shell builtin)97 297.6 Q 6($t)97 309.6 S +(ype -t export)-6 E(builtin)97 321.6 Q 6($t)97 333.6 S(ype bash)-6 E +(bash is /bin/bash)97 345.6 Q 6($t)97 357.6 S(ype cd)-6 E +(cd is a function)97 369.6 Q(cd \(\))97 381.6 Q({)97 393.6 Q +(builtin cd ${1+"$@"} && xtitle $HOST: $PWD)121 405.6 Q(})97 417.6 Q F0 +-1.11(Va)72 439.2 S .682(rious modes tell what a command w)1.11 F .681 +(ord is \(reserv)-.1 F .681(ed w)-.15 F .681(ord, alias, function, b)-.1 +F .681(uiltin, or \214le\) or which v)-.2 F(er)-.15 E(-)-.2 E 1.15 +(sion of a command will be e)72 451.2 R -.15(xe)-.15 G 1.15 +(cuted based on a user').15 F 3.65(ss)-.55 G 1.15(earch path.)-3.65 F +1.15(Some of this functionality has been)6.15 F +(adopted by POSIX.2 and folded into the)72 463.2 Q F1(command)2.5 E F0 +(utility)2.5 E(.)-.65 E F1 2.5(4.3. Editing)72 487.2 R(and Completion) +2.5 E F0 .682(One area in which Bash shines is command line editing.)97 +502.8 R .682(Bash uses the)5.682 F F2 -.37(re)3.182 G(adline).37 E F0 +.681(library to read and)3.181 F .942(edit lines when interacti)72 514.8 +R -.15(ve)-.25 G 5.942(.R).15 G .942(eadline is a po)-5.942 F .942 +(werful and \215e)-.25 F .942(xible input f)-.15 F .943 +(acility that a user can con\214gure to)-.1 F(indi)72 526.8 Q .732 +(vidual tastes.)-.25 F .732(It allo)5.732 F .732(ws lines to be edited \ +using either emacs or vi commands, where those commands)-.25 F .2 +(are appropriate.)72 538.8 R .2 +(The full capability of emacs is not present \255 there is no w)5.2 F .2 +(ay to e)-.1 F -.15(xe)-.15 G .2(cute a named command).15 F 1.15 +(with M-x, for instance \255 b)72 550.8 R 1.15(ut the e)-.2 F 1.149 +(xisting commands are more than adequate.)-.15 F 1.149 +(The vi mode is compliant)6.149 F +(with the command line editing standardized by POSIX.2.)72 562.8 Q 1.69 +(Readline is fully customizable.)97 578.4 R 1.691 +(In addition to the basic commands and k)6.69 F 1.991 -.15(ey b)-.1 H +1.691(indings, the library).15 F(allo)72 590.4 Q .028 +(ws users to de\214ne additional k)-.25 F .327 -.15(ey b)-.1 H .027 +(indings using a startup \214le.).15 F(The)5.027 E F2(inputr)2.527 E(c) +-.37 E F0 .027(\214le, which def)2.527 F .027(aults to the \214le)-.1 F +F2(~/.inputr)72 602.4 Q(c)-.37 E F0 3.002(,i)C 3.002(sr)-3.002 G .503(e\ +ad each time readline initializes, permitting users to maintain a consi\ +stent interf)-3.002 F .503(ace across a)-.1 F .893(set of programs.)72 +614.4 R .893(Readline includes an e)5.893 F .893(xtensible interf)-.15 F +.892(ace, so each program using the library can add its)-.1 F -.25(ow)72 +626.4 S 3.56(nb).25 G 1.06(indable commands and program-speci\214c k) +-3.56 F 1.361 -.15(ey b)-.1 H 3.561(indings. Bash).15 F 1.061 +(uses this f)3.561 F 1.061(acility to add bindings that)-.1 F +(perform history e)72 638.4 Q(xpansion or shell w)-.15 E(ord e)-.1 E +(xpansions on the current input line.)-.15 E .707 +(Readline interprets a number of v)97 654 R .706 +(ariables which further tune its beha)-.25 F(vior)-.2 E 5.706(.V)-.55 G +.706(ariables e)-6.816 F .706(xist to control)-.15 F .157 +(whether or not eight-bit characters are directly read as input or con) +72 666 R -.15(ve)-.4 G .158(rted to meta-pre\214x).15 F .158(ed k)-.15 F +.458 -.15(ey s)-.1 H .158(equences \(a).15 F(meta-pre\214x)72 678 Q .082 +(ed k)-.15 F .382 -.15(ey s)-.1 H .081(equence consists of the characte\ +r with the eighth bit zeroed, preceded by the).15 F F2(meta-pr)2.581 E +(e\214x)-.37 E F0(character)72 690 Q 3.233(,u)-.4 G .733 +(sually escape, which selects an alternate k)-3.233 F -.15(ey)-.1 G .734 +(map\), to decide whether to output characters with).15 F .624 +(the eighth bit set directly or as a meta-pre\214x)72 702 R .624(ed k) +-.15 F .924 -.15(ey s)-.1 H .623 +(equence, whether or not to wrap to a ne).15 F 3.123(ws)-.25 G .623 +(creen line)-3.123 F 1.196 +(when a line being edited is longer than the screen width, the k)72 714 +R -.15(ey)-.1 G 1.196(map to which subsequent k).15 F 1.496 -.15(ey b) +-.1 H(indings).15 E .531(should apply)72 726 R 3.031(,o)-.65 G 3.031(re) +-3.031 G -.15(ve)-3.281 G 3.031(nw).15 G .531 +(hat happens when readline w)-3.031 F .531(ants to ring the terminal') +-.1 F 3.03(sb)-.55 G 3.03(ell. All)-3.03 F .53(of these v)3.03 F +(ariables)-.25 E EP +%%Page: 5 5 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-5-)282.17 48 Q +(can be set in the inputrc \214le.)72 84 Q .284 +(The startup \214le understands a set of C preprocessor)97 99.6 R(-lik) +-.2 E 2.785(ec)-.1 G .285(onditional constructs which allo)-2.785 F +2.785(wv)-.25 G(ariables)-3.035 E .12(or k)72 111.6 R .42 -.15(ey b)-.1 +H .119(indings to be assigned based on the application using readline, \ +the terminal currently being used, or).15 F .338(the editing mode.)72 +123.6 R .338(Users can add program-speci\214c bindings to mak)5.338 F +2.838(et)-.1 G .338(heir li)-2.838 F -.15(ve)-.25 G 2.838(se).15 G 2.838 +(asier: I)-2.838 F(ha)2.838 E .639 -.15(ve b)-.2 H .339(indings that).15 +F(let me edit the v)72 135.6 Q(alue of)-.25 E/F1 10/Times-Bold@0 SF($P) +2.5 E -.95(AT)-.74 G(H).95 E F0(and double-quote the current or pre)2.5 +E(vious w)-.25 E(ord:)-.1 E/F2 10/Courier@0 SF 6(#M)97 153.6 S +(acros that are convenient for shell interaction)-6 E($if Bash)97 165.6 +Q 6(#e)97 177.6 S(dit the path)-6 E +("\\C-xp": "PATH=${PATH}\\e\\C-e\\C-a\\ef\\C-f")97 189.6 Q 6(#p)97 201.6 +S(repare to type a quoted word -- insert open and close double)-6 E 6 +(#q)97 213.6 S(uotes and move to just after the open quote)-6 E +("\\C-x\\"": "\\"\\"\\C-b")97 225.6 Q 6(#Q)97 237.6 S +(uote the current or previous word)-6 E("\\C-xq": "\\eb\\"\\ef\\"")97 +249.6 Q($endif)97 261.6 Q F0 .322(There is a readline command to re-rea\ +d the \214le, so users can edit the \214le, change some bindings, and b\ +e)72 283.2 R(gin)-.15 E(to use them almost immediately)72 295.2 Q(.)-.65 +E .851(Bash implements the)97 310.8 R F1(bind)3.351 E F0 -.2(bu)3.351 G +.851(iltin for more dyamic control of readline than the startup \214le \ +permits.).2 F F1(Bind)72 322.8 Q F0 .25(is used in se)2.75 F -.15(ve) +-.25 G .25(ral w).15 F 2.75(ays. In)-.1 F/F3 10/Times-Italic@0 SF(list) +2.75 E F0 .25(mode, it can display the current k)2.75 F .55 -.15(ey b) +-.1 H .25(indings, list all the readline edit-).15 F .149(ing directi)72 +334.8 R -.15(ve)-.25 G 2.649(sa).15 G -.25(va)-2.849 G .149 +(ilable for binding, list which k).25 F -.15(ey)-.1 G 2.649(si).15 G +-1.9 -.4(nv o)-2.649 H .349 -.1(ke a g).4 H -2.15 -.25(iv e).1 H 2.65 +(nd).25 G(irecti)-2.65 E -.15(ve)-.25 G 2.65(,o).15 G 2.65(ro)-2.65 G +.15(utput the current set of k)-2.65 F -.15(ey)-.1 G .042(bindings in a\ + format that can be incorporated directly into an inputrc \214le.)72 +346.8 R(In)5.041 E F3(batc)2.541 E(h)-.15 E F0 .041 +(mode, it reads a series of)2.541 F -.1(ke)72 358.8 S 2.858(yb)-.05 G +.359(indings directly from a \214le and passes them to readline.)-2.858 +F .359(In its most common usage,)5.359 F F1(bind)2.859 E F0(tak)2.859 E +.359(es a sin-)-.1 F 1.117(gle string and passes it directly to readlin\ +e, which interprets the line as if it had just been read from the)72 +370.8 R(inputrc \214le.)72 382.8 Q(Both k)5 E .3 -.15(ey b)-.1 H +(indings and v).15 E(ariable assignments may appear in the string gi) +-.25 E -.15(ve)-.25 G 2.5(nt).15 G(o)-2.5 E F1(bind)2.5 E F0(.)A .53 +(The readline library also pro)97 398.4 R .53(vides an interf)-.15 F .53 +(ace for)-.1 F F3(wor)3.03 E 3.03(dc)-.37 G(ompletion)-3.03 E F0 5.53 +(.W)C .53(hen the)-5.53 F F3(completion)3.03 E F0(character)3.03 E 1.261 +(\(usually T)72 410.4 R 1.261(AB\) is typed, readline looks at the w) +-.93 F 1.26(ord currently being entered and computes the set of \214le-) +-.1 F .523(names of which the current w)72 422.4 R .523(ord is a v)-.1 F +.523(alid pre\214x.)-.25 F .524 +(If there is only one possible completion, the rest of the)5.523 F .358 +(characters are inserted directly)72 434.4 R 2.858(,o)-.65 G .358(therw\ +ise the common pre\214x of the set of \214lenames is added to the curre\ +nt)-2.858 F -.1(wo)72 446.4 S 3.199(rd. A).1 F .699(second T)3.199 F +.699(AB character entered immediately after a non-unique completion cau\ +ses readline to list)-.93 F 1.814 +(the possible completions; there is an option to ha)72 458.4 R 2.113 +-.15(ve t)-.2 H 1.813(he list displayed immediately).15 F 6.813(.R)-.65 +G 1.813(eadline pro)-6.813 F(vides)-.15 E .482 +(hooks so that applications can pro)72 470.4 R .482 +(vide speci\214c types of completion before the def)-.15 F .483 +(ault \214lename completion)-.1 F .132(is attempted.)72 482.4 R .132 +(This is quite \215e)5.132 F .132 +(xible, though it is not completely user)-.15 F 2.632 +(-programmable. Bash,)-.2 F .132(for e)2.632 F .132(xample, can)-.15 F +.37(complete \214lenames, command names \(including aliases, b)72 494.4 +R .37(uiltins, shell reserv)-.2 F .37(ed w)-.15 F .37 +(ords, shell functions, and)-.1 F -.15(exe)72 506.4 S .424 +(cutables found in the \214le system\), shell v).15 F .424 +(ariables, usernames, and hostnames.)-.25 F .423 +(It uses a set of heuristics)5.424 F(that, while not perfect, is genera\ +lly quite good at determining what type of completion to attempt.)72 +518.4 Q F1 2.5(4.4. History)72 542.4 R F0 .144 +(Access to the list of commands pre)97 558 R .144(viously entered \(the) +-.25 F F3 .144(command history)2.644 F F0 2.644(\)i)C 2.644(sp)-2.644 G +(ro)-2.644 E .144(vided jointly by Bash)-.15 F .078 +(and the readline library)72 570 R 5.077(.B)-.65 G .077(ash pro)-5.077 F +.077(vides v)-.15 F .077(ariables \()-.25 F F1($HISTFILE)A F0(,)A F1 +($HISTSIZE)2.577 E F0 2.577(,a)C(nd)-2.577 E F1($HISTCONTR)2.577 E(OL) +-.3 E F0 2.577(\)a)C(nd)-2.577 E(the)72 582 Q F1(history)2.89 E F0(and) +2.89 E F1(fc)2.89 E F0 -.2(bu)2.89 G .39 +(iltins to manipulate the history list.).2 F .391(The v)5.391 F .391 +(alue of)-.25 F F1($HISTFILE)2.891 E F0 .391(specifes the \214le where) +2.891 F .49(Bash writes the command history on e)72 594 R .489 +(xit and reads it on startup.)-.15 F F1($HISTSIZE)5.489 E F0 .489 +(is used to limit the number)2.989 F .642(of commands sa)72 606 R -.15 +(ve)-.2 G 3.142(di).15 G 3.142(nt)-3.142 G .642(he history)-3.142 F(.) +-.65 E F1($HISTCONTR)5.642 E(OL)-.3 E F0(pro)3.142 E .642 +(vides a crude form of control o)-.15 F -.15(ve)-.15 G 3.142(rw).15 G +.642(hich com-)-3.142 F .025(mands are sa)72 618 R -.15(ve)-.2 G 2.525 +(do).15 G 2.525(nt)-2.525 G .025(he history list: a v)-2.525 F .025 +(alue of)-.25 F F3(ignor)2.525 E(espace)-.37 E F0 .025(means to not sa) +2.525 F .324 -.15(ve c)-.2 H .024(ommands which be).15 F .024 +(gin with a)-.15 F .927(space; a v)72 630 R .927(alue of)-.25 F F3 +(ignor)3.427 E(edups)-.37 E F0 .927(means to not sa)3.427 F 1.228 -.15 +(ve c)-.2 H .928(ommands identical to the last command sa).15 F -.15(ve) +-.2 G(d.).15 E F1($HIST)5.928 E(-)-.92 E(CONTR)72 642 Q(OL)-.3 E F0 -.1 +(wa)3.778 G 3.778(sn).1 G(amed)-3.778 E F1($history_contr)3.778 E(ol) +-.18 E F0 1.278(in earlier v)3.778 F 1.278 +(ersions of Bash; the old name is still accepted for)-.15 F(backw)72 654 +Q .575(ards compatibility)-.1 F 5.575(.T)-.65 G(he)-5.575 E F1(history) +3.075 E F0 .575 +(command can read or write \214les containing the history list and dis-) +3.075 F .167(play the current list contents.)72 666 R(The)5.167 E F1(fc) +2.667 E F0 -.2(bu)2.667 G .167(iltin, adopted from POSIX.2 and the K).2 +F .167(orn Shell, allo)-.35 F .167(ws display and)-.25 F(re-e)72 678 Q +-.15(xe)-.15 G .58 +(cution, with optional editing, of commands from the history list.).15 F +.58(The readline library of)5.58 F .58(fers a set of)-.25 F 1.255(comma\ +nds to search the history list for a portion of the current input line \ +or a string typed by the user)72 690 R(.)-.55 E(Finally)72 702 Q 2.535 +(,t)-.65 G(he)-2.535 E F3(history)2.535 E F0(library)2.535 E 2.535(,g) +-.65 G .036(enerally incorporated directly into the readline library) +-2.535 F 2.536(,i)-.65 G .036(mplements a f)-2.536 F .036(acility for) +-.1 F 1.023(history recall, e)72 714 R 1.022(xpansion, and re-e)-.15 F +-.15(xe)-.15 G 1.022(cution of pre).15 F 1.022(vious commands v)-.25 F +1.022(ery similar to csh \(\231bang history\232, so)-.15 F +(called because the e)72 726 Q +(xclamation point introduces a history substitution\):)-.15 E EP +%%Page: 6 6 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-6-)282.17 48 Q/F1 10/Courier@0 SF 6($e)97 84 S +(cho a b c d e)-6 E 6(abcde)97 96 S 6($!)97 108 S 6(!fghi)-6 G +(echo a b c d e f g h i)97 120 Q 6(abcdefghi)97 132 S 6($!)97 144 S(-2) +-6 E(echo a b c d e)97 156 Q 6(abcde)97 168 S 6($e)97 180 S(cho !-2:1-4) +-6 E(echo a b c d)97 192 Q 6(abcd)97 204 S F0 1.456 +(The command history is only sa)72 225.6 R -.15(ve)-.2 G 3.957(dw).15 G +1.457(hen the shell is interacti)-3.957 F -.15(ve)-.25 G 3.957(,s).15 G +3.957(oi)-3.957 G 3.957(ti)-3.957 G 3.957(sn)-3.957 G 1.457(ot a)-3.957 +F -.25(va)-.2 G 1.457(ilable for use by shell).25 F(scripts.)72 237.6 Q +/F2 10/Times-Bold@0 SF 2.5(4.5. New)72 261.6 R(Shell V)2.5 E(ariables) +-.92 E F0 .59(There are a number of con)97 277.2 R -.15(ve)-.4 G .589 +(nience v).15 F .589(ariables that Bash interprets to mak)-.25 F 3.089 +(el)-.1 G .589(ife easier)-3.089 F 5.589(.T)-.55 G .589(hese include) +-5.589 F F2(FIGNORE)72 289.2 Q F0 3.973(,w)C 1.473 +(hich is a set of \214lename suf)-3.973 F<8c78>-.25 E 1.474 +(es identifying \214les to e)-.15 F 1.474 +(xclude when completing \214lenames;)-.15 F F2(HOSTTYPE)72 301.2 Q F0 +2.932(,w)C .432 +(hich is automatically set to a string describing the type of hardw) +-2.932 F .431(are on which Bash is cur)-.1 F(-)-.2 E .335(rently e)72 +313.2 R -.15(xe)-.15 G(cuting;).15 E F2(command_oriented_history)2.835 E +F0 2.835(,w)C .335(hich directs Bash to sa)-2.835 F .635 -.15(ve a)-.2 H +.336(ll lines of a multiple-line com-).15 F 1.071(mand such as a)72 +325.2 R/F3 10/Times-Italic@0 SF(while)3.571 E F0(or)3.571 E F3(for)3.571 +E F0 1.071(loop in a single history entry)3.571 F 3.57(,a)-.65 G(llo) +-3.57 E 1.07(wing easy re-editing; and)-.25 F F2(IGNOREEOF)3.57 E F0(,)A +.747(whose v)72 337.2 R .747(alue indicates the number of consecuti)-.25 +F 1.047 -.15(ve E)-.25 H .747(OF characters that an interacti).15 F +1.048 -.15(ve s)-.25 H .748(hell will read before).15 F -.15(ex)72 349.2 +S 1.432(iting \255 an easy w).15 F 1.432(ay to k)-.1 F 1.432 +(eep yourself from being logged out accidentally)-.1 F 6.432(.T)-.65 G +(he)-6.432 E F2(auto_r)3.932 E(esume)-.18 E F0 -.25(va)3.932 G(riable) +.25 E .571(alters the w)72 361.2 R .571 +(ay the shell treats simple command names: if job control is acti)-.1 F +-.15(ve)-.25 G 3.071(,a).15 G .571(nd this v)-3.071 F .571 +(ariable is set, sin-)-.25 F(gle-w)72 373.2 Q .239(ord simple commands \ +without redirections cause the shell to \214rst look for and restart a \ +suspended job)-.1 F(with that name before starting a ne)72 385.2 Q 2.5 +(wp)-.25 G(rocess.)-2.5 E F2 2.5(4.6. Brace)72 409.2 R(Expansion)2.5 E +F0 .653(Since sh of)97 424.8 R .653(fers no con)-.25 F -.15(ve)-.4 G +.653(nient w).15 F .653 +(ay to generate arbitrary strings that share a common pre\214x or suf) +-.1 F<8c78>-.25 E 2.124(\(\214lename e)72 436.8 R 2.124 +(xpansion requires that the \214lenames e)-.15 F 2.123 +(xist\), Bash implements)-.15 F F3(br)4.623 E 2.123(ace e)-.15 F +(xpansion)-.2 E F0 4.623(,ac)C(apability)-4.623 E(pick)72 448.8 Q .773 +(ed up from csh.)-.1 F .774(Brace e)5.773 F .774 +(xpansion is similar to \214lename e)-.15 F .774(xpansion, b)-.15 F .774 +(ut the strings generated need not)-.2 F 1.211(correspond to e)72 460.8 +R 1.211(xisting \214les.)-.15 F 3.711(Ab)6.211 G 1.211(race e)-3.711 F +1.211(xpression consists of an optional)-.15 F F3(pr)3.71 E(eamble)-.37 +E F0 3.71(,f)C(ollo)-3.71 E 1.21(wed by a pair of)-.25 F 2.938 +(braces enclosing a series of comma-separated strings, and an optional) +72 472.8 R F3(postamble)5.438 E F0 7.938(.T)C 2.938(he preamble is) +-7.938 F(prepended to each string within the braces, and the postamble \ +is then appended to each resulting string:)72 484.8 Q F1 6($e)97 502.8 S +(cho a{d,c,b}e)-6 E(ade ace abe)97 514.8 Q F0 .306(As this e)72 536.4 R +.306(xample demonstrates, the results of brace e)-.15 F .305 +(xpansion are not sorted, as the)-.15 F 2.805(ya)-.15 G .305 +(re by \214lename e)-2.805 F(xpan-)-.15 E(sion.)72 548.4 Q F2 2.5 +(4.7. Pr)72 572.4 R(ocess Substitution)-.18 E F0 .457 +(On systems that can support it, Bash pro)97 588 R .457(vides a f)-.15 F +.457(acility kno)-.1 F .458(wn as)-.25 F F3(pr)2.958 E .458 +(ocess substitution)-.45 F F0 5.458(.P)C .458(rocess sub-)-5.458 F .347 +(stitution is similar to command substitution in that its speci\214cati\ +on includes a command to e)72 600 R -.15(xe)-.15 G .346(cute, b).15 F +.346(ut the)-.2 F .181(shell does not collect the command')72 612 R +2.681(so)-.55 G .181(utput and insert it into the command line.)-2.681 F +(Rather)5.181 E 2.681(,B)-.4 G .182(ash opens a pipe)-2.681 F 1.861 +(to the command, which is run in the background.)72 624 R 1.861 +(The shell uses named pipes \(FIFOs\) or the)6.861 F F3(/de)4.361 E +(v/fd)-.15 E F0 .961(method of naming open \214les to e)72 636 R .962(x\ +pand the process substitution to a \214lename which connects to the pip\ +e)-.15 F .104(when opened.)72 648 R .103 +(This \214lename becomes the result of the e)5.104 F 2.603 +(xpansion. Process)-.15 F .103(substitution can be used to com-)2.603 F +(pare the outputs of tw)72 660 Q 2.5(od)-.1 G(if)-2.5 E(ferent v)-.25 E +(ersions of an application as part of a re)-.15 E(gression test:)-.15 E +F1 6($c)97 678 S(mp <\(old_prog\) <\(new_prog\))-6 E EP +%%Page: 7 7 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-7-)282.17 48 Q/F1 10/Times-Bold@0 SF 2.5 +(4.8. Pr)72 84 R(ompt Customization)-.18 E F0 2.229 +(One of the more popular interacti)97 99.6 R 2.529 -.15(ve f)-.25 H +2.229(eatures that Bash pro).15 F 2.23 +(vides is the ability to customize the)-.15 F 3.234(prompt. Both)72 +111.6 R F1($PS1)3.234 E F0(and)3.234 E F1($PS2,)3.234 E F0 .734 +(the primary and secondary prompts, are e)3.234 F .733 +(xpanded before being displayed.)-.15 F -.15(Pa)72 123.6 S .804 +(rameter and v).15 F .804(ariable e)-.25 F .805 +(xpansion is performed when the prompt string is e)-.15 F .805 +(xpanded, so an)-.15 F 3.305(ys)-.15 G .805(hell v)-3.305 F(ariable)-.25 +E .729(can be put into the prompt \(e.g.,)72 135.6 R F1($SHL)3.228 E(VL) +-.92 E F0 3.228(,w)C .728(hich indicates ho)-3.228 F 3.228(wd)-.25 G +.728(eeply the current shell is nested\).)-3.228 F(Bash)5.728 E 1.895(s\ +pecially interprets characters in the prompt string preceded by a backs\ +lash.)72 147.6 R 1.895(Some of these backslash)6.895 F .874 +(escapes are replaced with the current time, the date, the current w)72 +159.6 R .874(orking directory)-.1 F 3.373(,t)-.65 G .873 +(he username, and the)-3.373 F .78 +(command number or history number of the command being entered.)72 171.6 +R .781(There is e)5.781 F -.15(ve)-.25 G 3.281(nab).15 G .781 +(ackslash escape to)-3.281 F .007 +(cause the shell to change its prompt when running as root after an)72 +183.6 R/F2 10/Times-Italic@0 SF(su)2.507 E F0 5.007(.B)C .007 +(efore printing each primary prompt,)-5.007 F .305(Bash e)72 195.6 R +.305(xpands the v)-.15 F(ariable)-.25 E F1($PR)2.805 E(OMPT_COMMAND)-.3 +E F0 .305(and, if it has a v)2.805 F .306(alue, e)-.25 F -.15(xe)-.15 G +.306(cutes the e).15 F .306(xpanded v)-.15 F .306(alue as)-.25 F 3.735 +(ac)72 207.6 S 1.235(ommand, allo)-3.735 F 1.234 +(wing additional prompt customization.)-.25 F -.15(Fo)6.234 G 3.734(re) +.15 G 1.234(xample, this assignment causes the current)-3.884 F(user)72 +219.6 Q 2.917(,t)-.4 G .417 +(he current host, the time, the last component of the current w)-2.917 F +.417(orking directory)-.1 F 2.917(,t)-.65 G .418(he le)-2.917 F -.15(ve) +-.25 G 2.918(lo).15 G 2.918(fs)-2.918 G .418(hell nest-)-2.918 F(ing, a\ +nd the history number of the current command to be embedded into the pr\ +imary prompt:)72 231.6 Q/F3 10/Courier@0 SF 6($P)97 249.6 S +(S1='\\u@\\h [\\t] \\W\($SHLVL:\\!\)\\$ ')-6 E +(chet@odin [21:03:44] documentation\(2:636\)$ cd ..)97 261.6 Q +(chet@odin [21:03:54] src\(2:637\)$)97 273.6 Q F0 .146(The string being\ + assigned is surrounded by single quotes so that if it is e)72 295.2 R +.146(xported, the v)-.15 F .146(alue of)-.25 F F1($SHL)2.646 E(VL)-.92 E +F0(will)2.646 E(be updated by a child shell:)72 307.2 Q F3 +(chet@odin [21:17:35] src\(2:638\)$ export PS1)97 325.2 Q +(chet@odin [21:17:40] src\(2:639\)$ bash)97 337.2 Q +(chet@odin [21:17:46] src\(3:696\)$)97 349.2 Q F0 +(The \\$ escape is displayed as \231)72 370.8 Q F1($)A F0 2.5<9a77>C +(hen running as a normal user)-2.5 E 2.5(,b)-.4 G(ut as \231)-2.7 E F1 +(#)A F0 2.5<9a77>C(hen running as root.)-2.5 E F1 2.5(4.9. File)72 394.8 +R(System V)2.5 E(iews)-.37 E F0 .029(Since Berk)97 410.4 R(ele)-.1 E +2.529(yi)-.15 G .029 +(ntroduced symbolic links in 4.2 BSD, one of their most anno)-2.529 F +.03(ying properties has been)-.1 F .764(the \231w)72 422.4 R .764 +(arping\232 to a completely dif)-.1 F .764 +(ferent area of the \214le system when using)-.25 F F1(cd)3.263 E F0 +3.263(,a)C .763(nd the resultant non-intu-)-3.263 F(iti)72 434.4 Q .704 +-.15(ve b)-.25 H(eha).15 E .405(vior of \231)-.2 F F1 .405(cd ..)B F0 +2.905(\232. The)B/F4 9/Times-Roman@0 SF(UNIX)2.905 E F0 -.1(ke)2.905 G +.405(rnel treats symbolic links).1 F F2(physically)2.905 E F0 5.405(.W)C +.405(hen the k)-5.405 F .405(ernel is translating)-.1 F 3.223(ap)72 +446.4 S .723(athname in which one component is a symbolic link, it repl\ +aces all or part of the pathname while pro-)-3.223 F .668 +(cessing the link.)72 458.4 R .668 +(If the contents of the symbolic link be)5.668 F .669 +(gin with a slash, the k)-.15 F .669(ernel replaces the pathname)-.1 F +.219(entirely; if not, the link contents replace the current component.) +72 470.4 R .219(In either case, the symbolic link is visible.)5.219 F +.058(If the link v)72 482.4 R .058(alue is an absolute pathname, the us\ +er \214nds himself in a completely dif)-.25 F .059 +(ferent part of the \214le sys-)-.25 F(tem.)72 494.4 Q .704(Bash pro)97 +510 R .704(vides a)-.15 F F2(lo)3.203 E(gical)-.1 E F0(vie)3.203 E 3.203 +(wo)-.25 G 3.203(ft)-3.203 G .703(he \214le system.)-3.203 F .703 +(In this def)5.703 F .703(ault mode, command and \214lename com-)-.1 F +.522(pletion and b)72 522 R .522(uiltin commands such as)-.2 F F1(cd) +3.022 E F0(and)3.022 E F1(pushd)3.022 E F0 .522 +(which change the current w)3.022 F .522(orking directory transpar)-.1 F +(-)-.2 E .127(ently follo)72 534 R 2.627(ws)-.25 G .127 +(ymbolic links as if the)-2.627 F 2.627(yw)-.15 G .127(ere directories.) +-2.627 F(The)5.126 E F1($PWD)2.626 E F0 -.25(va)2.626 G .126 +(riable, which holds the shell').25 F 2.626(si)-.55 G .126(dea of)-2.626 +F .366(the current w)72 546 R .366(orking directory)-.1 F 2.866(,d)-.65 +G .367 +(epends on the path used to reach the directory rather than its ph) +-2.866 F .367(ysical loca-)-.05 F +(tion in the local \214le system hierarch)72 558 Q 3.8 -.65(y. F)-.05 H +(or e).5 E(xample:)-.15 E F3 6($c)97 576 S 6(d/)-6 G(usr/local/bin)-6 E +6($e)97 588 S(cho $PWD)-6 E(/usr/local/bin)97 600 Q 6($p)97 612 S(wd)-6 +E(/usr/local/bin)97 624 Q 6($/)97 636 S(bin/pwd)-6 E +(/net/share/sun4/local/bin)97 648 Q 6($c)97 660 S 6(d.)-6 G(.)-6 E 6($p) +97 672 S(wd)-6 E(/usr/local)97 684 Q 6($/)97 696 S(bin/pwd)-6 E +(/net/share/sun4/local)97 708 Q 6($c)97 720 S 6(d.)-6 G(.)-6 E EP +%%Page: 8 8 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-8-)282.17 48 Q/F1 10/Courier@0 SF 6($p)97 84 S +(wd)-6 E(/usr)97 96 Q 6($/)97 108 S(bin/pwd)-6 E(/usr)97 120 Q F0 .3(On\ +e problem with this, of course, arises when programs that do not unders\ +tand the shell')72 141.6 R 2.8(sl)-.55 G .3(ogical notion of)-2.8 F .217 +(the \214le system interpret \231..)72 153.6 R 2.718<9a64>-.7 G(if) +-2.718 E(ferently)-.25 E 5.218(.T)-.65 G .218 +(his generally happens when Bash completes \214lenames containing)-5.218 +F(\231..)72 165.6 Q 3.384<9a61>-.7 G .884 +(ccording to a logical hierarch)-3.384 F 3.384(yw)-.05 G .884 +(hich does not correspond to their ph)-3.384 F .883(ysical location.) +-.05 F -.15(Fo)5.883 G 3.383(ru).15 G .883(sers who)-3.383 F +(\214nd this troublesome, a corresponding)72 177.6 Q/F2 10 +/Times-Italic@0 SF(physical)2.5 E F0(vie)2.5 E 2.5(wo)-.25 G 2.5(ft)-2.5 +G(he \214le system is a)-2.5 E -.25(va)-.2 G(ilable:).25 E F1 6($c)97 +195.6 S 6(d/)-6 G(usr/local/bin)-6 E 6($p)97 207.6 S(wd)-6 E +(/usr/local/bin)97 219.6 Q 6($s)97 231.6 S(et -o physical)-6 E 6($p)97 +243.6 S(wd)-6 E(/net/share/sun4/local/bin)97 255.6 Q/F3 10/Times-Bold@0 +SF 2.5(4.10. Inter)72 285.6 R(nationalization)-.15 E F0 .145 +(One of the most signi\214cant impro)97 301.2 R -.15(ve)-.15 G .145 +(ments in v).15 F .145(ersion 1.13 of Bash w)-.15 F .145 +(as the change to \231eight-bit clean-)-.1 F 2.933(liness\232. Pre)72 +313.2 R .433(vious v)-.25 F .432 +(ersions used the eighth bit of characters to mark whether or not the) +-.15 F 2.932(yw)-.15 G .432(ere quoted when)-2.932 F 1.495(performing w) +72 325.2 R 1.495(ord e)-.1 F 3.995(xpansions. While)-.15 F 1.495 +(this did not af)3.995 F 1.496 +(fect the majority of users, most of whom used only)-.25 F(se)72 337.2 Q +-.15(ve)-.25 G 1.236(n-bit ASCII characters, some found it con\214ning.) +.15 F(Be)6.236 E 1.236(ginning with v)-.15 F 1.236 +(ersion 1.13, Bash implemented a)-.15 F(dif)72 349.2 Q .02(ferent quoti\ +ng mechanism that did not alter the eighth bit of characters.)-.25 F +.021(This allo)5.021 F .021(wed Bash to manipulate)-.25 F .427 +(\214les with \231odd\232 characters in their names, b)72 361.2 R .427 +(ut did nothing to help users enter those names, so v)-.2 F .426 +(ersion 1.13)-.15 F 1.458 +(introduced changes to readline that made it eight-bit clean as well.)72 +373.2 R 1.458(Options e)6.458 F 1.458(xist that force readline to)-.15 F +.744(attach no special signi\214cance to characters with the eighth bit\ + set \(the def)72 385.2 R .744(ault beha)-.1 F .744(vior is to con)-.2 F +-.15(ve)-.4 G .744(rt these).15 F .641(characters to meta-pre\214x)72 +397.2 R .641(ed k)-.15 F .941 -.15(ey s)-.1 H .642 +(equences\) and to output these characters without con).15 F -.15(ve)-.4 +G .642(rsion to meta-pre-).15 F<8c78>72 409.2 Q .008(ed sequences.)-.15 +F .007(These changes, along with the e)5.007 F .007(xpansion of k)-.15 F +-.15(ey)-.1 G .007(maps to a full eight bits, enable readline to).15 F +-.1(wo)72 421.2 S(rk with most of the ISO-8859 f).1 E +(amily of character sets, used by man)-.1 E 2.5(yE)-.15 G +(uropean countries.)-2.5 E F3 2.5(4.11. POSIX)72 445.2 R(Mode)2.5 E F0 +.584(Although Bash is intended to be POSIX.2 conformant, there are area\ +s in which the def)97 460.8 R .584(ault beha)-.1 F(vior)-.2 E .463 +(is not compatible with the standard.)72 472.8 R -.15(Fo)5.463 G 2.962 +(ru).15 G .462(sers who wish to operate in a strict POSIX.2 en)-2.962 F +.462(vironment, Bash)-.4 F .505(implements a)72 484.8 R F2 .505 +(POSIX mode)3.005 F F0 5.505(.W)C .505(hen this mode is acti)-5.505 F +-.15(ve)-.25 G 3.005(,B).15 G .505(ash modi\214es its def)-3.005 F .505 +(ault operation where it dif)-.1 F(fers)-.25 E .267 +(from POSIX.2 to match the standard.)72 496.8 R .266 +(POSIX mode is entered when Bash is started with the)5.267 F F3(-posix) +2.766 E F0(option.)2.766 E .149(This feature is also a)72 508.8 R -.25 +(va)-.2 G .149(ilable as an option to the).25 F F3(set)2.649 E F0 -.2 +(bu)2.649 G(iltin,).2 E F3 .149(set -o posix)2.649 F F0 5.149(.F)C .149 +(or compatibility with other GNU)-5.299 F(softw)72 520.8 Q 4.02(are tha\ +t attempts to be POSIX.2 compliant, Bash also enters POSIX mode if the \ +v)-.1 F(ariable)-.25 E F3($POSIXL)72 532.8 Q(Y_CORRECT)-.92 E F0 5.824 +(is set when Bash is started or assigned a v)8.324 F 5.825 +(alue during e)-.25 F -.15(xe)-.15 G(cution.).15 E F3($POSIX_PED)72 +544.8 Q(ANTIC)-.35 E F0 .27 +(is accepted as well, to be compatible with some older GNU utilities.) +2.77 F .27(When Bash is)5.27 F .506(started in POSIX mode, for e)72 +556.8 R .506(xample, it sources the \214le named by the v)-.15 F .507 +(alue of)-.25 F F3($ENV)3.007 E F0 .507(rather than the \231nor)3.007 F +(-)-.2 E(mal\232 startup \214les, and does not allo)72 568.8 Q 2.5(wr) +-.25 G(eserv)-2.5 E(ed w)-.15 E(ords to be aliased.)-.1 E F3 2.5(5. New) +72 592.8 R -.25(Fe)2.5 G(atur).25 E(es and Futur)-.18 E 2.5(eP)-.18 G +(lans)-2.5 E F0 1.632(There are se)97 608.4 R -.15(ve)-.25 G 1.632 +(ral features introduced in the current v).15 F 1.631(ersion of Bash, v) +-.15 F 1.631(ersion 1.14, and a number)-.15 F .241 +(under consideration for future releases.)72 620.4 R .242 +(This section will brie\215y detail the ne)5.242 F 2.742(wf)-.25 G .242 +(eatures in v)-2.742 F .242(ersion 1.14 and)-.15 F(describe se)72 632.4 +Q -.15(ve)-.25 G(ral features that may appear in later v).15 E(ersions.) +-.15 E F3 2.5(5.1. New)72 656.4 R -.25(Fe)2.5 G(atur).25 E +(es in Bash-1.14)-.18 E F0 .884(The ne)97 672 R 3.384(wf)-.25 G .884 +(eatures a)-3.384 F -.25(va)-.2 G .884(ilable in Bash-1.14 answer se).25 +F -.15(ve)-.25 G .883(ral of the most common requests for enhance-).15 F +2.931(ments. Most)72 684 R(notably)2.931 E 2.931(,t)-.65 G .432(here is\ + a mechanism for including non-visible character sequences in prompts, \ +such)-2.931 F .136 +(as those which cause a terminal to print characters in dif)72 696 R +.135(ferent colors or in standout mode.)-.25 F .135(There w)5.135 F .135 +(as noth-)-.1 F .558(ing pre)72 708 R -.15(ve)-.25 G .558 +(nting the use of these sequences in earlier v).15 F .559(ersions, b) +-.15 F .559(ut the readline redisplay algorithm assumed)-.2 F +(each character occupied ph)72 720 Q(ysical screen space and w)-.05 E +(ould wrap lines prematurely)-.1 E(.)-.65 E EP +%%Page: 9 9 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-9-)282.17 48 Q .13(Readline has a fe)97 84 R +2.63(wn)-.25 G .63 -.25(ew va)-2.63 H .13(riables, se).25 F -.15(ve)-.25 +G .13(ral ne).15 F 2.63(wb)-.25 G .13 +(indable commands, and some additional emacs mode)-2.63 F(def)72 96 Q +.918(ault k)-.1 F 1.218 -.15(ey b)-.1 H 3.418(indings. A).15 F(ne)3.418 +E 3.418(wh)-.25 G .919(istory search mode has been implemented: in this\ + mode, readline searches)-3.418 F .336(the history for lines be)72 108 R +.336(ginning with the characters between the be)-.15 F .336 +(ginning of the current line and the cursor)-.15 F(.)-.55 E .555(The e) +72 120 R .556(xisting readline incremental search commands no longer ma\ +tch identical lines more than once.)-.15 F(File-)5.556 E 1.979 +(name completion no)72 132 R 4.479(we)-.25 G 1.979(xpands v)-4.629 F +1.979(ariables in directory names.)-.25 F 1.978(The history e)6.978 F +1.978(xpansion f)-.15 F 1.978(acilities are no)-.1 F(w)-.25 E 1.449 +(nearly completely csh-compatible: missing modi\214ers ha)72 144 R 1.749 +-.15(ve b)-.2 H 1.449(een added and history substitution has been).15 F +-.15(ex)72 156 S(tended.).15 E(Se)97 171.6 Q -.15(ve)-.25 G .474 +(ral of the features described earlier).15 F 2.973(,s)-.4 G .473(uch as) +-2.973 F/F1 10/Times-Bold@0 SF .473(set -o posix)2.973 F F0(and)2.973 E +F1($POSIX_PED)2.973 E(ANTIC)-.35 E F0 2.973(,a)C .473(re ne)-2.973 F +2.973(wi)-.25 G(n)-2.973 E -.15(ve)72 183.6 S .106(rsion 1.14.).15 F +.106(There is a ne)5.106 F 2.606(ws)-.25 G .106(hell v)-2.606 F +(ariable,)-.25 E F1(OSTYPE)2.606 E F0 2.606(,t)C 2.606(ow)-2.606 G .106 +(hich Bash assigns a v)-2.606 F .106(alue that identi\214es the v)-.25 F +(er)-.15 E(-)-.2 E 1.38(sion of)72 195.6 R/F2 9/Times-Roman@0 SF(UNIX) +3.88 E F0(it')3.88 E 3.879(sr)-.55 G 1.379(unning on \(great for puttin\ +g architecture-speci\214c binary directories into the)-3.879 F F1($P) +3.879 E -.95(AT)-.74 G(H).95 E F0(\).)A -1 -.8(Tw o)72 207.6 T -.25(va) +6.215 G 2.915(riables ha).25 F 3.215 -.15(ve b)-.2 H 2.915(een renamed:) +.15 F F1($HISTCONTR)5.416 E(OL)-.3 E F0(replaces)5.416 E F1 +($history_contr)5.416 E(ol)-.18 E F0 5.416(,a)C(nd)-5.416 E F1 +($HOSTFILE)5.416 E F0(replaces)72 219.6 Q F1 +($hostname_completion_\214le)2.521 E F0 5.021(.I)C 2.521(nb)-5.021 G +.021(oth cases, the old names are accepted for backw)-2.521 F .02 +(ards compatibil-)-.1 F(ity)72 231.6 Q 5.788(.T)-.65 G .788(he ksh) +-5.788 F/F3 10/Times-Italic@0 SF(select)3.288 E F0 .788 +(construct, which allo)3.288 F .788 +(ws the generation of simple menus, has been implemented.)-.25 F(Ne) +5.788 E(w)-.25 E 1.496(capabilities ha)72 243.6 R 1.796 -.15(ve b)-.2 H +1.496(een added to e).15 F 1.495(xisting v)-.15 F(ariables:)-.25 E F1 +($auto_r)3.995 E(esume)-.18 E F0 1.495(can no)3.995 F 3.995(wt)-.25 G +(ak)-3.995 E 3.995(ev)-.1 G 1.495(alues of)-4.245 F F3 -.2(ex)3.995 G +(act).2 E F0(or)3.995 E F3(sub-)3.995 E(string)72 255.6 Q F0 4.843(,a)C +(nd)-4.843 E F1($HISTCONTR)4.843 E(OL)-.3 E F0 2.343(understands the v) +4.843 F(alue)-.25 E F3(ignor)4.844 E(eboth)-.37 E F0 4.844(,w)C 2.344 +(hich combines the tw)-4.844 F 4.844(op)-.1 G(re)-4.844 E(viously)-.25 E +1.556(acceptable v)72 267.6 R 4.056(alues. The)-.25 F F1(dirs)4.056 E F0 +-.2(bu)4.056 G 1.556(iltin has acquired options to print out speci\214c\ + members of the directory).2 F 3.062(stack. The)72 279.6 R F1($nolinks) +3.062 E F0 -.25(va)3.062 G .562(riable, which forces a ph).25 F .562 +(ysical vie)-.05 F 3.062(wo)-.25 G 3.062(ft)-3.062 G .563 +(he \214le system, has been superseded by the)-3.062 F F172 291.6 +Q F0 .494(option to the)2.994 F F1(set)2.994 E F0 -.2(bu)2.994 G .494 +(iltin \(equi).2 F -.25(va)-.25 G .494(lent to).25 F F1 .494(set -o ph) +2.994 F(ysical)-.15 E F0 .493(\); the v)B .493 +(ariable is retained for backw)-.25 F .493(ards compati-)-.1 F(bility)72 +303.6 Q 5.196(.T)-.65 G .196(he v)-5.196 F .196 +(ersion string contained in)-.15 F F1($B)2.696 E(ASH_VERSION)-.3 E F0 +(no)2.696 E 2.696(wi)-.25 G .196(ncludes an indication of the patch le) +-2.696 F -.15(ve)-.25 G 2.696(la).15 G(s)-2.696 E .85(well as the \231b) +72 315.6 R .85(uild v)-.2 F 3.35(ersion\232. Some)-.15 F .85 +(little-used features ha)3.35 F 1.15 -.15(ve b)-.2 H .85(een remo).15 F +-.15(ve)-.15 G 3.35(d: the).15 F F1(by)3.35 E(e)-.1 E F0(synon)3.35 E +.85(ym for)-.15 F F1(exit)3.35 E F0(and)3.35 E(the)72 327.6 Q F1($NO_PR) +3.498 E(OMPT_V)-.3 E(ARS)-1.35 E F0 -.25(va)3.498 G .998 +(riable are gone.).25 F .998(There is no)5.998 F 3.498(wa)-.25 G 3.498 +(no)-3.498 G -2.19 -.18(rg a)-3.498 H .998 +(nized test suite that can be run as a).18 F(re)72 339.6 Q +(gression test when b)-.15 E(uilding a ne)-.2 E 2.5(wv)-.25 G +(ersion of Bash.)-2.65 E 1.696(The documentation has been thoroughly o) +97 355.2 R -.15(ve)-.15 G 1.696(rhauled: there is a ne).15 F 4.196(wm) +-.25 G 1.695(anual page on the readline)-4.196 F .467(library and the)72 +367.2 R F3(info)2.967 E F0 .467 +(\214le has been updated to re\215ect the current v)2.967 F 2.968 +(ersion. As)-.15 F(al)2.968 E -.1(wa)-.1 G .468(ys, as man).1 F 2.968 +(yb)-.15 G .468(ugs as possi-)-3.168 F(ble ha)72 379.2 Q .3 -.15(ve b) +-.2 H(een \214x).15 E(ed, although some surely remain.)-.15 E F1 2.5 +(5.2. Other)72 403.2 R -.25(Fe)2.5 G(atur).25 E(es)-.18 E F0 1.68 +(There are a fe)97 418.8 R 4.18(wf)-.25 G 1.68 +(eatures that I hope to include in later Bash releases.)-4.18 F 1.68 +(Some are based on w)6.68 F(ork)-.1 E(already done in other shells.)72 +430.8 Q .958(In addition to simple v)97 446.4 R .959(ariables, a future\ + release of Bash will include one-dimensional arrays, using)-.25 F .206 +(the ksh implementation of arrays as a model.)72 458.4 R .205 +(Additions to the ksh syntax, such as)5.205 F F3(varname)2.705 E F0 .205 +(=\( ... \) to assign)B 2.587(al)72 470.4 S .087(ist of w)-2.587 F .088 +(ords directly to an array and a mechanism to allo)-.1 F 2.588(wt)-.25 G +(he)-2.588 E F1 -.18(re)2.588 G(ad).18 E F0 -.2(bu)2.588 G .088 +(iltin to read a list of v).2 F .088(alues directly)-.25 F .092 +(into an array)72 482.4 R 2.592(,w)-.65 G .092(ould be desirable.)-2.692 +F(Gi)5.092 E -.15(ve)-.25 G 2.592(nt).15 G .092(hose e)-2.592 F .092 +(xtensions, the ksh)-.15 F F1 .092(set \255A)2.592 F F0 .091 +(syntax may not be w)2.591 F .091(orth support-)-.1 F(ing \(the)72 494.4 +Q F12.5 E F0(option assigns a list of v)2.5 E(alues to an array) +-.25 E 2.5(,b)-.65 G(ut is a rather peculiar special case\).)-2.7 E .76 +(Some shells include a means of)97 510 R F3(pr)3.26 E -.1(og)-.45 G -.15 +(ra).1 G(mmable).15 E F0 -.1(wo)3.26 G .76 +(rd completion, where the user speci\214es on a per).1 F(-)-.2 E .163 +(command basis ho)72 522 R 2.663(wt)-.25 G .163(he ar)-2.663 F .163(gum\ +ents of the command are to be treated when completion is attempted: as \ +\214le-)-.18 F .194(names, hostnames, e)72 534 R -.15(xe)-.15 G .194 +(cutable \214les, and so on.).15 F .195 +(The other aspects of the current Bash implementation could)5.195 F .482 +(remain as-is; the e)72 546 R .482(xisting heuristics w)-.15 F .481 +(ould still be v)-.1 F 2.981(alid. Only)-.25 F .481 +(when completing the ar)2.981 F .481(guments to a simple)-.18 F +(command w)72 558 Q(ould the programmable completion be in ef)-.1 E +(fect.)-.25 E .479(It w)97 573.6 R .479(ould also be nice to gi)-.1 F +.779 -.15(ve t)-.25 H .479(he user \214ner).15 F .479 +(-grained control o)-.2 F -.15(ve)-.15 G 2.98(rw).15 G .48 +(hich commands are sa)-2.98 F -.15(ve)-.2 G 2.98(do).15 G .48(nto the) +-2.98 F 1.786(history list.)72 585.6 R 1.786(One proposal is for a v) +6.786 F 1.786(ariable, tentati)-.25 F -.15(ve)-.25 G 1.786(ly named).15 +F F1(HISTIGNORE)4.286 E F0 4.285(,w)C 1.785(hich w)-4.285 F 1.785 +(ould contain a)-.1 F .496(colon-separated list of commands.)72 597.6 R +.496(Lines be)5.496 F .496 +(ginning with these commands, after the restrictions of)-.15 F F1($HIST) +2.997 E(-)-.92 E(CONTR)72 609.6 Q(OL)-.3 E F0(ha)2.65 E .45 -.15(ve b) +-.2 H .15(een applied, w).15 F .15 +(ould not be placed onto the history list.)-.1 F .15 +(The shell pattern-matching capa-)5.15 F(bilities could also be a)72 +621.6 Q -.25(va)-.2 G(ilable when specifying the contents of).25 E F1 +($HISTIGNORE)2.5 E F0(.)A .729(One thing that ne)97 637.2 R .729 +(wer shells such as)-.25 F F1(wksh)3.229 E F0 .729(\(also kno)3.229 F +.729(wn as)-.25 F F1(dtksh)3.23 E F0 3.23(\)p)C(ro)-3.23 E .73 +(vide is a command to dynami-)-.15 F 1.189 +(cally load code implementing additional b)72 649.2 R 1.189 +(uiltin commands into a running shell.)-.2 F 1.188(This ne)6.188 F 3.688 +(wb)-.25 G 1.188(uiltin w)-3.888 F(ould)-.1 E(tak)72 661.2 Q 2.875(ea) +-.1 G 2.875(no)-2.875 G .375 +(bject \214le or shared library implementing the \231body\232 of the b) +-2.875 F .375(uiltin \()-.2 F F3(xxx_b)A(uiltin\(\))-.2 E F0 .375 +(for those f)2.875 F(amiliar)-.1 E .052 +(with Bash internals\) and a structure containing the name of the ne)72 +673.2 R 2.552(wc)-.25 G .051(ommand, the function to call when the) +-2.552 F(ne)72 685.2 Q 3.458(wb)-.25 G .958(uiltin is in)-3.658 F -.2 +(vo)-.4 G -.1(ke).2 G 3.458(d\().1 G .959 +(presumably de\214ned in the shared object speci\214ed as an ar)-3.458 F +.959(gument\), and the docu-)-.18 F 1.352 +(mentation to be printed by the)72 697.2 R F1(help)3.851 E F0 1.351 +(command \(possibly present in the shared object as well\).)3.851 F +1.351(It w)6.351 F(ould)-.1 E(manage the details of e)72 709.2 Q +(xtending the internal table of b)-.15 E(uiltins.)-.2 E EP +%%Page: 10 10 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-10-)279.67 48 Q 3.291(Af)97 84 S 1.291 -.25 +(ew o)-3.291 H .791(ther b).25 F .791(uiltins w)-.2 F .791 +(ould also be desirable: tw)-.1 F 3.291(oa)-.1 G .791(re the POSIX.2) +-3.291 F/F1 10/Times-Bold@0 SF(getconf)3.292 E F0 .792 +(command, which prints)3.292 F 1.412(the v)72 96 R 1.412 +(alues of system con\214guration v)-.25 F 1.411 +(ariables de\214ned by POSIX.2, and a)-.25 F F1(diso)3.911 E(wn)-.1 E F0 +-.2(bu)3.911 G 1.411(iltin, which causes a).2 F 1.347 +(shell running with job control acti)72 108 R 1.647 -.15(ve t)-.25 H +3.847<6f99>.15 G(for)-3.847 E 1.347 +(get about\232 one or more background jobs in its internal jobs)-.18 F +3.465(table. Using)72 120 R F1(getconf)3.465 E F0 3.465(,f)C .965(or e) +-3.465 F .965(xample, a user could retrie)-.15 F 1.264 -.15(ve a v)-.25 +H .964(alue for)-.1 F F1($P)3.464 E -.95(AT)-.74 G(H).95 E F0 .964 +(guaranteed to \214nd all of the)3.464 F .884 +(POSIX standard utilities, or \214nd out ho)72 132 R 3.385(wl)-.25 G +.885 +(ong \214lenames may be in the \214le system containing a speci\214ed) +-3.385 F(directory)72 144 Q(.)-.65 E 1.521 +(There are no implementation timetables for an)97 159.6 R 4.021(yo)-.15 +G 4.021(ft)-4.021 G 1.52(hese features, nor are there concrete plans to) +-4.021 F(include them.)72 171.6 Q(If an)5 E(yone has comments on these \ +proposals, feel free to send me electronic mail.)-.15 E F1 2.5 +(6. Re\215ections)72 195.6 R(and Lessons Lear)2.5 E(ned)-.15 E F0 .433 +(The lesson that has been repeated most often during Bash de)97 211.2 R +-.15(ve)-.25 G .433(lopment is that there are dark corners).15 F .181 +(in the Bourne shell, and people use all of them.)72 223.2 R .18 +(In the original description of the Bourne shell, quoting and)5.181 F +.073(the shell grammar are both poorly speci\214ed and incomplete; subs\ +equent descriptions ha)72 235.2 R .373 -.15(ve n)-.2 H .073 +(ot helped much.).15 F 1.856(The grammar presented in Bourne')72 247.2 R +4.356(sp)-.55 G 1.856(aper describing the shell distrib)-4.356 F 1.855 +(uted with the Se)-.2 F -.15(ve)-.25 G 1.855(nth Edition of).15 F/F2 9 +/Times-Roman@0 SF(UNIX)72 259.2 Q F0 2.5<8769>C 2.5(ss)-2.5 G 2.5(of) +-2.5 G(ar of)-2.6 E 2.5(ft)-.25 G(hat it does not allo)-2.5 E 2.5(wt) +-.25 G(he command)-2.5 E/F3 10/Courier@0 SF(who|wc)2.5 E F0 5(.I)C 2.5 +(nf)-5 G(act, as T)-2.6 E(om Duf)-.8 E 2.5(fs)-.25 G(tates:)-2.5 E 1.375 +(Nobody really kno)97 274.8 R 1.375(ws what the Bourne shell')-.25 F +3.875(sg)-.55 G 1.375(rammar is.)-3.875 F(Ev)6.376 E 1.376(en e)-.15 F +1.376(xamination of the source)-.15 F(code is little help.\210)97 286.8 +Q .382(The POSIX.2 standard includes a)72 302.4 R/F4 10/Times-Italic@0 +SF(yacc)2.882 E F0 .382 +(grammar that comes close to capturing the Bourne shell')2.882 F 2.882 +(sb)-.55 G(eha)-2.882 E(vior)-.2 E(,)-.4 E -.2(bu)72 314.4 S 3.246(ti).2 +G 3.246(td)-3.246 G(isallo)-3.246 E .747(ws some constructs which sh ac\ +cepts without complaint \255 and there are scripts out there that)-.25 F +.501(use them.)72 326.4 R .501(It took a fe)5.501 F 3.001(wv)-.25 G .501 +(ersions and se)-3.151 F -.15(ve)-.25 G .501(ral b).15 F .5 +(ug reports before Bash implemented sh-compatible quoting,)-.2 F .279 +(and there are still some \231le)72 338.4 R -.05(ga)-.15 G .279 +(l\232 sh constructs which Bash \215ags as syntax errors.).05 F .28 +(Complete sh compatibility)5.28 F(is a tough nut.)72 350.4 Q 1.231 +(The shell is bigger and slo)97 366 R 1.231(wer than I w)-.25 F 1.231 +(ould lik)-.1 F 1.23(e, though the current v)-.1 F 1.23 +(ersion is substantially f)-.15 F(aster)-.1 E .086(than pre)72 378 R +(viously)-.25 E 5.086(.T)-.65 G .087 +(he readline library could stand a substantial re)-5.086 F 2.587 +(write. A)-.25 F .087(hand-written parser to replace the)2.587 F +(current)72 390 Q F4(yacc)2.978 E F0 .478(-generated one w)B .477 +(ould probably result in a speedup, and w)-.1 F .477(ould solv)-.1 F +2.977(eo)-.15 G .477(ne glaring problem:)-2.977 F(the)5.477 E .384 +(shell could parse commands in \231$\(...\)\232 constructs as the)72 402 +R 2.884(ya)-.15 G .385 +(re entered, rather than reporting errors when the)-2.884 F +(construct is e)72 414 Q(xpanded.)-.15 E 1.064(As al)97 429.6 R -.1(wa) +-.1 G 1.064(ys, there is some chaf).1 F 3.564(ft)-.25 G 3.564(og)-3.564 +G 3.564(ow)-3.564 G 1.064(ith the wheat.)-3.564 F 1.063 +(Areas of duplicated functionality need to be)6.063 F .382(cleaned up.) +72 441.6 R .382(There are se)5.382 F -.15(ve)-.25 G .382 +(ral cases where Bash treats a v).15 F .382 +(ariable specially to enable functionality a)-.25 F -.25(va)-.2 G +(ilable).25 E .185(another w)72 453.6 R .185(ay \()-.1 F F1($notify)A F0 +(vs.)2.684 E F1 .184(set -o notify)5.184 F F0(and)2.684 E F1($nolinks) +2.684 E F0(vs.)2.684 E F1 .184(set -o ph)2.684 F(ysical)-.15 E F0 2.684 +(,f)C .184(or instance\); the special treatment)-2.684 F 3.421(of the v) +72 465.6 R 3.421(ariable name should probably be remo)-.25 F -.15(ve) +-.15 G 5.921(d. A).15 F(fe)5.921 E 5.921(wm)-.25 G 3.422 +(ore things could stand remo)-5.921 F -.25(va)-.15 G 3.422(l; the).25 F +F1($allo)72 477.6 Q(w_null_glob_expansion)-.1 E F0(and)4.112 E F1 +($glob_dot_\214lenames)4.112 E F0 -.25(va)4.111 G 1.611 +(riables are of particularly questionable v).25 F(alue.)-.25 E(The)72 +489.6 Q F1($[...])3.977 E F0 1.477(arithmetic e)3.977 F -.25(va)-.25 G +1.478(luation syntax is redundant no).25 F 3.978(wt)-.25 G 1.478 +(hat the POSIX-mandated)-3.978 F F1($\(\(...\)\))3.978 E F0 1.478 +(construct has)3.978 F .326(been implemented, and could be deleted.)72 +501.6 R .326(It w)5.326 F .326(ould be nice if the te)-.1 F .326 +(xt output by the)-.15 F F1(help)2.825 E F0 -.2(bu)2.825 G .325 +(iltin were e).2 F(xter)-.15 E(-)-.2 E .061 +(nal to the shell rather than compiled into it.)72 513.6 R .062 +(The beha)5.062 F .062(vior enabled by)-.2 F F1 +($command_oriented_history)2.562 E F0 2.562(,w)C(hich)-2.562 E 1.125 +(causes the shell to attempt to sa)72 525.6 R 1.424 -.15(ve a)-.2 H +1.124(ll lines of a multi-line command in a single history entry).15 F +3.624(,s)-.65 G 1.124(hould be)-3.624 F(made the def)72 537.6 Q +(ault and the v)-.1 E(ariable remo)-.25 E -.15(ve)-.15 G(d.).15 E F1 2.5 +(7. A)72 561.6 R -.1(va)-1 G(ilability).1 E F0 .047 +(As with all other GNU softw)97 577.2 R .047(are, Bash is a)-.1 F -.25 +(va)-.2 G .047(ilable for anon).25 F .047(ymous FTP from)-.15 F F4(pr) +2.547 E(ep.ai.mit.edu:/pub/gnu)-.37 E F0 1.05(and from other GNU softw) +72 589.2 R 1.05(are mirror sites.)-.1 F 1.049(The current v)6.049 F +1.049(ersion is in)-.15 F F4(bash-1.14.1.tar)3.549 E(.gz)-1.11 E F0 +1.049(in that directory)3.549 F(.)-.65 E(Use)72 601.2 Q F4(ar)5.965 E +-.15(ch)-.37 G(ie).15 E F0 3.465(to \214nd the nearest archi)5.965 F +3.766 -.15(ve s)-.25 H 5.966(ite. The).15 F 3.466(latest v)5.966 F 3.466 +(ersion is al)-.15 F -.1(wa)-.1 G 3.466(ys a).1 F -.25(va)-.2 G 3.466 +(ilable for FTP from).25 F F4(bash.CWR)72 613.2 Q -.25(U.)-.4 G +(Edu:/pub/dist.).25 E F0(Bash documentation is a)5 E -.25(va)-.2 G +(ilable for FTP from).25 E F4(bash.CWR)2.5 E -.25(U.)-.4 G +(Edu:/pub/bash.).25 E F0 1.169(The Free Softw)97 628.8 R 1.169(are F)-.1 +F 1.169(oundation sells tapes and CD-R)-.15 F 1.168 +(OMs containing Bash; send electronic mail to)-.4 F F3 +(gnu@prep.ai.mit.edu)72 640.8 Q F0(or call)2.5 E F3(+1-617-876-3296)2.5 +E F0(for more information.)2.5 E .694(Bash is also distrib)97 656.4 R +.694(uted with se)-.2 F -.15(ve)-.25 G .694(ral v).15 F .694(ersions of) +-.15 F F2(UNIX)3.194 E F0 .694(-compatible systems.)B .695 +(It is included as /bin/sh)5.694 F .948(and /bin/bash on se)72 668.4 R +-.15(ve)-.25 G .948(ral Linux distrib).15 F .948 +(utions \(more about the dif)-.2 F .948 +(ference in a moment\), and as contrib)-.25 F(uted)-.2 E .32 LW 144 +676.4 72 676.4 DL/F5 8/Times-Roman@0 SF .781 +(\207S. R. Bourne, \231UNIX T)72 688.2 R .781(ime-Sharing System:)-.28 F +.781(The UNIX Shell\232,)4.781 F/F6 8/Times-Italic@0 SF .78 +(Bell System T)2.78 F(ec)-.736 E .78(hnical J)-.12 F(ournal)-.2 E F5 +2.78(,5)C .78(7\(6\), July-)-2.78 F(August, 1978, pp. 1971-1990.)72 +698.2 Q<8854>72 710 Q .431(om Duf)-.64 F .431 +(f, \231Rc \255 A Shell for Plan 9 and)-.2 F/F7 7/Times-Roman@0 SF(UNIX) +2.432 E F5(systems\232,)2.432 E F6(Pr)2.432 E .432 +(oc. of the Summer 1990 EUUG Confer)-.36 F(ence)-.296 E F5 2.432(,L)C +(on-)-2.432 E(don, July)72 720 Q 2(,1)-.52 G(990, pp. 21-33.)-2 E EP +%%Page: 11 11 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF(-11-)279.67 48 Q(softw)72 84 Q(are in BSDI')-.1 +E 2.5(sB)-.55 G(SD/386* and FreeBSD.)-2.5 E .598(The Linux distrib)97 +99.6 R .598(ution deserv)-.2 F .598(es special mention.)-.15 F .598 +(There are tw)5.598 F 3.099(oc)-.1 G .599 +(on\214gurations included in the stan-)-3.099 F .733(dard Bash distrib) +72 111.6 R .732(ution: a \231normal\232 con\214guration, in which all o\ +f the standard features are included, and a)-.2 F .519(\231minimal\232 \ +con\214guration, which omits job control, aliases, history and command \ +line editing, the directory)72 123.6 R .886(stack and)72 135.6 R/F1 10 +/Times-Bold@0 SF(pushd/popd/dirs,)3.386 E F0 .886(process substitution,\ + prompt string special character decoding, and the)3.386 F/F2 10 +/Times-Italic@0 SF(select)3.385 E F0 3.368(construct. This)72 147.6 R +.868(minimal v)3.368 F .869 +(ersion is designed to be a drop-in replacement for the traditional)-.15 +F/F3 9/Times-Roman@0 SF(UNIX)3.369 E F0(/bin/sh,)3.369 E +(and is included as the Linux /bin/sh in se)72 159.6 Q -.15(ve)-.25 G +(ral packagings.).15 E F1 2.5(8. Conclusion)72 183.6 R F0 .8 +(Bash is a w)97 199.2 R(orth)-.1 E 3.3(ys)-.05 G .8(uccessor to sh.)-3.3 +F .8(It is suf)5.8 F .8(\214ciently portable to run on nearly e)-.25 F +-.15(ve)-.25 G .8(ry v).15 F .8(ersion of)-.15 F F3(UNIX)3.299 E F0 .31 +(from 4.3 BSD to SVR4.2, and se)72 211.2 R -.15(ve)-.25 G(ral).15 E F3 +(UNIX)2.81 E F0 -.1(wo)2.81 G(rkalik).1 E 2.81(es. It)-.1 F .311(is rob) +2.81 F .311(ust enough to replace sh on most of those)-.2 F 1.515 +(systems, and pro)72 223.2 R 1.515(vides more functionality)-.15 F 6.515 +(.I)-.65 G 4.015(th)-6.515 G 1.515(as se)-4.015 F -.15(ve)-.25 G 1.515 +(ral thousand re).15 F 1.515(gular users, and their feedback has)-.15 F +(helped to mak)72 235.2 Q 2.5(ei)-.1 G 2.5(ta)-2.5 G 2.5(sg)-2.5 G +(ood as it is today \255 a testament to the bene\214ts of free softw) +-2.5 E(are.)-.1 E .32 LW 144 708.2 72 708.2 DL/F4 8/Times-Roman@0 SF +(*BSD/386 is a trademark of Berk)72 720 Q(ele)-.08 E 2(yS)-.12 G(oftw)-2 +E(are Design, Inc.)-.08 E EP +%%Trailer +end +%%EOF diff --git a/doc/bash.1 b/doc/bash.1 new file mode 100644 index 0000000..40e1fbd --- /dev/null +++ b/doc/bash.1 @@ -0,0 +1,8866 @@ +\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Information Network Services +.\" Case Western Reserve University +.\" chet@po.cwru.edu +.\" +.\" Last Change: Sat Aug 27 13:28:44 EDT 2005 +.\" +.\" bash_builtins, strip all but Built-Ins section +.if \n(zZ=1 .ig zZ +.if \n(zY=1 .ig zY +.TH BASH 1 "2005 Aug 27" "GNU Bash-3.1-beta1" +.\" +.\" 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-2005 by the Free Software Foundation, Inc. +.if t Bash is Copyright \(co 1989-2005 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 intended to be a conformant implementation of the IEEE +POSIX Shell and Tools specification (IEEE Working Group 1003\.2). +.B Bash +can be configured to be POSIX-conformant by default. +.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 options when it is invoked: +.PP +.PD 0 +.TP 10 +.BI \-c "\| string\^" +If the +.B \-c +option 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 \-i +If the +.B \-i +option is present, the shell is +.IR interactive . +.TP +.B \-l +Make +.B bash +act as if it had been invoked as a login shell (see +.SM +.B INVOCATION +below). +.TP +.B \-r +If the +.B \-r +option is present, the shell becomes +.I restricted +(see +.SM +.B "RESTRICTED SHELL" +below). +.TP +.B \-s +If the +.B \-s +option 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 output. +These are the strings that +are subject to language translation when the current locale +is not \fBC\fP or \fBPOSIX\fP. +This implies the \fB\-n\fP option; no commands will be executed. +.TP +.B [\-+]O [\fIshopt_option\fP] +\fIshopt_option\fP is one of the shell options accepted by the +\fBshopt\fP builtin (see +.SM +.B SHELL BUILTIN COMMANDS +below). +If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option; +\fB+O\fP unsets it. +If \fIshopt_option\fP is not supplied, the names and values of the shell +options accepted by \fBshopt\fP are printed on the standard output. +If the invocation option is \fB+O\fP, the output is displayed in a format +that may be reused as input. +.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 to be recognized. +.PP +.PD 0 +.TP +.B \-\-debugger +Arrange for the debugger profile to be executed before the shell +starts. +Turns on extended debugging mode (see the description of the +.B extdebug +option to the +.B shopt +builtin below) +and shell function tracing (see the description of the +\fB\-o functrace\fP option to the +.B set +builtin below). +.TP +.B \-\-dump\-po\-strings +Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP +\fBpo\fP (portable object) file format. +.TP +.B \-\-dump\-strings +Equivalent to \fB\-D\fP. +.TP +.B \-\-help +Display a usage message on standard output and exit successfully. +.TP +\fB\-\-init\-file\fP \fIfile\fP +.PD 0 +.TP +\fB\-\-rcfile\fP \fIfile\fP +.PD +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 \-\-login +Equivalent to \fB\-l\fP. +.TP +.B \-\-noediting +Do not use the GNU +.B readline +library to read command lines when the shell is 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 (\fIposix mode\fP). +.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. +An attempt is first made to open the file in the current directory, and, +if no file is found, then the shell searches the directories in +.SM +.B PATH +for the script. +.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 started without non-option arguments +and without the +.B \-c +option +whose standard input and error 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 an interactive login shell, or as a non-interactive shell +with the \fB\-\-login\fP option, 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 +.if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP +.if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi +.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 an interactive login shell, or a non-interactive +shell with the \fB\-\-login\fP option, 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 other 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, interactive shells expand the +.SM +.B ENV +variable and commands are read and executed from the file +whose name is the expanded value. +No other startup files are read. +.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. +.PP +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the \fB\-p\fP option is not supplied, no startup +files are read, shell functions are not inherited from the environment, the +.SM +.B SHELLOPTS +variable, if it appears in the environment, is ignored, +and the effective user id is set to the real user id. +If the \fB\-p\fP option is supplied at invocation, the startup behavior is +the same, but the effective user id is not reset. +.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 & && ; ;; ( ) | \fP +.if n \fB|| & && ; ;; ( ) | \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 +.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, and is passed as argument zero. +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 via a pipe to the standard input of +.IR command2 . +This connection is performed before any redirections specified by the +command (see +.SM +.B REDIRECTION +below). +.PP +The return status of a pipeline is the exit status of the last +command, unless the \fBpipefail\fP option is enabled. +If \fBpipefail\fP is enabled, the pipeline's return status is the +value of the last (rightmost) command to exit with a non-zero status, +or zero if all commands exit successfully. +If the reserved word +.B ! +precedes a pipeline, the exit status of that pipeline is the logical +negation of the exit status as described above. +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 . +.PP +Of these list operators, +.B && +and +.B \(bv\(bv +have equal precedence, followed by +.B ; +and +.BR &, +which have equal precedence. +.PP +A sequence of one or more newlines may appear in a \fIlist\fP instead +of a semicolon to delimit commands. +.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 +\fIcommand1\fP \fB&&\fP \fIcommand2\fP +.RE +.PP +.I command2 +is executed if, and only if, +.I command1 +returns an exit status of zero. +.PP +An OR list has the form +.RS +.PP +\fIcommand1\fP \fB\(bv\(bv\fP \fIcommand2\fP +.PP +.RE +.PP +.I command2 +is executed if and only if +.I command1 +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 environment (see +.SM +\fBCOMMAND EXECUTION ENVIRONMENT\fP +below). +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. +Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and +\fB}\fP are \fIreserved words\fP and must occur where a reserved +word is permitted to be recognized. Since they do not cause a word +break, they must be separated from \fIlist\fP by whitespace. +.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 +\fB[[\fP \fIexpression\fP \fB]]\fP +Return a status of 0 or 1 depending on the evaluation of +the conditional expression \fIexpression\fP. +Expressions are composed of the primaries described below under +.SM +.BR "CONDITIONAL EXPRESSIONS" . +Word splitting and pathname expansion are not performed on the words +between the \fB[[\fP and \fB]]\fP; tilde expansion, parameter and +variable expansion, arithmetic expansion, command substitution, process +substitution, and quote removal are performed. +Conditional operators such as \fB\-f\fP must be unquoted to be recognized +as primaries. +.if t .sp 0.5 +.if n .sp 1 +When the \fB==\fP and \fB!=\fP operators are used, the string to the +right of the operator is considered a pattern and matched according +to the rules described below under \fBPattern Matching\fP. +If the shell option +.B nocasematch +is enabled, the match is performed without regard to the case +of alphabetic characters. +The return value is 0 if the string matches or does not match +the pattern, respectively, and 1 otherwise. +Any part of the pattern may be quoted to force it to be matched as a +string. +.if t .sp 0.5 +.if n .sp 1 +An additional binary operator, \fB=~\fP, is available, with the same +precedence as \fB==\fP and \fB!=\fP. +When it is used, the string to the right of the operator is considered +an extended regular expression and matched accordingly (as in \fIregex\fP(3)). +The return value is 0 if the string matches +the pattern, and 1 otherwise. +If the regular expression is syntactically incorrect, the conditional +expression's return value is 2. +If the shell option +.B nocasematch +is enabled, the match is performed without regard to the case +of alphabetic characters. +Substrings matched by parenthesized subexpressions within the regular +expression are saved in the array variable \fBBASH_REMATCH\fP. +The element of \fBBASH_REMATCH\fP with index 0 is the portion of the string +matching the entire regular expression. +The element of \fBBASH_REMATCH\fP with index \fIn\fP is the portion of the +string matching the \fIn\fPth parenthesized subexpression. +.if t .sp 0.5 +.if n .sp 1 +Expressions may be combined using the following operators, listed +in decreasing order of precedence: +.if t .sp 0.5 +.if n .sp 1 +.RS +.PD 0 +.TP +.B ( \fIexpression\fP ) +Returns the value of \fIexpression\fP. +This may be used to override the normal precedence of operators. +.TP +.B ! \fIexpression\fP +True if +.I expression +is false. +.TP +\fIexpression1\fP \fB&&\fP \fIexpression2\fP +True if both +.I expression1 +and +.I expression2 +are true. +.TP +.if t \fIexpression1\fP \fB\(bv\(bv\fP \fIexpression2\fP +.if n \fIexpression1\fP \fB||\fP \fIexpression2\fP +True if either +.I expression1 +or +.I expression2 +is true. +.PD +.LP +The \fB&&\fP and +.if t \fB\(bv\(bv\fP +.if n \fB||\fP +operators do not evaluate \fIexpression2\fP if the value of +\fIexpression1\fP is sufficient to determine the return value of +the entire conditional expression. +.RE +.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). +The return status is the exit status of the last command that executes. +If the expansion of the items following \fBin\fP results in an empty +list, no commands are executed, and the return status is 0. +.TP +\fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP +First, the arithmetic expression \fIexpr1\fP is evaluated according +to the rules described below under +.SM +.BR "ARITHMETIC EVALUATION" . +The arithmetic expression \fIexpr2\fP is then evaluated repeatedly +until it evaluates to zero. +Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is +executed and the arithmetic expression \fIexpr3\fP is evaluated. +If any expression is omitted, it behaves as if it evaluates to 1. +The return value is the exit status of the last command in \fIlist\fP +that is executed, or false if any of the expressions is invalid. +.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 +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). +If the shell option +.B nocasematch +is enabled, the match is performed without regard to the case +of alphabetic characters. +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 +\fBwhile\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP +.PD 0 +.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. +.SS Shell Function Definitions +.PP +A shell function is an object that is called like a simple command and +executes a compound command with a new set of positional parameters. +Shell functions are declared as follows: +.TP +[ \fBfunction\fP ] \fIname\fP () \fIcompound\-command\fP [\fIredirection\fP] +This defines a function named \fIname\fP. +The reserved word \fBfunction\fP is optional. +If the \fBfunction\fP reserved word is supplied, the parentheses are optional. +The \fIbody\fP of the function is the compound command +.I compound\-command +(see \fBCompound Commands\fP above). +That command is usually a \fIlist\fP of commands between { and }, but +may be any command listed under \fBCompound Commands\fP above. +\fIcompound\-command\fP is executed whenever \fIname\fP is specified as the +name of a simple command. +Any redirections (see +.SM +.B REDIRECTION +below) specified when a function is defined are performed +when the function is executed. +The exit status of a function definition is zero unless a syntax error +occurs or a readonly function with the same name already exists. +When executed, 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 +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 it is to +represent itself. +.PP +When the command history expansion facilities are being used +(see +.SM +.B HISTORY EXPANSION +below), the +\fIhistory expansion\fP character, usually \fB!\fP, must be quoted +to prevent history expansion. +.PP +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 . If a \fB\e\fP pair +appears, and the backslash is not itself quoted, the \fB\e\fP +is treated as a line continuation (that is, it is removed from the +input stream and 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 ` , +.BR \e , +and, when history expansion is enabled, +.BR ! . +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 . +A double quote may be quoted within double quotes by preceding it with +a backslash. +If enabled, history expansion will be performed unless an +.B ! +appearing in double quotes is escaped using a backslash. +The backslash preceding the +.B ! +is not removed. +.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 specified 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' +single quote +.TP +.B \e\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(one to three digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.TP +.B \ec\fIx\fP +a control-\fIx\fP character +.PD +.RE +.LP +The expanded 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" . +A +.I variable +is a parameter denoted by a +.IR name . +A variable has a \fIvalue\fP and zero or more \fIattributes\fP. +Attributes are assigned using the +.B declare +builtin command (see +.B declare +below in +.SM +.BR "SHELL BUILTIN COMMANDS" ). +.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, +command substitution, arithmetic expansion, and quote +removal (see +.SM +.B EXPANSION +below). If the variable has its +.B integer +attribute set, then +.I value +is evaluated as an arithmetic expression even if the $((...)) expansion is +not used (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. +Assignment statements may also appear as arguments to the +.BR alias , +.BR declare , +.BR typeset , +.BR export , +.BR readonly , +and +.B local +builtin commands. +.PP +In the context where an assignment statement is assigning a value +to a shell variable or array index, the += operator can be used to +append to or add to the variable's previous value. +When += is applied to a variable for which the integer attribute has been +set, \fIvalue\fP is evaluated as an arithmetic expression and added to the +variable's current value, which is also evaluated. +When += is applied to an array variable using compound assignment (see +.B Arrays +below), the +variable's value is not unset (as it is when using =), and new values are +appended to the array beginning at one greater than the array's maximum index. +When applied to a string-valued variable, \fIvalue\fP is expanded and +appended to the variable's value. +.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 unset, the parameters are separated by spaces. +If +.SM +.B IFS +is null, the parameters are joined without intervening separators. +.TP +.B @ +Expands to the positional parameters, starting from one. When the +expansion occurs within double quotes, each parameter expands to a +separate word. That is, "\fB$@\fP" is equivalent to +"\fB$1\fP" "\fB$2\fP" ... +If the double-quoted expansion occurs within a word, the expansion of +the first parameter is joined with the beginning part of the original +word, and the expansion of the last parameter is joined with the last +part of the original word. +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 +option). +.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 pathname used to invoke the +shell or shell script being executed as passed in the environment +or argument list. +Subsequently, expands to the last argument to the previous command, +after expansion. +Also set to the full pathname used to invoke 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 BASH +Expands to the full file name used to invoke this instance of +.BR bash . +.TP +.B BASH_ARGC +An array variable whose values are the number of parameters in each +frame of the current bash execution call stack. +The number of +parameters to the current subroutine (shell function or script executed +with \fB.\fP or \fBsource\fP) is at the top of the stack. +When a subroutine is executed, the number of parameters passed is pushed onto +\fBBASH_ARGC\fP. +The shell sets \fBBASH_ARGC\fP only when in extended debugging mode +(see the description of the +.B extdebug +option to the +.B shopt +builtin below) +.TP +.B BASH_ARGV +An array variable containing all of the parameters in the current bash +execution call stack. The final parameter of the last subroutine call +is at the top of the stack; the first parameter of the initial call is +at the bottom. When a subroutine is executed, the parameters supplied +are pushed onto \fBBASH_ARGV\fP. +The shell sets \fBBASH_ARGV\fP only when in extended debugging mode +(see the description of the +.B extdebug +option to the +.B shopt +builtin below) +.TP +.B BASH_COMMAND +The command currently being executed or about to be executed, unless the +shell is executing a command as the result of a trap, +in which case it is the command executing at the time of the trap. +.TP +.B BASH_EXECUTION_STRING +The command argument to the \fB\-c\fP invocation option. +.TP +.B BASH_LINENO +An array variable whose members are the line numbers in source files +corresponding to each member of \fBFUNCNAME\fP. +\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source +file where \fB${FUNCNAME[\fP\fI$ifP\fB]}\fP was called. +The corresponding source file name is \fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fB. +Use \fBLINENO\fP to obtain the current line number. +.TP +.B BASH_REMATCH +An array variable whose members are assigned by the \fB=~\fP binary +operator to the \fB[[\fP conditional command. +The element with index 0 is the portion of the string +matching the entire regular expression. +The element with index \fIn\fP is the portion of the +string matching the \fIn\fPth parenthesized subexpression. +This variable is read-only. +.TP +.B BASH_SOURCE +An array variable whose members are the source filenames corresponding +to the elements in the \fBFUNCNAME\fP array variable. +.TP +.B BASH_SUBSHELL +Incremented by one each time a subshell or subshell environment is spawned. +The initial value is 0. +.TP +.B BASH_VERSINFO +A readonly 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 BASH_VERSION +Expands to a string describing the version of this instance of +.BR bash . +.TP +.B COMP_CWORD +An index into \fB${COMP_WORDS}\fP of the word containing the current +cursor position. +This variable is available only in shell functions invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_LINE +The current command line. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_POINT +The index of the current cursor position relative to the beginning of +the current command. +If the current cursor position is at the end of the current command, +the value of this variable is equal to \fB${#COMP_LINE}\fP. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_WORDBREAKS +The set of characters that the Readline library treats as word +separators when performing word completion. +If +.SM +.B COMP_WORDBREAKS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B COMP_WORDS +An array variable (see \fBArrays\fP below) consisting of the individual +words in the current command line. +This variable is available only in shell functions invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.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 EUID +Expands to the effective user ID of the current user, initialized at +shell startup. This variable is readonly. +.TP +.B FUNCNAME +An array variable containing the names of all shell functions +currently in the execution call stack. +The element with index 0 is the name of any currently-executing +shell function. +The bottom-most element is "main". +This variable exists only when a shell function is executing. +Assignments to +.SM +.B FUNCNAME +have no effect and return an error status. +If +.SM +.B FUNCNAME +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B GROUPS +An array variable containing the list of groups of which the current +user is a member. +Assignments to +.SM +.B GROUPS +have no effect and return an error status. +If +.SM +.B GROUPS +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 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 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 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 OLDPWD +The previous working directory as set by the +.B cd +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 OSTYPE +Automatically set to a string that +describes the operating system on which +.B bash +is executing. +The default is system-dependent. +.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 PPID +The process ID of the shell's parent. This variable is readonly. +.TP +.B PWD +The current working directory as set by the +.B cd +command. +.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 REPLY +Set to the line of input read by the +.B read +builtin command when no arguments are supplied. +.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 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. +.TP +.B SHLVL +Incremented by one each time an instance of +.B bash +is started. +.TP +.B UID +Expands to the user ID of the current user, initialized at shell startup. +This variable is readonly. +.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 BASH_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 BASH_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 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 +.if t \f(CW".:~:/usr"\fP. +.if n ".:~:/usr". +.TP +.B COLUMNS +Used by the \fBselect\fP builtin command to determine the terminal width +when printing selection lists. Automatically set upon receipt of a SIGWINCH. +.TP +.B COMPREPLY +An array variable from which \fBbash\fP reads the possible completions +generated by a shell function invoked by the programmable completion +facility (see \fBProgrammable Completion\fP below). +.TP +.B EMACS +If \fBbash\fP finds this variable in the environment when the shell starts +with value +.if t \f(CWt\fP, +.if n "t", +it assumes that the shell is running in an emacs shell buffer and disables +line editing. +.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 +.if t \f(CW".o:~"\fP. +.if n ".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 HISTCONTROL +A colon-separated list of values controlling how commands are saved on +the history list. +If the list of values includes +.IR ignorespace , +lines which begin with a +.B space +character are not saved in the history list. +A value of +.I ignoredups +causes lines matching the previous history entry to not be saved. +A value of +.I ignoreboth +is shorthand for \fIignorespace\fP and \fIignoredups\fP. +A value of +.IR erasedups +causes all previous lines matching the current line to be removed from +the history list before that line is saved. +Any value not in the above list is ignored. +If \fBHISTCONTROL\fP is unset, or does not include a valid value, +all lines read by the shell parser are saved on the history list, +subject to the value of +.BR HISTIGNORE . +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +.BR HISTCONTROL . +.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 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 match the complete 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. +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +.BR HISTIGNORE . +.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 HISTTIMEFORMAT +If this variable is set and not null, its value is used as a format string +for \fIstrftime\fP(3) to print the time stamp associated with each history +entry displayed by the \fBhistory\fP builtin. +If this variable is set, time stamps are written to the history file so +they may be preserved across shell sessions. +.TP +.B HOME +The home directory of the current user; the default argument for the +\fBcd\fP builtin command. +The value of this variable is also used when performing tilde expansion. +.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 list of possible hostname completions may be changed while the +shell is running; +the next time hostname completion is attempted after the +value is changed, +.B bash +adds the contents of the new file to the existing list. +If +.SM +.B HOSTFILE +is set, but has no value, \fBbash\fP attempts to read +.FN /etc/hosts +to obtain the list of possible hostname completions. +When +.SM +.B HOSTFILE +is unset, the hostname list is cleared. +.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 +``''. +.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 INPUTRC +The filename for the +.B readline +startup file, overriding the default of +.FN ~/.inputrc +(see +.SM +.B READLINE +below). +.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, and determines the behavior of range +expressions, equivalence classes, and collating sequences within +pathname expansion and pattern matching. +.TP +.B LC_CTYPE +This variable determines the interpretation of characters and the +behavior of character classes within pathname expansion and pattern +matching. +.TP +.B LC_MESSAGES +This variable determines the locale used to translate double-quoted +strings preceded by a \fB$\fP. +.TP +.B LC_NUMERIC +This variable determines the locale category used for number formatting. +.TP +.B LINES +Used by the \fBselect\fP builtin command to determine the column length +for printing selection lists. Automatically set upon receipt of a SIGWINCH. +.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, or set to a value that is not a number +greater than or equal to zero, 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 when mail arrives in a particular file +may be specified by separating the file name from the message with a `?'. +When used in the text of the message, \fB$_\fP expands to the name of +the current mailfile. +Example: +.RS +.PP +\fBMAILPATH\fP='/var/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., /var/mail/\fB$USER\fP). +.RE +.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 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). +A zero-length (null) directory name in the value of \fBPATH\fP indicates the +current directory. +A null directory name may appear as two adjacent colons, or as an initial +or trailing colon. +The default path is system-dependent, +and is set by the administrator who installs +.BR bash . +A common value is +.if t \f(CW/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin\fP. +.if n ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin''. +.TP +.B POSIXLY_CORRECT +If this variable is in the environment when \fBbash\fP starts, the shell +enters \fIposix mode\fP before reading the startup files, as if the +.B \-\-posix +invocation option had been supplied. If it is set while the shell is +running, \fBbash\fP enables \fIposix mode\fP, as if the command +.if t \f(CWset -o posix\fP +.if n \fIset -o posix\fP +had been executed. +.TP +.B PROMPT_COMMAND +If set, the value is executed as a command prior to issuing each primary +prompt. +.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 SHELL +The full pathname to the shell is kept in this environment variable. +If it is not set when the shell starts, +.B bash +assigns to it the full pathname of the current user's login shell. +.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 TMOUT +If set to a value greater than zero, \fBTMOUT\fP is treated as the +default timeout for the \fBread\fP builtin. +The \fBselect\fP command terminates if input does not arrive +after \fBTMOUT\fP seconds when input is coming from a terminal. +In an interactive shell, 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 TMPDIR +If set, \fBBash\fP uses its value as the name of a directory in which +\fBBash\fP creates temporary files for the shell's use. +.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 \fB%\fP\fIstring\fP job identifier. +.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 \fIhistory expansion\fP character, +the character which signals the start of a history +expansion, normally `\fB!\fP'. +The second character is the \fIquick substitution\fP +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 indicates 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. +.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. +If the double-quoted expansion occurs within a word, the expansion of +the first parameter is joined with the beginning part of the original +word, and the expansion of the last parameter is joined with the last +part of the original word. +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. +Care must be taken to avoid unwanted side effects caused by filename +generation. +\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 either a series of comma-separated strings or +a sequence expression between a pair of braces, followed by +an optional +.IR postscript . +The preamble is prefixed to each string contained +within the braces, and the postscript 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 +A sequence expression takes the form \fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB}\fP, +where \fIx\fP and \fIy\fP are either integers or single characters. +When integers are supplied, the expression expands to each number between +\fIx\fP and \fIy\fP, inclusive. +When characters are supplied, the expression expands to each character +lexicographically between \fIx\fP and \fIy\fP, inclusive. Note that +both \fIx\fP and \fIy\fP must be of the same type. +.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 or a valid +sequence expression. +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. +To avoid conflicts with parameter expansion, the string \fB${\fP +is not considered eligible for brace expansion. +.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 an unquoted tilde character (`\fB~\fP'), all of +the characters preceding the first unquoted slash (or all characters, +if there is no unquoted slash) are considered a \fItilde-prefix\fP. +If none of the characters in the tilde-prefix are quoted, the +characters in the tilde-prefix following the tilde are treated as a +possible \fIlogin name\fP. +If this login name is the null string, the tilde is replaced with the +value of the shell parameter +.SM +.BR HOME . +If +.SM +.B HOME +is unset, the home directory of the user executing the shell is +substituted instead. +Otherwise, the tilde-prefix is replaced with the home directory +associated with the specified login name. +.PP +If the tilde-prefix is a `~+', the value of the shell variable +.SM +.B PWD +replaces the tilde-prefix. +If the tilde-prefix is a `~\-', the value of the shell variable +.SM +.BR OLDPWD , +if it is set, is substituted. +If the characters following the tilde in the tilde-prefix consist +of a number \fIN\fP, optionally prefixed +by a `+' or a `\-', the tilde-prefix is replaced with the corresponding +element from the directory stack, as it would be displayed by the +.B dirs +builtin invoked with the tilde-prefix as an argument. +If the characters following the tilde in the tilde-prefix consist of a +number without a leading `+' or `\-', `+' is assumed. +.PP +If the login name is invalid, or the tilde expansion fails, the word +is unchanged. +.PP +Each variable assignment is checked for unquoted tilde-prefixes immediately +following a +.B : +or the first +.BR = . +In these cases, tilde expansion 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 +When braces are used, the matching ending brace is the first `\fB}\fP' +not escaped by a backslash or within a quoted string, and not within an +embedded arithmetic expansion, command substitution, or parameter +expansion. +.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 is used in the rest of the substitution, rather +than the value of \fIparameter\fP itself. +This is known as \fIindirect expansion\fP. +The exceptions to this are the expansions of ${!\fIprefix\fP*} and +${\fB!\fP\fIname\fP[\fI@\fP]} described below. +The exclamation point must immediately follow the left brace in order to +introduce indirection. +.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 +${\fIparameter\fP\fB:\fP\fIoffset\fP} +.PD 0 +.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 the character specified by \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]}. +A negative \fIoffset\fP is taken relative to one greater than the maximum +index of the specified array. +Note that a negative offset must be separated from the colon by at least +one space to avoid being confused with the :- expansion. +Substring indexing is zero-based unless the positional parameters +are used, in which case the indexing starts at 1. +.TP +${\fB!\fP\fIprefix\fP\fB*\fP} +.PD 0 +.TP +${\fB!\fP\fIprefix\fP\fB@\fP} +.PD +Expands to the names of variables whose names begin with \fIprefix\fP, +separated by the first character of the +.SM +.B IFS +special variable. +.TP +${\fB!\fP\fIname\fP[\fI@\fP]} +.PD 0 +.TP +${\fB!\fP\fIname\fP[\fI*\fP]} +.PD +If \fIname\fP is an array variable, expands to the list of array indices +(keys) assigned in \fIname\fP. +If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null +otherwise. +When \fI@\fP is used and the expansion appears within double quotes, each +key expands to a separate word. +.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 value substituted is the number of positional parameters. +If +.I parameter +is an array name subscripted by +.B * +or +.BR @ , +the value substituted is the number of elements in the array. +.TP +${\fIparameter\fP\fB#\fP\fIword\fP} +.PD 0 +.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 result of the expansion is the expanded 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 +${\fIparameter\fP\fB%\fP\fIword\fP} +.PD 0 +.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 expanded value of +.IR parameter , +then the result of the expansion is the expanded 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 +${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.PD 0 +.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 the expanded value of \fIparameter\fP. +If \fIpattern\fP begins with \fB%\fP, it must match at the end +of the expanded value of \fIparameter\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. +Embedded newlines are not deleted, but they may be removed during +word splitting. +The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by +the equivalent but faster \fB$(< \fIfile\fP)\fR. +.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 . +The first backquote not preceded by a backslash terminates the +command substitution. +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 backquoted 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 expansions 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 +When available, process substitution 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 , +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 +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 +.B nullglob +option is set, and no matches are found, +the word is removed. +If the +.B failglob +shell option is set, and no matches are found, an error message +is printed and the command is not executed. +If the shell option +.B nocaseglob +is enabled, the match is performed without regard to the case +of alphabetic characters. +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. +When matching a pathname, 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 +.BR nocaseglob , +.BR nullglob , +.BR failglob , +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 when +.SM +.B GLOBIGNORE +is set and not null. However, setting +.SM +.B GLOBIGNORE +to a non-null value 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 +\fBPattern Matching\fP +.PP +Any character that appears in a pattern, other than the special pattern +characters described below, matches itself. The NUL character may not +occur in a pattern. A backslash escapes the following character; the +escaping backslash is discarded when matching. +The special pattern characters must be quoted if +they are to be matched literally. +.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 hyphen denotes a +\fIrange expression\fP; +any character that sorts between those two characters, inclusive, +using the current locale's collating sequence and character set, +is matched. If the first character following the +.B [ +is a +.B ! +or a +.B ^ +then any character not enclosed is matched. +The sorting order of characters in range expressions is determined by +the current locale and the value of the \fBLC_COLLATE\fP shell variable, +if set. +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. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +\fIcharacter classes\fP can be specified using the syntax +\fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the +following classes defined in the POSIX.2 standard: +.PP +.RS +.B +.if n alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit +.if t alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit +.br +A character class matches any character belonging to that class. +The \fBword\fP character class matches letters, digits, and the character _. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +an \fIequivalence class\fP can be specified using the syntax +\fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the +same collation weight (as defined by the current locale) as +the character \fIc\fP. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol +\fIsymbol\fP. +.RE +.PD +.PP +If the \fBextglob\fP shell option is enabled using the \fBshopt\fP +builtin, several extended pattern matching operators are recognized. +In the following description, a \fIpattern-list\fP is a list of one +or more patterns separated by a \fB|\fP. +Composite patterns may be formed using one or more of the following +sub-patterns: +.sp 1 +.PD 0 +.RS +.TP +\fB?(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches zero or one occurrence of the given patterns +.TP +\fB*(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches zero or more occurrences of the given patterns +.TP +\fB+(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches one or more occurrences of the given patterns +.TP +\fB@(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches one of the given patterns +.TP +\fB!(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches anything except one of the given patterns +.RE +.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 following the redirection operator in the following +descriptions, unless otherwise noted, is subjected to brace expansion, +tilde expansion, parameter expansion, command substitution, arithmetic +expansion, quote removal, pathname expansion, and word splitting. +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 . +.PP +\fBBash\fP handles several filenames specially when they are used in +redirections, as described in the following table: +.RS +.PP +.PD 0 +.TP +.B /dev/fd/\fIfd\fP +If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated. +.TP +.B /dev/stdin +File descriptor 0 is duplicated. +.TP +.B /dev/stdout +File descriptor 1 is duplicated. +.TP +.B /dev/stderr +File descriptor 2 is duplicated. +.TP +.B /dev/tcp/\fIhost\fP/\fIport\fP +If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP +is an integer port number or service name, \fBbash\fP attempts to open +a TCP connection to the corresponding socket. +.TP +.B /dev/udp/\fIhost\fP/\fIport\fP +If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP +is an integer port number or service name, \fBbash\fP attempts to open +a UDP connection to the corresponding socket. +.PD +.RE +.PP +A failure to open or create a file causes the redirection to fail. +.PP +Redirections using file descriptors greater than 9 should be used with +care, as they may conflict with file descriptors the shell uses +internally. +.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 noclobber +option to the +.B set +builtin has been enabled, the redirection will fail if the file +whose name results from the expansion of \fIword\fP exists and is +a regular file. +If the redirection operator is +.BR >| , +or the redirection operator is +.B > +and the +.B noclobber +option to the +.B set +builtin command is not enabled, 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: +.RS +.PP +.nf +\fB<<\fP[\fB\-\fP]\fIword\fP + \fIhere-document\fP +\fIdelimiter\fP +.fi +.RE +.PP +No parameter expansion, command substitution, arithmetic expansion, +or pathname 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. +If \fIword\fP is unquoted, +all lines of the here-document are subjected to parameter expansion, +command substitution, and arithmetic expansion. In the latter +case, the character sequence +.B \e +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 "Here Strings" +A variant of here documents, the format is: +.RS +.PP +.nf +\fB<<<\fP\fIword\fP +.fi +.RE +.PP +The \fIword\fP is expanded and supplied to the command on its standard +input. +.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 the digits in +.I word +do not specify a file descriptor open for input, a redirection error occurs. +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. +If the digits in +.I word +do not specify a file descriptor open for output, a redirection error occurs. +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 "Moving File Descriptors" +.PP +The redirection operator +.RS +.PP +[\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP +.RE +.PP +moves the file descriptor \fIdigit\fP to file descriptor +.IR n , +or the standard input (file descriptor 0) if \fIn\fP is not specified. +\fIdigit\fP is closed after being duplicated to \fIn\fP. +.PP +Similarly, the redirection operator +.RS +.PP +[\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP +.RE +.PP +moves the file descriptor \fIdigit\fP to file descriptor +.IR n , +or the standard output (file descriptor 1) if \fIn\fP is not specified. +.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 +\fIAliases\fP allow a string to be substituted for a word when it is used +as the first word of a simple command. +The shell maintains a list of 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 simple 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 characters \fB/\fP, \fB$\fP, \fB`\fP, and \fB=\fP and +any of the shell \fImetacharacters\fP or quoting characters +listed above may not appear in an alias name. +The replacement text may contain any valid shell input, +including shell metacharacters. +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 (see +.SM +.B FUNCTIONS +below). +.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 a 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 +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. +When the name of a shell function is used as a simple command name, +the list of commands associated with that function name is executed. +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. Special parameter 0 +is unchanged. +The first element of the +.SM +.B FUNCNAME +variable is set to the name of the function while the function +is executing. +All other aspects of the shell execution +environment are identical between a function and its caller +with the exception that the +.SM +.B DEBUG +and +.B RETURN +traps (see the description of the +.B trap +builtin under +.SM +.B SHELL BUILTIN COMMANDS +below) are not inherited unless the function has been given the +\fBtrace\fP attribute (see the description of the +.SM +.B declare +builtin below) or the +\fB\-o functrace\fP shell option has been enabled with +the \fBset\fP builtin +(in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps). +.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. +Any command associated with the \fBRETURN\fP trap is executed +before execution resumes. +When a function completes, the values of the +positional parameters and the special parameter +.B # +are restored to the values they had prior to the function's +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 +(and optionally the source file and line number, if the \fBextdebug\fP +shell option is enabled). +Functions may be exported so that subshells +automatically have them defined with the +.B \-f +option to the +.B export +builtin. +Note that shell functions and variables with the same name may result +in multiple identically-named entries in the environment passed to the +shell's children. +Care should be taken in cases where this may cause a problem. +.PP +Functions may be recursive. No limit is imposed on the number +of recursive calls. +.SH "ARITHMETIC EVALUATION" +The shell allows arithmetic expressions to be evaluated, under +certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin +commands and \fBArithmetic Expansion\fP). +Evaluation is done in fixed-width integers with no check for overflow, +though division by 0 is trapped and flagged as an error. +The operators and their precedence, associativity, and values +are the same as in the C language. +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 \fIid\fP++ \fIid\fP\-\- +variable post-increment and post-decrement +.TP +.B ++\fIid\fP \-\-\fIid\fP +variable pre-increment and pre-decrement +.TP +.B \- + +unary minus and plus +.TP +.B ! ~ +logical and bitwise negation +.TP +.B ** +exponentiation +.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 operator +.TP +.B = *= /= %= += \-= <<= >>= &= ^= |= +assignment +.TP +.B \fIexpr1\fP , \fIexpr2\fP +comma +.PD +.PP +Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. +Within an expression, shell variables may also be referenced by name +without using the parameter expansion syntax. +A shell variable that is null or unset evaluates to 0 when referenced +by name without using the parameter expansion syntax. +The value of a variable is evaluated as an arithmetic expression +when it is referenced, or when a variable which has been given the +\fIinteger\fP attribute using \fBdeclare -i\fP is assigned a value. +A null value evaluates to 0. +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 interchangeably 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 "CONDITIONAL EXPRESSIONS" +Conditional expressions are used by the \fB[[\fP compound command and +the \fBtest\fP and \fB[\fP builtin commands to test file attributes +and perform string and arithmetic comparisons. +Expressions are formed from the following unary or binary primaries. +If any \fIfile\fP argument to one of the primaries is of the form +\fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked. +If the \fIfile\fP argument to one of the primaries is one of +\fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file +descriptor 0, 1, or 2, respectively, is checked. +.PP +Unless otherwise specified, primaries that operate on files follow symbolic +links and operate on the target of the link, rather than the link itself. +.sp 1 +.PD 0 +.TP +.B \-a \fIfile\fP +True if \fIfile\fP exists. +.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 \-h \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP +.B \-k \fIfile\fP +True if \fIfile\fP exists and its ``sticky'' bit is set. +.TP +.B \-p \fIfile\fP +True if \fIfile\fP exists and is a named pipe (FIFO). +.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 \-t \fIfd\fP +True if file descriptor +.I fd +is open and refers to 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 +.B \-L \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP +.B \-S \fIfile\fP +True if \fIfile\fP exists and is a socket. +.TP +.B \-N \fIfile\fP +True if \fIfile\fP exists and has been modified since it was last read. +.TP +\fIfile1\fP \-\fBnt\fP \fIfile2\fP +True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP, +or if \fIfile1\fP exists and \fPfile2\fP does not. +.TP +\fIfile1\fP \-\fBot\fP \fIfile2\fP +True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists +and \fIfile1\fP does not. +.TP +\fIfile1\fP \fB\-ef\fP \fIfile2\fP +True if \fIfile1\fP and \fIfile2\fP refer to 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 below. +.TP +.B \-z \fIstring\fP +True if the length of \fIstring\fP is zero. +.TP +\fIstring\fP +.PD 0 +.TP +.B \-n \fIstring\fP +.PD +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 for strict POSIX compliance. +.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 +in the current locale. +.TP +\fIstring1\fP \fB>\fP \fIstring2\fP +True if \fIstring1\fP sorts after \fIstring2\fP lexicographically +in the current locale. +.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 +.SH "SIMPLE COMMAND EXPANSION" +When a simple command is executed, the shell performs the following +expansions, assignments, and redirections, from left to right. +.IP 1. +The words that the parser has marked as variable assignments (those +preceding the command name) and redirections are saved for later +processing. +.IP 2. +The words that are not variable assignments or redirections are +expanded. If any words remain after expansion, the first word +is taken to be the name of the command and the remaining words are +the arguments. +.IP 3. +Redirections are performed as described above under +.SM +.BR REDIRECTION . +.IP 4. +The text after the \fB=\fP in each variable assignment undergoes tilde +expansion, parameter expansion, command substitution, arithmetic expansion, +and quote removal before being assigned to the variable. +.PP +If no command name results, the variable assignments affect the current +shell environment. Otherwise, the variables are added to the environment +of the executed command and do not affect the current shell environment. +If any of the assignments attempts to assign a value to a readonly variable, +an error occurs, and the command exits with a non-zero status. +.PP +If no command name results, redirections are performed, but do not +affect the current shell environment. A redirection error causes the +command to exit with a non-zero status. +.PP +If there is a command name left after expansion, execution proceeds as +described below. Otherwise, the command exits. If one of the expansions +contained a command substitution, the exit status of the command is +the exit status of the last command substitution performed. If there +were no command substitutions, the command exits with a status of zero. +.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 pathnames 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 an exit status of 127. +.PP +If the search is successful, or if the command name contains +one or more slashes, the shell executes the named program in a +separate execution environment. +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 COMMAND EXECUTION ENVIRONMENT +The shell has an \fIexecution environment\fP, which consists of the +following: +.sp 1 +.IP \(bu +open files inherited by the shell at invocation, as modified by +redirections supplied to the \fBexec\fP builtin +.IP \(bu +the current working directory as set by \fBcd\fP, \fBpushd\fP, or +\fBpopd\fP, or inherited by the shell at invocation +.IP \(bu +the file creation mode mask as set by \fBumask\fP or inherited from +the shell's parent +.IP \(bu +current traps set by \fBtrap\fP +.IP \(bu +shell parameters that are set by variable assignment or with \fBset\fP +or inherited from the shell's parent in the environment +.IP \(bu +shell functions defined during execution or inherited from the shell's +parent in the environment +.IP \(bu +options enabled at invocation (either by default or with command-line +arguments) or by \fBset\fP +.IP \(bu +options enabled by \fBshopt\fP +.IP \(bu +shell aliases defined with \fBalias\fP +.IP \(bu +various process IDs, including those of background jobs, the value +of \fB$$\fP, and the value of \fB$PPID\fP +.PP +When a simple command other than a builtin or shell function +is to be executed, it +is invoked in a separate execution environment that consists of +the following. Unless otherwise noted, the values are inherited +from the shell. +.sp 1 +.IP \(bu +the shell's open files, plus any modifications and additions specified +by redirections to the command +.IP \(bu +the current working directory +.IP \(bu +the file creation mode mask +.IP \(bu +shell variables and functions marked for export, along with variables +exported for the command, passed in the environment +.IP \(bu +traps caught by the shell are reset to the values inherited from the +shell's parent, and traps ignored by the shell are ignored +.PP +A command invoked in this separate environment cannot affect the +shell's execution environment. +.PP +Command substitution, commands grouped with parentheses, +and asynchronous commands are invoked in a +subshell environment that is a duplicate of the shell environment, +except that traps caught by the shell are reset to the values +that the shell inherited from its parent at invocation. Builtin +commands that are invoked as part of a pipeline are also executed in a +subshell environment. Changes made to the subshell environment +cannot affect the shell's execution environment. +.PP +If a command is followed by a \fB&\fP and job control is not active, the +default standard input for the command is the empty file \fI/dev/null\fP. +Otherwise, the invoked command inherits the file descriptors of the calling +shell as modified by redirections. +.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 provides several ways to manipulate the environment. +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 +option 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 shell's purposes, 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 \fIN\fP, \fBbash\fP uses +the value of 128+\fIN\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 +If a command fails because of an error during expansion or redirection, +the exit status is greater than zero. +.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, in the absence of any traps, 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 +Non-builtin commands run by \fBbash\fP have signal handlers +set to the values inherited by the shell from its parent. +When job control is not in effect, asynchronous commands +ignore +.SM +.B SIGINT +and +.SM +.B SIGQUIT +in addition to these inherited handlers. +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, an interactive shell resends the +.SM +.B SIGHUP +to all jobs, running or stopped. +Stopped jobs are sent +.SM +.B SIGCONT +to ensure that they receive the +.SM +.BR SIGHUP . +To prevent the shell from +sending the signal to a particular job, it should be removed from the +jobs table with the +.B disown +builtin (see +.SM +.B "SHELL BUILTIN COMMANDS" +below) or marked +to not receive +.SM +.B SIGHUP +using +.BR "disown \-h" . +.PP +If the +.B huponexit +shell option has been set with +.BR shopt , +.B bash +sends a +.SM +.B SIGHUP +to all jobs when an interactive login shell exits. +.PP +If \fBbash\fP is waiting for a command to complete and receives a signal +for which a trap has been set, the trap will not be executed until +the command completes. +When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP +builtin, the reception of a signal for which a trap has been set will +cause the \fBwait\fP builtin to return immediately with an exit status +greater than 128, immediately after which the trap is executed. +.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 operating 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 +contains facilities 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 control 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 . +The user 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 or started in the background. +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 \- . +A single % (with no accompanying job specification) also refers to the +current job. +.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 enabled, +.B bash +reports such changes immediately. +Any trap on +.SM +.B SIGCHLD +is executed for each child that exits. +.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 \eD{\fIformat\fP} +the \fIformat\fP is passed to \fIstrftime\fP(3) and the result is inserted +into the prompt string; an empty \fIformat\fP results in a locale-specific +time representation. The braces are required +.TP +.B \ee +an ASCII escape character (033) +.TP +.B \eh +the hostname up to the first `.' +.TP +.B \eH +the hostname +.TP +.B \ej +the number of jobs currently managed by the shell +.TP +.B \el +the basename of the shell's terminal device name +.TP +.B \en +newline +.TP +.B \er +carriage return +.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 \eA +the current time in 24-hour HH:MM 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 + patch level (e.g., 2.00.0) +.TP +.B \ew +the current working directory, with \fB$HOME\fP abbreviated with a tilde +.TP +.B \eW +the basename of the current working directory, with \fB$HOME\fP +abbreviated with a tilde +.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, 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 . +.PP +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. +.PP +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 +.if t \f(CW> output\fP +.if n ``> 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, but the symbolic character names +are not recognized. +.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 +.if t \f(CWFunction Key 1\fP. +.if n ``Function Key 1''. +.PP +The full set of GNU Emacs style escape sequences is +.RS +.PD 0 +.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 +.PD +.PP +In addition to the GNU Emacs style escape sequences, a second +set of backslash escapes is available: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ed +delete +.TP +.B \ef +form feed +.TP +.B \en +newline +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(one to three digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.RE +.PD +.PP +When entering the text of a macro, single or double quotes must +be used to indicate a macro definition. +Unquoted text is assumed to be a function name. +In the macro body, the backslash escapes described above are expanded. +Backslash will quote any other 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 +.B Off +(without regard to case). +Unrecognized variable names are ignored. +When a variable value is read, empty or null values, "on" (case-insensitive), +and "1" are equivalent to \fBOn\fP. All other values are equivalent to +\fBOff\fP. +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 bind\-tty\-special\-chars (On) +If set to \fBOn\fP, readline attempts to bind the control characters +treated specially by the kernel's terminal driver to their readline +equivalents. +.TP +.B comment\-begin (``#'') +The string that is inserted when the 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\-ignore\-case (Off) +If set to \fBOn\fP, readline performs filename matching and completion +in a case\-insensitive fashion. +.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 prefixing 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 history\-preserve\-point (Off) +If set to \fBon\fP, the history code attempts to place point at the +same location on each history line retrieved with \fBprevious-history\fP +or \fBnext-history\fP. +.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 isearch\-terminators (``C\-[C\-J'') +The string of characters that should terminate an incremental +search without subsequently executing the character as a command. +If this variable has not been given a value, the characters +\fIESC\fP and \fIC\-J\fP will terminate an incremental search. +.TP +.B keymap (emacs) +Set the current readline keymap. The set of valid 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 mark\-symlinked\-directories (Off) +If set to \fBOn\fP, completed names which are symbolic links to directories +have a slash appended (subject to the value of +\fBmark\-directories\fP). +.TP +.B match\-hidden\-files (On) +This variable, when set to \fBOn\fP, causes readline to match files whose +names begin with a `.' (hidden files) when performing filename +completion, unless the leading `.' is +supplied by the user in the filename to be completed. +.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 page\-completions (On) +If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager +to display a screenful of possible completions at a time. +.TP +.B print\-completions\-horizontally (Off) +If set to \fBOn\fP, readline will display completions with matches +sorted horizontally in alphabetical order, rather than down the screen. +.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 show\-all\-if\-unmodified (Off) +This alters the default behavior of the completion functions in +a fashion similar to \fBshow\-all\-if\-ambiguous\fP. +If set to +.BR on , +words which have more than one possible completion without any +possible partial completion (the possible completions don't share +a common prefix) 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 four 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 both 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: +.sp 1 +.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 seen 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. +.IP \fB$include\fP +This directive takes a single filename as an argument and reads commands +and bindings from that file. For example, the following directive +would read \fI/etc/inputrc\fP: +.sp 1 +.RS +.nf +\fB$include\fP \^ \fI/etc/inputrc\fP +.fi +.RE +.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 characters present in the value of the \fBisearch-terminators\fP +variable are used to terminate an incremental search. +If that variable has not been assigned a value the Escape and +Control-J characters will terminate an incremental 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. +.PP +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 +Readline remembers the last incremental search string. If two +Control-Rs are typed without any intervening characters defining a +new search string, any remembered search string is used. +.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 be 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. +In the following descriptions, \fIpoint\fP refers to the current cursor +position, and \fImark\fP refers to a cursor position saved by the +\fBset\-mark\fP command. +The text between the point and mark is referred to as the \fIregion\fP. +.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 the current or 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 point. +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. +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. +Once the argument \fIn\fP is computed, the argument is extracted +as if the "!\fIn\fP" history expansion had been specified. +.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. +Successive calls to \fByank\-last\-arg\fP move back through the history +list, inserting the last argument of each line in turn. +The history expansion facilities are used to extract the last argument, +as if the "!$" history expansion had been specified. +.TP +.B shell\-expand\-line (M\-C\-e) +Expand the line as the shell does. 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 magic\-space +Perform history expansion on the current line and insert a space. +See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B alias\-expand\-line +Perform alias expansion on the current line. +See +.SM +.B ALIASES +above for a description of alias expansion. +.TP +.B history\-and\-alias\-expand\-line +Perform history and alias expansion on the current line. +.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. +.TP +.B edit\-and\-execute\-command (C\-xC\-e) +Invoke an editor on the current command line, and execute the result as shell +commands. +\fBBash\fP attempts to invoke +.SM +.BR $FCEDIT , +.SM +.BR $EDITOR , +and \fIemacs\fP as the editor, in that order. +.PD +.SS Commands for Changing Text +.PP +.PD 0 +.TP +.B delete\-char (C\-d) +Delete the character at point. If point is at the +beginning of the line, there are no characters in the line, and +the last character typed was not bound to \fBdelete\-char\fP, +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 forward\-backward\-delete\-char +Delete the character under the cursor, unless the cursor is at the +end of the line, in which case the character behind the cursor is +deleted. +.TP +.B quoted\-insert (C\-q, C\-v) +Add the next character typed 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, +moving point forward as well. +If point is at the end of the line, then this transposes +the two characters before point. +Negative arguments have no effect. +.TP +.B transpose\-words (M\-t) +Drag the word before point past the word after point, +moving point over that word as well. +If point is at the end of the line, this transposes +the last two words on the line. +.TP +.B upcase\-word (M\-u) +Uppercase the current (or following) word. With a negative argument, +uppercase the previous word, but do not move point. +.TP +.B downcase\-word (M\-l) +Lowercase the current (or following) word. With a negative argument, +lowercase the previous word, but do not move point. +.TP +.B capitalize\-word (M\-c) +Capitalize the current (or following) word. With a negative argument, +capitalize the previous word, but do not move point. +.TP +.B overwrite\-mode +Toggle overwrite mode. With an explicit positive numeric argument, +switches to overwrite mode. With an explicit non-positive numeric +argument, switches to insert mode. This command affects only +\fBemacs\fP mode; \fBvi\fP mode does overwrite differently. +Each call to \fIreadline()\fP starts in insert mode. +In overwrite mode, characters bound to \fBself\-insert\fP replace +the text at point rather than pushing the text to the right. +Characters bound to \fBbackward\-delete\-char\fP replace the character +before point with a space. By default, this command is unbound. +.PD +.SS Killing and Yanking +.PP +.PD 0 +.TP +.B kill\-line (C\-k) +Kill the text from point 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. +The killed text is saved on the kill-ring. +.\" 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 point is. +.TP +.B kill\-word (M\-d) +Kill from point 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 point. +Word boundaries are the same as those used by \fBbackward\-word\fP. +.TP +.B unix\-word\-rubout (C\-w) +Kill the word behind point, using white space as a word boundary. +The killed text is saved on the kill-ring. +.TP +.B unix\-filename\-rubout +Kill the word behind point, using white space and the slash character +as the word boundaries. +The killed text is saved on the kill-ring. +.TP +.B delete\-horizontal\-space (M\-\e) +Delete all spaces and tabs around point. +.TP +.B kill\-region +Kill the text in the current region. +.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. +The word boundaries are the same as \fBbackward\-word\fP. +.TP +.B copy\-forward\-word +Copy the word following point to the kill buffer. +The word boundaries are the same as \fBforward\-word\fP. +.TP +.B yank (C\-y) +Yank the top of the kill ring into the buffer at point. +.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 +This is another way to specify an argument. +If this command is followed by one or more digits, optionally with a +leading minus sign, those digits define the argument. +If the command is followed by digits, executing +.B universal\-argument +again ends the numeric argument, but is otherwise ignored. +As a special case, if this command is immediately followed by a +character that is neither a digit or minus sign, the argument count +for the next command is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four, a second time makes the +argument count sixteen, and so on. +.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 menu\-complete +Similar to \fBcomplete\fP, but replaces the word to be completed +with a single match from the list of possible completions. +Repeated execution of \fBmenu\-complete\fP steps through the list +of possible completions, inserting each match in turn. +At the end of the list of completions, the bell is rung +(subject to the setting of \fBbell\-style\fP) +and the original text is restored. +An argument of \fIn\fP moves \fIn\fP positions forward in the list +of matches; a negative argument may be used to move backward +through the list. +This command is intended to be bound to \fBTAB\fP, but is unbound +by default. +.TP +.B delete\-char\-or\-list +Deletes the character under the cursor if not at the beginning or +end of the line (like \fBdelete\-char\fP). +If at the end of the line, behaves identically to +\fBpossible\-completions\fP. +This command is unbound by default. +.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, shell 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 insert 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 executing 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\-) +Set the mark to the 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\-#) +Without a numeric argument, the value of the readline +.B comment\-begin +variable is inserted at the beginning of the current line. +If a numeric argument is supplied, this command acts as a toggle: if +the characters at the beginning of the line do not match the value +of \fBcomment\-begin\fP, the value is inserted, otherwise +the characters in \fBcomment-begin\fP are deleted from the beginning of +the line. +In either case, the line is accepted as if a newline had been typed. +The default value of +\fBcomment\-begin\fP causes this command to make the current line +a shell comment. +If a numeric argument causes the comment character to be removed, the line +will be executed by the shell. +.TP +.B glob\-complete\-word (M\-g) +The word before point is treated as a pattern for pathname expansion, +with an asterisk implicitly appended. This pattern is used to +generate a list of matching file names for possible completions. +.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. +If a numeric argument is supplied, an asterisk is appended before +pathname expansion. +.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. +If a numeric argument is supplied, an asterisk is appended before +pathname expansion. +.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 output. 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 +.SS Programmable Completion +.PP +When word completion is attempted for an argument to a command for +which a completion specification (a \fIcompspec\fP) has been defined +using the \fBcomplete\fP builtin (see +.SM +.B "SHELL BUILTIN COMMANDS" +below), the programmable completion facilities are invoked. +.PP +First, the command name is identified. +If a compspec has been defined for that command, the +compspec is used to generate the list of possible completions for the word. +If the command word is a full pathname, a compspec for the full +pathname is searched for first. +If no compspec is found for the full pathname, an attempt is made to +find a compspec for the portion following the final slash. +.PP +Once a compspec has been found, it is used to generate the list of +matching words. +If a compspec is not found, the default \fBbash\fP completion as +described above under \fBCompleting\fP is performed. +.PP +First, the actions specified by the compspec are used. +Only matches which are prefixed by the word being completed are +returned. +When the +.B \-f +or +.B \-d +option is used for filename or directory name completion, the shell +variable +.SM +.B FIGNORE +is used to filter the matches. +.PP +Any completions specified by a filename expansion pattern to the +\fB\-G\fP option are generated next. +The words generated by the pattern need not match the word +being completed. +The +.SM +.B GLOBIGNORE +shell variable is not used to filter the matches, but the +.SM +.B FIGNORE +variable is used. +.PP +Next, the string specified as the argument to the \fB\-W\fP option +is considered. +The string is first split using the characters in the +.SM +.B IFS +special variable as delimiters. +Shell quoting is honored. +Each word is then expanded using +brace expansion, tilde expansion, parameter and variable expansion, +command substitution, and arithmetic expansion, +as described above under +.SM +.BR EXPANSION . +The results are split using the rules described above under +\fBWord Splitting\fP. +The results of the expansion are prefix-matched against the word being +completed, and the matching words become the possible completions. +.PP +After these matches have been generated, any shell function or command +specified with the \fB\-F\fP and \fB\-C\fP options is invoked. +When the command or function is invoked, the +.SM +.B COMP_LINE +and +.SM +.B COMP_POINT +variables are assigned values as described above under +\fBShell Variables\fP. +If a shell function is being invoked, the +.SM +.B COMP_WORDS +and +.SM +.B COMP_CWORD +variables are also set. +When the function or command is invoked, the first argument is the +name of the command whose arguments are being completed, the +second argument is the word being completed, and the third argument +is the word preceding the word being completed on the current command line. +No filtering of the generated completions against the word being completed +is performed; the function or command has complete freedom in generating +the matches. +.PP +Any function specified with \fB\-F\fP is invoked first. +The function may use any of the shell facilities, including the +\fBcompgen\fP builtin described below, to generate the matches. +It must put the possible completions in the +.SM +.B COMPREPLY +array variable. +.PP +Next, any command specified with the \fB\-C\fP option is invoked +in an environment equivalent to command substitution. +It should print a list of completions, one per line, to the +standard output. +Backslash may be used to escape a newline, if necessary. +.PP +After all of the possible completions are generated, any filter +specified with the \fB\-X\fP option is applied to the list. +The filter is a pattern as used for pathname expansion; a \fB&\fP +in the pattern is replaced with the text of the word being completed. +A literal \fB&\fP may be escaped with a backslash; the backslash +is removed before attempting a match. +Any completion that matches the pattern will be removed from the list. +A leading \fB!\fP negates the pattern; in this case any completion +not matching the pattern will be removed. +.PP +Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP +options are added to each member of the completion list, and the result is +returned to the readline completion code as the list of possible +completions. +.PP +If the previously-applied actions do not generate any matches, and the +\fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the +compspec was defined, directory name completion is attempted. +.PP +If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the +compspec was defined, directory name completion is attempted and any +matches are added to the results of the other actions. +.PP +By default, if a compspec is found, whatever it generates is returned +to the completion code as the full set of possible completions. +The default \fBbash\fP completions are not attempted, and the readline +default of filename completion is disabled. +If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when +the compspec was defined, the \fBbash\fP default completions are attempted +if the compspec generates no matches. +If the \fB\-o default\fP option was supplied to \fBcomplete\fP when the +compspec was defined, readline's default completion will be performed +if the compspec (and, if attempted, the default \fBbash\fP completions) +generate no matches. +.PP +When a compspec indicates that directory name completion is desired, +the programmable completion functions force readline to append a slash +to completed names which are symbolic links to directories, subject to +the value of the \fBmark\-directories\fP readline variable, regardless +of the setting of the \fBmark-symlinked\-directories\fP readline variable. +.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 value of the \fBHISTSIZE\fP variable is used as the +number of commands to save in a history list. +The text of the last +.SM +.B HISTSIZE +commands (default 500) is saved. 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 . +.PP +On startup, the history is initialized from the file named by +the variable +.SM +.B HISTFILE +(default \fI~/.bash_history\fP). +The file named by the value of +.SM +.B HISTFILE +is truncated, if necessary, to contain no more than +the number of lines specified by the value of +.SM +.BR HISTFILESIZE . +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 may be used to display or modify the history list and +manipulate the history file. +When using 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 history list +to use during substitution. +The second is to select portions of that line for inclusion into +the current one. +The line selected from the 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 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 characters inhibit history expansion if found immediately +following the history expansion character, even if it is unquoted: +space, tab, newline, carriage return, and \fB=\fP. +If the \fBextglob\fP shell option is enabled, \fB(\fP will also +inhibit expansion. +.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, carriage return, = +or ( (when the \fBextglob\fP shell option is enabled using +the \fBshopt\fP builtin). +.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 may 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. +An \fBa\fP may be used as a synonym for \fBg\fP. +.TP +.B G +Apply the following `\fBs\fP' modifier once to each word in the event line. +.PD +.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. +For example, the \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP builtins +do not accept 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 +\fB .\| \fP \fIfilename\fP [\fIarguments\fP] +.PD 0 +.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. +When \fBbash\fP is not in \fIposix mode\fP, 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 or cannot be read. +.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 ...] +Resume each suspended job \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, any specified \fIjobspec\fP was not found +or was started without job control. +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSV\fP] +.PD 0 +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\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] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP +.TP +\fBbind\fP \fIreadline\-command\fP +.PD +Display current +.B readline +key and function bindings, bind a key sequence to a +.B readline +function or macro, or set a +.B readline +variable. +Each non-option argument is a command as it would appear in +.IR .inputrc , +but each binding or command 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\-move, 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 \-u \fIfunction\fP +Unbind all keys bound to the named \fIfunction\fP. +.TP +.B \-r \fIkeyseq\fP +Remove any current binding for \fIkeyseq\fP. +.TP +.B \-x \fIkeyseq\fP:\fIshell\-command\fP +Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is +entered. +.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 defining a +function whose name is the same as a shell builtin, +retaining the functionality of the builtin within the function. +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\-L|-P\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 . +If a non-empty directory name from \fBCDPATH\fP is used, or if +\fB\-\fP is the first argument, and the directory change is +successful, the absolute pathname of the new working directory is +written to the standard output. +The return value is true if the directory was successfully changed; +false otherwise. +.TP +\fBcaller\fP [\fIexpr\fP] +Returns the context of any active subroutine call (a shell function or +a script executed with the \fB.\fP or \fBsource\fP builtins. +Without \fIexpr\fP, \fBcaller\fP displays the line number and source +filename of the current subroutine call. +If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP +displays the line number, subroutine name, and source file corresponding +to that position in the current execution call stack. This extra +information may be used, for example, to print a stack trace. The +current frame is frame 0. +The return value is 0 unless the shell is not executing a subroutine +call or \fIexpr\fP does not correspond to a valid position in the +call stack. +.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 displayed; 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 +\fBcompgen\fP [\fIoption\fP] [\fIword\fP] +Generate possible completion matches for \fIword\fP according to +the \fIoption\fPs, which may be any option accepted by the +.B complete +builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write +the matches to the standard output. +When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables +set by the programmable completion facilities, while available, will not +have useful values. +.sp 1 +The matches will be generated in the same way as if the programmable +completion code had generated them directly from a completion specification +with the same flags. +If \fIword\fP is specified, only those completions matching \fIword\fP +will be displayed. +.sp 1 +The return value is true unless an invalid option is supplied, or no +matches were generated. +.TP +\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] +.br +[\fB\-X\fP \fIfilterpat\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] \fIname\fP [\fIname ...\fP] +.PD 0 +.TP +\fBcomplete\fP \fB\-pr\fP [\fIname\fP ...] +.PD +Specify how arguments to each \fIname\fP should be completed. +If the \fB\-p\fP option is supplied, or if no options are supplied, +existing completion specifications are printed in a way that allows +them to be reused as input. +The \fB\-r\fP option removes a completion specification for +each \fIname\fP, or, if no \fIname\fPs are supplied, all +completion specifications. +.sp 1 +The process of applying these completion specifications when word completion +is attempted is described above under \fBProgrammable Completion\fP. +.sp 1 +Other options, if specified, have the following meanings. +The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options +(and, if necessary, the \fB\-P\fP and \fB\-S\fP options) +should be quoted to protect them from expansion before the +.B complete +builtin is invoked. +.RS +.PD 0 +.TP 8 +\fB\-o\fP \fIcomp-option\fP +The \fIcomp-option\fP controls several aspects of the compspec's behavior +beyond the simple generation of completions. +\fIcomp-option\fP may be one of: +.RS +.TP 8 +.B bashdefault +Perform the rest of the default \fBbash\fP completions if the compspec +generates no matches. +.TP 8 +.B default +Use readline's default filename completion if the compspec generates +no matches. +.TP 8 +.B dirnames +Perform directory name completion if the compspec generates no matches. +.TP 8 +.B filenames +Tell readline that the compspec generates filenames, so it can perform any +filename\-specific processing (like adding a slash to directory names or +suppressing trailing spaces). Intended to be used with shell functions. +.TP 8 +.B nospace +Tell readline not to append a space (the default) to words completed at +the end of the line. +.TP 8 +.B plusdirs +After any matches defined by the compspec are generated, +directory name completion is attempted and any +matches are added to the results of the other actions. +.RE +.TP 8 +\fB\-A\fP \fIaction\fP +The \fIaction\fP may be one of the following to generate a list of possible +completions: +.RS +.TP 8 +.B alias +Alias names. May also be specified as \fB\-a\fP. +.TP 8 +.B arrayvar +Array variable names. +.TP 8 +.B binding +\fBReadline\fP key binding names. +.TP 8 +.B builtin +Names of shell builtin commands. May also be specified as \fB\-b\fP. +.TP 8 +.B command +Command names. May also be specified as \fB\-c\fP. +.TP 8 +.B directory +Directory names. May also be specified as \fB\-d\fP. +.TP 8 +.B disabled +Names of disabled shell builtins. +.TP 8 +.B enabled +Names of enabled shell builtins. +.TP 8 +.B export +Names of exported shell variables. May also be specified as \fB\-e\fP. +.TP 8 +.B file +File names. May also be specified as \fB\-f\fP. +.TP 8 +.B function +Names of shell functions. +.TP 8 +.B group +Group names. May also be specified as \fB\-g\fP. +.TP 8 +.B helptopic +Help topics as accepted by the \fBhelp\fP builtin. +.TP 8 +.B hostname +Hostnames, as taken from the file specified by the +.SM +.B HOSTFILE +shell variable. +.TP 8 +.B job +Job names, if job control is active. May also be specified as \fB\-j\fP. +.TP 8 +.B keyword +Shell reserved words. May also be specified as \fB\-k\fP. +.TP 8 +.B running +Names of running jobs, if job control is active. +.TP 8 +.B service +Service names. May also be specified as \fB\-s\fP. +.TP 8 +.B setopt +Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin. +.TP 8 +.B shopt +Shell option names as accepted by the \fBshopt\fP builtin. +.TP 8 +.B signal +Signal names. +.TP 8 +.B stopped +Names of stopped jobs, if job control is active. +.TP 8 +.B user +User names. May also be specified as \fB\-u\fP. +.TP 8 +.B variable +Names of all shell variables. May also be specified as \fB\-v\fP. +.RE +.TP 8 +\fB\-G\fP \fIglobpat\fP +The filename expansion pattern \fIglobpat\fP is expanded to generate +the possible completions. +.TP 8 +\fB\-W\fP \fIwordlist\fP +The \fIwordlist\fP is split using the characters in the +.SM +.B IFS +special variable as delimiters, and each resultant word is expanded. +The possible completions are the members of the resultant list which +match the word being completed. +.TP 8 +\fB\-C\fP \fIcommand\fP +\fIcommand\fP is executed in a subshell environment, and its output is +used as the possible completions. +.TP 8 +\fB\-F\fP \fIfunction\fP +The shell function \fIfunction\fP is executed in the current shell +environment. +When it finishes, the possible completions are retrieved from the value +of the +.SM +.B COMPREPLY +array variable. +.TP 8 +\fB\-X\fP \fIfilterpat\fP +\fIfilterpat\fP is a pattern as used for filename expansion. +It is applied to the list of possible completions generated by the +preceding options and arguments, and each completion matching +\fIfilterpat\fP is removed from the list. +A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this +case, any completion not matching \fIfilterpat\fP is removed. +.TP 8 +\fB\-P\fP \fIprefix\fP +\fIprefix\fP is added at the beginning of each possible completion +after all other options have been applied. +.TP 8 +\fB\-S\fP \fIsuffix\fP +\fIsuffix\fP is appended to each possible completion +after all other options have been applied. +.PD +.PP +The return value is true unless an invalid option is supplied, an option +other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP +argument, an attempt is made to remove a completion specification for +a \fIname\fP for which no specification exists, or +an error occurs adding a completion specification. +.RE +.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 +\fBdeclare\fP [\fB\-afFirtx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +.PD 0 +.TP +\fBtypeset\fP [\fB\-afFirtx\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. +If the \fBextdebug\fP shell option is enabled using \fBshopt\fP, +the source file name and line number where the function is defined +are displayed as well. 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 or unset. +.TP +.B \-t +Give each \fIname\fP the \fItrace\fP attribute. +Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from +the calling shell. +The trace attribute has no special meaning for variables. +.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. +If a variable name is followed by =\fIvalue\fP, the value of +the variable is set to \fIvalue\fP. +The return value is 0 unless an invalid option is encountered, +an attempt is made to define a function using +.if n ``\-f foo=bar'', +.if t \f(CW\-f foo=bar\fP, +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 valid 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 \fB\-f\fP. +.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 +invalid option is supplied or \fIn\fP indexes beyond the end +of the directory stack. +.RE +.TP +\fBdisown\fP [\fB\-ar\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, each +.I jobspec +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, and neither the +.B \-a +nor the +.B \-r +option is supplied, the \fIcurrent job\fP is used. +If no +.I jobspec +is supplied, the +.B \-a +option means to remove or mark all jobs; the +.B \-r +option without a +.I jobspec +argument restricts operation to running jobs. +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. +The \fBxpg_echo\fP shell option may be used to +dynamically determine whether or not \fBecho\fP expands these +escape characters by default. +.B echo +does not interpret \fB\-\-\fP 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 \e0\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(zero to three octal digits) +.TP +.B \e\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(one to three octal digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.PD +.RE +.TP +\fBenable\fP [\fB\-adnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...] +Enable and disable builtin shell commands. +Disabling a builtin allows a disk command which has the same name +as a shell builtin to be executed without specifying a full pathname, +even though the shell normally searches for builtins before disk commands. +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 +.if t \f(CWenable -n test\fP. +.if n ``enable -n test''. +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 an error 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 at the beginning of 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. If there is a redirection error, the +return status is 1. +.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 +\fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ... +.PD 0 +.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 each +\fIname\fP. +If a variable name is followed by =\fIword\fP, the value of +the variable is set to \fIword\fP. +.B export +returns an exit status of 0 unless an invalid option is +encountered, +one of the \fInames\fP is not a valid shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +\fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-nlr\fP] [\fIfirst\fP] [\fIlast\fP] +.PD 0 +.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 +.if n ``fc \-l \-10'' +.if t \f(CWfc \-l \-10\fP +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 +option suppresses +the command numbers when listing. The +.B \-r +option reverses the order of +the commands. If the +.B \-l +option 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 invalid +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] +Resume +.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 characters to be recognized; if a character +is followed by a colon, the option is expected to have an +argument, which should be separated from it by white space. +The colon and question mark characters may not be used as +option characters. +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 +When the end of options is encountered, \fBgetopts\fP exits with a +return value greater than zero. +\fBOPTIND\fP is set to the index of the first non-option argument, +and \fBname\fP is set to ?. +.sp 1 +.B getopts +normally parses the positional parameters, but if more arguments are +given in +.IR args , +.B getopts +parses those instead. +.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 invalid options or missing option arguments are +encountered. +If the variable +.SM +.B OPTERR +is set to 0, no error messages will be displayed, even if the first +character of +.I optstring +is not a colon. +.sp 1 +If an invalid 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 , +.SM +.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 +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\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\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. +The +.B \-d +option causes the shell to forget the remembered location of each \fIname\fP. +If the +.B \-t +option is supplied, the full pathname to which each \fIname\fP corresponds +is printed. If multiple \fIname\fP arguments are supplied with \fB\-t\fP, +the \fIname\fP is printed before the hashed full pathname. +The +.B \-l +option causes output to be displayed in a format that may be reused as input. +If no arguments are given, or if only \fB\-l\fP is supplied, +information about remembered commands is printed. +The return status is true unless a +.I name +is not found or an invalid option is supplied. +.TP +\fBhelp\fP [\fB\-s\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 \fB\-s\fP option restricts the information displayed to a short +usage synopsis. +The return status is 0 unless no command matches +.IR pattern . +.TP +\fBhistory [\fIn\fP] +.PD 0 +.TP +\fBhistory\fP \fB\-c\fP +.TP +\fBhistory \-d\fP \fIoffset\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 the shell variable \fBHISTTIMEFORMAT\fP is set and not null, +it is used as a format string for \fIstrftime\fP(3) to display +the time stamp associated with each displayed history entry. +No intervening blank is printed between the formatted time stamp +and the history line. +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 \-c +Clear the history list by deleting all the entries. +.TP +\fB\-d\fP \fIoffset\fP +Delete the history entry at position \fIoffset\fP. +.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 \-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 +If the \fBHISTTIMEFORMAT\fP is set, the time stamp information +associated with each history entry is written to the history file. +The return value is 0 unless an invalid option is encountered, an +error occurs while reading or writing the history file, an invalid +\fIoffset\fP is supplied as an argument to \fB\-d\fP, or the +history expansion supplied as an argument to \fB\-p\fP fails. +.RE +.TP +\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ] +.PD 0 +.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 invalid option is encountered +or an invalid +.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 +\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ... +.PD 0 +.TP +\fBkill\fP \fB\-l\fP [\fIsigspec\fP | \fIexit_status\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 case-insensitive signal name such as +.SM +.B SIGKILL +(with or without the +.SM +.B SIG +prefix) or a signal number; +.I signum +is a signal number. +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 signals corresponding to the arguments are +listed, and the return status is 0. +The \fIexit_status\fP argument to +.B \-l +is a number specifying either a signal number or the exit status of +a process terminated by a signal. +.B kill +returns true if at least one signal was successfully sent, or false +if an error occurs or an invalid 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 [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ...] +For each argument, a local variable named +.I name +is created, and assigned +.IR value . +The \fIoption\fP can be any of the options accepted by \fBdeclare\fP. +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, an invalid +.I name +is supplied, or +\fIname\fP is a readonly variable. +.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: +.if n ``popd +0'' +.if t \f(CWpopd +0\fP +removes the first directory, +.if n ``popd +1'' +.if t \f(CWpopd +1\fP +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: +.if n ``popd -0'' +.if t \f(CWpopd -0\fP +removes the last directory, +.if n ``popd -1'' +.if t \f(CWpopd -1\fP +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 invalid option is encountered, the directory stack +is empty, a non-existent directory stack entry is specified, or the +directory change fails. +.RE +.TP +\fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP] +Write the formatted \fIarguments\fP to the standard output under the +control of the \fIformat\fP. +The \fIformat\fP is a character string which contains three types of objects: +plain characters, which are simply copied to standard output, character +escape sequences, which are converted and copied to the standard output, and +format specifications, each of which causes printing of the next successive +\fIargument\fP. +In addition to the standard \fIprintf\fP(1) formats, \fB%b\fP causes +\fBprintf\fP to expand backslash escape sequences in the corresponding +\fIargument\fP (except that \fB\ec\fP terminates output, backslashes in +\fB\e'\fP, \fB\e"\fP, and \fB\e?\fP are not removed, and octal escapes +beginning with \fB\e0\fP may contain up to four digits), +and \fB%q\fP causes \fBprintf\fP to output the corresponding +\fIargument\fP in a format that can be reused as shell input. +.sp 1 +The \fB\-v\fP option causes the output to be assigned to the variable +\fIvar\fP rather than being printed to the standard output. +.sp 1 +The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP. +If the \fIformat\fP requires more \fIarguments\fP than are supplied, the +extra format specifications behave as if a zero value or null string, as +appropriate, had been supplied. The return value is zero on success, +non-zero on failure. +.TP +\fBpushd\fP [\fB\-n\fP] [\fIdir\fP] +.PD 0 +.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 , +starting with zero) +is at the top. +.TP +\fB\-\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the right of the list shown by +.BR dirs , +starting with zero) 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 +.I 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 pathname of the current working directory. +The pathname 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, the pathname printed may contain symbolic links. +The return status is 0 unless an error occurs while +reading the name of the current directory or an +invalid option is supplied. +.TP +\fBread\fP [\fB\-ers\fP] [\fB\-u\fP \fIfd\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-a\fP \fIaname\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-n\fP \fInchars\fP] [\fB\-d\fP \fIdelim\fP] [\fIname\fP ...] +One line is read from the standard input, or from the file descriptor +\fIfd\fP supplied as an argument to the \fB\-u\fP option, 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 and their intervening separators assigned +to the last +.IR name . +If there are fewer words read from the input stream than names, +the remaining names are assigned empty values. +The characters in +.SM +.B IFS +are used to split the line into words. +The backslash character (\fB\e\fP) may be used to remove any special +meaning for the next character read and for line continuation. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-a \fIaname\fP +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. +Other \fIname\fP arguments are ignored. +.TP +.B \-d \fIdelim\fP +The first character of \fIdelim\fP is used to terminate the input line, +rather than newline. +.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. +.TP +.B \-n \fInchars\fP +\fBread\fP returns after reading \fInchars\fP characters rather than +waiting for a complete line of input. +.TP +.B \-p \fIprompt\fP +Display \fIprompt\fP on standard error, without a +trailing newline, before attempting to read any input. The prompt +is displayed only if input is coming from a terminal. +.TP +.B \-r +Backslash does not act as an escape character. +The backslash is considered to be part of the line. +In particular, a backslash-newline pair may not be used as a line +continuation. +.TP +.B \-s +Silent mode. If input is coming from a terminal, characters are +not echoed. +.TP +.B \-t \fItimeout\fP +Cause \fBread\fP to time out and return failure if a complete line of +input is not read within \fItimeout\fP seconds. +This option has no effect if \fBread\fP is not reading input from the +terminal or a pipe. +.TP +.B \-u \fIfd\fP +Read input from file descriptor \fIfd\fP. +.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, \fBread\fP +times out, or an invalid file descriptor is supplied as the argument to +\fB\-u\fP. +.RE +.TP +\fBreadonly\fP [\fB\-apf\fP] [\fIname\fP[=\fIword\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 +.B \-p +option causes output to be displayed in a format that +may be reused as input. +If a variable name is followed by =\fIword\fP, the value of +the variable is set to \fIword\fP. +The return status is 0 unless an invalid option is encountered, +one of the +.I names +is not a valid 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. +Any command associated with the \fBRETURN\fP trap is executed +before execution resumes after the function or script. +.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 reused as input +for setting or resetting the currently-set variables. +Read-only variables cannot be reset. +In \fIposix mode\fP, only shell variables are listed. +The output is sorted according to the current locale. +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 and functions 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 the command list immediately following a +.B while +or +.B until +keyword, +part of the test in 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 ! . +A trap on \fBERR\fP, if set, is executed before the shell exits. +.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 enabled 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 option 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 errtrace +Same as +.BR \-E . +.TP 8 +.B functrace +Same as +.BR \-T . +.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 +.if t \f(CWIGNOREEOF=10\fP +.if n ``IGNOREEOF=10'' +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 . +.B nolog +Currently ignored. +.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 pipefail +If set, the return value of a pipeline is the value of the last +(rightmost) command to exit with a non-zero status, or zero if all +commands in the pipeline exit successfully. +This option is disabled by default. +.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 (\fIposix mode\fP). +.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 +.SM +.B $ENV +and +.SM +.B $BASH_ENV +files are not processed, shell functions are not inherited from the +environment, and the +.SM +.B SHELLOPTS +variable, if it appears in the environment, is ignored. +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the \fB\-p\fP option is not supplied, these actions +are taken and the effective user id is set to the real user id. +If the \fB\-p\fP option is supplied at startup, the effective user id is +not reset. +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, +\fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or +arithmetic \fBfor\fP command, display the expanded value of +.SM +.BR PS4 , +followed by the command and its expanded arguments +or associated word list. +.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 \-E +If set, any trap on \fBERR\fP is inherited by shell functions, command +substitutions, and commands executed in a subshell environment. +The \fBERR\fP trap is normally not inherited in such cases. +.TP 8 +.B \-H +Enable +.B ! +style history substitution. This option 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 \-T +If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell +functions, command substitutions, and commands executed in a +subshell environment. +The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited +in such cases. +.TP 8 +.B \-\- +If no arguments follow this option, 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 options are off by default unless otherwise noted. +Using + rather than \- causes these options to be turned off. +The options can also be specified as arguments to an invocation of +the shell. +The current set of options may be found in +.BR $\- . +The return status is always true unless an invalid 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. +The \fB\-p\fP option causes output to be displayed in a form that +may be reused as input. +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 valid 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 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 extdebug +If set, behavior intended for use by debuggers is enabled: +.RS +.TP +.B 1. +The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source +file name and line number corresponding to each function name supplied +as an argument. +.TP +.B 2. +If the command run by the \fBDEBUG\fP trap returns a non-zero value, the +next command is skipped and not executed. +.TP +.B 3. +If the command run by the \fBDEBUG\fP trap returns a value of 2, and the +shell is executing in a subroutine (a shell function or a shell script +executed by the \fB.\fP or \fBsource\fP builtins), a call to +\fBreturn\fP is simulated. +.TP +.B 4. +\fBBASH_ARGC\fP and \fBBASH_ARGV\fP are updated as described in their +descriptions above. +.TP +.B 5. +Function tracing is enabled: command substitution, shell functions, and +subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the +\fBDEBUG\fP and \fBRETURN\fP traps. +.TP +.B 6. +Error tracing is enabled: command substitution, shell functions, and +subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the +\fBERROR\fP trap. +.RE +.TP 8 +.B extglob +If set, the extended pattern matching features described above under +\fBPathname Expansion\fP are enabled. +.TP 8 +.B extquote +If set, \fB$\fP'\fIstring\fP' and \fB$\fP"\fIstring\fP" quoting is +performed within \fB${\fP\fIparameter\fP\fB}\fP expansions +enclosed in double quotes. This option is enabled by default. +.TP 8 +.B failglob +If set, patterns which fail to match filenames during pathname expansion +result in an expansion error. +.TP 8 +.B force_fignore +If set, the suffixes specified by the \fBFIGNORE\fP shell variable +cause words to be ignored when performing word completion even if +the ignored words are the only possible completions. +See +.SM +\fBSHELL VARIABLES\fP +above for a description of \fBFIGNORE\fP. +This option is enabled by default. +.TP 8 +.B gnu_errfmt +If set, shell error messages are written in the standard GNU error +message format. +.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, \fBbash\fP will attempt to perform hostname completion when a +word containing a \fB@\fP is being completed (see +.B Completing +under +.SM +.B READLINE +above). +This is enabled by default. +.TP 8 +.B huponexit +If set, \fBbash\fP will send +.SM +.B SIGHUP +to all jobs when an interactive login shell exits. +.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 login_shell +The shell sets this option if it is started as a login shell (see +.SM +.B "INVOCATION" +above). +The value may not be changed. +.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 no_empty_cmd_completion +If set, and +.B readline +is being used, +.B bash +will not attempt to search the \fBPATH\fP for possible completions when +completion is attempted on an empty line. +.TP 8 +.B nocaseglob +If set, +.B bash +matches filenames in a case\-insensitive fashion when performing pathname +expansion (see +.B Pathname Expansion +above). +.TP 8 +.B nocasematch +If set, +.B bash +matches patterns in a case\-insensitive fashion when performing matching +while executing \fBcase\fP or \fB[[\fP conditional commands. +.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 progcomp +If set, the programmable completion facilities (see +\fBProgrammable Completion\fP above) are enabled. +This option is enabled by default. +.TP 8 +.B promptvars +If set, prompt strings undergo +parameter expansion, command substitution, arithmetic +expansion, and quote removal after being expanded as described in +.SM +.B PROMPTING +above. This option is enabled by default. +.TP 8 +.B restricted_shell +The shell sets this option if it is started in restricted mode (see +.SM +.B "RESTRICTED SHELL" +below). +The value may not be changed. +This is not reset when the startup files are executed, allowing +the startup files to discover whether or not a shell is restricted. +.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 option is enabled by default. +.TP 8 +.B xpg_echo +If set, the \fBecho\fP builtin expands backslash-escape sequences +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 +\fBtest\fP \fIexpr\fP +.PD 0 +.TP +\fB[\fP \fIexpr\fP \fB]\fP +Return a status of 0 or 1 depending on +the evaluation of the conditional expression +.IR expr . +Each operator and operand must be a separate argument. +Expressions are composed of the primaries described above under +.SM +.BR "CONDITIONAL EXPRESSIONS" . +\fBtest\fP does not accept any options, nor does it accept and ignore +an argument of \fB\-\-\fP as signifying the end of options. +.if t .sp 0.5 +.if n .sp 1 +Expressions may be combined using the following operators, listed +in decreasing order of precedence. +.RS +.PD 0 +.TP +.B ! \fIexpr\fP +True if +.I expr +is false. +.TP +.B ( \fIexpr\fP ) +Returns the value of \fIexpr\fP. +This may be used to override the normal precedence of operators. +.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. +.PD +.PP +\fBtest\fP and \fB[\fP evaluate conditional +expressions using a set of rules based on the number of arguments. +.if t .sp 0.5 +.if n .sp 1 +.PD 0 +.TP +0 arguments +The expression is false. +.TP +1 argument +The expression is true if and only if the argument is not null. +.TP +2 arguments +If the first argument is \fB!\fP, the expression is true if and +only if the second argument is null. +If the first argument is one of the unary conditional operators listed above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" , +the expression is true if the unary test is true. +If the first argument is not a valid unary conditional operator, the expression +is false. +.TP +3 arguments +If the second argument is one of the binary conditional operators listed above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" , +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 \fB!\fP, the value is the negation of +the two-argument test using the second and third arguments. +If the first argument is exactly \fB(\fP and the third argument is +exactly \fB)\fP, the result is the one-argument test of the second +argument. +Otherwise, the expression is false. +The \fB\-a\fP and \fB\-o\fP operators are considered binary operators +in this case. +.TP +4 arguments +If the first argument is \fB!\fP, 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 using the rules listed above. +.TP +5 or more arguments +The expression is parsed and evaluated according to precedence +using the rules listed above. +.RE +.PD +.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 (and there is a single \fIsigspec\fP) or +.BR \- , +each specified signal is +reset to its original disposition (the value it had +upon entrance to the shell). +If +.I arg +is the null string the signal specified by each +.I sigspec +is ignored by the shell and by the commands it invokes. +If +.I arg +is not present and +.B \-p +has been supplied, 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. +The +.B \-l +option causes the shell to print a list of signal names and +their corresponding numbers. +Each +.I sigspec +is either +a signal name defined in <\fIsignal.h\fP>, or a signal number. +Signal names are case insensitive and the SIG prefix is optional. +If a +.I sigspec +is +.SM +.B EXIT +(0) the command +.I arg +is executed on exit from the shell. +If a +.I sigspec +is +.SM +.BR DEBUG , +the command +.I arg +is executed before every \fIsimple command\fP, \fIfor\fP command, +\fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP +command, and before the first command executes in a shell function (see +.SM +.B SHELL GRAMMAR +above). +Refer to the description of the \fBextdebug\fP option to the +\fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap. +If a +.I sigspec +is +.SM +.BR ERR , +the command +.I arg +is executed whenever a simple command has a non\-zero exit status, +subject to the following conditions. +The +.SM +.B ERR +trap is not executed if the failed +command is part of the command list immediately following a +.B while +or +.B until +keyword, +part of the test in 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 ! . +These are the same conditions obeyed by the \fBerrexit\fP option. +If a +.I sigspec +is +.SM +.BR RETURN , +the command +.I arg +is executed each time a shell function or a script executed with the +\fB.\fP or \fBsource\fP builtins finishes executing. +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\-aftpP\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 \-t +option 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 \-p +option 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 +.if t \f(CWtype -t name\fP +.if n ``type -t name'' +would not return +.IR file . +The +.B \-P +option forces a +.SM +.B PATH +search for each \fIname\fP, even if +.if t \f(CWtype -t name\fP +.if n ``type -t name'' +would not return +.IR file . +If a command is hashed, +.B \-p +and +.B \-P +print the hashed value, not necessarily the file that appears +first in +.SM +.BR PATH . +If the +.B \-a +option 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 \-p +option is not also used. +The table of hashed commands is not consulted +when using +.BR \-a . +The +.B \-f +option suppresses shell function lookup, as with the \fBcommand\fP builtin. +.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 \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. +The value of +.I limit +can be a number in the unit specified for the resource +or one of the special values +.BR hard , +.BR soft , +or +.BR unlimited , +which stand for the current hard limit, the current soft limit, and +no limit, respectively. +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 invalid option or argument is supplied, +or an error occurs while setting a new limit. +.RE +.TP +\fBumask\fP [\fB\-p\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, 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. +If the +.B \-p +option is supplied, and +.I mode +is omitted, the output is in a form that may be reused as input. +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 each \fIname\fP 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 specified, 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 , +.SM +.BR FUNCNAME , +.SM +.BR GROUPS , +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 +is readonly. +.TP +\fBwait\fP [\fIn ...\fP] +Wait for each specified process and return its termination status. +Each +.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" +.\" rbash.1 +.zY +.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 or not performed: +.IP \(bu +changing directories with \fBcd\fP +.IP \(bu +setting or unsetting the values of +.BR SHELL , +.BR PATH , +.BR ENV , +or +.B BASH_ENV +.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 +Specifying a filename containing a slash as an argument to the +.B \-p +option to the +.B hash +builtin command +.IP \(bu +importing function definitions from the shell environment at startup +.IP \(bu +parsing the value of \fBSHELLOPTS\fP 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 +Using the \fBenable\fP builtin command to enable disabled shell builtins +.IP \(bu +specifying the +.B \-p +option to the +.B command +builtin command +.IP \(bu +turning off restricted mode with +\fBset +r\fP or \fBset +o restricted\fP. +.PP +These restrictions are enforced after any startup files are read. +.PP +.ie \n(zY=1 When a command that is found to be a shell script is executed, +.el \{ 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. +.\" end of rbash.1 +.if \n(zY=1 .ig zY +.SH "SEE ALSO" +.PD 0 +.TP +\fIBash Reference Manual\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 ~/.bash_logout +The individual login shell cleanup file, executed when a login shell exits +.TP +.FN ~/.inputrc +Individual \fIreadline\fP initialization file +.PD +.SH AUTHORS +Brian Fox, Free Software Foundation +.br +bfox@gnu.org +.PP +Chet Ramey, Case Western Reserve University +.br +chet@po.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 +.BR bash . +The latest version is always available from +\fIftp://ftp.gnu.org/pub/bash/\fP. +.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 encouraged to mail that as well! +Suggestions and `philosophical' bug reports may be mailed +to \fIbug-bash@gnu.org\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@po.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. For example, +unmatched parentheses, even inside shell comments, will result in +error messages while the construct is being read. +.PP +Array variables may not (yet) be exported. +.zZ +.zY diff --git a/doc/bashbug.1 b/doc/bashbug.1 new file mode 100644 index 0000000..971e4c4 --- /dev/null +++ b/doc/bashbug.1 @@ -0,0 +1,41 @@ +.TH BASHBUG 1 "1998 July 30" 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@gnu.org\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.texi b/doc/bashref.texi new file mode 100644 index 0000000..cdc3df0 --- /dev/null +++ b/doc/bashref.texi @@ -0,0 +1,14 @@ +\input texinfo.tex @c -*- texinfo -*- +@c %**start of header +@setfilename bashref.info +@settitle Bash Reference Manual +@c %**end of header + +@dircategory Basics +@direntry +* Bash: (bash). The GNU Bourne-Again SHell. +@end direntry + +@finalout + +@bye diff --git a/doc/builtins.1 b/doc/builtins.1 new file mode 100644 index 0000000..6a0b248 --- /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 "2004 Apr 20" "GNU Bash-3.0" +.SH NAME +bash, :, ., [, alias, bg, bind, break, builtin, cd, command, compgen, complete, +continue, declare, dirs, disown, echo, enable, eval, exec, exit, +export, fc, fg, getopts, hash, help, history, jobs, kill, +let, local, logout, popd, printf, pushd, pwd, read, readonly, return, set, +shift, shopt, source, suspend, test, times, trap, type, typeset, +ulimit, umask, unalias, unset, wait \- 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/fdl.texi b/doc/fdl.texi new file mode 100644 index 0000000..47ead9f --- /dev/null +++ b/doc/fdl.texi @@ -0,0 +1,452 @@ + +@node GNU Free Documentation License +@appendixsec GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.2, November 2002 + +@display +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@appendixsubsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/doc/fdl.txt b/doc/fdl.txt new file mode 100644 index 0000000..daa2dd4 --- /dev/null +++ b/doc/fdl.txt @@ -0,0 +1,397 @@ + GNU Free Documentation License + Version 1.2, November 2002 + + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The "Document", below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as "you". You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section "Entitled XYZ" means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as "Acknowledgements", +"Dedications", "Endorsements", or "History".) To "Preserve the Title" +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. +O. Preserve any Warranty Disclaimers. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. diff --git a/doc/htmlpost.sh b/doc/htmlpost.sh new file mode 100755 index 0000000..51241b1 --- /dev/null +++ b/doc/htmlpost.sh @@ -0,0 +1,19 @@ +#! /bin/sh +# +# Some of these should really be done by man2html +# +# The ~/xxx links don't really work -- netscape doesn't expand the home +# directory of the user running navigator +# + +sed -e 's|gnu.bash.bug|gnu.bash.bug|g' \ + -e 's|/bin/bash|/bin/bash|g' \ + -e 's|/etc/profile|/etc/profile|g' \ + -e 's|~/.bash_profile|~/.bash_profile|g' \ + -e 's|~/.bash_login|~/.bash_login|g' \ + -e 's|~/.profile|~/.profile|g' \ + -e 's|~/.bashrc|~/.bashrc|g' \ + -e 's|~/.bash_logout|~/.bash_logout|g' \ + -e 's|~/.bash_history|~/.bash_history|g' \ + -e 's|~/.inputrc|~/.inputrc|g' \ + -e 's|/etc/inputrc|/etc/inputrc|g' diff --git a/doc/infopost.sh b/doc/infopost.sh new file mode 100755 index 0000000..85c49b4 --- /dev/null +++ b/doc/infopost.sh @@ -0,0 +1,8 @@ +#! /bin/sh +# +# Some of these should really be done by options to makeinfo or by +# using @setfilename, but this way we can have both bashref.info and +# bash.info (for installing) +# + +sed -e 's|bashref.info|bash.info|g' diff --git a/doc/rbash.1 b/doc/rbash.1 new file mode 100644 index 0000000..c148abf --- /dev/null +++ b/doc/rbash.1 @@ -0,0 +1,8 @@ +.TH RBASH 1 "2004 Apr 20" "GNU Bash-3.0" +.SH NAME +rbash \- restricted bash, see \fBbash\fR(1) +.SH RESTRICTED SHELL +.nr zY 1 +.so bash.1 +.SH SEE ALSO +bash(1) diff --git a/doc/rose94.ps b/doc/rose94.ps new file mode 100644 index 0000000..1fff283 --- /dev/null +++ b/doc/rose94.ps @@ -0,0 +1,1581 @@ +%!PS-Adobe-3.0 +%%Creator: groff version 1.08 +%%DocumentNeededResources: font Times-Bold +%%+ font Times-Italic +%%+ font Times-Roman +%%+ font Courier +%%+ font Symbol +%%DocumentSuppliedResources: procset grops 1.08 0 +%%Pages: 13 +%%PageOrder: Ascend +%%Orientation: Portrait +%%EndComments +%%BeginProlog +%%BeginResource: procset grops 1.08 0 +/setpacking where{ +pop +currentpacking +true setpacking +}if +/grops 120 dict dup begin +/SC 32 def +/A/show load def +/B{0 SC 3 -1 roll widthshow}bind def +/C{0 exch ashow}bind def +/D{0 exch 0 SC 5 2 roll awidthshow}bind def +/E{0 rmoveto show}bind def +/F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def +/G{0 rmoveto 0 exch ashow}bind def +/H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/I{0 exch rmoveto show}bind def +/J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def +/K{0 exch rmoveto 0 exch ashow}bind def +/L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/M{rmoveto show}bind def +/N{rmoveto 0 SC 3 -1 roll widthshow}bind def +/O{rmoveto 0 exch ashow}bind def +/P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/Q{moveto show}bind def +/R{moveto 0 SC 3 -1 roll widthshow}bind def +/S{moveto 0 exch ashow}bind def +/T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def +/SF{ +findfont exch +[exch dup 0 exch 0 exch neg 0 0]makefont +dup setfont +[exch/setfont cvx]cvx bind def +}bind def +/MF{ +findfont +[5 2 roll +0 3 1 roll +neg 0 0]makefont +dup setfont +[exch/setfont cvx]cvx bind def +}bind def +/level0 0 def +/RES 0 def +/PL 0 def +/LS 0 def +/PLG{ +gsave newpath clippath pathbbox grestore +exch pop add exch pop +}bind def +/BP{ +/level0 save def +1 setlinecap +1 setlinejoin +72 RES div dup scale +LS{ +90 rotate +}{ +0 PL translate +}ifelse +1 -1 scale +}bind def +/EP{ +level0 restore +showpage +}bind def +/DA{ +newpath arcn stroke +}bind def +/SN{ +transform +.25 sub exch .25 sub exch +round .25 add exch round .25 add exch +itransform +}bind def +/DL{ +SN +moveto +SN +lineto stroke +}bind def +/DC{ +newpath 0 360 arc closepath +}bind def +/TM matrix def +/DE{ +TM currentmatrix pop +translate scale newpath 0 0 .5 0 360 arc closepath +TM setmatrix +}bind def +/RC/rcurveto load def +/RL/rlineto load def +/ST/stroke load def +/MT/moveto load def +/CL/closepath load def +/FL{ +currentgray exch setgray fill setgray +}bind def +/BL/fill load def +/LW/setlinewidth load def +/RE{ +findfont +dup maxlength 1 index/FontName known not{1 add}if dict begin +{ +1 index/FID ne{def}{pop pop}ifelse +}forall +/Encoding exch def +dup/FontName exch def +currentdict end definefont pop +}bind def +/DEFS 0 def +/EBEGIN{ +moveto +DEFS begin +}bind def +/EEND/end load def +/CNT 0 def +/level1 0 def +/PBEGIN{ +/level1 save def +translate +div 3 1 roll div exch scale +neg exch neg exch translate +0 setgray +0 setlinecap +1 setlinewidth +0 setlinejoin +10 setmiterlimit +[]0 setdash +/setstrokeadjust where{ +pop +false setstrokeadjust +}if +/setoverprint where{ +pop +false setoverprint +}if +newpath +/CNT countdictstack def +userdict begin +/showpage{}def +}bind def +/PEND{ +clear +countdictstack CNT sub{end}repeat +level1 restore +}bind def +end def +/setpacking where{ +pop +setpacking +}if +%%EndResource +%%IncludeResource: font Times-Bold +%%IncludeResource: font Times-Italic +%%IncludeResource: font Times-Roman +%%IncludeResource: font Courier +%%IncludeResource: font Symbol +grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72 def/PL +792 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron/Zcaron/scaron/zcaron +/Ydieresis/trademark/quotesingle/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef +/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/space +/exclam/quotedbl/numbersign/dollar/percent/ampersand/quoteright/parenleft +/parenright/asterisk/plus/comma/hyphen/period/slash/zero/one/two/three/four +/five/six/seven/eight/nine/colon/semicolon/less/equal/greater/question/at/A/B/C +/D/E/F/G/H/I/J/K/L/M/N/O/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash +/bracketright/circumflex/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q +/r/s/t/u/v/w/x/y/z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase +/guillemotleft/guillemotright/bullet/florin/fraction/perthousand/dagger +/daggerdbl/endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut +/dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash +/quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen/brokenbar +/section/dieresis/copyright/ordfeminine/guilsinglleft/logicalnot/minus +/registered/macron/degree/plusminus/twosuperior/threesuperior/acute/mu +/paragraph/periodcentered/cedilla/onesuperior/ordmasculine/guilsinglright +/onequarter/onehalf/threequarters/questiondown/Agrave/Aacute/Acircumflex/Atilde +/Adieresis/Aring/AE/Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute +/Icircumflex/Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis +/multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn/germandbls +/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla/egrave/eacute +/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis/eth/ntilde/ograve +/oacute/ocircumflex/otilde/odieresis/divide/oslash/ugrave/uacute/ucircumflex +/udieresis/yacute/thorn/ydieresis]def/Courier@0 ENC0/Courier RE/Times-Roman@0 +ENC0/Times-Roman RE/Times-Italic@0 ENC0/Times-Italic RE/Times-Bold@0 ENC0 +/Times-Bold RE +%%EndProlog +%%Page: 1 1 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 12/Times-Bold@0 SF(Bash, the Bour)210.99 123 Q(ne\255Again Shell)-.18 E/F1 +10/Times-Italic@0 SF(Chet Rame)263.85 147 Q(y)-.3 E(Case W)221.72 159 Q +(estern Reserve Univer)-.92 E(sity)-.1 E -.15(ch)250.425 171 S(et@po.cwru.edu) +.15 E(ABSTRA)264.535 213 Q(CT)-.3 E/F2 10/Times-Roman@0 SF .019(An o)133 237 R +-.15(ve)-.15 G(rvie).15 E 2.519(wo)-.25 G 2.519(f/)191.918 237 S .018 +(bin/sh\255compatible shells is presented, as well as an introduction to) +200.547 237 R .128(the POSIX.2 shell and tools standard.)108 249 R .128 +(These serv)5.128 F 2.628(ea)-.15 G 2.628(sa)318.562 249 S 2.628(ni)329.52 249 +S .128(ntroduction to bash.)339.928 249 R 2.628(Ac)5.128 G(ompar)439.32 249 Q +(-)-.2 E .188(ison of bash to sh and ksh is presented, as well as a discussion\ + of features unique to bash.)108 261 R(Finally)108 273 Q 3.178(,s)-.65 G .678 +(ome of the changes and ne)145.258 273 R 3.178(wf)-.25 G .678 +(eatures to appear in the ne)268.486 273 R .678(xt bash release will be)-.15 F +(discussed.)108 285 Q/F3 10/Times-Bold@0 SF 2.5(1. Intr)72 321 R(oduction)-.18 +E(Bash)97 336.6 Q F2 .904(is the shell, or command language interpreter)3.404 F +3.404(,t)-.4 G .904(hat will appear in the GNU operating system.)316.032 336.6 +R .782(The name is an acron)72 348.6 R .782(ym for the `)-.15 F(`Bourne\255Ag) +-.74 E .782(ain SHell')-.05 F .782(', a pun on Ste)-.74 F 1.082 -.15(ve B)-.25 +H .783(ourne, the author of the direct).15 F .212(ancestor of the current)72 +360.6 R/F4 9/Times-Roman@0 SF(UNIX)2.712 E F2 2.712<8773>C(hell)199.131 360.6 Q +F1(/bin/sh)2.712 E F2 2.712(,w)C .212(hich appeared in the Se)256.505 360.6 R +-.15(ve)-.25 G .211(nth Edition Bell Labs Research v).15 F(er)-.15 E(-)-.2 E +(sion of)72 372.6 Q F4(UNIX)2.5 E F2([1].).833 E .191(Bash is an)97 388.2 R F3 +(sh)2.691 E F2 .192 +(\255compatible shell that incorporates useful features from the K)B .192 +(orn shell \()-.35 F F3(ksh)A F2 .833(\)[)C .192(2] and the)-.833 F 2.767(Cs)72 +400.2 S .267(hell \()85.327 400.2 R F3(csh)A F2 .833(\)[)C .267 +(3], described later in this article.)-.833 F .266 +(It is ultimately intended to be a conformant implementation)5.267 F 1.965 +(of the IEEE POSIX Shell and T)72 412.2 R 1.966(ools speci\214cation \(IEEE W) +-.8 F 1.966(orking Group 1003.2\).)-.8 F 1.966(It of)6.966 F 1.966 +(fers functional)-.25 F(impro)72 424.2 Q -.15(ve)-.15 G(ments o).15 E -.15(ve) +-.15 G 2.5(rs).15 G 2.5(hf)155.28 424.2 S(or both interacti)166.11 424.2 Q .3 +-.15(ve a)-.25 H(nd programming use.).15 E .802 +(While the GNU operating system will most lik)97 439.8 R .801(ely include a v) +-.1 F .801(ersion of the Berk)-.15 F(ele)-.1 E 3.301(ys)-.15 G .801 +(hell csh, bash)448.238 439.8 R .108(will be the def)72 451.8 R .108 +(ault shell.)-.1 F(Lik)5.108 E 2.608(eo)-.1 G .108(ther GNU softw)199.658 451.8 +R .108(are, bash is quite portable.)-.1 F .109(It currently runs on nearly e) +5.109 F -.15(ve)-.25 G(ry).15 E -.15(ve)72 463.8 S .367(rsion of).15 F F4(UNIX) +2.867 E F2 .367(and a fe)2.867 F 2.867(wo)-.25 G .367 +(ther operating systems \255 an independently-supported port e)187.933 463.8 R +.366(xists for OS/2, and)-.15 F .706(there are rumors of ports to DOS and W)72 +475.8 R(indo)-.4 E .706(ws NT)-.25 F 5.706(.P)-.74 G .706(orts to)295.97 475.8 +R F4(UNIX)3.206 E F2(-lik)A 3.206(es)-.1 G .706(ystems such as QNX and Minix) +372.979 475.8 R(are part of the distrib)72 487.8 Q(ution.)-.2 E .51 +(The original author of bash w)97 503.4 R .51(as Brian F)-.1 F .509 +(ox, an emplo)-.15 F .509(yee of the Free Softw)-.1 F .509(are F)-.1 F 3.009 +(oundation. The)-.15 F(cur)3.009 E(-)-.2 E(rent de)72 515.4 Q -.15(ve)-.25 G +(loper and maintainer is Chet Rame).15 E 1.3 -.65(y, a v)-.15 H(olunteer who w) +.45 E(orks at Case W)-.1 E(estern Reserv)-.8 E 2.5(eU)-.15 G(ni)458.91 515.4 Q +-.15(ve)-.25 G(rsity).15 E(.)-.65 E F3 2.5(2. What)72 539.4 R(is a shell?)2.5 E +F2 1.241(At its base, a shell is simply a macro processor that e)97 555 R -.15 +(xe)-.15 G 1.242(cutes commands.).15 F(A)6.242 E F4(UNIX)3.742 E F2 1.242 +(shell is both a)3.742 F .189(command interpreter)72 567 R 2.688(,w)-.4 G .188 +(hich pro)167.787 567 R .188(vides the user interf)-.15 F .188 +(ace to the rich set of)-.1 F F4(UNIX)2.688 E F2 .188 +(utilities, and a programming)2.688 F .751(language, allo)72 579 R .752 +(wing these utilitites to be combined.)-.25 F .752 +(The shell reads commands either from a terminal or a)5.752 F 2.52 +(\214le. Files)72 591 R .019 +(containing commands can be created, and become commands themselv)2.52 F 2.519 +(es. These)-.15 F(ne)2.519 E 2.519(wc)-.25 G(ommands)465.11 591 Q(ha)72 603 Q +.395 -.15(ve t)-.2 H .095(he same status as system commands in directories lik) +.15 F(e)-.1 E F3(/bin)2.595 E F2 2.595(,a)C(llo)342.575 603 Q .096 +(wing users or groups to establish cus-)-.25 F(tom en)72 615 Q(vironments.)-.4 +E F3 2.5(2.1. Command)72 639 R(Inter)2.5 E(pr)-.1 E(eter)-.18 E F2 2.926(As)97 +654.6 S .426(hell allo)111.036 654.6 R .426(ws e)-.25 F -.15(xe)-.15 G .426 +(cution of).15 F F4(UNIX)2.926 E F2 .426 +(commands, both synchronously and asynchronously)2.926 F 5.425(.T)-.65 G(he) +460.165 654.6 Q F1 -.37(re)2.925 G(dir).37 E(ec-)-.37 E(tion)72 666.6 Q F2 .334 +(constructs permit \214ne-grained control of the input and output of those com\ +mands, and the shell allo)2.833 F(ws)-.25 E .559(control o)72 678.6 R -.15(ve) +-.15 G 3.058(rt).15 G .558(he contents of their en)126.697 678.6 R(vironment.) +-.4 E F4(UNIX)5.558 E F2 .558(shells also pro)3.058 F .558 +(vide a small set of b)-.15 F .558(uilt-in commands)-.2 F(\()72 690.6 Q F1 -.2 +(bu)C(iltins).2 E F2 4.611(\)i)C 2.112 +(mplementing functionality impossible \(e.g.,)115.861 690.6 R F3(cd)4.612 E F2 +(,)A F3(br)4.612 E(eak)-.18 E F2(,)A F3(continue)4.612 E F2 4.612(,a)C(nd) +399.074 690.6 Q F3(exec)4.612 E F2 4.612(\)o)C 4.612(ri)444.948 690.6 S(ncon) +455.67 690.6 Q -.15(ve)-.4 G(nient).15 E .32 LW 76 700.6 72 700.6 DL 80 700.6 +76 700.6 DL 84 700.6 80 700.6 DL 88 700.6 84 700.6 DL 92 700.6 88 700.6 DL 96 +700.6 92 700.6 DL 100 700.6 96 700.6 DL 104 700.6 100 700.6 DL 108 700.6 104 +700.6 DL 112 700.6 108 700.6 DL 116 700.6 112 700.6 DL 120 700.6 116 700.6 DL +124 700.6 120 700.6 DL 128 700.6 124 700.6 DL 132 700.6 128 700.6 DL 136 700.6 +132 700.6 DL 140 700.6 136 700.6 DL 144 700.6 140 700.6 DL/F5 8/Times-Roman@0 +SF 2<8755>72 710.6 S(NIX is a trademark of X/OPEN)83.776 710.6 Q EP +%%Page: 2 2 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-2-)279.67 48 S(\()72 84 Q/F1 10/Times-Bold@0 SF +(history)A F0(,)A F1(getopts)3.505 E F0(,)A F1(kill)3.505 E F0 3.505(,o)C(r) +172.795 84 Q F1(pwd)3.505 E F0 3.505(,f)C 1.005(or e)207.305 84 R 1.005 +(xample\) to obtain via separate utilities.)-.15 F 1.005 +(Shells may be used interac-)6.005 F(ti)72 96 Q -.15(ve)-.25 G +(ly or non-interacti).15 E -.15(ve)-.25 G 2.5(ly: the).15 F 2.5(ya)-.15 G +(ccept input typed from the k)207.42 96 Q -.15(ey)-.1 G +(board or from a \214le.).15 E F1 2.5(2.2. Pr)72 120 R(ogramming Language)-.18 +E F0 .501(While e)97 135.6 R -.15(xe)-.15 G .501 +(cuting commands is essential, most of the po).15 F .501(wer \(and comple)-.25 +F .502(xity\) of shells is due to their)-.15 F .05 +(embedded programming languages.)72 147.6 R(Lik)5.049 E 2.549(ea)-.1 G .349 +-.15(ny h)245.398 147.6 T(igh-le).15 E -.15(ve)-.25 G 2.549(ll).15 G .049 +(anguage, the shell pro)303.276 147.6 R .049(vides v)-.15 F .049 +(ariables, \215o)-.25 F 2.549(wc)-.25 G(ontrol)480.11 147.6 Q +(constructs, quoting, and functions.)72 159.6 Q .475 +(The basic syntactic element is a)97 175.2 R/F2 10/Times-Italic@0 SF .475 +(simple command)2.975 F F0 5.475(.A)C .475 +(simple command consists of an optional set of)315.405 175.2 R -.25(va)72 187.2 +S .525(riable assignments, a command w).25 F .525 +(ord, and an optional list of ar)-.1 F 3.024(guments. Operators)-.18 F .524 +(to redirect input and)3.024 F(output may appear an)72 199.2 Q +(ywhere in a simple command.)-.15 E(Some e)5 E(xamples are:)-.15 E/F3 10 +/Courier@0 SF(who)97 211.2 Q(trn -e -S1 -N)97 223.2 Q(ls -l /bin > binfiles)97 +235.2 Q(make > make.out 2>make.errs)97 247.2 Q F0 2.518(Ap)97 262.8 S .018 +(ipeline is a sequence of tw)111.738 262.8 R 2.518(oo)-.1 G 2.518(rm)230.056 +262.8 S .018(ore commands separated by the character)243.684 262.8 R/F4 10 +/Symbol SF2.519 E F0 5.019(.T)C .019(he standard output)430.082 262.8 R +(of the \214rst command is connected to the standard input of the second.)72 +274.8 Q(Examples of pipelines include:)5 E F3(who | wc -l)97 286.8 Q +(ls -l | sort +3nr)97 298.8 Q F0 .578 +(Simple commands and pipelines may be combined into)97 314.4 R F2(lists)3.078 E +F0 5.578(.A)C .578(list is a sequence of pipelines sepa-)360.002 314.4 R .289 +(rated by one of)72 326.4 R F1(;)2.789 E F0(,)A F1(&)2.789 E F0(,)A F1(&&)2.789 +E F0 2.789(,o)C(r)185.103 326.4 Q F42.789 E F0 2.789(,a)C .289 +(nd optionally terminated by)210.831 326.4 R F1(;)2.789 E F0(,)A F1(&)2.789 E +F0 2.789(,o)C 2.789(ran)352.555 326.4 S -.25(ew)370.903 326.4 S 2.789 +(line. Commands).25 F .289(separated by)2.789 F F1(;)72 338.4 Q F0 .336(are e) +2.836 F -.15(xe)-.15 G .336(cuted sequentially; the shell w).15 F .335 +(aits for each to complete in turn.)-.1 F .335(If a command is terminated by) +5.335 F F1(&)2.835 E F0(,)A .007(the shell e)72 350.4 R -.15(xe)-.15 G .007 +(cutes it in the).15 F F2(bac)2.507 E(kgr)-.2 E(ound)-.45 E F0 2.508(,a)1.666 G +.008(nd does not w)236.076 350.4 R .008(ait for it to \214nish.)-.1 F .008 +(If tw)5.008 F 2.508(oc)-.1 G .008(ommands are separated by)397.616 350.4 R F1 +(&&)72 362.4 Q F0 3.008(,t)C .508(he second command e)96.948 362.4 R -.15(xe) +-.15 G .508(cutes only if the \214rst command succeeds.).15 F 3.007(As)5.508 G +.507(eparator of)383.575 362.4 R F43.007 E F0 .507(causes the sec-)3.007 +F(ond command to e)72 374.4 Q -.15(xe)-.15 G(cute only if the \214rst f).15 E +2.5(ails. Some)-.1 F -.15(ex)2.5 G(amples are:).15 E F3(who ; date)97 386.4 Q +(cd /usr/src || exit 1)97 398.4 Q(cd "$@" && xtitle $HOST: $PWD)97 410.4 Q F0 +1.36(The shell programming language pro)97 426 R 1.361(vides a v)-.15 F 1.361 +(ariety of \215o)-.25 F 3.861(wc)-.25 G 1.361(ontrol structures.)353.276 426 R +(The)6.361 E F1 -.25(fo)3.861 G(r).25 E F0(command)3.861 E(allo)72 438 Q .654 +(ws a list of commands to be e)-.25 F -.15(xe)-.15 G .654 +(cuted once for each w).15 F .654(ord in a w)-.1 F .654(ord list.)-.1 F(The) +5.654 E F1(case)3.154 E F0 .654(command allo)3.154 F .654(ws a)-.25 F .627 +(list to be e)72 450 R -.15(xe)-.15 G .628(cuted if a w).15 F .628 +(ord matches a speci\214ed pattern.)-.1 F(The)5.628 E F1(while)3.128 E F0(and) +3.128 E F1(until)3.128 E F0 .628(commands e)3.128 F -.15(xe)-.15 G .628 +(cute a list of).15 F 1.559 +(commands as long as a guard command completes successfully or f)72 462 R 1.559 +(ails, respecti)-.1 F -.15(ve)-.25 G(ly).15 E 6.559(.T)-.65 G(he)440.892 462 Q +F1(if)4.059 E F0(command)4.059 E(allo)72 474 Q(ws e)-.25 E -.15(xe)-.15 G +(cution of dif).15 E(ferent command lists depending on the e)-.25 E +(xit status of a guard command.)-.15 E(A)97 489.6 Q F2 .385(shell function) +2.885 F F0 .385(associates a list of commands with a name.)2.885 F .386 +(Each time the name is used as a simple)5.385 F .938(command, the list is e)72 +501.6 R -.15(xe)-.15 G 3.438(cuted. This).15 F -.15(exe)3.438 G .938 +(cution tak).15 F .938(es place in the current shell conte)-.1 F .937 +(xt; no ne)-.15 F 3.437(wp)-.25 G .937(rocess is)468.903 501.6 R 2.5 +(created. Functions)72 513.6 R(may ha)2.5 E .3 -.15(ve t)-.2 H(heir o).15 E +(wn ar)-.25 E(gument lists and local v)-.18 E(ariables, and may be recursi)-.25 +E -.15(ve)-.25 G(.).15 E .722(The shell language pro)97 529.2 R .722(vides v) +-.15 F .722(ariables, which may be both set and referenced.)-.25 F 3.222(An) +5.722 G .722(umber of special)435.906 529.2 R 1.02 +(parameters are present, such as)72 541.2 R F1($@)3.519 E F0 3.519(,w)C 1.019 +(hich returns the shell')231.257 541.2 R 3.519(sp)-.55 G 1.019 +(ositional parameters \(command-line ar)333.103 541.2 R(gu-)-.18 E(ments\),)72 +553.2 Q F1($?)2.906 E F0 2.906(,t)C .406(he e)122.812 553.2 R .406 +(xit status of the pre)-.15 F .406(vious command, and)-.25 F F1($$)2.906 E F0 +2.906(,t)C .406(he shell')322.436 553.2 R 2.906(sp)-.55 G .406(rocess I.D.) +368.248 553.2 R .407(In addition to pro)5.406 F(vid-)-.15 E .129 +(ing special parameters and user)72 565.2 R .129(-de\214ned v)-.2 F .129 +(ariables, the shell permits the v)-.25 F .128(alues of certain v)-.25 F .128 +(ariables to control)-.25 F .16(its beha)72 577.2 R(vior)-.2 E 5.16(.S)-.55 G +.16(ome of these v)131.57 577.2 R .16(ariables include)-.25 F F1(IFS)2.661 E F0 +2.661(,w)C .161(hich controls ho)284.202 577.2 R 2.661(wt)-.25 G .161 +(he shell splits w)361.375 577.2 R(ords,)-.1 E F1 -.74(PA)2.661 G(TH)-.21 E F0 +2.661(,w)C(hich)486.78 577.2 Q .392 +(tells the shell where to look for commands, and)72 589.2 R F1(PS1)2.892 E F0 +2.892(,w)C .392(hose v)297.01 589.2 R .392 +(alue is the string the shell uses to prompt for)-.25 F 3.371(commands. There) +72 601.2 R .871(are a fe)3.371 F 3.371(wv)-.25 G .871(ariables whose v)196.645 +601.2 R .871(alues are set by the shell and normally only referenced by)-.25 F +(users;)72 613.2 Q F1(PWD)3.663 E F0 3.663(,w)C 1.163(hose v)135.706 613.2 R +1.163(alue is the pathname of the shell')-.25 F 3.662(sc)-.55 G 1.162(urrent w) +313.068 613.2 R 1.162(orking directory)-.1 F 3.662(,i)-.65 G 3.662(so)421.894 +613.2 S 1.162(ne such v)434.446 613.2 R(ariable.)-.25 E -1.11(Va)72 625.2 S +.008(riables can be used in nearly an)1.11 F 2.509(ys)-.15 G .009(hell conte) +219.37 625.2 R .009(xt and are particularly v)-.15 F .009 +(aluable when used with control struc-)-.25 F(tures.)72 637.2 Q .583 +(There are se)97 652.8 R -.15(ve)-.25 G .583(ral shell).15 F F2 -.2(ex)3.083 G +(pansions).2 E F0 5.583(.A)C -.25(va)254.298 652.8 S(riable).25 E F2(name)3.083 +E F0 .583(is e)3.083 F .582(xpanded to its v)-.15 F .582(alue using ${)-.25 F +F2(name)A F0 .582(}, where)B 1.387(the braces are optional.)72 664.8 R 1.387 +(There are a number of parameter e)6.387 F 1.388(xpansions a)-.15 F -.25(va)-.2 +G 3.888(ilable. F).25 F 1.388(or e)-.15 F 1.388(xample, there are)-.15 F(${)72 +676.8 Q F2(name)A F0<3aad>A F2(wor)A(d)-.37 E F0 .891(}, which e)B .891 +(xpands to)-.15 F F2(wor)3.391 E(d)-.37 E F0(if)3.391 E F2(name)3.391 E F0 .891 +(is unset or null, and the in)3.391 F -.15(ve)-.4 G .89(rse ${).15 F F2(name)A +F0(:+)A F2(wor)A(d)-.37 E F0 .89(}, which)B -.15(ex)72 688.8 S 1.203(pands to) +.15 F F2(wor)3.703 E(d)-.37 E F0(if)3.703 E F2(name)3.703 E F0 1.203 +(is set and not null.)3.703 F F2 1.203(Command substitution)6.203 F F0(allo) +3.703 E 1.204(ws the output of a command to)-.25 F .918 +(replace the command name.)72 700.8 R .918(The syntax is `)5.918 F F2(command)A +F0(`.)A F2(Command)5.918 E F0 .918(is e)3.418 F -.15(xe)-.15 G .918 +(cuted and it and the backquotes).15 F .299 +(are replaced by its output, with trailing ne)72 712.8 R .299(wlines remo)-.25 +F -.15(ve)-.15 G(d.).15 E F2 -.8(Pa)5.299 G .299(thname e).8 F(xpansion)-.2 E +F0 .299(is a w)2.799 F .299(ay to e)-.1 F .299(xpand a w)-.15 F(ord)-.1 E 1.586 +(to a set of \214lenames.)72 724.8 R -.8(Wo)6.586 G 1.586(rds are re).8 F -.05 +(ga)-.15 G 1.586(rded as patterns, in which the characters).05 F F1(*)4.086 E +F0(,)A F1(?)4.086 E F0 4.085(,a)C(nd)432.115 724.8 Q F1([)4.085 E F0(ha)4.085 E +1.885 -.15(ve s)-.2 H(pecial).15 E EP +%%Page: 3 3 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-3-)279.67 48 S 2.845(meaning. W)72 84 R .346(ords\ + containing these special characters are replaced with a sorted list of matchi\ +ng pathnames.)-.8 F(If a w)72 96 Q +(ord generates no matches, it is left unchanged.)-.1 E/F1 10/Times-Italic@0 SF +(Quoting)97 111.6 Q F0 .85(is used to remo)3.35 F 1.15 -.15(ve t)-.15 H .85 +(he special meaning of characters or w).15 F 3.35(ords. It)-.1 F .85 +(can disable special treat-)3.35 F .314 +(ment for shell operators or other special characters, pre)72 123.6 R -.15(ve) +-.25 G .315(nt reserv).15 F .315(ed w)-.15 F .315 +(ords from being recognized as such,)-.1 F .683(and inhibit v)72 135.6 R .683 +(ariable e)-.25 F 3.183(xpansion. The)-.15 F .683 +(shell has three quoting mechanisms:)3.183 F 3.183(ab)5.683 G .683 +(ackslash preserv)387.413 135.6 R .682(es the literal)-.15 F -.25(va)72 147.6 S +.417(lue of the ne).25 F .417(xt character)-.15 F 2.917(,ap)-.4 G .417 +(air of single quotes preserv)196.712 147.6 R .417(es the literal v)-.15 F .418 +(alue of each character between the)-.25 F 1.426 +(quotes, and a pair of double quotes preserv)72 159.6 R 1.425 +(es the literal meaning of enclosed characters while allo)-.15 F(wing)-.25 E +(some e)72 171.6 Q(xpansions.)-.15 E 1.054(Some of the commands b)97 187.2 R +1.054(uilt into the shell are part of the programming language.)-.2 F(The)6.055 +E/F2 10/Times-Bold@0 SF(br)3.555 E(eak)-.18 E F0(and)3.555 E F2(continue)72 +199.2 Q F0 1.175(commands control loop e)3.675 F -.15(xe)-.15 G 1.175 +(cution as in the C language.).15 F(The)6.175 E F2 -2.3 -.15(ev a)3.675 H(l).15 +E F0 -.2(bu)3.675 G 1.174(iltin allo).2 F 1.174(ws a string to be)-.25 F .204 +(parsed and e)72 211.2 R -.15(xe)-.15 G .204(cuted as a command.).15 F F2 -.65 +(Wa)5.205 G(it).65 E F0 .205 +(tells the shell to pause until the processes speci\214ed as ar)2.705 F +(guments)-.18 E(ha)72 223.2 Q .3 -.15(ve ex)-.2 H(ited.).15 E F2 2.5 +(2.3. Interacti)72 247.2 R .2 -.1(ve F)-.1 H(eatur)-.15 E(es)-.18 E F0 .51 +(Shells ha)97 262.8 R .81 -.15(ve b)-.2 H -.15(eg).15 G .51(un of).15 F .51 +(fering features geared speci\214cally for interacti)-.25 F .81 -.15(ve u)-.25 +H .51(se rather than to augment the).15 F .76(programming language.)72 274.8 R +.761(These interacti)5.76 F 1.061 -.15(ve f)-.25 H .761 +(eatures include job control, command line editing, history and).15 F(aliases.) +72 286.8 Q .626(Job control is a f)97 302.4 R .626(acility pro)-.1 F .626 +(vided jointly by the shell and the)-.15 F/F3 9/Times-Roman@0 SF(UNIX)3.125 E +F0 -.1(ke)3.125 G .625(rnel that allo).1 F .625(ws users to selec-)-.25 F(ti)72 +314.4 Q -.15(ve)-.25 G .344 +(ly stop \(suspend\) and restart \(resume\) processes.).15 F .345 +(Each pipeline e)5.345 F -.15(xe)-.15 G .345 +(cuted by the shell is referred to as a).15 F F1(job)72 326.4 Q F0 2.989(.J)C +.488(obs may be suspended and restarted in either the fore)94.159 326.4 R .488 +(ground, where the)-.15 F 2.988(yh)-.15 G -2.25 -.2(av e)397.148 326.4 T .488 +(access to the terminal,)3.188 F .833(or background, where the)72 338.4 R 3.333 +(ya)-.15 G .834(re isolated and cannot read from the terminal.)189.312 338.4 R +-.8(Ty)5.834 G .834(ping the).8 F F1(suspend)3.334 E F0(character)5 E .459(whi\ +le a process is running stops that process and returns control to the shell.)72 +350.4 R .459(Once a job is suspended, the)5.459 F .392 +(user manipulates the job')72 362.4 R 2.892(ss)-.55 G .392(tate, using)184.118 +362.4 R F2(bg)2.892 E F0 .393(to continue it in the background,)2.892 F F2(fg) +2.893 E F0 .393(to return it to the fore)2.893 F(ground)-.15 E .891(and a)72 +374.4 R -.1(wa)-.15 G .891(it its completion, or).1 F F2(kill)3.391 E F0 .891 +(to send it a signal.)3.391 F(The)5.89 E F2(jobs)3.39 E F0 .89 +(command lists the status of jobs, and)3.39 F F2(wait)3.39 E F0 .407 +(will pause the shell until a speci\214ed job terminates.)72 386.4 R .407 +(The shell pro)5.407 F .407(vides a number of w)-.15 F .407 +(ays to refer to a job,)-.1 F(and will notify the user whene)72 398.4 Q -.15 +(ve)-.25 G 2.5(rab).15 G(ackground job terminates.)220.18 398.4 Q -.4(Wi)97 414 +S .956(th the adv).4 F .956(ent of more po)-.15 F .956 +(werful terminals and terminal emulators, more sophisticated interaction)-.25 F +.253(than that pro)72 426 R .253(vided by the)-.15 F F3(UNIX)2.753 E F0 -.1(ke) +2.754 G .254(rnel terminal dri).1 F -.15(ve)-.25 G 2.754(ri).15 G 2.754(sp) +293.592 426 S 2.754(ossible. Some)305.236 426 R .254(shells of)2.754 F .254 +(fer command line editing,)-.25 F 1.141 +(which permits a user to edit lines of input using f)72 438 R(amiliar)-.1 E F1 +(emacs)3.64 E F0(or)3.64 E F1(vi)3.64 E F0 1.14 +(-style commands before submitting)B .02(them to the shell.)72 450 R .02 +(Editors allo)5.02 F 2.52(wc)-.25 G .02(orrections to be made without ha)206.31 +450 R .021(ving to erase back to the point of error)-.2 F 2.521(,o)-.4 G(r) +500.67 450 Q .135(start the line ane)72 462 R 3.935 -.65(w. C)-.25 H .135 +(ommand line editors run the g).65 F .135(amut from a small \214x)-.05 F .134 +(ed set of commands and k)-.15 F .434 -.15(ey b)-.1 H(ind-).15 E +(ings to input f)72 474 Q(acilities which allo)-.1 E 2.5(wa)-.25 G +(rbitrary actions to be bound to a k)217.2 474 Q .3 -.15(ey o)-.1 H 2.5(rk).15 +G .3 -.15(ey s)379.88 474 T(equence.).15 E .145(Modern shells also k)97 489.6 R +.145(eep a history)-.1 F 2.645(,w)-.65 G .146 +(hich is the list of commands a user has typed.)243.49 489.6 R .146(Shell f) +5.146 F .146(acilities are)-.1 F -.2(av)72 501.6 S .368(ailable to recall pre) +-.05 F .367(vious commands and use portions of old commands when composing ne) +-.25 F 2.867(wo)-.25 G 2.867(nes. The)467.253 501.6 R 1.456 +(command history can be sa)72 513.6 R -.15(ve)-.2 G 3.957(dt).15 G 3.957 +(oa\214)207.522 513.6 S 1.457 +(le and read back in at shell startup, so it persists across sessions.)230.436 +513.6 R .675(Shells which pro)72 525.6 R .675 +(vide both command editing and history generally ha)-.15 F .974 -.15(ve e)-.2 H +.674(diting commands to interacti).15 F -.15(ve)-.25 G(ly).15 E(step forw)72 +537.6 Q(ard and backw)-.1 E(ard through the history list.)-.1 E .013 +(Aliases allo)97 553.2 R -5.012 2.513(wa s)-.25 H .014 +(tring to be substituted for a command name.)164.28 553.2 R(The)5.014 E 2.514 +(yc)-.15 G .014(an be used to create a mnemonic)373.396 553.2 R .568(for a)72 +565.2 R F3(UNIX)3.068 E F0 .568(command name \()3.068 F/F4 10/Courier@0 SF .568 +(alias del=rm)B F0 .568(\), to e)B .567(xpand a single w)-.15 F .567 +(ord to a comple)-.1 F 3.067(xc)-.15 G .567(ommand \()432.603 565.2 R F4(alias) +A .255(news='xterm -g 80x45 -title trn -e trn -e -S1 -N &')72 577.2 R F0 .255 +(\), or to ensure that a command)B(is in)72 589.2 Q -.2(vo)-.4 G -.1(ke).2 G +2.5(dw).1 G(ith a basic set of options \()122.41 589.2 Q F4 +(alias ls="/bin/ls -F")A F0(\).)A F2 2.5(3. The)72 613.2 R +(POSIX Shell Standard)2.5 E F1(POSIX)97 628.8 Q F0 .239 +(is a name originally coined by Richard Stallman for a f)4.405 F .239 +(amily of open system standards based)-.1 F(on)72 640.8 Q F3(UNIX)3.239 E F0 +5.739(.T)C .74(here are a number of aspects of)122.079 640.8 R F3(UNIX)3.24 E +F0 .74(under consideration for standardization, from the basic)3.24 F .192 +(system services at the system call and C library le)72 652.8 R -.15(ve)-.25 G +2.692(lt).15 G 2.692(oa)290.16 652.8 S .191 +(pplications and tools to system administration and)302.292 652.8 R 2.5 +(management. Each)72 664.8 R(area of standardization is assigned to a w)2.5 E +(orking group in the 1003 series.)-.1 E 3.602(The POSIX Shell and T)97 680.4 R +3.602(ools standard has been de)-.8 F -.15(ve)-.25 G 3.603(loped by IEEE W).15 +F 3.603(orking Group 1003.2)-.8 F -1.667(\(POSIX.2\) [4].)72 692.4 R 2.799 +(It concentrates on the command interpreter interf)7.799 F 2.799 +(ace and utility programs commonly)-.1 F -.15(exe)72 704.4 S 2.345 +(cuted from the command line or by other programs.).15 F 2.345(An initial v) +7.345 F 2.345(ersion of the standard has been)-.15 F(appro)72 716.4 Q -.15(ve) +-.15 G 2.915(da).15 G .414(nd published by the IEEE, and w)116.265 716.4 R .414 +(ork is currently underw)-.1 F .414(ay to update it.)-.1 F .414 +(There are four primary)5.414 F(areas of w)72 728.4 Q +(ork in the 1003.2 standard:)-.1 E EP +%%Page: 4 4 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-4-)279.67 48 S 21.5<8341>72 84 S .835 +(spects of the shell')104.22 84 R 3.335(ss)-.55 G .835 +(yntax and command language.)192 84 R 3.335(An)5.835 G .835(umber of special b) +338.095 84 R .835(uiltins such as)-.2 F/F1 10/Times-Bold@0 SF(cd)3.335 E F0 +(and)3.335 E F1(exec)97 96 Q F0 .545(are being speci\214ed as part of the shel\ +l, since their functionality usually cannot be implemented)3.046 F +(by a separate e)97 108 Q -.15(xe)-.15 G(cutable;).15 E 21.5<8341>72 123.6 S +.73(set of utilities to be called by shell scripts and applications.)107.45 +123.6 R .731(Examples are programs lik)5.731 F(e)-.1 E/F2 10/Times-Italic@0 SF +2.397(sed, tr)3.231 F(,)-1.11 E F0(and)97 135.6 Q F2(awk.)2.853 E F0 .352 +(Utilities commonly implemented as shell b)4.519 F .352 +(uiltins are described in this section, such as)-.2 F F1(test)2.852 E F0(and)97 +147.6 Q F1(kill)3.422 E F0 5.922(.A)C 3.422(ne)144.404 147.6 S .922 +(xpansion of this section')157.116 147.6 R 3.423(ss)-.55 G .923 +(cope, termed the User Portability Extension, or UPE, has)268.586 147.6 R +(standardized interacti)97 159.6 Q .3 -.15(ve p)-.25 H(rograms such as).15 E F2 +(vi)2.5 E F0(and)4.166 E F2(mailx;)2.5 E F0 21.5<8341>72 175.2 S .926 +(group of functional interf)107.646 175.2 R .926(aces to services pro)-.1 F +.926(vided by the shell, such as the traditional)-.15 F F2(system)3.425 E F0(C) +5.091 E .507(library function.)97 187.2 R .507 +(There are functions to perform shell w)5.507 F .508(ord e)-.1 F .508 +(xpansions, perform \214lename e)-.15 F(xpansion)-.15 E(\()97 199.2 Q F2 +(globbing)A F0 .58(\), obtain v)B .58 +(alues of POSIX.2 system con\214guration v)-.25 F .58(ariables, retrie)-.25 F +.88 -.15(ve v)-.25 H .58(alues of en)-.1 F(vironment)-.4 E -.25(va)97 211.2 S +(riables \().25 E F2 -.1(ge)C(ten).1 E(v\(\))-.4 E F0(\), and other services;) +.833 E 21.5<8341>72 226.8 S(suite of `)106.72 226.8 Q(`de)-.74 E -.15(ve)-.25 G +(lopment').15 E 2.5('u)-.74 G(tilities such as)209.54 226.8 Q F2(c89)2.5 E F0 +(\(the POSIX.2 v)4.166 E(ersion of)-.15 E F2(cc)2.5 E F0(\), and)A F2(yacc.)2.5 +E F0 .483(Bash is concerned with the aspects of the shell')97 242.4 R 2.983(sb) +-.55 G(eha)301.597 242.4 Q .484(vior de\214ned by POSIX.2.)-.2 F .484 +(The shell command)5.484 F 1.439 +(language has of course been standardized, including the basic \215o)72 254.4 R +3.938(wc)-.25 G 1.438(ontrol and program e)359.688 254.4 R -.15(xe)-.15 G 1.438 +(cution con-).15 F 1.145(structs, I/O redirection and pipelining, ar)72 266.4 R +1.145(gument handling, v)-.18 F 1.145(ariable e)-.25 F 1.146 +(xpansion, and quoting.)-.15 F(The)6.146 E F2(special)3.646 E F0 -.2(bu)72 +278.4 S .676(iltins, which must be implemented as part of the shell to pro).2 F +.676(vide the desired functionality)-.15 F 3.176(,a)-.65 G .676(re speci\214ed) +457.504 278.4 R .7(as being part of the shell; e)72 290.4 R .7 +(xamples of these are)-.15 F F1 -2.3 -.15(ev a)3.201 H(l).15 E F0(and)3.201 E +F1(export)3.201 E F0 5.701(.O)C .701(ther utilities appear in the sections of) +352.034 290.4 R .256(POSIX.2 not de)72 302.4 R -.2(vo)-.25 G .256(ted to the s\ +hell which are commonly \(and in some cases must be\) implemented as b).2 F +(uiltin)-.2 E(commands, such as)72 314.4 Q F1 -.18(re)2.5 G(ad).18 E F0(and)2.5 +E F1(test)2.5 E F0(.)A .972(POSIX.2 also speci\214es aspects of the shell')97 +330 R 3.473(si)-.55 G(nteracti)286.016 330 Q 1.273 -.15(ve b)-.25 H(eha).15 E +.973(vior as part of the UPE, including job)-.2 F .233 +(control, command line editing, and history)72 342 R 5.233(.I)-.65 G .233 +(nterestingly enough, only)253.849 342 R F2(vi)2.733 E F0 .233 +(-style line editing commands ha)B -.15(ve)-.2 G(been standardized;)72 354 Q F2 +(emacs)2.5 E F0(editing commands were left out due to objections.)2.5 E .148 +(There were certain areas in which POSIX.2 felt standardization w)97 369.6 R +.149(as necessary)-.1 F 2.649(,b)-.65 G .149(ut no e)420.643 369.6 R .149 +(xisting imple-)-.15 F 1.598(mentation pro)72 381.6 R 1.598 +(vided the proper beha)-.15 F(vior)-.2 E 6.598(.T)-.55 G 1.598(he w)251.56 +381.6 R 1.597(orking group in)-.1 F -.15(ve)-.4 G 1.597 +(nted and standardized functionality in).15 F .228(these areas.)72 393.6 R(The) +5.228 E F1(command)2.728 E F0 -.2(bu)2.728 G .228(iltin w).2 F .228(as in)-.1 F +-.15(ve)-.4 G .228(nted so that shell functions could be written to replace b) +.15 F(uiltins;)-.2 E 1.663(it mak)72 405.6 R 1.663 +(es the capabilities of the b)-.1 F 1.663(uiltin a)-.2 F -.25(va)-.2 G 1.663 +(ilable to the function.).25 F 1.663(The reserv)6.663 F 1.663(ed w)-.15 F 1.663 +(ord `)-.1 F(`!')-.74 E 4.163('w)-.74 G 1.663(as added to)455.685 405.6 R(ne)72 +417.6 Q -.05(ga)-.15 G .915(te the return v).05 F .915 +(alue of a command or pipeline; it w)-.25 F .916(as nearly impossible to e)-.1 +F .916(xpress `)-.15 F .916(`if not x')-.74 F 3.416('c)-.74 G(leanly)479.56 +417.6 Q .904(using the sh language.)72 429.6 R .904(There e)5.904 F .904 +(xist multiple incompatible implementations of the)-.15 F F1(test)3.403 E F0 +-.2(bu)3.403 G .903(iltin, which tests).2 F .28 +(\214les for type and other attrib)72 441.6 R .281 +(utes and performs arithmetic and string comparisons.)-.2 F .281 +(POSIX considered none)5.281 F .868(of these correct, so the standard beha)72 +453.6 R .868(vior w)-.2 F .868(as speci\214ed in terms of the number of ar)-.1 +F .867(guments to the com-)-.18 F 3.803(mand. POSIX.2)72 465.6 R 1.303 +(dictates e)3.803 F 1.303(xactly what will happen when four or fe)-.15 F 1.303 +(wer ar)-.25 F 1.303(guments are gi)-.18 F -.15(ve)-.25 G 3.803(nt).15 G(o) +459.462 465.6 Q F1(test)3.804 E F0 3.804(,a)C(nd)494 465.6 Q(lea)72 477.6 Q +-.15(ve)-.2 G 4.531(st).15 G 2.031(he beha)103.951 477.6 R 2.031 +(vior unde\214ned when more ar)-.2 F 2.031(guments are supplied.)-.18 F 2.03 +(Bash uses the POSIX.2 algorithm,)7.031 F(which w)72 489.6 Q(as concei)-.1 E +-.15(ve)-.25 G 2.5(db).15 G 2.5(yD)164.53 489.6 S -.2(av)179.25 489.6 S(id K).2 +E(orn.)-.35 E 1.128 +(While POSIX.2 includes much of what the shell has traditionally pro)97 505.2 R +1.129(vided, some important things)-.15 F(ha)72 517.2 Q .58 -.15(ve b)-.2 H .28 +(een omitted as being `).15 F(`be)-.74 E .28(yond its scope.)-.15 F 4.26 -.74 +('' T)-.7 H .28(here is, for instance, no mention of a dif).74 F .28 +(ference between)-.25 F(a)72 529.2 Q F2(lo)3.354 E(gin)-.1 E F0 .854 +(shell and an)5.02 F 3.354(yo)-.15 G .854(ther interacti)167.956 529.2 R 1.154 +-.15(ve s)-.25 H .854(hell \(since POSIX.2 does not specify a login program\).) +.15 F .855(No \214x)5.855 F(ed)-.15 E +(startup \214les are de\214ned, either \255 the standard does not mention)72 +541.2 Q F2(.pr)2.5 E(o\214le)-.45 E F0(.)1.666 E F1 2.5(4. Shell)72 565.2 R +(Comparison)2.5 E F0 .693(This section compares features of bash, sh, and ksh \ +\(the three shells closest to POSIX compliance\).)97 580.8 R .245(Since ksh an\ +d bash are supersets of sh, the features common to all three are co)72 592.8 R +-.15(ve)-.15 G .245(red \214rst.).15 F .245(Some of the fea-)5.245 F 1.198 +(tures bash and ksh contain which are not in sh will be discussed.)72 604.8 R +(Ne)6.198 E 1.198(xt, features unique to bash will be)-.15 F 2.866(listed. The) +72 616.8 R .366(\214rst three sections pro)2.866 F .366(vide a progressi)-.15 F +-.15(ve)-.25 G .366(ly more detailed o).15 F -.15(ve)-.15 G(rvie).15 E 2.866 +(wo)-.25 G 2.866(fb)395.706 616.8 S 2.866(ash. Finally)406.902 616.8 R 2.866 +(,f)-.65 G .366(eatures of)464.484 616.8 R(ksh-88 \(the currently-a)72 628.8 Q +-.25(va)-.2 G(ilable v).25 E(ersion\) not in sh or bash will be presented.)-.15 +E F1 2.5(4.1. Common)72 652.8 R -.25(Fe)2.5 G(atur).25 E(es)-.18 E F0 .021 +(All three shells ha)97 668.4 R .321 -.15(ve t)-.2 H .021 +(he same basic feature set, which is essentially that pro).15 F .02 +(vided by sh and described)-.15 F 1.026(in an)72 680.4 R 3.526(ys)-.15 G 3.526 +(hm)105.012 680.4 S 1.027 +(anual page. Bash and ksh are both sh supersets, and so all three pro)121.318 +680.4 R 1.027(vide the command inter)-.15 F(-)-.2 E .714 +(preter and programming language described earlier)72 692.4 R 3.214(.T)-.55 G +.714(he shell grammar)291.506 692.4 R 3.214(,s)-.4 G .714(yntax, \215o)371.568 +692.4 R 3.214(wc)-.25 G .714(ontrol, redirections,)424.686 692.4 R(and b)72 +704.4 Q(uiltins implemented by the Bourne shell are the baseline for subsequen\ +t discussion.)-.2 E EP +%%Page: 5 5 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-5-)279.67 48 S/F1 10/Times-Bold@0 SF 2.5(4.2. F)72 +84 R(eatur)-.25 E(es in bash and ksh)-.18 E F0 .458(Ksh and bash ha)97 99.6 R +.758 -.15(ve s)-.2 H -2.15 -.25(ev e).15 H .459(ral features in common be).25 F +.459(yond this base le)-.15 F -.15(ve)-.25 G 2.959(lo).15 G 2.959(ff)387.814 +99.6 S(unctionality)397.433 99.6 Q 5.459(.S)-.65 G .459(ome of this)458.082 +99.6 R(is due to the POSIX.2 standard.)72 111.6 Q(Other functions ha)5 E .3 +-.15(ve b)-.2 H(een implemented in bash using ksh as a guide.).15 E F1 2.5 +(4.2.1. V)72 135.6 R(ariables and V)-.92 E(ariable Expansion)-.92 E F0 .097 +(Bash and ksh ha)97 151.2 R .396 -.15(ve a)-.2 H .096(ugmented v).15 F .096 +(ariable e)-.25 F 2.596(xpansion. Arithmetic)-.15 F .096(substitution allo) +2.596 F .096(ws an e)-.25 F .096(xpression to be)-.15 F -.25(eva)72 163.2 S .6 +(luated and the result substituted.).25 F .6(Shell v)5.6 F .6 +(ariables may be used as operands, and the result of an e)-.25 F(xpres-)-.15 E +.41(sion may be assigned to a v)72 175.2 R 2.91(ariable. Nearly)-.25 F .41 +(all of the operators from the C language are a)2.91 F -.25(va)-.2 G .41 +(ilable, with the).25 F(same precedence rules:)72 187.2 Q/F2 10/Courier@0 SF 6 +($e)97 205.2 S(cho $\(\(3 + 5 * 32\)\))115 205.2 Q(163)97 217.2 Q F0 -1.11(Va) +72 238.8 S 1.445(riables may be declared as)1.11 F/F3 10/Times-Italic@0 SF +(inte)3.945 E -.1(ge)-.4 G(r).1 E F0 3.945(,w)1.666 G 1.446 +(hich causes arithmetic e)240.956 238.8 R -.25(va)-.25 G 1.446 +(luation to be performed on the v).25 F(alue)-.25 E(whene)72 250.8 Q -.15(ve) +-.25 G 2.5(rt).15 G(he)115.75 250.8 Q 2.5(ya)-.15 G(re assigned to.)136.98 +250.8 Q .483(There are ne)97 266.4 R 2.983(we)-.25 G .483 +(xpansions to obtain the length of a v)162.179 266.4 R(ariable')-.25 E 2.982 +(sv)-.55 G .482(alue and to remo)352.19 266.4 R .782 -.15(ve s)-.15 H .482 +(ubstrings match-).15 F .063(ing speci\214ed patterns from the be)72 278.4 R +.063(ginning and end of v)-.15 F .063(ariable v)-.25 F 2.563(alues. A)-.25 F +(ne)2.563 E 2.563(wf)-.25 G .064(orm of command substitution,)383.249 278.4 R +F1($\()72 290.4 Q F3(list)A F1(\))A F0 2.5(,i)C 2.5(sm)103.67 290.4 S +(uch easier to nest than `)117.84 290.4 Q F3(list)A F0 2.5(`a)C +(nd has simpli\214ed quoting rules.)235.04 290.4 Q .082(There are ne)97 306 R +2.582(wv)-.25 G .082(ariables to control the shell')161.436 306 R 2.581(sb)-.55 +G(eha)284.333 306 Q(vior)-.2 E 2.581(,a)-.4 G .081(nd additional v)323.244 306 +R .081(ariables set or interpreted spe-)-.25 F 1.038(cially by the shell.)72 +318 R F1(RANDOM)6.038 E F0(and)3.538 E F1(SECONDS)3.538 E F0(are)3.539 E F3 +(dynamic)3.539 E F0 -.25(va)3.539 G 3.539(riables: their).25 F -.25(va)3.539 G +1.039(lues are generated afresh).25 F 1.022(each time the)72 330 R 3.522(ya) +-.15 G 1.022(re referenced.)140.176 330 R F1(RANDOM)6.022 E F0 1.021 +(returns a dif)3.521 F 1.021(ferent random number each time it is referenced,) +-.25 F(and)72 342 Q F1(SECONDS)3.138 E F0 .638 +(returns the number of seconds since the shell w)3.138 F .638 +(as started or the v)-.1 F .639(ariable w)-.25 F .639(as assigned to,)-.1 F +1.448(plus an)72 354 R 3.948(yv)-.15 G 1.448(alue assigned.)115.606 354 R F1 +(PWD)6.448 E F0(and)3.948 E F1(OLDPWD)3.947 E F0 1.447 +(are set to the current and pre)3.947 F 1.447(vious w)-.25 F 1.447 +(orking directories,)-.1 F(respecti)72 366 Q -.15(ve)-.25 G(ly).15 E(.)-.65 E +F1(TMOUT)5.604 E F0 .604(controls ho)3.104 F 3.104(wl)-.25 G .604 +(ong the shell will w)226.436 366 R .604(ait at a prompt for input.)-.1 F(If) +5.604 E F1(TMOUT)3.104 E F0 .605(is set to a)3.105 F -.25(va)72 378 S 1.168 +(lue greater than zero, the shell e).25 F 1.168(xits after w)-.15 F 1.168 +(aiting that man)-.1 F 3.668(ys)-.15 G 1.167(econds for input.)337.478 378 R F1 +(REPL)6.167 E(Y)-.92 E F0 1.167(is the def)3.667 F(ault)-.1 E -.25(va)72 390 S +.991(riable for the).25 F F1 -.18(re)3.491 G(ad).18 E F0 -.2(bu)3.491 G .991 +(iltin; if no v).2 F .992(ariable names are supplied as ar)-.25 F .992 +(guments, the line read is assigned to)-.18 F F1(REPL)72 402 Q(Y)-.92 E F0(.)A +F1 2.5(4.2.2. New)72 426 R(and Modi\214ed Builtins)2.5 E F0 .652(Both shells e) +97 441.6 R .651(xpand the basic sh set of b)-.15 F .651(uiltin commands.)-.2 F +F1(Let)5.651 E F0(pro)3.151 E .651(vides a w)-.15 F .651 +(ay to perform arithmetic)-.1 F 2.767(on shell v)72 453.6 R 5.268 +(ariables. Shell)-.25 F 2.768(programmers use)5.268 F F1(typeset)5.268 E F0 +2.768(\(bash includes)5.268 F F1(declar)5.268 E(e)-.18 E F0 2.768(as a synon) +5.268 F 2.768(ym\) to assign)-.15 F(attrib)72 465.6 Q .295(utes such as)-.2 F +F3 -.2(ex)2.795 G(port).2 E F0(and)4.461 E F3 -.37(re)2.795 G(adonly).37 E F0 +.295(to v)4.461 F(ariables.)-.25 E F1(Getopts)5.295 E F0 .294 +(is used by shell scripts to parse script options)2.795 F .962(and ar)72 477.6 +R 3.462(guments. The)-.18 F F1(set)3.462 E F0 .962(command has a ne)3.462 F +3.462(wo)-.25 G(ption)266.446 477.6 Q F13.463 E F0 .963(which tak)3.463 F +.963(es option names as ar)-.1 F 3.463(guments. Option)-.18 F 1.28 +(names are synon)72 489.6 R 1.28(yms for the other set options \(e.g.,)-.15 F +F13.78 E F0(and)3.78 E F1 1.28(\255o noglob)3.78 F F0 3.78(\)o)C 3.78(rp) +375.97 489.6 S(ro)388.08 489.6 Q 1.28(vide ne)-.15 F 3.78(wf)-.25 G 1.28 +(unctionality \()440.78 489.6 R F1(-o)A(notify)72 501.6 Q F0 3.348(,f)C .849 +(or e)106.178 501.6 R 3.349(xample\). The)-.15 F F1 -.18(re)3.349 G(ad).18 E F0 +-.2(bu)3.349 G .849(iltin tak).2 F .849(es a ne)-.1 F(w)-.25 E F13.349 E +F0 .849(option to specify that a line ending in a backslash)3.349 F +(should not be continued.)72 513.6 Q F1 2.5(4.2.3. T)72 537.6 R(ilde Expansion) +-.18 E F0 -.35(Ti)97 553.2 S .252(lde e).35 F .251 +(xpansion is a feature adopted from the C shell.)-.15 F 2.751(At)5.251 G .251 +(ilde character at the be)331.172 553.2 R .251(ginning of a w)-.15 F .251 +(ord is)-.1 F -.15(ex)72 565.2 S(panded to either).15 E F1($HOME)2.5 E F0 +(or the home directory of another user)2.5 E 2.5(,d)-.4 G +(epending on what follo)345.84 565.2 Q(ws the tilde.)-.25 E F1 2.5 +(4.2.4. Interacti)72 589.2 R .2 -.1(ve I)-.1 H(mpr).1 E -.1(ove)-.18 G(ments).1 +E F0 .789(The most noticable impro)97 604.8 R -.15(ve)-.15 G .789(ments o).15 F +-.15(ve)-.15 G 3.289(rs).15 G 3.289(ha)263.385 604.8 S .789 +(re geared for interacti)276.114 604.8 R 1.089 -.15(ve u)-.25 H 3.29(se. Ksh) +.15 F .79(and bash pro)3.29 F .79(vide job)-.15 F .882(control in a v)72 616.8 +R .882(ery similar f)-.15 F .882 +(ashion, with the same options to enable and disable it \()-.1 F F1 .881 +(set -o monitor)B F0 3.381(\)a)C .881(nd the)478.399 616.8 R(same b)72 628.8 Q +(uiltin commands to manipulate jobs \()-.2 E F1(jobs/fg/bg/kill/wait)A F0(\).)A +.866(Command line editing, with emacs and vi-style k)97 644.4 R 1.166 -.15 +(ey b)-.1 H .866(indings, is a).15 F -.25(va)-.2 G .866(ilable in both shells.) +.25 F .866(The Bash)5.866 F F3 -.37(re)72 656.4 S(adline).37 E F0 1.578 +(library is considerably more sophisticated than the ksh editing library:)5.744 +F 1.577(it allo)6.577 F 1.577(ws arbitrary k)-.25 F -.15(ey)-.1 G 1.867 +(bindings, macros, a per)72 668.4 R 1.868(-user customization \214le \()-.2 F +F3(~/.inputr)A(c)-.37 E F0 1.868(\), a number of v)B 1.868 +(ariables to further customize)-.25 F(beha)72 680.4 Q(vior)-.2 E 3.538(,a)-.4 G +1.038(nd a much lar)116.868 680.4 R 1.038 +(ger set of bindable editing commands.)-.18 F 1.037 +(The ksh editing library pro)6.037 F 1.037(vides a small)-.15 F<8c78>72 692.4 Q +(ed command set and only clumsy macros.)-.15 E .706(Both shells of)97 708 R +.706(fer access to the command history)-.25 F 5.706(.T)-.65 G .706 +(he in-line editing options ha)307.278 708 R 1.006 -.15(ve d)-.2 H(ef).15 E +.706(ault k)-.1 F 1.006 -.15(ey b)-.1 H(ind-).15 E .624 +(ings to access the history list.)72 720 R(The)5.624 E F1(fc)3.124 E F0 .624 +(command is pro)3.124 F .624(vided to re-e)-.15 F -.15(xe)-.15 G .623(cute pre) +.15 F .623(vious commands and display)-.25 F EP +%%Page: 6 6 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-6-)279.67 48 S(the contents of the history list.) +72 84 Q/F1 10/Times-Bold@0 SF 2.5(4.2.5. Miscellaneous)72 108 R +(Changes and Impr)2.5 E -.1(ov)-.18 G(ments).1 E F0 .707(Other impro)97 123.6 R +-.15(ve)-.15 G .707(ments include aliases, the).15 F F1(select)3.207 E F0 .708 +(shell language construct, which supports the genera-)3.207 F 1.298 +(tion and presentation of simple menus, and e)72 135.6 R 1.298 +(xtensions to the)-.15 F F1(export)3.798 E F0(and)3.798 E F1 -.18(re)3.798 G +(adonly).18 E F0 -.2(bu)3.798 G 1.298(iltins which allo).2 F(w)-.25 E -.25(va) +72 147.6 S .017(riables to be assigned v).25 F .017 +(alues at the same time the attrib)-.25 F .017(utes are set.)-.2 F -.8(Wo)5.018 +G .018(rd splitting has changed:).8 F .018(if tw)5.018 F 2.518(oo)-.1 G(r) +500.67 147.6 Q .158(more adjacent w)72 159.6 R .157 +(ord splitting characters occur)-.1 F 2.657(,b)-.4 G .157 +(ash and ksh will generate null \214elds; sh mak)264.893 159.6 R .157 +(es runs of mul-)-.1 F .339 +(tiple \214eld separator charactors the same as a single separator)72 171.6 R +5.339(.B)-.55 G .34(ash and ksh split only the results of e)330.89 171.6 R +(xpan-)-.15 E(sion, rather than e)72 183.6 Q -.15(ve)-.25 G(ry w).15 E +(ord as sh does, closing a long-standing shell security hole.)-.1 E 1.234 +(Shell functions in bash and ksh may ha)97 199.2 R 1.534 -.15(ve l)-.2 H 1.234 +(ocal v).15 F 3.734(ariables. V)-.25 F 1.234(ariables declared with)-1.11 F F1 +(typeset)3.734 E F0 1.234(\(or the)3.734 F .001(bash synon)72 211.2 R(ym,)-.15 +E F1(local)2.501 E F0 .001(\), ha)B .301 -.15(ve a s)-.2 H .001 +(cope restricted to the function and its descendents, and may shado).15 F 2.502 +(wv)-.25 G(ariables)472.9 211.2 Q(de\214ned by the in)72 223.2 Q -.2(vo)-.4 G +(king shell.).2 E(Local v)5 E(ariables are remo)-.25 E -.15(ve)-.15 G 2.5(dw) +.15 G(hen a function completes.)317.75 223.2 Q F1 2.5(4.3. F)72 247.2 R(eatur) +-.25 E(es Unique to bash)-.18 E F0(Naturally)97 262.8 Q 2.895(,b)-.65 G .395 +(ash includes features not in sh or ksh.)144.515 262.8 R .395 +(This section discusses some of the features which)5.395 F(mak)72 274.8 Q 2.986 +(eb)-.1 G .486(ash unique.)101.546 274.8 R .486(Most of them pro)5.486 F .486 +(vide impro)-.15 F -.15(ve)-.15 G 2.986(di).15 G(nteracti)288.098 274.8 Q .787 +-.15(ve u)-.25 H .487(se, b).15 F .487(ut a fe)-.2 F 2.987(wp)-.25 G .487 +(rogramming impro)394.653 274.8 R -.15(ve)-.15 G(ments).15 E +(are present as well.)72 286.8 Q +(Full descriptions of these features can be found in the bash documentation.)5 +E F1 2.5(4.3.1. Startup)72 310.8 R(Files)2.5 E F0 .281(Bash e)97 326.4 R -.15 +(xe)-.15 G .281(cutes startup \214les dif).15 F .281 +(ferently than other shells.)-.25 F .281(The bash beha)5.281 F .28 +(vior is a compromise between)-.2 F .116 +(the csh principle of startup \214les with \214x)72 338.4 R .116(ed names e) +-.15 F -.15(xe)-.15 G .116(cuted for each shell and the sh `).15 F +(`minimalist')-.74 E 2.616('b)-.74 G(eha)472.26 338.4 Q(vior)-.2 E(.)-.55 E +2.956(An interacti)72 350.4 R 3.256 -.15(ve i)-.25 H 2.956 +(nstance of bash started as a login shell reads and e).15 F -.15(xe)-.15 G +(cutes).15 E/F2 10/Times-Italic@0 SF(~/.bash_pr)5.455 E(o\214le)-.45 E F0 2.955 +(\(the \214le)7.121 F F2(.bash_pr)72 362.4 Q(o\214le)-.45 E F0 .835 +(in the user')5 F 3.335(sh)-.55 G .835(ome directory\), if it e)187.385 362.4 R +3.335(xists. An)-.15 F(interacti)3.335 E 1.135 -.15(ve n)-.25 H .835 +(on-login shell reads and e).15 F -.15(xe)-.15 G(cutes).15 E F2(~/.bashr)72 +374.4 Q(c)-.37 E F0 5.538(.A)1.666 G(non-interacti)127.422 374.4 Q .838 -.15 +(ve s)-.25 H .538(hell \(one be).15 F .538(gun to e)-.15 F -.15(xe)-.15 G .538 +(cute a shell script, for e).15 F .537(xample\) reads no \214x)-.15 F .537 +(ed startup)-.15 F .139(\214le, b)72 386.4 R .139(ut uses the v)-.2 F .139 +(alue of the v)-.25 F(ariable)-.25 E F1(ENV)2.639 E F0 2.639(,i)C 2.639(fs) +253.361 386.4 S .139(et, as the name of a startup \214le.)263.22 386.4 R .139 +(The ksh practice of reading)5.139 F F1($ENV)72 398.4 Q F0 .69(for e)3.19 F +-.15(ve)-.25 G .69(ry shell, with the accompan).15 F .689(ying dif)-.15 F .689 +(\214culty of de\214ning the proper v)-.25 F .689(ariables and functions for) +-.25 F(interacti)72 410.4 Q .946 -.15(ve a)-.25 H .646(nd non-interacti).15 F +.946 -.15(ve s)-.25 H .646(hells or ha).15 F .646 +(ving the \214le read only for interacti)-.2 F .946 -.15(ve s)-.25 H .646 +(hells, w).15 F .646(as considered too)-.1 F(comple)72 422.4 Q(x.)-.15 E F1 2.5 +(4.3.2. New)72 446.4 R(Builtin Commands)2.5 E F0 1.119(There are a fe)97 462 R +3.619(wb)-.25 G 1.118(uiltins which are ne)170.986 462 R 3.618(wo)-.25 G 3.618 +(rh)268.528 462 S -2.25 -.2(av e)280.476 462 T 1.118(been e)3.818 F 1.118 +(xtended in bash.)-.15 F(The)6.118 E F1(enable)3.618 E F0 -.2(bu)3.618 G 1.118 +(iltin allo).2 F(ws)-.25 E -.2(bu)72 474 S .736 +(iltin commands to be turned on and of).2 F 3.236(fa)-.25 G(rbitrarily)250.198 +474 Q 5.736(.T)-.65 G 3.237(ou)298.644 474 S .737(se the v)311.881 474 R .737 +(ersion of)-.15 F F2(ec)3.237 E(ho)-.15 E F0 .737(found in a user')4.903 F +3.237(ss)-.55 G(earch)482.35 474 Q .013(path rather than the bash b)72 486 R +(uiltin,)-.2 E/F3 10/Courier@0 SF .013(enable -n echo)2.513 F F0(suf)2.513 E +2.513(\214ces. The)-.25 F F1(help)2.513 E F0 -.2(bu)2.513 G .013(iltin pro).2 F +.013(vides quick synopses of)-.15 F 1.382(the shell f)72 498 R 1.382 +(acilities without requiring access to a manual page.)-.1 F F1(Builtin)6.382 E +F0 1.383(is similar to)3.882 F F1(command)3.883 E F0 1.383(in that it)3.883 F +.342(bypasses shell functions and directly e)72 510 R -.15(xe)-.15 G .342 +(cutes b).15 F .342(uiltin commands.)-.2 F .342 +(Access to a csh-style stack of directories)5.342 F .072(is pro)72 522 R .073 +(vided via the)-.15 F F1(pushd)2.573 E F0(,)A F1(popd)2.573 E F0 2.573(,a)C(nd) +211.197 522 Q F1(dirs)2.573 E F0 -.2(bu)2.573 G(iltins.).2 E F1(Pushd)5.073 E +F0(and)2.573 E F1(popd)2.573 E F0 .073(insert and remo)2.573 F .373 -.15(ve d) +-.15 H .073(irectories from the).15 F .094(stack, respecti)72 534 R -.15(ve) +-.25 G(ly).15 E 2.594(,a)-.65 G(nd)154.448 534 Q F1(dirs)2.594 E F0 .094 +(lists the stack contents.The)2.594 F F1(suspend)2.594 E F0 .094 +(command will stop the shell process when)2.594 F 1.329(job control is acti)72 +546 R -.15(ve)-.25 G 3.829(;m).15 G 1.329(ost other shells do not allo)169.136 +546 R 3.829(wt)-.25 G(hemselv)294.64 546 Q 1.33(es to be stopped lik)-.15 F +3.83(et)-.1 G(hat.)421.31 546 Q F1 -.74(Ty)6.33 G(pe,).74 E F0 1.33(the bash) +3.83 F(answer to)72 558 Q F1(which)2.5 E F0(and)2.5 E F1(whence,)2.5 E F0(sho) +2.5 E(ws what will happen when a w)-.25 E(ord is typed as a command:)-.1 E F3 6 +($t)97 576 S(ype export)115 576 Q(export is a shell builtin)97 588 Q 6($t)97 +600 S(ype -t export)115 600 Q(builtin)97 612 Q 6($t)97 624 S(ype bash)115 624 Q +(bash is /bin/bash)97 636 Q 6($t)97 648 S(ype cd)115 648 Q(cd is a function)97 +660 Q(cd \(\))97 672 Q({)97 684 Q(builtin cd "$@" && xtitle $HOST: $PWD)121 696 +Q(})97 708 Q EP +%%Page: 7 7 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-7-)279.67 48 S -1.11(Va)72 84 S .682 +(rious modes tell what a command w)1.11 F .681(ord is \(reserv)-.1 F .681(ed w) +-.15 F .681(ord, alias, function, b)-.1 F .681(uiltin, or \214le\) or which v) +-.2 F(er)-.15 E(-)-.2 E 1.15(sion of a command will be e)72 96 R -.15(xe)-.15 G +1.15(cuted based on a user').15 F 3.65(ss)-.55 G 1.15(earch path.)305.7 96 R +1.15(Some of this functionality has been)6.15 F +(adopted by POSIX.2 and folded into the)72 108 Q/F1 10/Times-Bold@0 SF(command) +2.5 E F0(utility)2.5 E(.)-.65 E F1 2.5(4.3.3. Editing)72 132 R(and Completion) +2.5 E F0 .682(One area in which bash shines is command line editing.)97 147.6 R +.682(Bash uses the)5.682 F/F2 10/Times-Italic@0 SF -.37(re)3.182 G(adline).37 E +F0 .682(library to read and)4.848 F .102(edit lines when interacti)72 159.6 R +-.15(ve)-.25 G 5.102(.R).15 G .103(eadline is a po)191.438 159.6 R .103 +(werful and \215e)-.25 F .103(xible input f)-.15 F .103 +(acility that a user can con\214gure to his)-.1 F 2.506(tastes. It)72 171.6 R +(allo)2.506 E .006(ws lines to be edited using either emacs or vi commands, wh\ +ere those commands are appropri-)-.25 F 2.994(ate. The)72 183.6 R .494 +(full capability of emacs is not present \255 there is no w)2.994 F .495 +(ay to e)-.1 F -.15(xe)-.15 G .495(cute a named command with M-x,).15 F .222 +(for instance \255 b)72 195.6 R .222(ut the e)-.2 F .222 +(xisting commands are more than adequate.)-.15 F .221 +(The vi mode is compliant with the com-)5.222 F +(mand line editing standardized by POSIX.2.)72 207.6 Q 1.69 +(Readline is fully customizable.)97 223.2 R 1.691 +(In addition to the basic commands and k)6.69 F 1.991 -.15(ey b)-.1 H 1.691 +(indings, the library).15 F(allo)72 235.2 Q .83 +(ws users to de\214ne additional k)-.25 F 1.13 -.15(ey b)-.1 H .83 +(indings using a startup \214le.).15 F(The)5.83 E F2(inputr)3.329 E(c)-.37 E F0 +.829(\214le, which def)4.995 F .829(aults to the)-.1 F(\214le)72 247.2 Q F2 +(~/.inputr)4.287 E(c)-.37 E F0 4.287(,i)1.666 G 4.287(sr)137.43 247.2 S 1.788(\ +ead each time readline initializes, permitting users to maintain a consistent \ +interf)148.937 247.2 R(ace)-.1 E .547(across a set of programs.)72 259.2 R .546 +(Readline includes an e)5.546 F .546(xtensible interf)-.15 F .546 +(ace, so each program using the library can)-.1 F .23(add its o)72 271.2 R .23 +(wn bindable commands and program-speci\214c k)-.25 F .531 -.15(ey b)-.1 H +2.731(indings. Bash).15 F .231(uses this f)2.731 F .231 +(acility to add bindings)-.1 F(that perform history e)72 283.2 Q +(xpansion or shell w)-.15 E(ord e)-.1 E(xpansions on the current input line.) +-.15 E .707(Readline interprets a number of v)97 298.8 R .706 +(ariables which further tune its beha)-.25 F(vior)-.2 E 5.706(.V)-.55 G .706 +(ariables e)408.432 298.8 R .706(xist to control)-.15 F .157 +(whether or not eight-bit characters are directly read as input or con)72 310.8 +R -.15(ve)-.4 G .158(rted to meta-pre\214x).15 F .158(ed k)-.15 F .458 -.15 +(ey s)-.1 H .158(equences \(a).15 F(meta-pre\214x)72 322.8 Q 1.575(ed k)-.15 F +1.875 -.15(ey s)-.1 H 1.575 +(equence consists of the character with the eighth bit zeroed, preceded by the) +.15 F F2(meta-)4.074 E(pr)72 334.8 Q(e\214x)-.37 E F0(character)4.45 E 2.784 +(,u)-.4 G .284(sually escape, which selects an alternate k)145.374 334.8 R -.15 +(ey)-.1 G .285(map\), to decide whether to output characters).15 F .485 +(with the eighth bit set directly or as a meta-pre\214x)72 346.8 R .485(ed k) +-.15 F .784 -.15(ey s)-.1 H .484(equence, whether or not to wrap to a ne).15 F +2.984(ws)-.25 G(creen)482.35 346.8 Q .157 +(line when a line being edited is longer than the screen width, the k)72 358.8 +R -.15(ey)-.1 G .158(map to which subsequent k).15 F .458 -.15(ey b)-.1 H +(indings).15 E .531(should apply)72 370.8 R 3.031(,o)-.65 G 3.031(re)133.802 +370.8 S -.15(ve)144.353 370.8 S 3.031(nw).15 G .531 +(hat happens when readline w)168.894 370.8 R .531(ants to ring the terminal') +-.1 F 3.03(sb)-.55 G 3.03(ell. All)399.37 370.8 R .53(of these v)3.03 F +(ariables)-.25 E(can be set in the inputrc \214le.)72 382.8 Q .284 +(The startup \214le understands a set of C preprocessor)97 398.4 R(-lik)-.2 E +2.785(ec)-.1 G .285(onditional constructs which allo)329.49 398.4 R 2.785(wv) +-.25 G(ariables)472.9 398.4 Q .12(or k)72 410.4 R .42 -.15(ey b)-.1 H .119(ind\ +ings to be assigned based on the application using readline, the terminal curr\ +ently being used, or).15 F .316(the editing mode.)72 422.4 R .317 +(Users can add program-speci\214c bindings to mak)5.317 F 2.817(et)-.1 G .317 +(heir li)352.808 422.4 R -.15(ve)-.25 G 2.817(se).15 G 2.817(asier: here) +396.922 422.4 R .317(are bindings to)2.817 F(edit the v)72 434.4 Q(alue of)-.25 +E F1 -.74(PA)2.5 G(TH)-.21 E F0(and double-quote the current or pre)2.5 E +(vious w)-.25 E(ord:)-.1 E/F3 10/Courier@0 SF 6(#M)97 452.4 S +(acros that are convenient for shell interaction)115 452.4 Q($if Bash)97 464.4 +Q 6(#e)97 476.4 S(dit the path)115 476.4 Q +("\\C-xp": "PATH=${PATH}\\e\\C-e\\C-a\\ef\\C-f")97 488.4 Q 6(#p)97 500.4 S +(repare to type a quoted word -- insert open and close double quotes)115 500.4 +Q 6(#a)97 512.4 S(nd move to just after the open quote)115 512.4 Q +("\\C-x\\"": "\\"\\"\\C-b")97 524.4 Q 6(#Q)97 536.4 S +(uote the current or previous word)115 536.4 Q("\\C-xq": "\\eb\\"\\ef\\"")97 +548.4 Q($endif)97 560.4 Q F0 .322(There is a readline command to re-read the \ +\214le, so users can edit the \214le, change some bindings, and be)72 582 R +(gin)-.15 E(to use them almost immediately)72 594 Q(.)-.65 E .851 +(Bash implements the)97 609.6 R F1(bind)3.351 E F0 -.2(bu)3.351 G .851 +(iltin for more dyamic control of readline than the startup \214le permits.).2 +F F1(Bind)72 621.6 Q F0 .167(is used in se)2.667 F -.15(ve)-.25 G .167(ral w) +.15 F 2.667(ays. In)-.1 F F2(list)2.667 E F0 .167 +(mode, it can display the current k)4.333 F .466 -.15(ey b)-.1 H .166 +(indings, list all the readline edit-).15 F .149(ing directi)72 633.6 R -.15 +(ve)-.25 G 2.649(sa).15 G -.25(va)132.798 633.6 S .149 +(ilable for binding, list which k).25 F -.15(ey)-.1 G 2.649(si).15 G -1.9 -.4 +(nv o)282.352 633.6 T .349 -.1(ke a g).4 H -2.15 -.25(iv e).1 H 2.65(nd).25 G +(irecti)345.3 633.6 Q -.15(ve)-.25 G 2.65(,o).15 G 2.65(ro)385.04 633.6 S .15 +(utput the current set of k)396.02 633.6 R -.15(ey)-.1 G .526(bindings in a fo\ +rmat that can be incorporated directly into an inputrc \214le.)72 645.6 R(In) +5.526 E F2(batc)3.026 E(h)-.15 E F0 .526(mode, it reads a series)4.692 F .71 +(of k)72 657.6 R 1.01 -.15(ey b)-.1 H .71 +(indings directly from a \214le and passes them to readline.).15 F .71 +(In its most common usage,)5.71 F F1(bind)3.21 E F0(tak)3.21 E .71(es a)-.1 F +.534(single string and passes it directly to readline, which interprets the li\ +ne as if it had just been read from the)72 669.6 R(inputrc \214le.)72 681.6 Q +(Both k)5 E .3 -.15(ey b)-.1 H(indings and v).15 E +(ariable assignments can appear in the string gi)-.25 E -.15(ve)-.25 G 2.5(nt) +.15 G(o)424.4 681.6 Q F1(bind)2.5 E F0(.)A .401(The readline library also pro) +97 697.2 R .402(vides an interf)-.15 F .402(ace for)-.1 F F2(wor)2.902 E 2.902 +(dc)-.37 G(ompletion)328.546 697.2 Q F0 5.402(.W)C .402(hen the)385.888 697.2 R +F2(completion)2.902 E F0(character)4.568 E 1.261(\(usually T)72 709.2 R 1.261 +(AB\) is typed, readline looks at the w)-.93 F 1.26 +(ord currently being entered and computes the set of \214le-)-.1 F .523 +(names of which the current w)72 721.2 R .523(ord is a v)-.1 F .523 +(alid pre\214x.)-.25 F .524 +(If there is only one possible completion, the rest of the)5.523 F EP +%%Page: 8 8 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-8-)279.67 48 S .358 +(characters are inserted directly)72 84 R 2.858(,o)-.65 G .358(therwise the co\ +mmon pre\214x of the set of \214lenames is added to the current)205.232 84 R +-.1(wo)72 96 S 3.199(rd. A).1 F .699(second T)3.199 F .699(AB character entere\ +d immediately after a non-unique completion causes readline to list)-.93 F +1.814(the possible completions; there is an option to ha)72 108 R 2.113 -.15 +(ve t)-.2 H 1.813(he list displayed immediately).15 F 6.813(.R)-.65 G 1.813 +(eadline pro)436.517 108 R(vides)-.15 E .482 +(hooks so that applications can pro)72 120 R .482 +(vide speci\214c types of completion before the def)-.15 F .483 +(ault \214lename completion)-.1 F .132(is attempted.)72 132 R .132 +(This is quite \215e)5.132 F .132(xible, though it is not completely user)-.15 +F 2.632(-programmable. Bash,)-.2 F .132(for e)2.632 F .132(xample, can)-.15 F +.37(complete \214lenames, command names \(including aliases, b)72 144 R .37 +(uiltins, shell reserv)-.2 F .37(ed w)-.15 F .37(ords, shell functions, and)-.1 +F -.15(exe)72 156 S .424(cutables found in the \214le system\), shell v).15 F +.424(ariables, usernames, and hostnames.)-.25 F .423 +(It uses a set of heuristics)5.424 F(that, while not perfect, is generally qui\ +te good at determining what type of completion to attempt.)72 168 Q/F1 10 +/Times-Bold@0 SF 2.5(4.3.4. History)72 192 R F0 .255 +(Access to the list of commands pre)97 207.6 R .255(viously entered \(the)-.25 +F/F2 10/Times-Italic@0 SF .255(command history)2.755 F F0 2.756(\)i)C 2.756(sp) +399.236 207.6 S(ro)410.882 207.6 Q .256(vided jointly by bash)-.15 F .095 +(and the readline library)72 219.6 R 5.094(.B)-.65 G .094(ash pro)178.928 219.6 +R .094(vides v)-.15 F .094(ariables \()-.25 F F1(HISTFILE)A F0(,)A F1(HISTSIZE) +2.594 E F0 2.594(,a)C(nd)382.068 219.6 Q F1(HISTCONTR)2.594 E(OL)-.3 E F0 2.594 +(\)a)C .094(nd the)479.186 219.6 R F1(history)72 231.6 Q F0(and)2.825 E F1(fc) +2.825 E F0 -.2(bu)2.825 G .325(iltins to manipulate the history list.).2 F .325 +(The v)5.325 F .325(alue of)-.25 F F1(HISTFILE)2.825 E F0 .326 +(specifes the \214le where bash)2.826 F .128(writes the command history on e)72 +243.6 R .128(xit and reads it on startup.)-.15 F F1(HISTSIZE)5.128 E F0 .128 +(is used to limit the number of com-)2.628 F .346(mands sa)72 255.6 R -.15(ve) +-.2 G 2.846(di).15 G 2.846(nt)129.002 255.6 S .346(he history)139.628 255.6 R +(.)-.65 E F1(HISTCONTR)5.346 E(OL)-.3 E F0(pro)2.846 E .346 +(vides a crude form of control o)-.15 F -.15(ve)-.15 G 2.846(rw).15 G .346 +(hich commands are)425.548 255.6 R(sa)72 267.6 Q -.15(ve)-.2 G 2.905(do).15 G +2.905(nt)102.325 267.6 S .405(he history list: a v)113.01 267.6 R .405(alue of) +-.25 F F2(ignor)2.905 E(espace)-.37 E F0 .405(means to not sa)4.571 F .705 -.15 +(ve c)-.2 H .405(ommands which be).15 F .405(gin with a space; a)-.15 F -.25 +(va)72 279.6 S .339(lue of).25 F F2(ignor)2.839 E(edups)-.37 E F0 .339 +(means to not sa)4.505 F .64 -.15(ve c)-.2 H .34 +(ommands identical to the last command sa).15 F -.15(ve)-.2 G(d.).15 E F1 +(HISTCONTR)5.34 E(OL)-.3 E F0 -.1(wa)72 291.6 S 3.15(sn).1 G(amed)95.6 291.6 Q +F1(history_contr)3.15 E(ol)-.18 E F0 .65(in earlier v)3.15 F .649 +(ersions of bash; the old name is still accepted for backw)-.15 F .649 +(ards com-)-.1 F(patibility)72 303.6 Q 5.723(.T)-.65 G(he)121.803 303.6 Q F1 +(history)3.223 E F0 .724(command can read or write \214les containing the hist\ +ory list and display the current)3.223 F .895(list contents.)72 315.6 R(The) +5.895 E F1(fc)3.395 E F0 -.2(bu)3.395 G .895 +(iltin, adopted from POSIX.2 and the K).2 F .894(orn Shell, allo)-.35 F .894 +(ws display and re-e)-.25 F -.15(xe)-.15 G(cution,).15 E .461 +(with optional editing, of commands from the history list.)72 327.6 R .462 +(The readline library of)5.462 F .462(fers a set of commands to)-.25 F .657(se\ +arch the history list for a portion of the current input line or a string type\ +d by the user)72 339.6 R 5.657(.F)-.55 G(inally)445.836 339.6 Q 3.157(,t)-.65 G +(he)476.403 339.6 Q F2(his-)3.157 E(tory)72 351.6 Q F0(library)4.196 E 2.53(,g) +-.65 G .03(enerally incorporated directly into the readline library)128.346 +351.6 R 2.53(,i)-.65 G .03(mplements a f)350.636 351.6 R .031 +(acility for history recall,)-.1 F -.15(ex)72 363.6 S .594(pansion, and re-e) +.15 F -.15(xe)-.15 G .594(cution of pre).15 F .594(vious commands v)-.25 F .594 +(ery similar to csh \(`)-.15 F .593(`bang history')-.74 F .593 +(', so called because)-.74 F(the e)72 375.6 Q +(xclamation point introduces a history substitution\):)-.15 E/F3 10/Courier@0 +SF 6($e)97 393.6 S(cho a b c d e)115 393.6 Q 6(abcde)97 405.6 S 6($!)97 417.6 S +6(!fghi)115 417.6 S(echo a b c d e f g h i)97 429.6 Q 6(abcdefghi)97 441.6 S 6 +($!)97 453.6 S(-2)115 453.6 Q(echo a b c d e)97 465.6 Q 6(abcde)97 477.6 S 6 +($e)97 489.6 S(cho !-2:1-4)115 489.6 Q(echo a b c d)97 501.6 Q 6(abcd)97 513.6 +S F0 1.456(The command history is only sa)72 535.2 R -.15(ve)-.2 G 3.957(dw).15 +G 1.457(hen the shell is interacti)232.599 535.2 R -.15(ve)-.25 G 3.957(,s).15 +G 3.957(oi)352.804 535.2 S 3.957(ti)364.541 535.2 S 3.957(sn)374.058 535.2 S +1.457(ot a)386.905 535.2 R -.25(va)-.2 G 1.457(ilable for use by shell).25 F +(scripts.)72 547.2 Q F1 2.5(4.3.5. New)72 571.2 R(Shell V)2.5 E(ariables)-.92 E +F0 .701(There are a number of con)97 586.8 R -.15(ve)-.4 G .701(nience v).15 F +.701(ariables that bash interprets to mak)-.25 F 3.2(el)-.1 G .7(ife easier) +402.76 586.8 R 5.7(.T)-.55 G .7(hese include)453.59 586.8 R F1(FIGNORE)72 598.8 +Q F0 3.973(,w)C 1.473(hich is a set of \214lename suf)132.363 598.8 R<8c78>-.25 +E 1.474(es identifying \214les to e)-.15 F 1.474 +(xclude when completing \214lenames;)-.15 F F1(HOSTTYPE)72 610.8 Q F0 3.03(,w)C +.53(hich is automatically set to a string describing the type of hardw)139.21 +610.8 R .53(are on which bash is cur)-.1 F(-)-.2 E .76(rently e)72 622.8 R -.15 +(xe)-.15 G(cuting;).15 E F1(OSTYPE)3.26 E F0 3.26(,t)C 3.26(ow)191.76 622.8 S +.76(hich bash assigns a v)207.24 622.8 R .761(alue that identi\214es the v)-.25 +F .761(ersion of)-.15 F/F4 9/Times-Roman@0 SF(UNIX)3.261 E F0(it')3.261 E 3.261 +(sr)-.55 G(unning)476.22 622.8 Q 1.354 +(on \(great for putting architecture-speci\214c binary directories into the)72 +634.8 R F1 -.74(PA)3.854 G(TH)-.21 E F0 1.354(\); and)B F1(IGNOREEOF)3.854 E F0 +3.854(,w)C(hose)485.67 634.8 Q -.25(va)72 646.8 S .062 +(lue indicates the number of consecuti).25 F .362 -.15(ve E)-.25 H .062 +(OF characters that an interacti).15 F .362 -.15(ve s)-.25 H .062 +(hell will read before e).15 F .062(xiting \255)-.15 F .114(an easy w)72 658.8 +R .113(ay to k)-.1 F .113(eep yourself from being logged out accidentally)-.1 F +5.113(.T)-.65 G(he)344.285 658.8 Q F1(auto_r)2.613 E(esume)-.18 E F0 -.25(va) +2.613 G .113(riable alters the w).25 F(ay)-.1 E .409 +(the shell treats simple command names: if job control is acti)72 670.8 R -.15 +(ve)-.25 G 2.909(,a).15 G .409(nd this v)335.516 670.8 R .409 +(ariable is set, single-w)-.25 F .409(ord simple)-.1 F .17(commands without re\ +directions cause the shell to \214rst look for a suspended job with that name \ +before start-)72 682.8 R(ing a ne)72 694.8 Q 2.5(wp)-.25 G(rocess.)118.13 694.8 +Q EP +%%Page: 9 9 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-9-)279.67 48 S/F1 10/Times-Bold@0 SF 2.5 +(4.3.6. Brace)72 84 R(Expansion)2.5 E F0 .653(Since sh of)97 99.6 R .653 +(fers no con)-.25 F -.15(ve)-.4 G .653(nient w).15 F .653 +(ay to generate arbitrary strings that share a common pre\214x or suf)-.1 F +<8c78>-.25 E 1.893(\(pathname e)72 111.6 R 1.893 +(xpansion requires that the \214lenames e)-.15 F 1.892(xist\), bash implements) +-.15 F/F2 10/Times-Italic@0 SF(br)4.392 E 1.892(ace e)-.15 F(xpansion)-.2 E F0 +4.392(,ac)C(apability)469 111.6 Q(pick)72 123.6 Q .496(ed up from csh.)-.1 F +.496(Brace e)5.496 F .496(xpansion is similar to pathname e)-.15 F .496 +(xpansion, b)-.15 F .497(ut the strings generated need not)-.2 F 1.107 +(correspond to e)72 135.6 R 1.107(xisting \214les.)-.15 F 3.607(Ab)6.107 G +1.107(race e)207.655 135.6 R 1.107(xpression consists of an optional)-.15 F F2 +(pr)3.606 E(eamble)-.37 E F0 3.606(,f)1.666 G(ollo)419.286 135.6 Q 1.106 +(wed by a pair of)-.25 F 2.809 +(braces enclosing a series of comma-separated strings, and an optional)72 147.6 +R F2(postamble)5.31 E F0 7.81(.T)1.666 G 2.81(he preamble is)440.06 147.6 R(pr\ +epended to each string within the braces, and the postamble is then appended t\ +o each resulting string:)72 159.6 Q/F3 10/Courier@0 SF 6($e)97 177.6 S +(cho a{d,c,b}e)115 177.6 Q(ade ace abe)97 189.6 Q F1 2.5(4.3.7. Pr)72 219.6 R +(ompt Customization)-.18 E F0 .077(One of the more popular interacti)97 235.2 R +.376 -.15(ve f)-.25 H .076(eatures that bash pro).15 F .076 +(vides is the ability to customize the prompt.)-.15 F(Both)72 247.2 Q F1(PS1) +3.305 E F0(and)3.305 E F1(PS2,)3.305 E F0 .805 +(the primary and secondary prompts, are e)3.305 F .805 +(xpanded before being displayed.)-.15 F -.15(Pa)5.805 G(rameter).15 E .324 +(and v)72 259.2 R .324(ariable e)-.25 F .324 +(xpansion is performed when the prompt string is e)-.15 F .323 +(xpanded, so the v)-.15 F .323(alue of an)-.25 F 2.823(ys)-.15 G .323(hell v) +454.217 259.2 R(ariable)-.25 E .728(can be put into the prompt \(e.g.,)72 271.2 +R F1($SHL)3.228 E(VL)-.92 E F0 3.228(,w)C .728(hich indicates ho)258.564 271.2 +R 3.228(wd)-.25 G .729(eeply the current shell is nested\).)342.988 271.2 R +(Bash)5.729 E 1.895 +(specially interprets characters in the prompt string preceded by a backslash.) +72 283.2 R 1.895(Some of these backslash)6.895 F .874 +(escapes are replaced with the current time, the date, the current w)72 295.2 R +.874(orking directory)-.1 F 3.374(,t)-.65 G .874(he username, and the)416.958 +295.2 R .781(command number or history number of the command being entered.)72 +307.2 R .78(There is e)5.781 F -.15(ve)-.25 G 3.28(nab).15 G .78 +(ackslash escape to)429.13 307.2 R .007 +(cause the shell to change its prompt when running as root after an)72 319.2 R +F2(su)2.507 E F0 5.007(.B)C .008(efore printing each primary prompt,)360.388 +319.2 R .27(bash e)72 331.2 R .27(xpands the v)-.15 F(ariable)-.25 E F1(PR)2.77 +E(OMPT_COMMAND)-.3 E F0 .269(and, if it has a v)2.77 F .269(alue, e)-.25 F -.15 +(xe)-.15 G .269(cutes the e).15 F .269(xpanded v)-.15 F .269(alue as a)-.25 F +.04(command, allo)72 343.2 R .041(wing additional prompt customization.)-.25 F +-.15(Fo)5.041 G 2.541(re).15 G .041 +(xample, this assignment causes the current user)311.964 343.2 R(,)-.4 E .99 +(the current host, the time, the last component of the current w)72 355.2 R +.989(orking directory)-.1 F 3.489(,t)-.65 G .989(he le)402.954 355.2 R -.15(ve) +-.25 G 3.489(lo).15 G 3.489(fs)443.412 355.2 S .989(hell nesting,)454.121 355.2 +R(and the history number of the current command to be embedded into the primar\ +y prompt:)72 367.2 Q F3 6($P)97 385.2 S +(S1='\\u@\\h [\\t] \\W\($SHLVL:\\!\)\\$ ')115 385.2 Q +(chet@odin [21:03:44] documentation\(2:636\)$ cd ..)97 397.2 Q +(chet@odin [21:03:54] src\(2:637\)$)97 409.2 Q F0 .619 +(The string being assigned is surrounded by single quotes so that if it is e)72 +430.8 R(xported,)-.15 E F1(SHL)3.119 E(VL)-.92 E F0 .619(will be updated)3.119 +F(by a child shell:)72 442.8 Q F3 +(chet@odin [21:13:35] src\(2:638\)$ export PS1)97 460.8 Q +(chet@odin [21:17:40] src\(2:639\)$ bash)97 472.8 Q +(chet@odin [21:17:46] src\(3:696\)$)97 484.8 Q F0(The)72 506.4 Q F1(\\$)2.5 E +F0(escape is displayed as `)2.5 E(`)-.74 E F1($)A F0 1.48 -.74('' w)D +(hen running as a normal user).74 E 2.5(,b)-.4 G(ut as `)342.08 506.4 Q(`)-.74 +E F1(#)A F0 1.48 -.74('' w)D(hen running as root.).74 E F1 2.5(4.3.8. POSIX)72 +530.4 R(Mode)2.5 E F0 .46(Although bash is intended to be POSIX.2 compliant, t\ +here are areas in which the def)97 546 R .46(ault beha)-.1 F .46(vior is)-.2 F +1.168(not compatible with the standard.)72 558 R -.15(Fo)6.169 G 3.669(ru).15 G +1.169(sers who wish to operate in a strict POSIX.2 en)238.85 558 R 1.169 +(vironment, bash)-.4 F .61(implements a)72 570 R F2 .61(POSIX mode)3.11 F F0 +5.61(.W)C .61(hen this mode is acti)199.42 570 R -.15(ve)-.25 G 3.109(,b).15 G +.609(ash modi\214es its def)303.727 570 R .609(ault operation where it dif)-.1 +F(fers)-.25 E .066(from POSIX.2 to match the standard.)72 582 R .067 +(POSIX mode is entered when bash is started with the)5.066 F F1 .067(-o posix) +2.567 F F0(option)2.567 E .382(or when)72 594 R F1 .382(set -o posix)2.882 F F0 +.381(is e)2.881 F -.15(xe)-.15 G 2.881(cuted. F).15 F .381 +(or compatibility with other GNU softw)-.15 F .381 +(are that attempts to be POSIX.2)-.1 F 5.752 +(compliant, bash also enters POSIX mode if either of the v)72 606 R(ariables) +-.25 E F1(POSIX_PED)8.253 E(ANTIC)-.35 E F0(or)8.253 E F1(POSIXL)72 618 Q +(Y_CORRECT)-.92 E F0 1.179(is set when bash is started or assigned a v)3.679 F +1.178(alue during e)-.25 F -.15(xe)-.15 G 3.678(cution. When).15 F 1.178 +(bash is)3.678 F .218(started in POSIX mode, for e)72 630 R .218(xample, the) +-.15 F F1(kill)2.718 E F0 -.2(bu)2.718 G(iltin').2 E(s)-.55 E F12.718 E +F0 .218(option beha)2.718 F -.15(ve)-.2 G 2.718(sd).15 G(if)370.166 630 Q .219 +(ferently: it lists the names of all)-.25 F 1.084(signals on a single line sep\ +arated by spaces, rather than listing the signal names and their corresponding) +72 642 R(numbers.)72 654 Q .865(Some of the def)97 669.6 R .865(ault bash beha) +-.1 F .865(vior dif)-.2 F .865 +(fers from other shells as a result of the POSIX standard.)-.25 F -.15(Fo)5.866 +G(r).15 E 1.16(instance, bash includes the)72 681.6 R F1(!)3.66 E F0(reserv) +6.16 E 1.16(ed w)-.15 F 1.16(ord to ne)-.1 F -.05(ga)-.15 G 1.16 +(te the return status of a pipeline because it has been).05 F +(de\214ned by POSIX.2.)72 693.6 Q +(Neither sh nor ksh has implemented that feature.)5 E EP +%%Page: 10 10 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-1)277.17 48 S 2.5(0-)288 48 S/F1 10/Times-Bold@0 +SF 2.5(4.4. F)72 84 R(eatur)-.25 E(es Unique to ksh)-.18 E F0 .177 +(Ksh includes a number of features not in the currently-released v)97 99.6 R +.178(ersion of bash, v)-.15 F .178(ersion 1.14.)-.15 F(Unless)5.178 E .822 +(noted, none of these features is in the POSIX.2 standard.)72 111.6 R .821 +(Where appropriate the equi)5.821 F -.25(va)-.25 G .821(lent bash features).25 +F(are noted.)72 123.6 Q F1 2.5(4.4.1. The)72 147.6 R(ksh Language)2.5 E F0 +2.955(An)97 163.2 S .955 -.25(ew c)112.175 163.2 T .455(ompound command folds) +.25 F F1(test)2.955 E F0 .456(into the ksh language, delimited by the reserv) +2.955 F .456(ed w)-.15 F(ords)-.1 E F1([[)2.956 E F0(and)2.956 E F1(]])72 175.2 +Q F0 5.726(.T)C .726(he syntax is identical to)92.996 175.2 R F1(test)3.225 E +F0 .725(with a fe)3.225 F 3.225(wc)-.25 G .725 +(hanges: for instance, instead of)262.855 175.2 R F13.225 E F0(and)3.225 +E F13.225 E F0(,)A F1(&&)3.225 E F0(and)3.225 E/F2 10/Symbol SF +3.225 E F0(are)3.225 E 3.32(used. The)72 187.2 R -.1(wo)3.32 G .82(rds between) +.1 F F1([[)3.32 E F0(and)3.32 E F1(]])3.32 E F0 .82(are not processed for w) +3.32 F .82(ord splitting or \214lename generation.)-.1 F .82(The ne)5.82 F(w) +-.25 E .926 +(command does pattern matching as well as string comparison, a la the)72 199.2 +R F1(case)3.425 E F0 3.425(command. This)3.425 F(ne)3.425 E 3.425(wc)-.25 G +(ontrol)480.11 199.2 Q .165(structure does ha)72 211.2 R .465 -.15(ve t)-.2 H +.165(he adv).15 F .166(antage of reducing common ar)-.25 F .166 +(gument problems encountered using test \(e.g.)-.18 F F1(test)2.666 E +("$string")72 223.2 Q F0 2.928(,w)C(here)125.748 223.2 Q F1($string)2.928 E F0 +-.15(ex)2.928 G .428(pands to).15 F F12.928 E F0 .428(\), b)B .428 +(ut at the cost of bloating the language.)-.2 F .427(The POSIX.2 test algo-) +5.427 F 2.752(rithm that bash uses, along with some programmer care, alle)72 +235.2 R 2.752(viates those problems in a backw)-.25 F(ards-)-.1 E .854 +(compatible w)72 247.2 R .853(ay with no additions to the language.)-.1 F .853 +(The one capability of)5.853 F F1 .853([[ ]])3.353 F F0 .853(not a)3.353 F -.25 +(va)-.2 G .853(ilable in bash is its).25 F(ability to test whether an indi)72 +259.2 Q(vidual)-.25 E F1(set \255o)2.5 E F0(option is turned on or of)2.5 E(f.) +-.25 E .339(Other parts of the ksh language are not common to bash.)97 274.8 R +(The)5.34 E F1(\(\(...\)\))2.84 E F0(operator)5.34 E 2.84(,e)-.4 G(qui)419.33 +274.8 Q -.25(va)-.25 G .34(lent to).25 F F1 .34(let "...")2.84 F F0(,)A .197 +(is unique to ksh, as are the concept of co-processes and the)72 286.8 R F1 +(time)2.697 E F0 -.1(ke)2.696 G(yw)-.05 E .196 +(ord to time commands and pipelines.)-.1 F F1 2.5(4.4.2. Functions)72 310.8 R +(and Aliases)2.5 E F0 1.022(The K)97 326.4 R 1.022(orn shell has)-.35 F/F3 10 +/Times-Italic@0 SF(autoloaded)3.522 E F0 3.522(functions. A)3.522 F 1.022 +(function mark)3.522 F 1.022(ed as)-.1 F F3(autoload)3.522 E F0 1.022 +(is not de\214ned until it is)5.188 F 1.042(\214rst e)72 338.4 R -.15(xe)-.15 G +3.542(cuted. When).15 F 1.042(such a function is e)3.542 F -.15(xe)-.15 G 1.042 +(cuted, a search is made through the directories in).15 F F1(FP)3.541 E -.95 +(AT)-.74 G(H).95 E F0(\(a)3.541 E .27 +(colon-separated list of directories similar to)72 350.4 R F1 -.74(PA)2.77 G +(TH)-.21 E F0 2.77(\)f)C .27(or a \214le with the same name as the function.) +285.78 350.4 R .27(That \214le)5.27 F .548(is then read in as with the)72 362.4 +R F1(.)3.881 E F0 .547(command; presumably the function is de\214ned therein.) +3.047 F .547(There is a pair of shell)5.547 F .886 +(functions included in the bash distrib)72 374.4 R .886(ution \()-.2 F F3 -.2 +(ex)C(amples/functions/autoload).2 E F0 5.886(\)t)C .886(hat pro)378.35 374.4 R +.886(vide much of this func-)-.15 F +(tionality without changing the shell itself.)72 386.4 Q .116 +(Ksh functions are scoped in such a w)97 402 R .116(ay that the en)-.1 F .116 +(vironment in which the)-.4 F 2.616(ya)-.15 G .116(re e)405.144 402 R -.15(xe) +-.15 G .115(cuted is closer to a).15 F .827(shell script en)72 414 R 3.327 +(vironment. Bash)-.4 F .827(uses the POSIX.2 scoping rules, which mak)3.327 F +3.327(et)-.1 G .827(he function e)392.517 414 R -.15(xe)-.15 G .828(cution en) +.15 F(vi-)-.4 E 1.2(ronment an e)72 426 R 1.2(xact cop)-.15 F 3.7(yo)-.1 G 3.7 +(ft)174.86 426 S 1.199(he shell en)184.67 426 R 1.199 +(vironment with the replacement of the shell')-.4 F 3.699(sp)-.55 G 1.199 +(ositional paramters)426.421 426 R(with the function ar)72 438 Q 2.5 +(guments. K)-.18 F +(orn shell functions do not share options or traps with the in)-.35 E -.2(vo) +-.4 G(king shell.).2 E .451(Ksh has)97 453.6 R F3(tr)2.951 E(ac)-.15 E -.1(ke) +-.2 G(d).1 E F0 .452(aliases, which alias a command name to its full pathname.) +2.952 F .452(Bash has true command)5.452 F(hashing.)72 465.6 Q F1 2.5 +(4.4.3. Arrays)72 489.6 R F0 .246 +(Arrays are an aspect of ksh that has no real bash equi)97 505.2 R -.25(va)-.25 +G 2.746(lent. The).25 F 2.746(ya)-.15 G .246(re easy to create and manipulate:) +371.42 505.2 R 1.637 +(an array is created automatically by using subscript assignment \()72 517.2 R +F1(name)A F0([)A F3(inde)A(x)-.2 E F0(]=)A F1 -.1(va)C(lue).1 E F0 1.637 +(\), and an)B 4.137(yv)-.15 G(ariable)476.79 517.2 Q 1.967 +(may be referred to as an array)72 529.2 R 6.967(.K)-.65 G 1.967(sh arrays, ho) +219.229 529.2 R(we)-.25 E -.15(ve)-.25 G 2.767 -.4(r, h).15 H -2.25 -.2(av e).4 +H(se)4.667 E -.15(ve)-.25 G 1.967(ral anno).15 F 1.967(ying limitations: the) +-.1 F 4.466(ym)-.15 G 1.966(ay be)480.654 529.2 R(inde)72 541.2 Q -.15(xe)-.15 +G 3.498(do).15 G .998(nly up to 512 or 1024 elements, depending on ho)111.858 +541.2 R 3.498(wt)-.25 G .999(he shell is compiled, and there is only the) +330.188 541.2 R(clumsy)72 553.2 Q F1 .223(set -A)2.723 F F0 .223 +(to assign a list of v)2.723 F .223(alues sequentially)-.25 F 5.223(.D)-.65 G +.223(espite these limits, arrays are useful, if underutilized)293.31 553.2 R +(by shell programmers.)72 565.2 Q F1 2.5(4.4.4. Builtin)72 589.2 R(Commands)2.5 +E F0 .112(Some of the b)97 604.8 R .112(uiltin commands ha)-.2 F .412 -.15 +(ve b)-.2 H .112(een e).15 F .112(xtended or are ne)-.15 F 2.612(wi)-.25 G +2.613(nk)351.402 604.8 S 2.613(sh. The)364.015 604.8 R F1(print)2.613 E F0 -.2 +(bu)2.613 G .113(iltin w).2 F .113(as included)-.1 F .242(to w)72 616.8 R .242 +(ork around the incompatibilities and limitations of)-.1 F F1(echo)2.741 E F0 +5.241(.T)C(he)328.234 616.8 Q F1(whence)2.741 E F0 .241(command tells what w) +2.741 F .241(ould hap-)-.1 F .418(pen if each ar)72 628.8 R .418 +(gument were typed as a command name.)-.18 F(The)5.418 E F1(cd)2.919 E F0 -.2 +(bu)2.919 G .419(iltin has been e).2 F .419(xtended to tak)-.15 F 2.919(eu)-.1 +G 2.919(pt)470.482 628.8 S 2.919(ot)481.181 628.8 S -.1(wo)491.88 628.8 S(ar)72 +640.8 Q 1.425(guments: if tw)-.18 F 3.925(oa)-.1 G -.18(rg)153.485 640.8 S +1.424(uments are supplied, the second is substituted for the \214rst in the cu\ +rrent directory).18 F 2.294 +(name and the shell changes to the resultant directory name.)72 652.8 R 2.295 +(The ksh)7.294 F F1(trap)4.795 E F0 -.2(bu)4.795 G 2.295(iltin accepts).2 F F1 +(ERR)4.795 E F0(and)4.795 E F1(DEB)72 664.8 Q(UG)-.1 E F0 .15(as trap names.) +2.65 F(The)5.15 E F1(ERR)2.65 E F0 .15(trap is e)2.65 F -.15(xe)-.15 G .15 +(cuted when a command f).15 F(ails;)-.1 E F1(DEB)2.65 E(UG)-.1 E F0 .15(is e) +2.65 F -.15(xe)-.15 G .15(cuted after e).15 F -.15(ve)-.25 G(ry).15 E +(simple command.)72 676.8 Q .05(The bash distrib)97 692.4 R .05 +(ution includes shell functions that implement)-.2 F F1(print)2.55 E F0(and) +2.55 E F1(whence)2.55 E F0 .05(and the e)2.55 F .05(xtensions to)-.15 F F1(cd) +72 704.4 Q F0(.)A EP +%%Page: 11 11 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-1)277.17 48 S 2.5(1-)288 48 S/F1 10/Times-Bold@0 +SF 2.5(4.4.5. Expansion)72 84 R F0 .282(The ksh \214lename generation \()97 +99.6 R/F2 10/Times-Italic@0 SF(globbing)A F0 2.782(\)f)C .282(acilities ha) +262.45 99.6 R .581 -.15(ve b)-.2 H .281(een e).15 F .281(xtended be)-.15 F .281 +(yond their bash and sh coun-)-.15 F 3.68(terparts. In)72 111.6 R 1.181 +(this area, ksh can be thought of as)3.681 F F2 -.4(eg)3.681 G -.37(re).4 G(p) +.37 E F0 1.181(to the bash)5.347 F F2(gr)3.681 E(ep)-.37 E F0 6.181(.K)1.666 G +1.181(sh globbing of)382.406 111.6 R 1.181(fers things lik)-.25 F(e)-.1 E 1.018 +(alternation, the ability to match zero or more instances of a pattern, and th\ +e ability to match e)72 123.6 R 1.018(xactly one)-.15 F(occurrence of an)72 +135.6 Q 2.5(yo)-.15 G 2.5(fal)150.98 135.6 S(ist of patterns.)166.53 135.6 Q F1 +2.5(4.4.6. Startup)72 159.6 R(Files)2.5 E F0 .977(Ksh and bash e)97 175.2 R +-.15(xe)-.15 G .977(cute startup \214les dif).15 F(ferently)-.25 E 5.977(.K) +-.65 G .977(sh e)297.879 175.2 R(xpands)-.15 E F1(ENV)3.478 E F0 .978 +(and sources the \214le it names for)3.478 F -2.15 -.25(ev e)72 187.2 T 1.85 +(ry shell.).25 F 1.85(Bash sources)6.85 F F1($ENV)4.35 E F0 1.85 +(only in non-interacti)4.35 F 2.15 -.15(ve s)-.25 H 1.85(hells; interacti).15 F +2.15 -.15(ve s)-.25 H 1.85(hells source \214x).15 F 1.85(ed \214les, as)-.15 F +-.15(ex)72 199.2 S 1.285(plained in the pre).15 F 1.285(vious section.)-.25 F +1.285(The POSIX standard has speci\214ed the ksh beha)6.285 F(vior)-.2 E 3.785 +(,s)-.4 G 3.785(ob)441.545 199.2 S 1.285(ash acts the)455.33 199.2 R +(same as ksh if started with the)72 211.2 Q F1(\255posix)2.5 E F0(or)2.5 E F1 +(\255o posix)2.5 E F0(options.)2.5 E F1 2.5(4.4.7. History)72 235.2 R F0 +(Finally)97 250.8 Q 3.372(,t)-.65 G .872(he ksh history implementation dif) +133.342 250.8 R .871(fers slightly from bash.)-.25 F .871 +(Each instance of bash k)5.871 F .871(eeps the)-.1 F .633 +(history list in memory and of)72 262.8 R .633(fers options to the)-.25 F F1 +(history)3.133 E F0 -.2(bu)3.133 G .634 +(iltin to write the list to or read it from a named).2 F 3.216(\214le. Ksh)72 +274.8 R -.1(ke)3.216 G .716 +(eps the history in a \214le, which it accesses each time a command is sa).1 F +-.15(ve)-.2 G 3.215(dt).15 G 3.215(oo)426.445 274.8 S 3.215(rr)439.66 274.8 S +(etrie)449.535 274.8 Q -.15(ve)-.25 G 3.215(df).15 G(rom)487.89 274.8 Q .338 +(the history)72 286.8 R 5.338(.K)-.65 G .338 +(sh history \214les may be shared among dif)129.246 286.8 R .338 +(ferent concurrent instances of ksh, which could be a)-.25 F +(bene\214t to the user)72 298.8 Q(.)-.55 E F1 2.5(5. F)72 322.8 R(eatur)-.25 E +(es in Bash-2.0)-.18 E F0 .657(The ne)97 338.4 R .657 +(xt release of bash, 2.0, will be a major o)-.15 F -.15(ve)-.15 G 3.157 +(rhaul. It).15 F .656(will include man)3.157 F 3.156(yn)-.15 G 1.156 -.25(ew f) +419.532 338.4 T .656(eatures, for both).25 F .705(programming and interacti)72 +350.4 R 1.005 -.15(ve u)-.25 H 3.205(se. Redundant).15 F -.15(ex)3.205 G .705 +(isting functions will be remo).15 F -.15(ve)-.15 G 3.206(d. There).15 F .706 +(are se)3.206 F -.15(ve)-.25 G .706(ral cases).15 F 1.34(where bash treats a v) +72 362.4 R 1.34(ariable specially to enable functionality a)-.25 F -.25(va)-.2 +G 1.34(ilable another w).25 F 1.34(ay \()-.1 F F1($nolinks)A F0(vs.)3.84 E F1 +1.34(set -o)3.84 F(ph)72 374.4 Q(ysical)-.15 E F0 2.5(,f)C(or e)115.19 374.4 Q +(xample\); the special treatment of the v)-.15 E(ariable name will be remo)-.25 +E -.15(ve)-.15 G(d.).15 E F1 2.5(5.1. Arrays)72 398.4 R F0 .546(Bash-2.0 will \ +include arrays which are a superset of those in ksh, with the size limitations\ + remo)97 414 R -.15(ve)-.15 G(d.).15 E(The)72 426 Q F1(declar)3.086 E(e)-.18 E +F0(,)A F1 -.18(re)3.086 G(adonly).18 E F0 3.086(,a)C(nd)174.768 426 Q F1 +(export)3.086 E F0 -.2(bu)3.086 G .586 +(iltins will accept options to specify arrays, and the).2 F F1 -.18(re)3.085 G +(ad).18 E F0 -.2(bu)3.085 G .585(iltin will).2 F(ha)72 438 Q .81 -.15(ve a)-.2 +H 3.01(no).15 G .51(ption to read a list of w)110.99 438 R .51 +(ords and assign them directly to an array)-.1 F 5.51(.T)-.65 G .51 +(here will also be a ne)386.23 438 R 3.01(wa)-.25 G(rray)487.9 438 Q F2 .262 +(compound assignment)72 450 R F0 .262(syntax a)2.762 F -.25(va)-.2 G .262 +(ilable for assignment statements and the).25 F F1(declar)2.761 E(e)-.18 E F0 +-.2(bu)2.761 G 2.761(iltin. This).2 F(ne)2.761 E 2.761(ws)-.25 G(yntax)481.78 +450 Q .441(has the form)72 462 R F2(name)2.941 E F0(=\()A F2(value1)A F0(...) +2.941 E F2(valueN)2.941 E F0 .441(\), where each)B F2(value)2.942 E F0 .442 +(has the form [)4.608 F F2(subscript)A F0(]=)A F2(string)A F0 5.442(.O)C .442 +(nly the)449.776 462 R F2(string)2.942 E F0 1.395(is required.)72 474 R 1.395 +(If the optional brack)6.395 F 1.395(ets and)-.1 F F2(subscript)3.894 E F0 +1.394(are included, that inde)3.894 F 3.894(xi)-.15 G 3.894(sa)388.714 474 S +1.394(ssigned to, otherwise the)400.938 474 R(inde)72 486 Q 3.656(xo)-.15 G +3.656(ft)102.726 486 S 1.156(he element assigned is the last inde)112.492 486 R +3.657(xa)-.15 G 1.157(ssigned to by the statement plus one.)272.917 486 R(Inde) +6.157 E 1.157(xing starts at)-.15 F 2.73(zero. The)72 498 R .23 +(same syntax is accepted by)2.73 F F1(declar)2.73 E(e)-.18 E F0 5.229(.I)C(ndi) +269.159 498 Q .229(vidual array elements may be assigned to using the ksh)-.25 +F F2(name)72 510 Q F0([)A F2(subscript)A F0(]=)A F2(value)A F0(.)A F1 2.5 +(5.2. Dynamic)72 534 R(Loading)2.5 E F0 .348(On systems that support the)97 +549.6 R F2(dlopen)2.848 E F0 .349(\(3\) library function, bash-2.0 will allo)B +2.849(wn)-.25 G .849 -.25(ew b)407.504 549.6 T .349(uiltins to be loaded).05 F +.049(into a running shell from a shared object \214le.)72 561.6 R .049(The ne) +5.049 F 2.549(wb)-.25 G .049(uiltins will ha)298.999 561.6 R .348 -.15(ve a)-.2 +H .048(ccess to the rest of the shell f).15 F(acil-)-.1 E .649(ities, b)72 +573.6 R .649(ut programmers will be subject to a fe)-.2 F 3.149(ws)-.25 G .649 +(tructural rules.)269.591 573.6 R .65(This will be pro)5.65 F .65 +(vided via a ne)-.15 F 3.15(wo)-.25 G .65(ption to)472.51 573.6 R F1(enable)72 +585.6 Q F0(.)A F1 2.5(5.3. Builtins)72 609.6 R F0 .889(Some of the e)97 625.2 R +.889(xisting b)-.15 F .889(uiltins will change in bash-2.0.)-.2 F .888(As pre) +5.888 F .888(viously noted,)-.25 F F1(declar)3.388 E(e)-.18 E F0(,)A F1(export) +3.388 E F0(,)A F1 -.18(re)3.388 G(ad-).18 E(only)72 637.2 Q F0 2.873(,a)C(nd) +100.153 637.2 Q F1 -.18(re)2.873 G(ad).18 E F0 .373(will accept ne)2.873 F +2.873(wo)-.25 G .374(ptions to specify arrays.)206.288 637.2 R(The)5.374 E F1 +(jobs)2.874 E F0 -.2(bu)2.874 G .374(iltin will be able to list only stopped).2 +F .323(or running jobs.)72 649.2 R(The)5.322 E F1(enable)2.822 E F0 .322 +(command will tak)2.822 F 2.822(ean)-.1 G -.25(ew)282.84 649.2 S F13.072 +E F0 .322(option to restrict its actions to the POSIX.2)2.822 F F2(spe-)2.822 E +(cial)72 661.2 Q F0 -.2(bu)3.14 G(iltins.).2 E F1(Kill)5.64 E F0 .64 +(will be able to list signal numbers corresponding to indi)3.14 F .64 +(vidual signal names.)-.25 F .64(The read-)5.64 F .703(line library interf)72 +673.2 R(ace,)-.1 E F1(bind)3.203 E F0 3.203(,w)C .703(ill ha)193.032 673.2 R +1.003 -.15(ve a)-.2 H 3.203(no).15 G .703(ption to remo)243.951 673.2 R 1.003 +-.15(ve t)-.15 H .703(he binding for an).15 F 3.203(yk)-.15 G 1.002 -.15(ey s) +398.032 673.2 T .702(equence \(which is not).15 F +(the same as binding it to self-insert\).)72 685.2 Q .494(There will be tw)97 +700.8 R 2.994(on)-.1 G .994 -.25(ew b)177.196 700.8 T .495 +(uiltin commands in bash-2.0.).05 F(The)5.495 E F1(diso)2.995 E(wn)-.1 E F0 +.495(command will remo)2.995 F .795 -.15(ve j)-.15 H .495(obs from).15 F(bash') +72 712.8 Q 3.445(si)-.55 G .945(nternal jobs table when job control is acti) +103.225 712.8 R -.15(ve)-.25 G 5.945(.A).15 G(diso)303.25 712.8 Q .944 +(wned job will not be listed by the jobs com-)-.25 F .666(mand, nor will its e) +72 724.8 R .666(xit status be reported.)-.15 F(Diso)5.667 E .667 +(wned jobs will not be sent a)-.25 F F1(SIGHUP)3.167 E F0 .667 +(when an interacti)3.167 F -.15(ve)-.25 G EP +%%Page: 12 12 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-1)277.17 48 S 2.5(2-)288 48 S .688(shell e)72 84 R +3.187(xits. Most)-.15 F .687(of the shell')3.187 F 3.187(so)-.55 G .687 +(ptional or)205.423 84 R/F1 10/Times-Italic@0 SF(to)3.187 E -.1(gg)-.1 G(led).1 +E F0 .687(functionality will be folded into the ne)3.187 F(w)-.25 E/F2 10 +/Times-Bold@0 SF(shopt)3.187 E F0 -.2(bu)3.187 G(iltin.).2 E(Man)72 96 Q 3.714 +(yo)-.15 G 3.714(ft)103.894 96 S 1.214(he v)113.718 96 R 1.214 +(ariables which alter the shell')-.25 F 3.714(sb)-.55 G(eha)266.282 96 Q 1.214 +(vior when set \(re)-.2 F -.05(ga)-.15 G 1.214(rdless of their v).05 F 1.215 +(alue\) will be made)-.25 F 6(options settable with)72 108 R F2(shopt)8.5 E F0 +11(.E)C 6(xamples of such v)218.23 108 R 6(ariables include)-.25 F F2(allo)8.5 +E(w_null_glob_expansion)-.1 E F0(,)A F2(glob_dot_\214lenames)72 120 Q F0 2.5 +(,a)C(nd)163.67 120 Q F2(MAIL_W)2.5 E(ARNING)-1.2 E F0(.)A F2 2.5(5.4. V)72 144 +R(ariables and V)-.92 E(ariable Expansion)-.92 E F0 .047 +(Bash-2.0 will implement se)97 159.6 R -.15(ve)-.25 G .048(ral ne).15 F 2.548 +(wv)-.25 G .048(ariable e)252.988 159.6 R 2.548(xpansions. These)-.15 F .048 +(will answer se)2.548 F -.15(ve)-.25 G .048(ral of the most per).15 F(-)-.2 E +.213(sistant requests for ne)72 171.6 R 2.713(wf)-.25 G 2.713(eatures. It) +172.582 171.6 R .213(will be possible to `)2.713 F .212(`indirectly reference') +-.74 F 2.712('av)-.74 G .212(ariable with an e)398.534 171.6 R(xpansion,)-.15 E +(lik)72 183.6 Q 3.01(eu)-.1 G(sing)94.91 183.6 Q/F3 10/Courier@0 SF .51 +(eval \\$${name})3.01 F F0 .51(to reference a v)3.01 F .51(ariable named by) +-.25 F F3(${name})3.01 E F0 5.51(.E)C .51(xpansions will be a)394.32 183.6 R +-.25(va)-.2 G(ilable).25 E .462(to retrie)72 195.6 R .762 -.15(ve s)-.25 H .462 +(ubstrings of v).15 F .461(ariables in an)-.25 F F1(awk)2.961 E F0(-lik)A 2.961 +(em)-.1 G .461(anner: starting at a speci\214c inde)277.692 195.6 R .461 +(x, retrie)-.15 F .461(ving some num-)-.25 F .941 +(ber of characters or the rest of the string.)72 207.6 R .941 +(It will be possible to retrie)5.941 F 1.241 -.15(ve s)-.25 H .941 +(equences of array elements lik).15 F(e)-.1 E .354(this, too.)72 219.6 R .354 +(It w)5.354 F .354(ould be nice to ha)-.1 F .654 -.15(ve a w)-.2 H .354 +(ay to replace portions of a v).05 F .353 +(ariable matching a pattern the same w)-.25 F(ay)-.1 E(leading or trailing sub\ +strings are presently stripped; that capability may be a)72 231.6 Q -.25(va)-.2 +G(ilable.).25 E .453(Another ne)97 247.2 R 2.953(we)-.25 G .453 +(xpansion will pro)156.376 247.2 R .453(vide a w)-.15 F .454 +(ay to create strings containing arbitrary characters, which is)-.1 F(incon)72 +259.2 Q -.15(ve)-.4 G 1.636(nient in the current v).15 F 4.136(ersion. W)-.15 F +1.635(ords of the form $')-.8 F F1(string)A F0 4.135('w)C 1.635(ill e)355.145 +259.2 R 1.635(xpand to)-.15 F F1(string)4.135 E F0 1.635(with backslash-)4.135 +F 1.231(escaped characters in)72 271.2 R F1(string)3.731 E F0 1.231 +(replaced as speci\214ed by the ANSI C standard.)3.731 F 1.232 +(As with other single-quoted)6.232 F +(shell strings, the only character that may not appear in)72 283.2 Q F1(string) +2.5 E F0(is a single quote.)2.5 E 1.436(The shell v)97 298.8 R 1.436 +(ariables will change also.)-.25 F 3.936(An)6.436 G 1.936 -.25(ew va)272.052 +298.8 T(riable).25 E F2(HISTIGNORE)3.936 E F0 1.435(will supersede)3.936 F F2 +(HISTCON-)3.935 E(TR)72 310.8 Q(OL)-.3 E F0(.)A F2(HISTIGNORE)5.327 E F0 .327 +(is the history analogy of)2.827 F F2(FIGNORE)2.828 E F0 2.828(:ac)C .328 +(olon-separated list of patterns specifying)339.938 310.8 R 1.082 +(commands to omit from the history list.)72 322.8 R 1.081 +(The special pattern '&' will match the pre)6.081 F 1.081 +(vious history line, to)-.25 F(pro)72 334.8 Q 1.568(vide the)-.15 F F2 +(HISTCONTR)4.068 E(OL)-.3 E F1(ignor)4.068 E(edups)-.37 E F0(beha)5.734 E(vior) +-.2 E 6.568(.M)-.55 G(an)303.546 334.8 Q 4.069(yv)-.15 G 1.569 +(ariables which modify the shell')326.655 334.8 R 4.069(sb)-.55 G(eha)474.21 +334.8 Q(vior)-.2 E .395(will lose their special meaning.)72 346.8 R -1.11(Va) +5.395 G .395(riables such as)1.11 F F2(notify)2.895 E F0(and)2.895 E F2(noclob) +2.895 E(ber)-.1 E F0 .395(which pro)2.895 F .395(vide functionality a)-.15 F +-.25(va)-.2 G(il-).25 E .931 +(able via other mechanisms will no longer be treated specially)72 358.8 R 5.931 +(.O)-.65 G .931(ther v)340.06 358.8 R .932(ariables will be folded into)-.25 F +F2(shopt)3.432 E F0(.)A(The)72 370.8 Q F2(history_contr)5.519 E(ol)-.18 E F0 +(and)5.519 E F2(hostname_completion_\214le)5.519 E F0 -.25(va)5.519 G 3.019 +(riables, superseded by).25 F F2(HISTCONTR)5.518 E(OL)-.3 E F0(and)5.518 E F2 +(HOSTFILE)72 382.8 Q F0(respecti)2.5 E -.15(ve)-.25 G(ly).15 E 2.5(,w)-.65 G +(ill be remo)185.12 382.8 Q -.15(ve)-.15 G(d.).15 E F2 2.5(5.5. Readline)72 +406.8 R F0(Naturally)97 422.4 Q 2.94(,t)-.65 G .44(here will be impro)142.34 +422.4 R -.15(ve)-.15 G .441(ments to readline as well.).15 F .441 +(All of the POSIX.2)5.441 F F1(vi)2.941 E F0 .441(-mode editing com-)B .33 +(mands will be implemented; missing commands lik)72 434.4 R 2.829(e`)-.1 G .329 +(m' to sa)290.599 434.4 R .629 -.15(ve t)-.2 H .329 +(he current cursor position \().15 F F1(mark)A F0 2.829(\)a)C .329(nd the) +478.951 434.4 R .36(`@' command for macro e)72 446.4 R .36(xpansion will be a) +-.15 F -.25(va)-.2 G 2.861(ilable. The).25 F .361 +(ability to set the mark and e)2.861 F .361(xchange the current)-.15 F .764 +(cursor position \()72 458.4 R F1(point)A F0 3.264(\)a)C .764 +(nd mark will be added to the readline emacs mode as well.)170.672 458.4 R .763 +(Since there are com-)5.764 F .196 +(mands to set the mark, commands to manipulate the re)72 470.4 R .197 +(gion \(the characters between the point and the mark\))-.15 F .111(will be a) +72 482.4 R -.25(va)-.2 G 2.611(ilable. Commands).25 F(ha)2.611 E .411 -.15 +(ve b)-.2 H .11 +(een added to the readline emacs mode for more complete ksh compati-).15 F +(bility)72 494.4 Q 2.5(,s)-.65 G(uch as the C-])101.36 494.4 Q F1(c)A F0 +(character search command.)2.5 E F2 2.5(5.6. Con\214guration)72 518.4 R F0 .318 +(Bash w)97 534 R .318 +(as the \214rst GNU program to completely autocon\214gure.)-.1 F .319 +(Its autocon\214guration mechanism pre-)5.319 F(dates)72 546 Q F1(autoconf)4.07 +E F0 4.07(,t)C 1.569 +(he current GNU con\214guration program, and needs updating.)140.97 546 R 1.569 +(Bash-2.0 may include an)6.569 F .603 +(autoconf-based con\214guration script, if necessary ne)72 558 R 3.103(wf)-.25 +G .603(unctionality can be added to autoconf, or its limita-)294.476 558 R +(tions bypassed.)72 570 Q F2 2.5(5.7. Miscellaneous)72 594 R F0 1.632 +(The POSIX mode will be impro)97 609.6 R -.15(ve)-.15 G 4.131(di).15 G 4.131 +(nb)254.26 609.6 S 1.631(ash-2.0; it will pro)268.391 609.6 R 1.631 +(vide a more complete superset of the)-.15 F(POSIX standard.)72 621.6 Q -.15 +(Fo)5 G 2.5(rt).15 G(he \214rst time, bash will recognize the e)163.79 621.6 Q +(xistance of the POSIX.2)-.15 E F1(special)2.5 E F0 -.2(bu)2.5 G(iltins.).2 E +2.627(An)97 637.2 S .627 -.25(ew t)111.847 637.2 T .127(rap v).25 F(alue,)-.25 +E F2(DEB)2.627 E(UG)-.1 E F0 2.627(,w)C .128(ill be present, as in ksh.)218.405 +637.2 R .128(Commands speci\214ed with a)5.128 F F2(DEB)2.628 E(UG)-.1 E F0 +.128(trap will)2.628 F 1.908(be e)72 649.2 R -.15(xe)-.15 G 1.908 +(cuted after e).15 F -.15(ve)-.25 G 1.908(ry simple command.).15 F 1.908 +(Since this mak)6.908 F 1.908(es shell script deb)-.1 F 1.908 +(uggers possible, I hope to)-.2 F(include a bash deb)72 661.2 Q +(ugger in the bash-2.0 release.)-.2 E F2 2.5(6. A)72 685.2 R -.1(va)-1 G +(ilability).1 E F0 5.997(The current v)97 700.8 R 5.997(ersion of bash is a) +-.15 F -.25(va)-.2 G 5.998(ilable for anon).25 F 5.998 +(ymous FTP from prep.ai.mit.edu as)-.15 F F1(/pub/gnu/bash-1.14.2.tar)72 712.8 +Q(.gz)-1.11 E F0(.)1.666 E EP +%%Page: 13 13 +%%BeginPageSetup +BP +%%EndPageSetup +/F0 10/Times-Roman@0 SF 2.5(-1)277.17 48 S 2.5(3-)288 48 S/F1 10/Times-Bold@0 +SF 2.5(7. Conclusion)72 84 R F0 .755(This paper has presented an o)97 99.6 R +-.15(ve)-.15 G(rvie).15 E 3.255(wo)-.25 G 3.255(fb)259.27 99.6 S .755 +(ash, compared its features with those of other shells, and)270.855 99.6 R +(hinted at features in the ne)72 111.6 Q(xt release, bash-2.0.)-.15 E .483 +(Bash is a solid replacement for sh.)97 127.2 R .483(It is suf)5.483 F .483 +(\214ciently portable to run on nearly e)-.25 F -.15(ve)-.25 G .484(ry v).15 F +.484(ersion of)-.15 F/F2 9/Times-Roman@0 SF(UNIX)2.984 E F0 .514 +(from 4.3 BSD to SVR4.2, and se)72 139.2 R -.15(ve)-.25 G(ral).15 E F2(UNIX) +3.013 E F0 -.1(wo)3.013 G(rkalik).1 E .513(es, and rob)-.1 F .513 +(ust enough to replace sh on most of those)-.2 F .771(systems, It is v)72 151.2 +R .771(ery close to POSIX.2-conformant in POSIX mode, and is getting f)-.15 F +(aster)-.1 E 5.771(.I)-.55 G 3.272(ti)436.684 151.2 S 3.272(sn)445.516 151.2 S +.772(ot, unfortu-)457.678 151.2 R(nately)72 163.2 Q 2.663(,g)-.65 G .163 +(etting smaller)105.953 163.2 R 2.663(,b)-.4 G .163(ut there are man)170.399 +163.2 R 2.663(yo)-.15 G .163(ptional features.)248.101 163.2 R .163(It is v) +5.163 F .162(ery easy to b)-.15 F .162(uild a small subset to use as)-.2 F 2.5 +(ad)72 175.2 S(irect replacement for /bin/sh.)83.94 175.2 Q .909 +(Bash has thousands of users w)97 190.8 R .909(orldwide, all of whom ha)-.1 F +1.209 -.15(ve h)-.2 H .91(elped to mak).15 F 3.41(ei)-.1 G 3.41(tb)409.34 190.8 +S(etter)420.53 190.8 Q 5.91(.A)-.55 G .91(nother testa-)453.38 190.8 R +(ment to the bene\214ts of free softw)72 202.8 Q(are.)-.1 E F1 2.5(8. Refer)72 +226.8 R(ences)-.18 E F0 .432([1] S. R. Bourne, `)72 242.4 R .432(`UNIX T)-.74 F +.432(ime-Sharing System:)-.35 F .431(The UNIX Shell')5.431 F(',)-.74 E/F3 10 +/Times-Italic@0 SF .431(Bell System T)2.931 F(ec)-.92 E .431(hnical J)-.15 F +(ournal)-.25 E F0 2.931(,5)C(7\(6\),)484.84 242.4 Q +(July-August, 1978, pp. 1971-1990.)72 254.4 Q .736([2] Morris Bolsk)72 270 R +3.237(ya)-.15 G .737(nd Da)153.22 270 R .737(vid K)-.2 F(orn,)-.35 E F3 .737 +(The K)3.237 F .737(ornShell Command and Pr)-.4 F -.1(og)-.45 G -.15(ra).1 G +.737(mming Langua).15 F -.1(ge)-.1 G F0 3.237(,P).1 G .737(rentice Hall,) +453.833 270 R(1989.)72 282 Q .142([3] Bill Jo)72 297.6 R 1.442 -.65(y, A)-.1 H +2.642(nI).65 G .141(ntroduction to the C Shell,)140.428 297.6 R F3 .141 +(UNIX User')2.641 F 2.641(sS)-.4 G .141(upplementary Documents)309.346 297.6 R +F0 2.641(,U)C(ni)424.328 297.6 Q -.15(ve)-.25 G .141(rsity of Califor).15 F(-) +-.2 E(nia at Berk)72 309.6 Q(ele)-.1 E 1.3 -.65(y, 1)-.15 H(986.).65 E .283 +([4] IEEE,)72 325.2 R F3 .283(IEEE Standar)2.783 F 2.783(df)-.37 G .283 +(or Information T)179.692 325.2 R(ec)-.92 E(hnolo)-.15 E .283(gy -- P)-.1 F +.283(ortable Oper)-.8 F .283(ating System Interface \(POSIX\) P)-.15 F(art)-.8 +E(2: Shell and Utilities)72 337.2 Q F0 2.5(,1)C(992.)165.06 337.2 Q F1 2.5 +(9. A)72 361.2 R(uthor Inf)-.5 E(ormation)-.25 E F0 .937(Chet Rame)97 376.8 R +3.437(yi)-.15 G 3.437(sas)153.724 376.8 S(oftw)172.818 376.8 Q .936 +(are engineer w)-.1 F .936(orking at Case W)-.1 F .936(estern Reserv)-.8 F +3.436(eU)-.15 G(ni)393.43 376.8 Q -.15(ve)-.25 G(rsity).15 E 5.936(.H)-.65 G +3.436(eh)443.036 376.8 S .936(as a B.S. in)455.912 376.8 R .072 +(Computer Engineering and an M.S. in Computer Science, both from CWR)72 388.8 R +2.573(U. He)-.4 F .073(has been w)2.573 F .073(orking on bash)-.1 F +(for six years, and the primary maintainer for one.)72 400.8 Q EP +%%Trailer +end +%%EOF diff --git a/doc/texinfo.tex b/doc/texinfo.tex new file mode 100644 index 0000000..555a077 --- /dev/null +++ b/doc/texinfo.tex @@ -0,0 +1,6688 @@ +% texinfo.tex -- TeX macros to handle Texinfo files. +% +% Load plain if necessary, i.e., if running under initex. +\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi +% +\def\texinfoversion{2003-02-03.16} +% +% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, +% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 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, Inc., 59 Temple Place - Suite 330, +% Boston, MA 02111-1307, 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! +% +% Please try the latest version of texinfo.tex before submitting bug +% reports; you can get the latest version from: +% ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex +% (and all GNU mirrors, see http://www.gnu.org/order/ftp.html) +% ftp://tug.org/tex/texinfo.tex +% (and all CTAN mirrors, see http://www.ctan.org), +% and /home/gd/gnu/doc/texinfo.tex on the GNU machines. +% +% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. +% +% The texinfo.tex in any given Texinfo distribution could well be out +% of date, so if that's what you're using, please check. +% +% Send bug reports to bug-texinfo@gnu.org. Please include including a +% complete document in each bug report with which we can reproduce the +% problem. Patches are, of course, greatly appreciated. +% +% To process a Texinfo manual with TeX, it's most reliable to use the +% texi2dvi shell script that comes with the distribution. For a simple +% manual foo.texi, however, you can get away with this: +% tex foo.texi +% texindex foo.?? +% tex foo.texi +% tex foo.texi +% dvips foo.dvi -o # or whatever; this makes foo.ps. +% The extra TeX runs get the cross-reference information correct. +% Sometimes one run after texindex suffices, and sometimes you need more +% than two; texi2dvi does it as many times as necessary. +% +% It is possible to adapt texinfo.tex for other languages, to some +% extent. You can get the existing language-specific files from the +% full Texinfo distribution. + +\message{Loading texinfo [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]}% + \catcode`+=\active \catcode`\_=\active} + +\message{Basics,} +\chardef\other=12 + +% We never want plain's outer \+ definition in Texinfo. +% For @tex, we can use \tabalign. +\let\+ = \relax + +% Save some parts of plain tex whose names we will redefine. +\let\ptexb=\b +\let\ptexbullet=\bullet +\let\ptexc=\c +\let\ptexcomma=\, +\let\ptexdot=\. +\let\ptexdots=\dots +\let\ptexend=\end +\let\ptexequiv=\equiv +\let\ptexexclam=\! +\let\ptexgtr=> +\let\ptexhat=^ +\let\ptexi=\i +\let\ptexlbrace=\{ +\let\ptexless=< +\let\ptexplus=+ +\let\ptexrbrace=\} +\let\ptexstar=\* +\let\ptext=\t + +% 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 if not already set. +\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi +\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi +\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi +\ifx\putwordin\undefined \gdef\putwordin{in}\fi +\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi +\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi +\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi +\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi +\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi +\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi +\ifx\putwordof\undefined \gdef\putwordof{of}\fi +\ifx\putwordon\undefined \gdef\putwordon{on}\fi +\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi +\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi +\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi +\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi +\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi +\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi +\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi +% +\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi +\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi +\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi +\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi +\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi +\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi +\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi +\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi +\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi +\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi +\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi +\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi +% +\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi +\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi +\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi +\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi +\ifx\putwordDeftypevar\undefined\gdef\putwordDeftypevar{Variable}\fi +\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi +\ifx\putwordDeftypefun\undefined\gdef\putwordDeftypefun{Function}\fi + +% In some macros, we cannot use the `\? notation---the left quote is +% in some cases the escape char. +\chardef\colonChar = `\: +\chardef\commaChar = `\, +\chardef\dotChar = `\. +\chardef\equalChar = `\= +\chardef\exclamChar= `\! +\chardef\questChar = `\? +\chardef\semiChar = `\; +\chardef\spaceChar = `\ % +\chardef\underChar = `\_ + +% Ignore a token. +% +\def\gobble#1{} + +% True if #1 is the empty string, i.e., called like `\ifempty{}'. +% +\def\ifempty#1{\ifemptyx #1\emptymarkA\emptymarkB}% +\def\ifemptyx#1#2\emptymarkB{\ifx #1\emptymarkA}% + +% Hyphenation fixes. +\hyphenation{ap-pen-dix} +\hyphenation{mini-buf-fer mini-buf-fers} +\hyphenation{eshell} +\hyphenation{white-space} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen\bindingoffset +\newdimen\normaloffset +\newdimen\pagewidth \newdimen\pageheight + +% 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. We also make +% some effort to order the tracing commands to reduce output in the log +% file; cf. trace.sty in LaTeX. +% +\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% +\def\loggingall{% + \tracingstats2 + \tracingpages1 + \tracinglostchars2 % 2 gives us more in etex + \tracingparagraphs1 + \tracingoutput1 + \tracingmacros2 + \tracingrestores1 + \showboxbreadth\maxdimen \showboxdepth\maxdimen + \ifx\eTeXversion\undefined\else % etex gives us more logging + \tracingscantokens1 + \tracingifs1 + \tracinggroups1 + \tracingnesting2 + \tracingassigns1 + \fi + \tracingcommands3 % 3 gives us more in etex + \errorcontextlines\maxdimen +}% + +% add check for \lastpenalty to plain's definitions. If the last thing +% we did was a \nobreak, we don't want to insert more space. +% +\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount + \removelastskip\penalty-50\smallskip\fi\fi} +\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount + \removelastskip\penalty-100\medskip\fi\fi} +\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount + \removelastskip\penalty-200\bigskip\fi\fi} + +% For @cropmarks command. +% Do @cropmarks to get crop marks. +% +\newif\ifcropmarks +\let\cropmarks = \cropmarkstrue +% +% Dimensions to add cropmarks at corners. +% Added by P. A. MacKay, 12 Nov. 1986 +% +\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines +\newdimen\cornerlong \cornerlong=1pc +\newdimen\cornerthick \cornerthick=.3pt +\newdimen\topandbottommargin \topandbottommargin=.75in + +% Main output routine. +\chardef\PAGE = 255 +\output = {\onepageout{\pagecontents\PAGE}} + +\newbox\headlinebox +\newbox\footlinebox + +% \onepageout takes a vbox as an argument. Note that \pagecontents +% does insertions, but you have to call it yourself. +\def\onepageout#1{% + \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi + % + \ifodd\pageno \advance\hoffset by \bindingoffset + \else \advance\hoffset by -\bindingoffset\fi + % + % Do this outside of the \shipout so @code etc. will be expanded in + % the headline as they should be, not taken literally (outputting ''code). + \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% + \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% + % + {% + % Have to do this stuff outside the \shipout because we want it to + % take effect in \write's, yet the group defined by the \vbox ends + % before the \shipout runs. + % + \escapechar = `\\ % use backslash in output files. + \indexdummies % don't expand commands in the output. + \normalturnoffactive % \ in index entries must not stay \, e.g., if + % the page break happens to be in the middle of an example. + \shipout\vbox{% + % Do this early so pdf references go to the beginning of the page. + \ifpdfmakepagedest \pdfmkdest{\the\pageno} \fi + % + \ifcropmarks \vbox to \outervsize\bgroup + \hsize = \outerhsize + \vskip-\topandbottommargin + \vtop to0pt{% + \line{\ewtop\hfil\ewtop}% + \nointerlineskip + \line{% + \vbox{\moveleft\cornerthick\nstop}% + \hfill + \vbox{\moveright\cornerthick\nstop}% + }% + \vss}% + \vskip\topandbottommargin + \line\bgroup + \hfil % center the page within the outer (page) hsize. + \ifodd\pageno\hskip\bindingoffset\fi + \vbox\bgroup + \fi + % + \unvbox\headlinebox + \pagebody{#1}% + \ifdim\ht\footlinebox > 0pt + % Only leave this space if the footline is nonempty. + % (We lessened \vsize for it in \oddfootingxxx.) + % The \baselineskip=24pt in plain's \makefootline has no effect. + \vskip 2\baselineskip + \unvbox\footlinebox + \fi + % + \ifcropmarks + \egroup % end of \vbox\bgroup + \hfil\egroup % end of (centering) \line\bgroup + \vskip\topandbottommargin plus1fill minus1fill + \boxmaxdepth = \cornerthick + \vbox to0pt{\vss + \line{% + \vbox{\moveleft\cornerthick\nsbot}% + \hfill + \vbox{\moveright\cornerthick\nsbot}% + }% + \nointerlineskip + \line{\ewbot\hfil\ewbot}% + }% + \egroup % \vbox from first cropmarks clause + \fi + }% end of \shipout\vbox + }% end of group with \normalturnoffactive + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi +} + +\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; press 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{Press 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}}% +} + + +%% Simple single-character @ commands + +% @@ prints an @ +% Kludge this until the fonts are right (grr). +\def\@{{\tt\char64}} + +% 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\char123}} +\def\myrbrace {{\tt\char125}} +\let\{=\mylbrace +\let\}=\myrbrace +\begingroup + % Definitions to produce \{ and \} commands for indices, + % and @{ and @} for the aux file. + \catcode`\{ = \other \catcode`\} = \other + \catcode`\[ = 1 \catcode`\] = 2 + \catcode`\! = 0 \catcode`\\ = \other + !gdef!lbracecmd[\{]% + !gdef!rbracecmd[\}]% + !gdef!lbraceatcmd[@{]% + !gdef!rbraceatcmd[@}]% +!endgroup + +% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent +% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. +\let\, = \c +\let\dotaccent = \. +\def\ringaccent#1{{\accent23 #1}} +\let\tieaccent = \t +\let\ubaraccent = \b +\let\udotaccent = \d + +% Other special characters: @questiondown @exclamdown +% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. +\def\questiondown{?`} +\def\exclamdown{!`} + +% Dotless i and dotless j, used for accents. +\def\imacro{i} +\def\jmacro{j} +\def\dotless#1{% + \def\temp{#1}% + \ifx\temp\imacro \ptexi + \else\ifx\temp\jmacro \j + \else \errmessage{@dotless can be used only with i or j}% + \fi\fi +} + +% 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 + % Avoid using \@M directly, because that causes trouble + % if the definition is written into an index file. + \global\let\tiepenalty = \@M + \gdef\tie{\leavevmode\penalty\tiepenalty\ } +} + +% @: 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 } + +% @! is an end-of-sentence bang. +\def\!{!\spacefactor=3000 } + +% @? is an end-of-sentence query. +\def\?{?\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. +% +% Another complication is that the group might be very large. This can +% cause the glue on the previous page to be unduly stretched, because it +% does not have much material. In this case, it's better to add an +% explicit \vfill so that the extra space is at the bottom. The +% threshold for doing this is if the group is more than \vfilllimit +% percent of a page (\vfilllimit can be changed inside of @tex). +% +\newbox\groupbox +\def\vfilllimit{0.7} +% +\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. + % \dimen0 is the vertical size of the group's box. + \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox + % \dimen2 is how much space is left on the page (more or less). + \dimen2 = \pageheight \advance\dimen2 by -\pagetotal + % if the group doesn't fit on the current page, and it's a big big + % group, force a page break. + \ifdim \dimen0 > \dimen2 + \ifdim \pagetotal < \vfilllimit\pageheight + \page + \fi + \fi + \copy\groupbox + \endgroup % End the \group. + }% + % + \setbox\groupbox = \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\nobreak +%\prevdepth=-1000pt +%}} + +\def\needx#1{% + % Ensure vertical mode, so we don't make a big box in the middle of a + % paragraph. + \par + % + % If the @need value is less than one line space, it's useless. + \dimen0 = #1\mil + \dimen2 = \ht\strutbox + \advance\dimen2 by \dp\strutbox + \ifdim\dimen0 > \dimen2 + % + % Do a \strut just to make the height of this box be normal, so the + % normal leading is inserted relative to the preceding line. + % And a page break here is fine. + \vtop to #1\mil{\strut\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 + \fi +} + +% @br forces paragraph break + +\let\br = \par + +% @dots{} output an ellipsis using the current font. +% We do .5em per period so that it has the same spacing in a typewriter +% font as three actual period characters. +% +\def\dots{% + \leavevmode + \hbox to 1.5em{% + \hskip 0pt plus 0.25fil minus 0.25fil + .\hss.\hss.% + \hskip 0pt plus 0.5fil minus 0.5fil + }% +} + +% @enddots{} is an end-of-sentence ellipsis. +% +\def\enddots{% + \leavevmode + \hbox to 2em{% + \hskip 0pt plus 0.25fil minus 0.25fil + .\hss.\hss.\hss.% + \hskip 0pt plus 0.5fil minus 0.5fil + }% + \spacefactor=3000 +} + + +% @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}}}} + +% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current +% paragraph. For more general purposes, use the \margin insertion +% class. WHICH is `l' or `r'. +% +\newskip\inmarginspacing \inmarginspacing=1cm +\def\strutdepth{\dp\strutbox} +% +\def\doinmargin#1#2{\strut\vadjust{% + \nobreak + \kern-\strutdepth + \vtop to \strutdepth{% + \baselineskip=\strutdepth + \vss + % if you have multiple lines of stuff to put here, you'll need to + % make the vbox yourself of the appropriate size. + \ifx#1l% + \llap{\ignorespaces #2\hskip\inmarginspacing}% + \else + \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}% + \fi + \null + }% +}} +\def\inleftmargin{\doinmargin l} +\def\inrightmargin{\doinmargin r} +% +% @inmargin{TEXT [, RIGHT-TEXT]} +% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right; +% else use TEXT for both). +% +\def\inmargin#1{\parseinmargin #1,,\finish} +\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing. + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \def\lefttext{#1}% have both texts + \def\righttext{#2}% + \else + \def\lefttext{#1}% have only one text + \def\righttext{#1}% + \fi + % + \ifodd\pageno + \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin + \else + \def\temp{\inleftmargin\lefttext}% + \fi + \temp +} + +% @include file insert text of that file as input. +% Allow normal characters that we make active in the argument (a file name). +\def\include{\begingroup + \catcode`\\=\other + \catcode`~=\other + \catcode`^=\other + \catcode`_=\other + \catcode`|=\other + \catcode`<=\other + \catcode`>=\other + \catcode`+=\other + \parsearg\includezzz} +% Restore active chars for included file. +\def\includezzz#1{\endgroup\begingroup + % Read the included file in a group so nested @include's work. + \def\thisfile{#1}% + \let\value=\expandablevalue + \input\thisfile +\endgroup} + +\def\thisfile{} + +% @center line +% outputs that line, centered. +% +\def\center{\parsearg\docenter} +\def\docenter#1{{% + \ifhmode \hfil\break \fi + \advance\hsize by -\leftskip + \advance\hsize by -\rightskip + \line{\hfil \ignorespaces#1\unskip \hfil}% + \ifhmode \break \fi +}} + +% @sp n outputs n lines of vertical space + +\def\sp{\parsearg\spxxx} +\def\spxxx #1{\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{\begingroup \catcode`\^^M=\other% +\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% +\commentxxx} +{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} + +\let\c=\comment + +% @paragraphindent NCHARS +% We'll use ems for NCHARS, close enough. +% We cannot implement @paragraphindent asis, though. +% +\def\asisword{asis} % no translation, these are keywords +\def\noneword{none} +% +\def\paragraphindent{\parsearg\doparagraphindent} +\def\doparagraphindent#1{% + \def\temp{#1}% + \ifx\temp\asisword + \else + \ifx\temp\noneword + \defaultparindent = 0pt + \else + \defaultparindent = #1em + \fi + \fi + \parindent = \defaultparindent +} + +% @exampleindent NCHARS +% We'll use ems for NCHARS like @paragraphindent. +% It seems @exampleindent asis isn't necessary, but +% I preserve it to make it similar to @paragraphindent. +\def\exampleindent{\parsearg\doexampleindent} +\def\doexampleindent#1{% + \def\temp{#1}% + \ifx\temp\asisword + \else + \ifx\temp\noneword + \lispnarrowing = 0pt + \else + \lispnarrowing = #1em + \fi + \fi +} + +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math outputs its argument in math mode. +% We don't use $'s directly in the definition of \math because we need +% to set catcodes according to plain TeX first, to allow for subscripts, +% superscripts, special math chars, etc. +% +\let\implicitmath = $%$ font-lock fix +% +% One complication: _ usually means subscripts, but it could also mean +% an actual _ character, as in @math{@var{some_variable} + 1}. So make +% _ within @math be active (mathcode "8000), and distinguish by seeing +% if the current family is \slfam, which is what @var uses. +% +{\catcode\underChar = \active +\gdef\mathunderscore{% + \catcode\underChar=\active + \def_{\ifnum\fam=\slfam \_\else\sb\fi}% +}} +% +% Another complication: we want \\ (and @\) to output a \ character. +% FYI, plain.tex uses \\ as a temporary control sequence (why?), but +% this is not advertised and we don't care. Texinfo does not +% otherwise define @\. +% +% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. +\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} +% +\def\math{% + \tex + \mathcode`\_="8000 \mathunderscore + \let\\ = \mathbackslash + \mathactive + \implicitmath\finishmath} +\def\finishmath#1{#1\implicitmath\Etex} + +% Some active characters (such as <) are spaced differently in math. +% We have to reset their definitions in case the @math was an +% argument to a command which set the catcodes (such as @item or @section). +% +{ + \catcode`^ = \active + \catcode`< = \active + \catcode`> = \active + \catcode`+ = \active + \gdef\mathactive{% + \let^ = \ptexhat + \let< = \ptexless + \let> = \ptexgtr + \let+ = \ptexplus + } +} + +% @bullet and @minus need the same treatment as @math, just above. +\def\bullet{\implicitmath\ptexbullet\implicitmath} +\def\minus{\implicitmath-\implicitmath} + +% @refill is a no-op. +\let\refill=\relax + +% If working on a large document in chapters, it is convenient to +% be able to disable indexing, cross-referencing, and contents, for test runs. +% This is done with @novalidate (before @setfilename). +% +\newif\iflinks \linkstrue % by default we want the aux files. +\let\novalidate = \linksfalse + +% @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{% + \iflinks + \readauxfile + \fi % \openindices needs to do some work in any case. + \openindices + \fixbackslash % Turn off hack to swallow `\input texinfo'. + \global\let\setfilename=\comment % Ignore extra @setfilename cmds. + % + % If texinfo.cnf is present on the system, read it. + % Useful for site-wide @afourpaper, etc. + % Just to be on the safe side, close the input stream before the \input. + \openin 1 texinfo.cnf + \ifeof1 \let\temp=\relax \else \def\temp{\input texinfo.cnf }\fi + \closein1 + \temp + % + \comment % Ignore the actual filename. +} + +% Called from \setfilename. +% +\def\openindices{% + \newindex{cp}% + \newcodeindex{fn}% + \newcodeindex{vr}% + \newcodeindex{tp}% + \newcodeindex{ky}% + \newcodeindex{pg}% +} + +% @bye. +\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} + + +\message{pdf,} +% adobe `portable' document format +\newcount\tempnum +\newcount\lnkcount +\newtoks\filename +\newcount\filenamelength +\newcount\pgn +\newtoks\toksA +\newtoks\toksB +\newtoks\toksC +\newtoks\toksD +\newbox\boxA +\newcount\countA +\newif\ifpdf +\newif\ifpdfmakepagedest + +\ifx\pdfoutput\undefined + \pdffalse + \let\pdfmkdest = \gobble + \let\pdfurl = \gobble + \let\endlink = \relax + \let\linkcolor = \relax + \let\pdfmakeoutlines = \relax +\else + \pdftrue + \pdfoutput = 1 + \input pdfcolor + \def\dopdfimage#1#2#3{% + \def\imagewidth{#2}% + \def\imageheight{#3}% + % without \immediate, pdftex seg faults when the same image is + % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.) + \ifnum\pdftexversion < 14 + \immediate\pdfimage + \else + \immediate\pdfximage + \fi + \ifx\empty\imagewidth\else width \imagewidth \fi + \ifx\empty\imageheight\else height \imageheight \fi + \ifnum\pdftexversion<13 + #1.pdf% + \else + {#1.pdf}% + \fi + \ifnum\pdftexversion < 14 \else + \pdfrefximage \pdflastximage + \fi} + \def\pdfmkdest#1{{\normalturnoffactive \pdfdest name{#1} xyz}} + \def\pdfmkpgn#1{#1} + \let\linkcolor = \Blue % was Cyan, but that seems light? + \def\endlink{\Black\pdfendlink} + % Adding outlines to PDF; macros for calculating structure of outlines + % come from Petr Olsak + \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% + \else \csname#1\endcsname \fi} + \def\advancenumber#1{\tempnum=\expnumber{#1}\relax + \advance\tempnum by1 + \expandafter\xdef\csname#1\endcsname{\the\tempnum}} + \def\pdfmakeoutlines{{% + \openin 1 \jobname.toc + \ifeof 1\else\begingroup + \closein 1 + % Thanh's hack / proper braces in bookmarks + \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace + \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace + % + \def\chapentry ##1##2##3{} + \def\secentry ##1##2##3##4{\advancenumber{chap##2}} + \def\subsecentry ##1##2##3##4##5{\advancenumber{sec##2.##3}} + \def\subsubsecentry ##1##2##3##4##5##6{\advancenumber{subsec##2.##3.##4}} + \let\appendixentry = \chapentry + \let\unnumbchapentry = \chapentry + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry + \input \jobname.toc + \def\chapentry ##1##2##3{% + \pdfoutline goto name{\pdfmkpgn{##3}}count-\expnumber{chap##2}{##1}} + \def\secentry ##1##2##3##4{% + \pdfoutline goto name{\pdfmkpgn{##4}}count-\expnumber{sec##2.##3}{##1}} + \def\subsecentry ##1##2##3##4##5{% + \pdfoutline goto name{\pdfmkpgn{##5}}count-\expnumber{subsec##2.##3.##4}{##1}} + \def\subsubsecentry ##1##2##3##4##5##6{% + \pdfoutline goto name{\pdfmkpgn{##6}}{##1}} + \let\appendixentry = \chapentry + \let\unnumbchapentry = \chapentry + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry + % + % Make special characters normal for writing to the pdf file. + % + \indexnofonts + \let\tt=\relax + \turnoffactive + \input \jobname.toc + \endgroup\fi + }} + \def\makelinks #1,{% + \def\params{#1}\def\E{END}% + \ifx\params\E + \let\nextmakelinks=\relax + \else + \let\nextmakelinks=\makelinks + \ifnum\lnkcount>0,\fi + \picknum{#1}% + \startlink attr{/Border [0 0 0]} + goto name{\pdfmkpgn{\the\pgn}}% + \linkcolor #1% + \advance\lnkcount by 1% + \endlink + \fi + \nextmakelinks + } + \def\picknum#1{\expandafter\pn#1} + \def\pn#1{% + \def\p{#1}% + \ifx\p\lbrace + \let\nextpn=\ppn + \else + \let\nextpn=\ppnn + \def\first{#1} + \fi + \nextpn + } + \def\ppn#1{\pgn=#1\gobble} + \def\ppnn{\pgn=\first} + \def\pdfmklnk#1{\lnkcount=0\makelinks #1,END,} + \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} + \def\skipspaces#1{\def\PP{#1}\def\D{|}% + \ifx\PP\D\let\nextsp\relax + \else\let\nextsp\skipspaces + \ifx\p\space\else\addtokens{\filename}{\PP}% + \advance\filenamelength by 1 + \fi + \fi + \nextsp} + \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax} + \ifnum\pdftexversion < 14 + \let \startlink \pdfannotlink + \else + \let \startlink \pdfstartlink + \fi + \def\pdfurl#1{% + \begingroup + \normalturnoffactive\def\@{@}% + \let\value=\expandablevalue + \leavevmode\Red + \startlink attr{/Border [0 0 0]}% + user{/Subtype /Link /A << /S /URI /URI (#1) >>}% + % #1 + \endgroup} + \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} + \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} + \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} + \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}} + \def\maketoks{% + \expandafter\poptoks\the\toksA|ENDTOKS| + \ifx\first0\adn0 + \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3 + \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6 + \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 + \else + \ifnum0=\countA\else\makelink\fi + \ifx\first.\let\next=\done\else + \let\next=\maketoks + \addtokens{\toksB}{\the\toksD} + \ifx\first,\addtokens{\toksB}{\space}\fi + \fi + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi + \next} + \def\makelink{\addtokens{\toksB}% + {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0} + \def\pdflink#1{% + \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}} + \linkcolor #1\endlink} + \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} +\fi % \ifx\pdfoutput + + +\message{fonts,} +% Font-change commands. + +% Texinfo sort of 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. + +% We don't need math for this one. +\def\ttsl{\tenttsl} + +% Default leading. +\newdimen\textleading \textleading = 13.2pt + +% 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 + }% +} + +% Set the font macro #1 to the font named #2, adding on the +% specified font prefix (normally `cm'). +% #3 is the font's design size, #4 is a scale factor +\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4} + +% 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 +% Support font families that don't use the same naming scheme as CM. +\def\rmshape{r} +\def\rmbshape{bx} %where the normal face is bold +\def\bfshape{b} +\def\bxshape{bx} +\def\ttshape{tt} +\def\ttbshape{tt} +\def\ttslshape{sltt} +\def\itshape{ti} +\def\itbshape{bxti} +\def\slshape{sl} +\def\slbshape{bxsl} +\def\sfshape{ss} +\def\sfbshape{ss} +\def\scshape{csc} +\def\scbshape{csc} + +\newcount\mainmagstep +\ifx\bigger\relax + % not really supported. + \mainmagstep=\magstep1 + \setfont\textrm\rmshape{12}{1000} + \setfont\texttt\ttshape{12}{1000} +\else + \mainmagstep=\magstephalf + \setfont\textrm\rmshape{10}{\mainmagstep} + \setfont\texttt\ttshape{10}{\mainmagstep} +\fi +% Instead of cmb10, you may want to use cmbx10. +% cmbx10 is a prettier font on its own, but cmb10 +% looks better when embedded in a line with cmr10 +% (in Bob's opinion). +\setfont\textbf\bfshape{10}{\mainmagstep} +\setfont\textit\itshape{10}{\mainmagstep} +\setfont\textsl\slshape{10}{\mainmagstep} +\setfont\textsf\sfshape{10}{\mainmagstep} +\setfont\textsc\scshape{10}{\mainmagstep} +\setfont\textttsl\ttslshape{10}{\mainmagstep} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep + +% A few fonts for @defun, etc. +\setfont\defbf\bxshape{10}{\magstep1} %was 1314 +\setfont\deftt\ttshape{10}{\magstep1} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} + +% Fonts for indices, footnotes, small examples (9pt). +\setfont\smallrm\rmshape{9}{1000} +\setfont\smalltt\ttshape{9}{1000} +\setfont\smallbf\bfshape{10}{900} +\setfont\smallit\itshape{9}{1000} +\setfont\smallsl\slshape{9}{1000} +\setfont\smallsf\sfshape{9}{1000} +\setfont\smallsc\scshape{10}{900} +\setfont\smallttsl\ttslshape{10}{900} +\font\smalli=cmmi9 +\font\smallsy=cmsy9 + +% Fonts for small examples (8pt). +\setfont\smallerrm\rmshape{8}{1000} +\setfont\smallertt\ttshape{8}{1000} +\setfont\smallerbf\bfshape{10}{800} +\setfont\smallerit\itshape{8}{1000} +\setfont\smallersl\slshape{8}{1000} +\setfont\smallersf\sfshape{8}{1000} +\setfont\smallersc\scshape{10}{800} +\setfont\smallerttsl\ttslshape{10}{800} +\font\smalleri=cmmi8 +\font\smallersy=cmsy8 + +% Fonts for title page: +\setfont\titlerm\rmbshape{12}{\magstep3} +\setfont\titleit\itbshape{10}{\magstep4} +\setfont\titlesl\slbshape{10}{\magstep4} +\setfont\titlett\ttbshape{12}{\magstep3} +\setfont\titlettsl\ttslshape{10}{\magstep4} +\setfont\titlesf\sfbshape{17}{\magstep1} +\let\titlebf=\titlerm +\setfont\titlesc\scbshape{10}{\magstep4} +\font\titlei=cmmi12 scaled \magstep3 +\font\titlesy=cmsy10 scaled \magstep4 +\def\authorrm{\secrm} +\def\authortt{\sectt} + +% Chapter (and unnumbered) fonts (17.28pt). +\setfont\chaprm\rmbshape{12}{\magstep2} +\setfont\chapit\itbshape{10}{\magstep3} +\setfont\chapsl\slbshape{10}{\magstep3} +\setfont\chaptt\ttbshape{12}{\magstep2} +\setfont\chapttsl\ttslshape{10}{\magstep3} +\setfont\chapsf\sfbshape{17}{1000} +\let\chapbf=\chaprm +\setfont\chapsc\scbshape{10}{\magstep3} +\font\chapi=cmmi12 scaled \magstep2 +\font\chapsy=cmsy10 scaled \magstep3 + +% Section fonts (14.4pt). +\setfont\secrm\rmbshape{12}{\magstep1} +\setfont\secit\itbshape{10}{\magstep2} +\setfont\secsl\slbshape{10}{\magstep2} +\setfont\sectt\ttbshape{12}{\magstep1} +\setfont\secttsl\ttslshape{10}{\magstep2} +\setfont\secsf\sfbshape{12}{\magstep1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep2} +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 + +% Subsection fonts (13.15pt). +\setfont\ssecrm\rmbshape{12}{\magstephalf} +\setfont\ssecit\itbshape{10}{1315} +\setfont\ssecsl\slbshape{10}{1315} +\setfont\ssectt\ttbshape{12}{\magstephalf} +\setfont\ssecttsl\ttslshape{10}{1315} +\setfont\ssecsf\sfbshape{12}{\magstephalf} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{\magstep1} +\font\sseci=cmmi12 scaled \magstephalf +\font\ssecsy=cmsy10 scaled 1315 +% The smallcaps and symbol fonts should actually be scaled \magstep1.5, +% but that is not a standard magnification. + +% 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 except +% in the main text, 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 font. Plain TeX does \def\bf{\fam=\bffam +% \tenbf}, for example. 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 \let\tenttsl=\textttsl + \resetmathfonts \setleading{\textleading}} +\def\titlefonts{% + \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl + \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc + \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy + \let\tenttsl=\titlettsl + \resetmathfonts \setleading{25pt}} +\def\titlefont#1{{\titlefonts\rm #1}} +\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 \let\tenttsl=\chapttsl + \resetmathfonts \setleading{19pt}} +\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 \let\tenttsl=\secttsl + \resetmathfonts \setleading{16pt}} +\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 \let\tenttsl=\ssecttsl + \resetmathfonts \setleading{15pt}} +\let\subsubsecfonts = \subsecfonts % Maybe make sssec fonts scaled magstephalf? +\def\smallfonts{% + \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl + \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc + \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy + \let\tenttsl=\smallttsl + \resetmathfonts \setleading{10.5pt}} +\def\smallerfonts{% + \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl + \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc + \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy + \let\tenttsl=\smallerttsl + \resetmathfonts \setleading{9.5pt}} + +% Set the fonts to use with the @small... environments. +\let\smallexamplefonts = \smallfonts + +% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample +% can fit this many characters: +% 8.5x11=86 smallbook=72 a4=90 a5=69 +% If we use \smallerfonts (8pt), then we can fit this many characters: +% 8.5x11=90+ smallbook=80 a4=90+ a5=77 +% For me, subjectively, the few extra characters that fit aren't worth +% the additional smallness of 8pt. So I'm making the default 9pt. +% +% By the way, for comparison, here's what fits with @example (10pt): +% 8.5x11=71 smallbook=60 a4=75 a5=58 +% +% I wish we used A4 paper on this side of the Atlantic. +% +% --karl, 24jan03. + + +% Set up the default fonts, so we can use them for creating boxes. +% +\textfonts + +% Define these so they can be easily changed for other fonts. +\def\angleleft{$\langle$} +\def\angleright{$\rangle$} + +% Count depth in font-changes, for error checks +\newcount\fontdepth \fontdepth=0 + +% Fonts for short table of contents. +\setfont\shortcontrm\rmshape{12}{1000} +\setfont\shortcontbf\bxshape{12}{1000} +\setfont\shortcontsl\slshape{12}{1000} +\setfont\shortconttt\ttshape{12}{1000} + +%% 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\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} +\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} + +\let\i=\smartitalic +\let\var=\smartslanted +\let\dfn=\smartslanted +\let\emph=\smartitalic +\let\cite=\smartslanted + +\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 = `- } + +% Set sfcode to normal for the chars that usually have another value. +% Can't use plain's \frenchspacing because it uses the `\x notation, and +% sometimes \x has an active definition that messes things up. +% +\catcode`@=11 + \def\frenchspacing{% + \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m + \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m + } +\catcode`@=\other + +\def\t#1{% + {\tt \rawbackslash \frenchspacing #1}% + \null +} +\let\ttfont=\t +\def\samp#1{`\tclose{#1}'\null} +\setfont\keyrm\rmshape{8}{1000} +\font\keysy=cmsy9 +\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% + \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% + \vbox{\hrule\kern-0.4pt + \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% + \kern-0.4pt\hrule}% + \kern-.06em\raise0.4pt\hbox{\angleright}}}} +% The old definition, with no lozenge: +%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} +\def\ctrl #1{{\tt \rawbackslash \hat}#1} + +% @file, @option are the same as @samp. +\let\file=\samp +\let\option=\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 overfull 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 at a dash. +% -- rms. +{ + \catcode`\-=\active + \catcode`\_=\active + % + \global\def\code{\begingroup + \catcode`\-=\active \let-\codedash + \catcode`\_=\active \let_\codeunder + \codex + } + % + % If we end up with any active - characters when handling the index, + % just treat them as a normal -. + \global\def\indexbreaks{\catcode`\-=\active \let-\realdash} +} + +\def\realdash{-} +\def\codedash{-\discretionary{}{}{}} +\def\codeunder{% + % this is all so @math{@code{var_name}+1} can work. In math mode, _ + % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) + % will therefore expand the active definition of _, which is us + % (inside @code that is), therefore an endless loop. + \ifusingtt{\ifmmode + \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_. + \else\normalunderscore \fi + \discretionary{}{}{}}% + {\_}% +} +\def\codex #1{\tclose{#1}\endgroup} + +% @kbd is like @code, except that if the argument is just one @key command, +% then @kbd has no effect. + +% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), +% `example' (@kbd uses ttsl only inside of @example and friends), +% or `code' (@kbd uses normal tty font always). +\def\kbdinputstyle{\parsearg\kbdinputstylexxx} +\def\kbdinputstylexxx#1{% + \def\arg{#1}% + \ifx\arg\worddistinct + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% + \else\ifx\arg\wordexample + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% + \else\ifx\arg\wordcode + \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% + \else + \errhelp = \EMsimple + \errmessage{Unknown @kbdinputstyle `\arg'}% + \fi\fi\fi +} +\def\worddistinct{distinct} +\def\wordexample{example} +\def\wordcode{code} + +% Default is `distinct.' +\kbdinputstyle distinct + +\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{\kbdfont\look}}\fi +\else{\tclose{\kbdfont\look}}\fi} + +% For @url, @env, @command quotes seem unnecessary, so use \code. +\let\url=\code +\let\env=\code +\let\command=\code + +% @uref (abbreviation for `urlref') takes an optional (comma-separated) +% second argument specifying the text to display and an optional third +% arg as text to display instead of (rather than in addition to) the url +% itself. First (mandatory) arg is the url. Perhaps eventually put in +% a hypertex \special here. +% +\def\uref#1{\douref #1,,,\finish} +\def\douref#1,#2,#3,#4\finish{\begingroup + \unsepspaces + \pdfurl{#1}% + \setbox0 = \hbox{\ignorespaces #3}% + \ifdim\wd0 > 0pt + \unhbox0 % third arg given, show only that + \else + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \ifpdf + \unhbox0 % PDF: 2nd arg given, show only it + \else + \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url + \fi + \else + \code{#1}% only url given, so show it + \fi + \fi + \endlink +\endgroup} + +% rms does not like angle brackets --karl, 17may97. +% So now @email is just like @uref, unless we are pdf. +% +%\def\email#1{\angleleft{\tt #1}\angleright} +\ifpdf + \def\email#1{\doemail#1,,\finish} + \def\doemail#1,#2,#3\finish{\begingroup + \unsepspaces + \pdfurl{mailto:#1}% + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi + \endlink + \endgroup} +\else + \let\email=\uref +\fi + +% Check if we are currently using a typewriter font. 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 property, we can check that font parameter. +% +\def\ifmonospace{\ifdim\fontdimen3\font=0pt } + +% 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} + +% @l was never documented to mean ``switch to the Lisp font'', +% and it is not used as such in any manual I can find. We need it for +% Polish suppressed-l. --karl, 22sep96. +%\def\l#1{{\li #1}\null} + +% Explicit font changes: @r, @sc, undocumented @ii. +\def\r#1{{\rm #1}} % roman font +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +% @acronym downcases the argument and prints in smallcaps. +\def\acronym#1{{\smallcaps \lowercase{#1}}} + +% @pounds{} is a sterling sign. +\def\pounds{{\it\$}} + + +\message{page headings,} + +\newskip\titlepagetopglue \titlepagetopglue = 1.5in +\newskip\titlepagebottomglue \titlepagebottomglue = 2pc + +% First the title page. Must do @settitle before @titlepage. +\newif\ifseenauthor +\newif\iffinishedtitlepage + +% Do an implicit @contents or @shortcontents after @end titlepage if the +% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage. +% +\newif\ifsetcontentsaftertitlepage + \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue +\newif\ifsetshortcontentsaftertitlepage + \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue + +\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 + \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% + % + \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines + \let\tt=\authortt}% + % + % 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{\titlefonts\rm ##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 + % + % Need this before the \...aftertitlepage checks so that if they are + % in effect the toc pages will come out with page numbers. + \HEADINGSon + % + % If they want short, they certainly want long too. + \ifsetshortcontentsaftertitlepage + \shortcontents + \contents + \global\let\shortcontents = \relax + \global\let\contents = \relax + \fi + % + \ifsetcontentsaftertitlepage + \contents + \global\let\contents = \relax + \global\let\shortcontents = \relax + \fi +} + +\def\finishtitlepage{% + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue +} + +%%% Set up page headings and footings. + +\let\thispage=\folio + +\newtoks\evenheadline % headline on even pages +\newtoks\oddheadline % headline on odd pages +\newtoks\evenfootline % footline on even pages +\newtoks\oddfootline % footline on 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{\oddheadingxxx{#1}\evenheadingxxx{#1}}% + +\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}}% + % + % Leave some space for the footline. Hopefully ok to assume + % @evenfooting will not be used by itself. + \global\advance\pageheight by -\baselineskip + \global\advance\vsize by -\baselineskip +} + +\gdef\everyfootingxxx#1{\oddfootingxxx{#1}\evenfootingxxx{#1}} +% +}% 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 at the start of a document, +% and turned `on' after @end titlepage. + +\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{ +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chapoddpage +} +\let\contentsalignmacro = \chappager + +% For single-sided printing, chapter title goes across top left of page, +% page number on top right. +\def\HEADINGSsingle{ +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chappager +} +\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}} +\global\let\contentsalignmacro = \chapoddpage +} + +\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}} +\global\let\contentsalignmacro = \chappager +} + +% Subroutines used in generating headings +% This produces Day Month Year style of output. +% Only define if not already defined, in case a txi-??.tex file has set +% up a different format (e.g., txi-cs.tex does this). +\ifx\today\undefined +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} +\fi + +% @settitle line... specifies the title of the document, for headings. +% It generates no output of its own. +\def\thistitle{\putwordNoTitle} +\def\settitle{\parsearg\settitlezzz} +\def\settitlezzz #1{\gdef\thistitle{#1}} + + +\message{tables,} +% 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\nobreak\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. + % + % 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.) However, if what follows is an environment + % such as @example, there will be no \parskip glue; then + % the negative vskip we just would cause the example and the item to + % crash together. So we use this bizarre value of 10001 as a signal + % to \aboveenvbreak to insert \parskip glue after all. + % (Possibly there are other commands that could be followed by + % @example which need the same treatment, but not section titles; or + % maybe section titles are the only special case and they should be + % penalty 10001...) + \penalty 10001 + \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. + \noindent + % Do this with kerns and \unhbox so that if there is a footnote in + % the item text, it can migrate to the main vertical list and + % eventually be printed. + \nobreak\kern-\tableindent + \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0 + \unhbox0 + \nobreak\kern\dimen0 + \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}{}{}{}{}} + +% @table, @ftable, @vtable. +\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}% Necessary 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 itemize + \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} + +% \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 . + % + \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, 3/6/96 +% +% @multitable ... @end multitable 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 @columnfractions .25 .3 .45 +% @item ... +% +% Numbers following @columnfractions 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. +% +% For those who want to use more than one line's worth of words in +% the preamble, break the line within one argument and it +% will parse correctly, i.e., +% +% @multitable {Column 1 template} {Column 2 template} {Column 3 +% template} +% Not: +% @multitable {Column 1 template} {Column 2 template} +% {Column 3 template} + +% 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, @multitable or @end multitable 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. +% @end multitable + +% Default dimensions may be reset by user. +% @multitableparskip is vertical space between paragraphs in table. +% @multitableparindent is paragraph indent in table. +% @multitablecolmargin is horizontal space to be left between columns. +% @multitablelinespace is space to leave between table items, baseline +% to baseline. +% 0pt means it depends on current normal line spacing. +% +\newskip\multitableparskip +\newskip\multitableparindent +\newdimen\multitablecolspace +\newskip\multitablelinespace +\multitableparskip=0pt +\multitableparindent=6pt +\multitablecolspace=12pt +\multitablelinespace=0pt + +% Macros used to set up halign preamble: +% +\let\endsetuptable\relax +\def\xendsetuptable{\endsetuptable} +\let\columnfractions\relax +\def\xcolumnfractions{\columnfractions} +\newif\ifsetpercent + +% #1 is the part of the @columnfraction before the decimal point, which +% is presumably either 0 or the empty string (but we don't check, we +% just throw it away). #2 is the decimal part, which we use as the +% percent of \hsize for this column. +\def\pickupwholefraction#1.#2 {% + \global\advance\colcount by 1 + \expandafter\xdef\csname col\the\colcount\endcsname{.#2\hsize}% + \setuptable +} + +\newcount\colcount +\def\setuptable#1{% + \def\firstarg{#1}% + \ifx\firstarg\xendsetuptable + \let\go = \relax + \else + \ifx\firstarg\xcolumnfractions + \global\setpercenttrue + \else + \ifsetpercent + \let\go\pickupwholefraction + \else + \global\advance\colcount by 1 + \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a + % separator; typically that is always in the input, anyway. + \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% + \fi + \fi + \ifx\go\pickupwholefraction + % Put the argument back for the \pickupwholefraction call, so + % we'll always have a period there to be parsed. + \def\go{\pickupwholefraction#1}% + \else + \let\go = \setuptable + \fi% + \fi + \go +} + +% @multitable ... @end multitable definitions: +% +\def\multitable{\parsearg\dotable} +\def\dotable#1{\bgroup + \vskip\parskip + \let\item=\crcrwithfootnotes + % A \tab used to include \hskip1sp. But then the space in a template + % line is not enough. That is bad. So let's go back to just & until + % we encounter the problem it was intended to solve again. --karl, + % nathan@acm.org, 20apr99. + \let\tab=&% + \let\startfootins=\startsavedfootnote + \tolerance=9500 + \hbadness=9500 + \setmultitablespacing + \parskip=\multitableparskip + \parindent=\multitableparindent + \overfullrule=0pt + \global\colcount=0 + \def\Emultitable{% + \global\setpercentfalse + \crcrwithfootnotes\crcr + \egroup\egroup + }% + % + % To parse everything between @multitable and @item: + \setuptable#1 \endsetuptable + % + % \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. + \everycr{\noalign{% + % + % \filbreak%% keeps underfull box messages off when table breaks over pages. + % Maybe so, but it also creates really weird page breaks when the table + % breaks over pages. Wouldn't \vfil be better? Wait until the problem + % manifests itself, so it can be fixed for real --karl. + \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 + \multistrut\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname + % + % In order to keep entries from bumping into each other + % we will add a \leftskip of \multitablecolspace to all columns after + % the first one. + % + % If a template has been used, we will add \multitablecolspace + % to the width of each template entry. + % + % If the 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. + % + % Make sure we don't inherit \rightskip from the outer environment. + \rightskip=0pt + \ifnum\colcount=1 + % The first column will be indented with the surrounding text. + \advance\hsize by\leftskip + \else + \ifsetpercent \else + % If user has not set preamble in terms of percent of \hsize + % we will advance \hsize by \multitablecolspace. + \advance\hsize by \multitablecolspace + \fi + % In either case we will make \leftskip=\multitablecolspace: + \leftskip=\multitablecolspace + \fi + % Ignoring space at the beginning and end avoids an occasional spurious + % blank line, when TeX decides to break the line at the space before the + % box from the multistrut, so the strut ends up on a line by itself. + % For example: + % @multitable @columnfractions .11 .89 + % @item @code{#} + % @tab Legal holiday which is valid in major parts of the whole country. + % Is automatically provided with highlighting sequences respectively marking + % characters. + \noindent\ignorespaces##\unskip\multistrut}\cr +} + +\def\setmultitablespacing{% test to see if user has set \multitablelinespace. +% If so, do nothing. If not, give it an appropriate dimension based on +% current baselineskip. +\ifdim\multitablelinespace=0pt +\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip +\global\advance\multitablelinespace by-\ht0 +%% strut to put in table in case some entry doesn't have descenders, +%% to keep lines equally spaced +\let\multistrut = \strut +\else +%% FIXME: what is \box0 supposed to be? +\gdef\multistrut{\vrule height\multitablelinespace depth\dp0 +width0pt\relax} \fi +%% Test to see if parskip is larger than space between lines of +%% table. If not, do nothing. +%% If so, set to same dimension as multitablelinespace. +\ifdim\multitableparskip>\multitablelinespace +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi% +\ifdim\multitableparskip=0pt +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi} + +% In case a @footnote appears inside an alignment, save the footnote +% text to a box and make the \insert when a row of the table is +% finished. Otherwise, the insertion is lost, it never migrates to the +% main vertical list. --kasal, 22jan03. +% +\newbox\savedfootnotes +% +% \dotable \let's \startfootins to this, so that \dofootnote will call +% it instead of starting the insertion right away. +\def\startsavedfootnote{% + \global\setbox\savedfootnotes = \vbox\bgroup + \unvbox\savedfootnotes +} +\def\crcrwithfootnotes{% + \crcr + \ifvoid\savedfootnotes \else + \noalign{\insert\footins{\box\savedfootnotes}}% + \fi +} + +\message{conditionals,} +% 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. +% +% We use \empty instead of \relax for the @def... commands, so that \end +% doesn't throw an error. For instance: +% @ignore +% @deffn ... +% @end deffn +% @end ignore +% +% The @end deffn is going to get expanded, because we're trying to allow +% nested conditionals. But we don't want to expand the actual @deffn, +% since it might be syntactically correct and intended to be ignored. +% Since \end checks for \relax, using \empty does not cause an error. +% +\def\ignoremorecommands{% + \let\defcodeindex = \relax + \let\defcv = \empty + \let\defcvx = \empty + \let\Edefcv = \empty + \let\deffn = \empty + \let\deffnx = \empty + \let\Edeffn = \empty + \let\defindex = \relax + \let\defivar = \empty + \let\defivarx = \empty + \let\Edefivar = \empty + \let\defmac = \empty + \let\defmacx = \empty + \let\Edefmac = \empty + \let\defmethod = \empty + \let\defmethodx = \empty + \let\Edefmethod = \empty + \let\defop = \empty + \let\defopx = \empty + \let\Edefop = \empty + \let\defopt = \empty + \let\defoptx = \empty + \let\Edefopt = \empty + \let\defspec = \empty + \let\defspecx = \empty + \let\Edefspec = \empty + \let\deftp = \empty + \let\deftpx = \empty + \let\Edeftp = \empty + \let\deftypefn = \empty + \let\deftypefnx = \empty + \let\Edeftypefn = \empty + \let\deftypefun = \empty + \let\deftypefunx = \empty + \let\Edeftypefun = \empty + \let\deftypeivar = \empty + \let\deftypeivarx = \empty + \let\Edeftypeivar = \empty + \let\deftypemethod = \empty + \let\deftypemethodx = \empty + \let\Edeftypemethod = \empty + \let\deftypeop = \empty + \let\deftypeopx = \empty + \let\Edeftypeop = \empty + \let\deftypevar = \empty + \let\deftypevarx = \empty + \let\Edeftypevar = \empty + \let\deftypevr = \empty + \let\deftypevrx = \empty + \let\Edeftypevr = \empty + \let\defun = \empty + \let\defunx = \empty + \let\Edefun = \empty + \let\defvar = \empty + \let\defvarx = \empty + \let\Edefvar = \empty + \let\defvr = \empty + \let\defvrx = \empty + \let\Edefvr = \empty + \let\clear = \relax + \let\down = \relax + \let\evenfooting = \relax + \let\evenheading = \relax + \let\everyfooting = \relax + \let\everyheading = \relax + \let\headings = \relax + \let\include = \relax + \let\item = \relax + \let\lowersections = \relax + \let\oddfooting = \relax + \let\oddheading = \relax + \let\printindex = \relax + \let\pxref = \relax + \let\raisesections = \relax + \let\ref = \relax + \let\set = \relax + \let\setchapternewpage = \relax + \let\setchapterstyle = \relax + \let\settitle = \relax + \let\up = \relax + \let\verbatiminclude = \relax + \let\xref = \relax +} + +% Ignore @ignore, @ifhtml, @ifinfo, and the like. +% +\def\direntry{\doignore{direntry}} +\def\documentdescriptionword{documentdescription} +\def\documentdescription{\doignore{documentdescription}} +\def\html{\doignore{html}} +\def\ifhtml{\doignore{ifhtml}} +\def\ifinfo{\doignore{ifinfo}} +\def\ifnottex{\doignore{ifnottex}} +\def\ifplaintext{\doignore{ifplaintext}} +\def\ifxml{\doignore{ifxml}} +\def\ignore{\doignore{ignore}} +\def\menu{\doignore{menu}} +\def\xml{\doignore{xml}} + +% @dircategory CATEGORY -- specify a category of the dir file +% which this file should belong to. Ignore this in TeX. +\let\dircategory = \comment + +% 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'. + % This @ is a catcode 12 token (that is the normal catcode of @ in + % this texinfo.tex file). We change the catcode of @ below to match. + \long\def\doignoretext##1@end #1{\enddoignore}% + % + % Make sure that spaces turn into tokens that match what \doignoretext wants. + \catcode\spaceChar = 10 + % + % Ignore braces, too, so mismatched braces don't cause trouble. + \catcode`\{ = 9 + \catcode`\} = 9 + % + % We must not have @c interpreted as a control sequence. + \catcode`\@ = 12 + % + \def\ignoreword{#1}% + \ifx\ignoreword\documentdescriptionword + % The c kludge breaks documentdescription, since + % `documentdescription' contains a `c'. Means not everything will + % be ignored inside @documentdescription, but oh well... + \else + % Make the letter c a comment character so that the rest of the line + % will be ignored. This way, the document can have (for example) + % @c @end ifinfo + % and the @end ifinfo will be properly ignored. + % (We've just changed @ to catcode 12.) + \catcode`\c = 14 + \fi + % + % And now expand the command defined above. + \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{ (See ftp://ftp.gnu.org/non-gnu/TeX.README.)} + \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{} + \global\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 chance of memory overflow, we follow the approach outlined on + % page 401 of the TeXbook. + % + \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 some sites + % might not 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. + \let\smallrm=\nullfont \let\smallit=\nullfont \let\smallsl=\nullfont + \let\smallbf=\nullfont \let\smalltt=\nullfont \let\smallsc=\nullfont + \let\smallsf=\nullfont + % Similarly for smallexample fonts. + \let\smallerrm=\nullfont \let\smallerit=\nullfont \let\smallersl=\nullfont + \let\smallerbf=\nullfont \let\smallertt=\nullfont \let\smallersc=\nullfont + \let\smallersf=\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}}% + % Do not execute macro definitions. + % `c' is a comment character, so the word `macro' will get cut off. + \def\macro{\doignore{ma}}% +} + +% @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. Make sure the catcode of space is correct to avoid +% losing inside @example, for instance. +% +\def\set{\begingroup\catcode` =10 + \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR. + \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 + \endgroup +} +% 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. +{ + \catcode`\_ = \active + % + % We might end up with active _ or - characters in the argument if + % we're called from @code, as @code{@value{foo-bar_}}. So \let any + % such active characters to their normal equivalents. + \gdef\value{\begingroup + \catcode`\-=\other \catcode`\_=\other + \indexbreaks \let_\normalunderscore + \valuexxx} +} +\def\valuexxx#1{\expandablevalue{#1}\endgroup} + +% We have this subroutine so that we can handle at least some @value's +% properly in indexes (we \let\value to this in \indexdummies). Ones +% whose names contain - or _ still won't work, but we can't do anything +% about that. The command has to be fully expandable (if the variable +% is set), since the result winds up in the index file. This means that +% if the variable's value contains other Texinfo commands, it's almost +% certain it will fail (although perhaps we could fix that with +% sufficient work to do a one-level expansion on the result, instead of +% complete). +% +\def\expandablevalue#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + {[No value for ``#1'']}% + \message{Variable `#1', used in @value, is not set.}% + \else + \csname SET#1\endcsname + \fi +} + +% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined +% with @set. +% +\def\ifset{\parsearg\doifset} +\def\doifset#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \let\next=\ifsetfail + \else + \let\next=\ifsetsucceed + \fi + \next +} +\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\doifclear} +\def\doifclear#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \let\next=\ifclearsucceed + \else + \let\next=\ifclearfail + \fi + \next +} +\def\ifclearsucceed{\conditionalsucceed{ifclear}} +\def\ifclearfail{\nestedignore{ifclear}} +\defineunmatchedend{ifclear} + +% @iftex, @ifnothtml, @ifnotinfo, @ifnotplaintext always succeed; we +% read the text following, through the first @end iftex (etc.). Make +% `@end iftex' (etc.) valid only after an @iftex. +% +\def\iftex{\conditionalsucceed{iftex}} +\def\ifnothtml{\conditionalsucceed{ifnothtml}} +\def\ifnotinfo{\conditionalsucceed{ifnotinfo}} +\def\ifnotplaintext{\conditionalsucceed{ifnotplaintext}} +\defineunmatchedend{iftex} +\defineunmatchedend{ifnothtml} +\defineunmatchedend{ifnotinfo} +\defineunmatchedend{ifnotplaintext} + +% True conditional. Since \set globally defines its variables, we can +% just start and end a group (to keep the @end definition undefined at +% the outer level). +% +\def\conditionalsucceed#1{\begingroup + \expandafter\def\csname E#1\endcsname{\endgroup}% +} + +% @defininfoenclose. +\let\definfoenclose=\comment + + +\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{% + \iflinks + \expandafter\newwrite \csname#1indfile\endcsname + \openout \csname#1indfile\endcsname \jobname.#1 % Open the file + \fi + \expandafter\xdef\csname#1index\endcsname{% % Define @#1index + \noexpand\doindex{#1}} +} + +% @defindex foo == \newindex{foo} +% +\def\defindex{\parsearg\newindex} + +% Define @defcodeindex, like @defindex except put all entries in @code. +% +\def\defcodeindex{\parsearg\newcodeindex} +% +\def\newcodeindex#1{% + \iflinks + \expandafter\newwrite \csname#1indfile\endcsname + \openout \csname#1indfile\endcsname \jobname.#1 + \fi + \expandafter\xdef\csname#1index\endcsname{% + \noexpand\docodeindex{#1}}% +} + + +% @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. +% +% @syncodeindex foo bar similar, but put all entries made for index foo +% inside @code. +% +\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}} +\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}} + +% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo), +% #3 the target index (bar). +\def\dosynindex#1#2#3{% + % Only do \closeout if we haven't already done it, else we'll end up + % closing the target index. + \expandafter \ifx\csname donesynindex#2\endcsname \undefined + % The \closeout helps reduce unnecessary open files; the limit on the + % Acorn RISC OS is a mere 16 files. + \expandafter\closeout\csname#2indfile\endcsname + \expandafter\let\csname\donesynindex#2\endcsname = 1 + \fi + % redefine \fooindfile: + \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname + \expandafter\let\csname#2indfile\endcsname=\temp + % redefine \fooindex: + \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}% +} + +% 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}}} + +% Take care of Texinfo commands that can appear in an index entry. +% Since there are some commands we want to expand, and others we don't, +% we have to laboriously prevent expansion for those that we don't. +% +\def\indexdummies{% + \def\@{@}% change to @@ when we switch to @ as escape char in index files. + \def\ {\realbackslash\space }% + % Need these in case \tex is in effect and \{ is a \delimiter again. + % But can't use \lbracecmd and \rbracecmd because texindex assumes + % braces and backslashes are used only as delimiters. + \let\{ = \mylbrace + \let\} = \myrbrace + % + % \definedummyword defines \#1 as \realbackslash #1\space, thus + % effectively preventing its expansion. This is used only for control + % words, not control letters, because the \space would be incorrect + % for control characters, but is needed to separate the control word + % from whatever follows. + % + % For control letters, we have \definedummyletter, which omits the + % space. + % + % These can be used both for control words that take an argument and + % those that do not. If it is followed by {arg} in the input, then + % that will dutifully get written to the index (or wherever). + % + \def\definedummyword##1{% + \expandafter\def\csname ##1\endcsname{\realbackslash ##1\space}% + }% + \def\definedummyletter##1{% + \expandafter\def\csname ##1\endcsname{\realbackslash ##1}% + }% + % + % Do the redefinitions. + \commondummies +} + +% For the aux file, @ is the escape character. So we want to redefine +% everything using @ instead of \realbackslash. When everything uses +% @, this will be simpler. +% +\def\atdummies{% + \def\@{@@}% + \def\ {@ }% + \let\{ = \lbraceatcmd + \let\} = \rbraceatcmd + % + % (See comments in \indexdummies.) + \def\definedummyword##1{% + \expandafter\def\csname ##1\endcsname{@##1\space}% + }% + \def\definedummyletter##1{% + \expandafter\def\csname ##1\endcsname{@##1}% + }% + % + % Do the redefinitions. + \commondummies +} + +% Called from \indexdummies and \atdummies. \definedummyword and +% \definedummyletter must be defined first. +% +\def\commondummies{% + % + \normalturnoffactive + % + % Control letters and accents. + \definedummyletter{_}% + \definedummyletter{,}% + \definedummyletter{"}% + \definedummyletter{`}% + \definedummyletter{'}% + \definedummyletter{^}% + \definedummyletter{~}% + \definedummyletter{=}% + \definedummyword{u}% + \definedummyword{v}% + \definedummyword{H}% + \definedummyword{dotaccent}% + \definedummyword{ringaccent}% + \definedummyword{tieaccent}% + \definedummyword{ubaraccent}% + \definedummyword{udotaccent}% + \definedummyword{dotless}% + % + % Other non-English letters. + \definedummyword{AA}% + \definedummyword{AE}% + \definedummyword{L}% + \definedummyword{OE}% + \definedummyword{O}% + \definedummyword{aa}% + \definedummyword{ae}% + \definedummyword{l}% + \definedummyword{oe}% + \definedummyword{o}% + \definedummyword{ss}% + % + % Although these internal commands shouldn't show up, sometimes they do. + \definedummyword{bf}% + \definedummyword{gtr}% + \definedummyword{hat}% + \definedummyword{less}% + \definedummyword{sf}% + \definedummyword{sl}% + \definedummyword{tclose}% + \definedummyword{tt}% + % + % Texinfo font commands. + \definedummyword{b}% + \definedummyword{i}% + \definedummyword{r}% + \definedummyword{sc}% + \definedummyword{t}% + % + \definedummyword{TeX}% + \definedummyword{acronym}% + \definedummyword{cite}% + \definedummyword{code}% + \definedummyword{command}% + \definedummyword{dfn}% + \definedummyword{dots}% + \definedummyword{emph}% + \definedummyword{env}% + \definedummyword{file}% + \definedummyword{kbd}% + \definedummyword{key}% + \definedummyword{math}% + \definedummyword{option}% + \definedummyword{samp}% + \definedummyword{strong}% + \definedummyword{uref}% + \definedummyword{url}% + \definedummyword{var}% + \definedummyword{w}% + % + % Assorted special characters. + \definedummyword{bullet}% + \definedummyword{copyright}% + \definedummyword{dots}% + \definedummyword{enddots}% + \definedummyword{equiv}% + \definedummyword{error}% + \definedummyword{expansion}% + \definedummyword{minus}% + \definedummyword{pounds}% + \definedummyword{point}% + \definedummyword{print}% + \definedummyword{result}% + % + % Handle some cases of @value -- where the variable name does not + % contain - or _, and the value does not contain any + % (non-fully-expandable) commands. + \let\value = \expandablevalue + % + % Normal spaces, not active ones. + \unsepspaces + % + % No macro expansion. + \turnoffmacros +} + +% If an index command is used in an @example environment, any spaces +% therein should become regular spaces in the raw index file, not the +% expansion of \tie (\leavevmode \penalty \@M \ ). +{\obeyspaces + \gdef\unsepspaces{\obeyspaces\let =\space}} + + +% \indexnofonts is used when outputting the strings to sort the index +% by, and when constructing control sequence names. It eliminates all +% control sequences and just writes whatever the best ASCII sort string +% would be for a given command (usually its argument). +% +\def\indexdummytex{TeX} +\def\indexdummydots{...} +% +\def\indexnofonts{% + \def\ { }% + \def\@{@}% + % how to handle braces? + \def\_{\normalunderscore}% + % + \let\,=\asis + \let\"=\asis + \let\`=\asis + \let\'=\asis + \let\^=\asis + \let\~=\asis + \let\==\asis + \let\u=\asis + \let\v=\asis + \let\H=\asis + \let\dotaccent=\asis + \let\ringaccent=\asis + \let\tieaccent=\asis + \let\ubaraccent=\asis + \let\udotaccent=\asis + \let\dotless=\asis + % + % Other non-English letters. + \def\AA{AA}% + \def\AE{AE}% + \def\L{L}% + \def\OE{OE}% + \def\O{O}% + \def\aa{aa}% + \def\ae{ae}% + \def\l{l}% + \def\oe{oe}% + \def\o{o}% + \def\ss{ss}% + \def\exclamdown{!}% + \def\questiondown{?}% + % + % Don't no-op \tt, since it isn't a user-level command + % and is used in the definitions of the active chars like <, >, |, etc. + % Likewise with the other plain tex font commands. + %\let\tt=\asis + % + % Texinfo font commands. + \let\b=\asis + \let\i=\asis + \let\r=\asis + \let\sc=\asis + \let\t=\asis + % + \let\TeX=\indexdummytex + \let\acronym=\asis + \let\cite=\asis + \let\code=\asis + \let\command=\asis + \let\dfn=\asis + \let\dots=\indexdummydots + \let\emph=\asis + \let\env=\asis + \let\file=\asis + \let\kbd=\asis + \let\key=\asis + \let\math=\asis + \let\option=\asis + \let\samp=\asis + \let\strong=\asis + \let\uref=\asis + \let\url=\asis + \let\var=\asis + \let\w=\asis +} + +\let\indexbackslash=0 %overridden during \printindex. +\let\SETmarginindex=\relax % put index entries in margin (undocumented)? + +% For \ifx comparisons. +\def\emptymacro{\empty} + +% Most index entries go through here, but \dosubind is the general case. +% +\def\doind#1#2{\dosubind{#1}{#2}\empty} + +% Workhorse for all \fooindexes. +% #1 is name of index, #2 is stuff to put there, #3 is subentry -- +% \empty if called from \doind, as we usually are. The main exception +% is with defuns, which call us directly. +% +\def\dosubind#1#2#3{% + % Put the index entry in the margin if desired. + \ifx\SETmarginindex\relax\else + \insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% + \fi + {% + \count255=\lastpenalty + {% + \indexdummies % Must do this here, since \bf, etc expand at this stage + \escapechar=`\\ + {% + \let\folio = 0% We will 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. + % + % The main index entry text. + \toks0 = {#2}% + % + % If third arg is present, precede it with space in sort key. + \def\thirdarg{#3}% + \ifx\thirdarg\emptymacro \else + % If the third (subentry) arg is present, add it to the index + % line to write. + \toks0 = \expandafter{\the\toks0 \space #3}% + \fi + % + % Process the index entry with all font commands turned off, to + % get the string to sort by. + {\indexnofonts + \edef\temp{\the\toks0}% need full expansion + \xdef\indexsorttmp{\temp}% + }% + % + % Set up the complete index entry, with both the sort key and + % the original text, including any font commands. We write + % three arguments to \entry to the .?? file (four in the + % subentry case), texindex reduces to two when writing the .??s + % sorted result. + \edef\temp{% + \write\csname#1indfile\endcsname{% + \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}% + }% + % + % If a skip is the last thing on the list now, preserve it + % by backing up by \lastskip, doing the \write, then inserting + % the skip again. Otherwise, the whatsit generated by the + % \write will make \lastskip zero. The result is that sequences + % like this: + % @end defun + % @tindex whatever + % @defun ... + % will have extra space inserted, because the \medbreak in the + % start of the @defun won't see the skip inserted by the @end of + % the previous defun. + % + % But don't do any of this if we're not in vertical mode. We + % don't want to do a \vskip and prematurely end a paragraph. + % + % Avoid page breaks due to these extra skips, too. + % + \iflinks + \ifvmode + \skip0 = \lastskip + \ifdim\lastskip = 0pt \else \nobreak\vskip-\skip0 \fi + \fi + % + \temp % do the write + % + \ifvmode \ifdim\skip0 = 0pt \else \nobreak\vskip\skip0 \fi \fi + \fi + }% + }% + \penalty\count255 + }% +} + +% 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. + +% @printindex causes a particular index (the ??s file) to get printed. +% It does not print any chapter heading (usually an @unnumbered). +% +\def\printindex{\parsearg\doprintindex} +\def\doprintindex#1{\begingroup + \dobreak \chapheadingskip{10000}% + % + \smallfonts \rm + \tolerance = 9500 + \indexbreaks + % + % See if the index file exists and is nonempty. + % Change catcode of @ here so that if the index file contains + % \initial {@} + % as its first line, TeX doesn't complain about mismatched braces + % (because it thinks @} is a control sequence). + \catcode`\@ = 11 + \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. + \putwordIndexNonexistent + \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 + \putwordIndexIsEmpty + \else + % Index files are almost Texinfo source, but we use \ as the escape + % character. It would be better to use @, but that's too big a change + % to make right now. + \def\indexbackslash{\rawbackslashxx}% + \catcode`\\ = 0 + \escapechar = `\\ + \begindoublecolumns + \input \jobname.#1s + \enddoublecolumns + \fi + \fi + \closein 1 +\endgroup} + +% These macros are used by the sorted index file itself. +% Change them to control the appearance of the index. + +\def\initial#1{{% + % Some minor font changes for the special characters. + \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt + % + % Remove any glue we may have, we'll be inserting our own. + \removelastskip + % + % We like breaks before the index initials, so insert a bonus. + \penalty -300 + % + % Typeset the initial. Making this add up to a whole number of + % baselineskips increases the chance of the dots lining up from column + % to column. It still won't often be perfect, because of the stretch + % we need before each entry, but it's better. + % + % No shrink because it confuses \balancecolumns. + \vskip 1.67\baselineskip plus .5\baselineskip + \leftline{\secbf #1}% + \vskip .33\baselineskip plus .1\baselineskip + % + % Do our best not to break after the initial. + \nobreak +}} + +% 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 + % + % A bit of stretch before each entry for the benefit of balancing columns. + \vskip 0pt plus1pt + % + % 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 kludged 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. + \ifpdf + \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. + \else + \ #2% The page number ends the paragraph. + \fi + \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 + \ifpdf + \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. + \else + #2 + \fi + \par +}} + +% Define two-column mode, which we use to typeset indexes. +% Adapted from the TeXbook, page 416, which is to say, +% the manmac.tex format used to print the TeXbook itself. +\catcode`\@=11 + +\newbox\partialpage +\newdimen\doublecolumnhsize + +\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns + % Grab any single-column material above us. + \output = {% + % + % Here is a possibility not foreseen in manmac: if we accumulate a + % whole lot of material, we might end up calling this \output + % routine twice in a row (see the doublecol-lose test, which is + % essentially a couple of indexes with @setchapternewpage off). In + % that case we just ship out what is in \partialpage with the normal + % output routine. Generally, \partialpage will be empty when this + % runs and this will be a no-op. See the indexspread.tex test case. + \ifvoid\partialpage \else + \onepageout{\pagecontents\partialpage}% + \fi + % + \global\setbox\partialpage = \vbox{% + % Unvbox the main output page. + \unvbox\PAGE + \kern-\topskip \kern\baselineskip + }% + }% + \eject % run that output routine to set \partialpage + % + % Use the double-column output routine for subsequent pages. + \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 in one place. + % + % 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 +} + +% The double-column output routine for all double-column pages except +% the last. +% +\def\doublecolumnout{% + \splittopskip=\topskip \splitmaxdepth=\maxdepth + % Get the available space for the double columns -- the normal + % (undoubled) page height minus any material left over from the + % previous page. + \dimen@ = \vsize + \divide\dimen@ by 2 + \advance\dimen@ by -\ht\partialpage + % + % box0 will be the left-hand column, box2 the right. + \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ + \onepageout\pagesofar + \unvbox255 + \penalty\outputpenalty +} +% +% Re-output the contents of the output page -- any previous material, +% followed by the two boxes we just split, in box0 and box2. +\def\pagesofar{% + \unvbox\partialpage + % + \hsize = \doublecolumnhsize + \wd0=\hsize \wd2=\hsize + \hbox to\pagewidth{\box0\hfil\box2}% +} +% +% All done with double columns. +\def\enddoublecolumns{% + \output = {% + % Split the last of the double-column material. Leave it on the + % current page, no automatic page break. + \balancecolumns + % + % If we end up splitting too much material for the current page, + % though, there will be another page break right after this \output + % invocation ends. Having called \balancecolumns once, we do not + % want to call it again. Therefore, reset \output to its normal + % definition right away. (We hope \balancecolumns will never be + % called on to balance too much material, but if it is, this makes + % the output somewhat more palatable.) + \global\output = {\onepageout{\pagecontents\PAGE}}% + }% + \eject + \endgroup % started in \begindoublecolumns + % + % \pagegoal was set to the doubled \vsize above, since we restarted + % the current page. We're now back to normal single-column + % typesetting, so reset \pagegoal to the normal \vsize (after the + % \endgroup where \vsize got restored). + \pagegoal = \vsize +} +% +% Called at the end of the double column material. +\def\balancecolumns{% + \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120. + \dimen@ = \ht0 + \advance\dimen@ by \topskip + \advance\dimen@ by-\baselineskip + \divide\dimen@ by 2 % target to split to + %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}% + \splittopskip = \topskip + % Loop until we get a decent breakpoint. + {% + \vbadness = 10000 + \loop + \global\setbox3 = \copy0 + \global\setbox1 = \vsplit3 to \dimen@ + \ifdim\ht3>\dimen@ + \global\advance\dimen@ by 1pt + \repeat + }% + %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}% + \setbox0=\vbox to\dimen@{\unvbox1}% + \setbox2=\vbox to\dimen@{\unvbox3}% + % + \pagesofar +} +\catcode`\@ = \other + + +\message{sectioning,} +% 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} +% We do the following for the sake of pdftex, which needs the actual +% letter in the expansion, not just typeset. +\def\appendixletter{% + \ifnum\appendixno=`A A% + \else\ifnum\appendixno=`B B% + \else\ifnum\appendixno=`C C% + \else\ifnum\appendixno=`D D% + \else\ifnum\appendixno=`E E% + \else\ifnum\appendixno=`F F% + \else\ifnum\appendixno=`G G% + \else\ifnum\appendixno=`H H% + \else\ifnum\appendixno=`I I% + \else\ifnum\appendixno=`J J% + \else\ifnum\appendixno=`K K% + \else\ifnum\appendixno=`L L% + \else\ifnum\appendixno=`M M% + \else\ifnum\appendixno=`N N% + \else\ifnum\appendixno=`O O% + \else\ifnum\appendixno=`P P% + \else\ifnum\appendixno=`Q Q% + \else\ifnum\appendixno=`R R% + \else\ifnum\appendixno=`S S% + \else\ifnum\appendixno=`T T% + \else\ifnum\appendixno=`U U% + \else\ifnum\appendixno=`V V% + \else\ifnum\appendixno=`W W% + \else\ifnum\appendixno=`X X% + \else\ifnum\appendixno=`Y Y% + \else\ifnum\appendixno=`Z Z% + % The \the is necessary, despite appearances, because \appendixletter is + % expanded while writing the .toc file. \char\appendixno is not + % expandable, thus it is written literally, thus all appendixes come out + % with the same letter (or @) in the toc without it. + \else\char\the\appendixno + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi} + +% Each @chapter defines this as the name of the chapter. +% page headings and footings can use it. @section does likewise. +\def\thischapter{} +\def\thissection{} + +\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 +} + +% @chapter, @appendix, @unnumbered. +\def\thischaptername{No Chapter Title} +\outer\def\chapter{\parsearg\chapteryyy} +\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz #1{% + \secno=0 \subsecno=0 \subsubsecno=0 + \global\advance \chapno by 1 \message{\putwordChapter\space \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}% + \writetocentry{chap}{#1}{{\the\chapno}} + \donoderef + \global\let\section = \numberedsec + \global\let\subsection = \numberedsubsec + \global\let\subsubsection = \numberedsubsubsec +} + +% we use \chapno to avoid indenting back +\def\appendixbox#1{% + \setbox0 = \hbox{\putwordAppendix{} \the\chapno}% + \hbox to \wd0{#1\hss}} + +\outer\def\appendix{\parsearg\appendixyyy} +\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz +\def\appendixzzz #1{% + \secno=0 \subsecno=0 \subsubsecno=0 + \global\advance \appendixno by 1 + \message{\putwordAppendix\space \appendixletter}% + \chapmacro {#1}{\appendixbox{\putwordAppendix{} \appendixletter}}% + \gdef\thissection{#1}% + \gdef\thischaptername{#1}% + \xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% + \writetocentry{appendix}{#1}{{\appendixletter}} + \appendixnoderef + \global\let\section = \appendixsec + \global\let\subsection = \appendixsubsec + \global\let\subsubsection = \appendixsubsubsec +} + +% @centerchap is like @unnumbered, but the heading is centered. +\outer\def\centerchap{\parsearg\centerchapyyy} +\def\centerchapyyy #1{{\let\unnumbchapmacro=\centerchapmacro \unnumberedyyy{#1}}} + +% @top is like @unnumbered. +\outer\def\top{\parsearg\unnumberedyyy} + +\outer\def\unnumbered{\parsearg\unnumberedyyy} +\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +\def\unnumberedzzz #1{% + \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 to achieve this: TeX expands \the only once, + % simply yielding the contents of . (We also do this for + % the toc entries.) + \toks0 = {#1}\message{(\the\toks0)}% + % + \unnumbchapmacro {#1}% + \gdef\thischapter{#1}\gdef\thissection{#1}% + \writetocentry{unnumbchap}{#1}{{\the\chapno}} + \unnumbnoderef + \global\let\section = \unnumberedsec + \global\let\subsection = \unnumberedsubsec + \global\let\subsubsection = \unnumberedsubsubsec +} + +% Sections. +\outer\def\numberedsec{\parsearg\secyyy} +\def\secyyy #1{\numhead1{#1}} % normally calls seczzz +\def\seczzz #1{% + \subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % + \gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% + \writetocentry{sec}{#1}{{\the\chapno}{\the\secno}} + \donoderef + \nobreak +} + +\outer\def\appendixsection{\parsearg\appendixsecyyy} +\outer\def\appendixsec{\parsearg\appendixsecyyy} +\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz +\def\appendixsectionzzz #1{% + \subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % + \gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% + \writetocentry{sec}{#1}{{\appendixletter}{\the\secno}} + \appendixnoderef + \nobreak +} + +\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} +\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz +\def\unnumberedseczzz #1{% + \plainsecheading {#1}\gdef\thissection{#1}% + \writetocentry{unnumbsec}{#1}{{\the\chapno}{\the\secno}} + \unnumbnoderef + \nobreak +} + +% Subsections. +\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} +\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz +\def\numberedsubseczzz #1{% + \gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % + \subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% + \writetocentry{subsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}} + \donoderef + \nobreak +} + +\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} +\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz +\def\appendixsubseczzz #1{% + \gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % + \subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% + \writetocentry{subsec}{#1}{{\appendixletter}{\the\secno}{\the\subsecno}} + \appendixnoderef + \nobreak +} + +\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} +\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +\def\unnumberedsubseczzz #1{% + \plainsubsecheading {#1}\gdef\thissection{#1}% + \writetocentry{unnumbsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}} + \unnumbnoderef + \nobreak +} + +% Subsubsections. +\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} +\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz +\def\numberedsubsubseczzz #1{% + \gdef\thissection{#1}\global\advance \subsubsecno by 1 % + \subsubsecheading {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% + \writetocentry{subsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}} + \donoderef + \nobreak +} + +\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} +\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz +\def\appendixsubsubseczzz #1{% + \gdef\thissection{#1}\global\advance \subsubsecno by 1 % + \subsubsecheading {#1} + {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% + \writetocentry{subsubsec}{#1}{{\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}} + \appendixnoderef + \nobreak +} + +\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} +\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +\def\unnumberedsubsubseczzz #1{% + \plainsubsubsecheading {#1}\gdef\thissection{#1}% + \writetocentry{unnumbsubsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}} + \unnumbnoderef + \nobreak +} + +% 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} + +% @heading, @subheading, @subsubheading. +\def\heading{\parsearg\plainsecheading} +\def\subheading{\parsearg\plainsubsecheading} +\def\subsubheading{\parsearg\plainsubsubsecheading} + +% 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 + +\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\contentsalignmacro = \chappager +\global\let\pchapsepmacro=\chapbreak +\global\let\pagealignmacro=\chappager} + +\def\CHAPPAGon{% +\global\let\contentsalignmacro = \chappager +\global\let\pchapsepmacro=\chappager +\global\let\pagealignmacro=\chappager +\global\def\HEADINGSon{\HEADINGSsingle}} + +\def\CHAPPAGodd{ +\global\let\contentsalignmacro = \chapoddpage +\global\let\pchapsepmacro=\chapoddpage +\global\let\pagealignmacro=\chapoddpage +\global\def\HEADINGSon{\HEADINGSdouble}} + +\CHAPPAGon + +\def\CHAPFplain{ +\global\let\chapmacro=\chfplain +\global\let\unnumbchapmacro=\unnchfplain +\global\let\centerchapmacro=\centerchfplain} + +% Plain chapter opening. +% #1 is the text, #2 the chapter number or empty if unnumbered. +\def\chfplain#1#2{% + \pchapsepmacro + {% + \chapfonts \rm + \def\chapnum{#2}% + \setbox0 = \hbox{#2\ifx\chapnum\empty\else\enspace\fi}% + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright + \hangindent = \wd0 \centerparametersmaybe + \unhbox0 #1\par}% + }% + \nobreak\bigskip % no page break after a chapter title + \nobreak +} + +% Plain opening for unnumbered. +\def\unnchfplain#1{\chfplain{#1}{}} + +% @centerchap -- centered and unnumbered. +\let\centerparametersmaybe = \relax +\def\centerchfplain#1{{% + \def\centerparametersmaybe{% + \advance\rightskip by 3\rightskip + \leftskip = \rightskip + \parfillskip = 0pt + }% + \chfplain{#1}{}% +}} + +\CHAPFplain % The default + +\def\unnchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\nobreak +} + +\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\centerchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt + \hfill {\rm #1}\hfill}}\bigskip \par\nobreak +} + +\def\CHAPFopen{ +\global\let\chapmacro=\chfopen +\global\let\unnumbchapmacro=\unnchfopen +\global\let\centerchapmacro=\centerchfopen} + + +% Section titles. +\newskip\secheadingskip +\def\secheadingbreak{\dobreak \secheadingskip {-1000}} +\def\secheading#1#2#3{\sectionheading{sec}{#2.#3}{#1}} +\def\plainsecheading#1{\sectionheading{sec}{}{#1}} + +% Subsection titles. +\newskip \subsecheadingskip +\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} +\def\subsecheading#1#2#3#4{\sectionheading{subsec}{#2.#3.#4}{#1}} +\def\plainsubsecheading#1{\sectionheading{subsec}{}{#1}} + +% Subsubsection titles. +\let\subsubsecheadingskip = \subsecheadingskip +\let\subsubsecheadingbreak = \subsecheadingbreak +\def\subsubsecheading#1#2#3#4#5{\sectionheading{subsubsec}{#2.#3.#4.#5}{#1}} +\def\plainsubsubsecheading#1{\sectionheading{subsubsec}{}{#1}} + + +% Print any size section title. +% +% #1 is the section type (sec/subsec/subsubsec), #2 is the section +% number (maybe empty), #3 the text. +\def\sectionheading#1#2#3{% + {% + \expandafter\advance\csname #1headingskip\endcsname by \parskip + \csname #1headingbreak\endcsname + }% + {% + % Switch to the right set of fonts. + \csname #1fonts\endcsname \rm + % + % Only insert the separating space if we have a section number. + \def\secnum{#2}% + \setbox0 = \hbox{#2\ifx\secnum\empty\else\enspace\fi}% + % + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright + \hangindent = \wd0 % zero if no section number + \unhbox0 #3}% + }% + % Add extra space after the heading -- either a line space or a + % paragraph space, whichever is more. (Some people like to set + % \parskip to large values for some reason.) Don't allow stretch, though. + \nobreak + \ifdim\parskip>\normalbaselineskip + \kern\parskip + \else + \kern\normalbaselineskip + \fi + \nobreak +} + + +\message{toc,} +% Table of contents. +\newwrite\tocfile + +% Write an entry to the toc file, opening it if necessary. +% Called from @chapter, etc. We supply {\folio} at the end of the +% argument, which will end up as the last argument to the \...entry macro. +% +% Usage: \writetocentry{chap}{The Name of The Game}{{\the\chapno}} +% We open the .toc file for writing here instead of at @setfilename (or +% any other fixed time) so that @contents can be anywhere in the document. +% +\newif\iftocfileopened +\def\writetocentry#1#2#3{% + \iftocfileopened\else + \immediate\openout\tocfile = \jobname.toc + \global\tocfileopenedtrue + \fi + % + \iflinks + \toks0 = {#2}% + \edef\temp{\write\tocfile{\realbackslash #1entry{\the\toks0}#3{\folio}}}% + \temp + \fi + % + % Tell \shipout to create a page destination if we're doing pdf, which + % will be the target of the links in the table of contents. We can't + % just do it on every page because the title pages are numbered 1 and + % 2 (the page numbers aren't printed), and so are the first two pages + % of the document. Thus, we'd have two destinations named `1', and + % two named `2'. + \ifpdf \pdfmakepagedesttrue \fi +} + +\newskip\contentsrightmargin \contentsrightmargin=1in +\newcount\savepageno +\newcount\lastnegativepageno \lastnegativepageno = -1 + +% Finish up the main text and prepare to read what we've written +% to \tocfile. +% +\def\startcontents#1{% + % If @setchapternewpage on, and @headings double, the contents should + % start on an odd page, unlike chapters. Thus, we maintain + % \contentsalignmacro in parallel with \pagealignmacro. + % From: Torbjorn Granlund + \contentsalignmacro + \immediate\closeout\tocfile + % + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \unnumbchapmacro{#1}\def\thischapter{}% + \savepageno = \pageno + \begingroup % Set up to handle contents files properly. + \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 + % We can't do this, because then an actual ^ in a section + % title fails, e.g., @chapter ^ -- exponentiation. --karl, 9jul97. + %\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. + % + % Roman numerals for page numbers. + \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi +} + + +% Normal (long) toc. +\def\contents{% + \startcontents{\putwordTOC}% + \openin 1 \jobname.toc + \ifeof 1 \else + \closein 1 + \input \jobname.toc + \fi + \vfill \eject + \contentsalignmacro % in case @setchapternewpage odd is in effect + \pdfmakeoutlines + \endgroup + \lastnegativepageno = \pageno + \global\pageno = \savepageno +} + +% And just the chapters. +\def\summarycontents{% + \startcontents{\putwordShortTOC}% + % + \let\chapentry = \shortchapentry + \let\appendixentry = \shortappendixentry + \let\unnumbchapentry = \shortunnumberedentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf + \let\sl=\shortcontsl \let\tt=\shortconttt + \rm + \hyphenpenalty = 10000 + \advance\baselineskip by 1pt % Open it up a little. + \def\secentry ##1##2##3##4{} + \def\subsecentry ##1##2##3##4##5{} + \def\subsubsecentry ##1##2##3##4##5##6{} + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry + \openin 1 \jobname.toc + \ifeof 1 \else + \closein 1 + \input \jobname.toc + \fi + \vfill \eject + \contentsalignmacro % in case @setchapternewpage odd is in effect + \endgroup + \lastnegativepageno = \pageno + \global\pageno = \savepageno +} +\let\shortcontents = \summarycontents + +\ifpdf + \pdfcatalog{/PageMode /UseOutlines}% +\fi + +% 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, ... + +% Chapters, in the main contents. +\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}} +% +% Chapters, in the short toc. +% See comments in \dochapentry re vbox and related settings. +\def\shortchapentry#1#2#3{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#3\egroup}% +} + +% Appendices, in the main contents. +\def\appendixentry#1#2#3{% + \dochapentry{\appendixbox{\putwordAppendix{} #2}\labelspace#1}{#3}} +% +% Appendices, in the short toc. +\let\shortappendixentry = \shortchapentry + +% 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. +% +\newdimen\shortappendixwidth +% +\def\shortchaplabel#1{% + % This space should be enough, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % But use \hss just in case. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in by \shortchapentry above.) + \dimen0 = 1em + \hbox to \dimen0{#1\hss}% +} + +% Unnumbered chapters. +\def\unnumbchapentry#1#2#3{\dochapentry{#1}{#3}} +\def\shortunnumberedentry#1#2#3{\tocentry{#1}{\doshortpageno\bgroup#3\egroup}} + +% Sections. +\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} +\def\unnumbsecentry#1#2#3#4{\dosecentry{#1}{#4}} + +% Subsections. +\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} +\def\unnumbsubsecentry#1#2#3#4#5{\dosubsecentry{#1}{#5}} + +% And subsubsections. +\def\subsubsecentry#1#2#3#4#5#6{% + \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} +\def\unnumbsubsubsecentry#1#2#3#4#5#6{\dosubsubsecentry{#1}{#6}} + +% 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 want it to be at chapters +% if at all possible; hence the \penalty. +\def\dochapentry#1#2{% + \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip + \begingroup + \chapentryfonts + \tocentry{#1}{\dopageno\bgroup#2\egroup}% + \endgroup + \nobreak\vskip .25\baselineskip plus.1\baselineskip +} + +\def\dosecentry#1#2{\begingroup + \secentryfonts \leftskip=\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\endgroup} + +\def\dosubsecentry#1#2{\begingroup + \subsecentryfonts \leftskip=2\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\endgroup} + +\def\dosubsubsecentry#1#2{\begingroup + \subsubsecentryfonts \leftskip=3\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\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 + \vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks + % Do not use \turnoffactive in these arguments. Since the toc is + % typeset in cmr, characters such as _ would come out wrong; we + % have to do the usual translation tricks. + \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,} +% @foo ... @end foo. + +% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. +% +% 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. +% +\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}} + +% The @error{} command. +% Adapted from the TeXbook's \boxit. +% +\newbox\errorbox +% +{\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} +% +\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 `\~=\active \let~=\tie + \catcode `\%=14 + \catcode `\+=\other + \catcode `\"=\other + \catcode `\==\other + \catcode `\|=\other + \catcode `\<=\other + \catcode `\>=\other + \escapechar=`\\ + % + \let\b=\ptexb + \let\bullet=\ptexbullet + \let\c=\ptexc + \let\,=\ptexcomma + \let\.=\ptexdot + \let\dots=\ptexdots + \let\equiv=\ptexequiv + \let\!=\ptexexclam + \let\i=\ptexi + \let\{=\ptexlbrace + \let\+=\tabalign + \let\}=\ptexrbrace + \let\*=\ptexstar + \let\t=\ptext + % + \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% + \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% + \def\@{@}% +\let\Etex=\endgroup} + +% Define @lisp ... @end lisp. +% @lisp does a \begingroup so it can rebind things, +% including the definition of @end lisp (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{{% + % =10000 instead of <10000 because of a special case in \itemzzz, q.v. + \ifnum \lastpenalty=10000 \else + \advance\envskipamount by \parskip + \endgraf + \ifdim\lastskip<\envskipamount + \removelastskip + % it's not a good place to break if the last penalty was \nobreak + % or better ... + \ifnum\lastpenalty>10000 \else \penalty-50 \fi + \vskip\envskipamount + \fi + \fi +}} + +\let\afterenvbreak = \aboveenvbreak + +% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins. +\let\nonarrowing=\relax + +% @cartouche ... @end cartouche: draw rectangle w/rounded corners around +% environment contents. +\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 + +\def\cartouche{% +\par % can't be in the midst of a paragraph. +\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 18.4pt % allow for 3pt kerns on either +% side, and for 6pt waste from +% each corner char, and rule thickness + \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. + \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 +} + +% Define the \E... control sequence only if we are inside the particular +% environment, so the error checking in \end will work. +% +% To end 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} + +% @lisp: indented, narrowed, typewriter font. +\def\lisp{\begingroup + \nonfillstart + \let\Elisp = \nonfillfinish + \tt + \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. + \gobble % eat return +} + +% @example: Same as @lisp. +\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} + +% @smallexample and @smalllisp: use smaller fonts. +% Originally contributed by Pavel@xerox. +\def\smalllisp{\begingroup + \def\Esmalllisp{\nonfillfinish\endgroup}% + \def\Esmallexample{\nonfillfinish\endgroup}% + \smallexamplefonts + \lisp +} +\let\smallexample = \smalllisp + + +% @display: same as @lisp except keep current font. +% +\def\display{\begingroup + \nonfillstart + \let\Edisplay = \nonfillfinish + \gobble +} +% +% @smalldisplay: @display plus smaller fonts. +% +\def\smalldisplay{\begingroup + \def\Esmalldisplay{\nonfillfinish\endgroup}% + \smallexamplefonts \rm + \display +} + +% @format: same as @display except don't narrow margins. +% +\def\format{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eformat = \nonfillfinish + \gobble +} +% +% @smallformat: @format plus smaller fonts. +% +\def\smallformat{\begingroup + \def\Esmallformat{\nonfillfinish\endgroup}% + \smallexamplefonts \rm + \format +} + +% @flushleft (same as @format). +% +\def\flushleft{\begingroup \def\Eflushleft{\nonfillfinish\endgroup}\format} + +% @flushright. +% +\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 + \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 +} + + +% LaTeX-like @verbatim...@end verbatim and @verb{...} +% If we want to allow any as delimiter, +% we need the curly braces so that makeinfo sees the @verb command, eg: +% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org +% +% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. +% +% [Knuth] p.344; only we need to do the other characters Texinfo sets +% active too. Otherwise, they get lost as the first character on a +% verbatim line. +\def\dospecials{% + \do\ \do\\\do\{\do\}\do\$\do\&% + \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% + \do\<\do\>\do\|\do\@\do+\do\"% +} +% +% [Knuth] p. 380 +\def\uncatcodespecials{% + \def\do##1{\catcode`##1=12}\dospecials} +% +% [Knuth] pp. 380,381,391 +% Disable Spanish ligatures ?` and !` of \tt font +\begingroup + \catcode`\`=\active\gdef`{\relax\lq} +\endgroup +% +% Setup for the @verb command. +% +% Eight spaces for a tab +\begingroup + \catcode`\^^I=\active + \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }} +\endgroup +% +\def\setupverb{% + \tt % easiest (and conventionally used) font for verbatim + \def\par{\leavevmode\endgraf}% + \catcode`\`=\active + \tabeightspaces + % Respect line breaks, + % print special symbols as themselves, and + % make each space count + % must do in this order: + \obeylines \uncatcodespecials \sepspaces +} + +% Setup for the @verbatim environment +% +% Real tab expansion +\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount +% +\def\starttabbox{\setbox0=\hbox\bgroup} +\begingroup + \catcode`\^^I=\active + \gdef\tabexpand{% + \catcode`\^^I=\active + \def^^I{\leavevmode\egroup + \dimen0=\wd0 % the width so far, or since the previous tab + \divide\dimen0 by\tabw + \multiply\dimen0 by\tabw % compute previous multiple of \tabw + \advance\dimen0 by\tabw % advance to next multiple of \tabw + \wd0=\dimen0 \box0 \starttabbox + }% + } +\endgroup +\def\setupverbatim{% + % Easiest (and conventionally used) font for verbatim + \tt + \def\par{\leavevmode\egroup\box0\endgraf}% + \catcode`\`=\active + \tabexpand + % Respect line breaks, + % print special symbols as themselves, and + % make each space count + % must do in this order: + \obeylines \uncatcodespecials \sepspaces + \everypar{\starttabbox}% +} + +% Do the @verb magic: verbatim text is quoted by unique +% delimiter characters. Before first delimiter expect a +% right brace, after last delimiter expect closing brace: +% +% \def\doverb'{'#1'}'{#1} +% +% [Knuth] p. 382; only eat outer {} +\begingroup + \catcode`[=1\catcode`]=2\catcode`\{=12\catcode`\}=12 + \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] +\endgroup +% +\def\verb{\begingroup\setupverb\doverb} +% +% +% Do the @verbatim magic: define the macro \doverbatim so that +% the (first) argument ends when '@end verbatim' is reached, ie: +% +% \def\doverbatim#1@end verbatim{#1} +% +% For Texinfo it's a lot easier than for LaTeX, +% because texinfo's \verbatim doesn't stop at '\end{verbatim}': +% we need not redefine '\', '{' and '}'. +% +% Inspired by LaTeX's verbatim command set [latex.ltx] +%% Include LaTeX hack for completeness -- never know +%% \begingroup +%% \catcode`|=0 \catcode`[=1 +%% \catcode`]=2\catcode`\{=12\catcode`\}=12\catcode`\ =\active +%% \catcode`\\=12|gdef|doverbatim#1@end verbatim[ +%% #1|endgroup|def|Everbatim[]|end[verbatim]] +%% |endgroup +% +\begingroup + \catcode`\ =\active + \obeylines % + % ignore everything up to the first ^^M, that's the newline at the end + % of the @verbatim input line itself. Otherwise we get an extra blank + % line in the output. + \gdef\doverbatim#1^^M#2@end verbatim{#2\end{verbatim}}% +\endgroup +% +\def\verbatim{% + \def\Everbatim{\nonfillfinish\endgroup}% + \begingroup + \nonfillstart + \advance\leftskip by -\defbodyindent + \begingroup\setupverbatim\doverbatim +} + +% @verbatiminclude FILE - insert text of file in verbatim environment. +% +% Allow normal characters that we make active in the argument (a file name). +\def\verbatiminclude{% + \begingroup + \catcode`\\=\other + \catcode`~=\other + \catcode`^=\other + \catcode`_=\other + \catcode`|=\other + \catcode`<=\other + \catcode`>=\other + \catcode`+=\other + \parsearg\doverbatiminclude +} +\def\setupverbatiminclude{% + \begingroup + \nonfillstart + \advance\leftskip by -\defbodyindent + \begingroup\setupverbatim +} +% +\def\doverbatiminclude#1{% + % Restore active chars for included file. + \endgroup + \begingroup + \let\value=\expandablevalue + \def\thisfile{#1}% + \expandafter\expandafter\setupverbatiminclude\input\thisfile + \endgroup + \nonfillfinish + \endgroup +} + +% @copying ... @end copying. +% Save the text away for @insertcopying later. Many commands won't be +% allowed in this context, but that's ok. +% +% We save the uninterpreted tokens, rather than creating a box. +% Saving the text in a box would be much easier, but then all the +% typesetting commands (@smallbook, font changes, etc.) have to be done +% beforehand -- and a) we want @copying to be done first in the source +% file; b) letting users define the frontmatter in as flexible order as +% possible is very desirable. +% +\def\copying{\begingroup + % Define a command to swallow text until we reach `@end copying'. + % \ is the escape char in this texinfo.tex file, so it is the + % delimiter for the command; @ will be the escape char when we read + % it, but that doesn't matter. + \long\def\docopying##1\end copying{\gdef\copyingtext{##1}\enddocopying}% + % + % We must preserve ^^M's in the input file; see \insertcopying below. + \catcode`\^^M = \active + \docopying +} + +% What we do to finish off the copying text. +% +\def\enddocopying{\endgroup\ignorespaces} + +% @insertcopying. Here we must play games with ^^M's. On the one hand, +% we need them to delimit commands such as `@end quotation', so they +% must be active. On the other hand, we certainly don't want every +% end-of-line to be a \par, as would happen with the normal active +% definition of ^^M. On the third hand, two ^^M's in a row should still +% generate a \par. +% +% Our approach is to make ^^M insert a space and a penalty1 normally; +% then it can also check if \lastpenalty=1. If it does, then manually +% do \par. +% +% This messes up the normal definitions of @c[omment], so we redefine +% it. Similarly for @ignore. (These commands are used in the gcc +% manual for man page generation.) +% +% Seems pretty fragile, most line-oriented commands will presumably +% fail, but for the limited use of getting the copying text (which +% should be quite simple) inserted, we can hope it's ok. +% +{\catcode`\^^M=\active % +\gdef\insertcopying{\begingroup % + \parindent = 0pt % looks wrong on title page + \def^^M{% + \ifnum \lastpenalty=1 % + \par % + \else % + \space \penalty 1 % + \fi % + }% + % + % Fix @c[omment] for catcode 13 ^^M's. + \def\c##1^^M{\ignorespaces}% + \let\comment = \c % + % + % Don't bother jumping through all the hoops that \doignore does, it + % would be very hard since the catcodes are already set. + \long\def\ignore##1\end ignore{\ignorespaces}% + % + \copyingtext % +\endgroup}% +} + +\message{defuns,} +% @defun etc. + +% 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\deflastargmargin \deflastargmargin=18pt + +\newcount\parencount + +% We want ()&[] to print specially on the defun line. +% +\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`\(}\global\advance\parencount by 1 } +\def\clnr{{\sf\char`\)}\global\advance\parencount by -1 } +\let\ampnr = \& +\def\lbrb{{\bf\char`\[}} +\def\rbrb{{\bf\char`\]}} + +% Active &'s sneak into the index arguments, so make sure it's defined. +{ + \catcode`& = \active + \global\let& = \ampnr +} + +% \defname, which formats the name of the @def (not the args). +% #1 is the function name. +% #2 is the type of definition, such as "Function". +% +\def\defname#1#2{% + % How we'll output the type name. Putting it in brackets helps + % distinguish it from the body text that may end up on the next line + % just below it. + \ifempty{#2}% + \def\defnametype{}% + \else + \def\defnametype{[\rm #2]}% + \fi + % + % Get the values of \leftskip and \rightskip as they were outside the @def... + \dimen2=\leftskip + \advance\dimen2 by -\defbodyindent + % + % Figure out values for the paragraph shape. + \setbox0=\hbox{\hskip \deflastargmargin{\defnametype}}% + \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 + % + % Output arg 2 ("Function" or some such) but stuck inside a box of + % width 0 so it does not interfere with linebreaking. + \noindent + % + {% Adjust \hsize to exclude the ambient margins, + % so that \rightline will obey them. + \advance \hsize by -\dimen2 + \dimen3 = 0pt % was -1.25pc + \rlap{\rightline{\defnametype\kern\dimen3}}% + }% + % + % Allow all lines to be underfull without complaint: + \tolerance=10000 \hbadness=10000 + \advance\leftskip by -\defbodyindent + \exdentamount=\defbodyindent + {\df #1}\enskip % output function name + % \defunargs will be called next to output the arguments, if any. +} + +% Common pieces to start any @def... +% #1 is the \E... control sequence to end the definition (which we define). +% #2 is the \...x control sequence (which our caller defines). +% #3 is the control sequence to process the header, such as \defunheader. +% +\def\parsebodycommon#1#2#3{% + \begingroup\inENV + % If there are two @def commands in a row, we'll have a \nobreak, + % which is there to keep the function description together with its + % header. But if there's nothing but headers, we want to allow a + % break after all. Check for penalty 10002 (inserted by + % \defargscommonending) instead of 10000, since the sectioning + % commands insert a \penalty10000, and we don't want to allow a break + % between a section heading and a defun. + \ifnum\lastpenalty=10002 \penalty0 \fi + \medbreak + % + % Define the \E... end token that this defining construct specifies + % so that it will exit this group. + \def#1{\endgraf\endgroup\medbreak}% + % + \parindent=0in + \advance\leftskip by \defbodyindent + \exdentamount=\defbodyindent +} + +% Common part of the \...x definitions. +% +\def\defxbodycommon{% + % As with \parsebodycommon above, allow line break if we have multiple + % x headers in a row. It's not a great place, though. + \ifnum\lastpenalty=10000 \penalty1000 \fi + % + \begingroup\obeylines +} + +% Process body of @defun, @deffn, @defmac, etc. +% +\def\defparsebody#1#2#3{% + \parsebodycommon{#1}{#2}{#3}% + \def#2{\defxbodycommon \activeparens \spacesplit#3}% + \catcode\equalChar=\active + \begingroup\obeylines\activeparens + \spacesplit#3% +} + +% #1, #2, #3 are the common arguments (see \parsebodycommon above). +% #4, delimited by the space, is the class name. +% +\def\defmethparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 {\defxbodycommon \activeparens \spacesplit{#3{##1}}}% + \begingroup\obeylines\activeparens + % The \empty here prevents misinterpretation of a construct such as + % @deffn {whatever} {Enharmonic comma} + % See comments at \deftpparsebody, although in our case we don't have + % to remove the \empty afterwards, since it is empty. + \spacesplit{#3{#4}}\empty +} + +% Used for @deftypemethod and @deftypeivar. +% #1, #2, #3 are the common arguments (see \defparsebody). +% #4, delimited by a space, is the class name. +% #5 is the method's return type. +% +\def\deftypemethparsebody#1#2#3#4 #5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\defxbodycommon \activeparens \spacesplit{#3{##1}{##2}}}% + \begingroup\obeylines\activeparens + \spacesplit{#3{#4}{#5}}% +} + +% Used for @deftypeop. The change from \deftypemethparsebody is an +% extra argument at the beginning which is the `category', instead of it +% being the hardwired string `Method' or `Instance Variable'. We have +% to account for this both in the \...x definition and in parsing the +% input at hand. Thus also need a control sequence (passed as #5) for +% the \E... definition to assign the category name to. +% +\def\deftypeopparsebody#1#2#3#4#5 #6 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 ##3 {\def#4{##1}% + \defxbodycommon \activeparens \spacesplit{#3{##2}{##3}}}% + \begingroup\obeylines\activeparens + \spacesplit{#3{#5}{#6}}% +} + +% For @defop. +\def\defopparsebody #1#2#3#4#5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\def#4{##1}% + \defxbodycommon \activeparens \spacesplit{#3{##2}}}% + \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{% + \parsebodycommon{#1}{#2}{#3}% + \def#2{\defxbodycommon \spacesplit#3}% + \catcode\equalChar=\active + \begingroup\obeylines + \spacesplit#3% +} + +% @defopvar. +\def\defopvarparsebody #1#2#3#4#5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\def#4{##1}% + \defxbodycommon \spacesplit{#3{##2}}}% + \begingroup\obeylines + \spacesplit{#3{#5}}% +} + +\def\defvrparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 {\defxbodycommon \spacesplit{#3{##1}}}% + \begingroup\obeylines + \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}% + \def#2##1 {\defxbodycommon \spacesplit{#3{##1}}}% + \begingroup\obeylines + \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. +% +\def\removeemptybraces\empty#1\relax{#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{% + #1{\removeemptybraces#2\relax}{#3}% +}% + +% Split up #2 (the rest of the input line) 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\spacesplitx{#1}#2 \relax\spacesplitx}% + \long\gdef\spacesplitx#1#2 #3#4\spacesplitx{% + \ifx\relax #3% + #1{#2}{}% + \else % + #1{#2}{#3#4}% + \fi}% +} + +% Define @defun. + +% This is called to end the arguments processing for all the @def... commands. +% +\def\defargscommonending{% + \interlinepenalty = 10000 + \advance\rightskip by 0pt plus 1fil + \endgraf + \nobreak\vskip -\parskip + \penalty 10002 % signal to \parsebodycommon. +} + +% This expands the args and terminates the paragraph they comprise. +% +\def\defunargs#1{\functionparens \sl +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +% Set the font temporarily and use \font in case \setfont made \tensl a macro. +{\tensl\hyphenchar\font=0}% +#1% +{\tensl\hyphenchar\font=45}% +\ifnum\parencount=0 \else \errmessage{Unbalanced parentheses in @def}\fi% + \defargscommonending +} + +\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 + \defargscommonending +} + +% 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\equalChar=\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}{\putwordDeffunc}% +\defunargs {#2}\endgroup % +\catcode\equalChar=\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}{\putwordDeftypefun}% +\deftypefunargs {#3}\endgroup % +\catcode\equalChar=\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\equalChar=\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}{\putwordDefmac}% +\defunargs {#2}\endgroup % +\catcode\equalChar=\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}{\putwordDefspec}% +\defunargs {#2}\endgroup % +\catcode\equalChar=\other % Turn off change made in \defparsebody +} + +% @defop CATEGORY CLASS OPERATION ARG... +% +\def\defop #1 {\def\defoptype{#1}% +\defopparsebody\Edefop\defopx\defopheader\defoptype} +% +\def\defopheader#1#2#3{% + \dosubind{fn}{\code{#2}}{\putwordon\ \code{#1}}% function index entry + \begingroup + \defname{#2}{\defoptype\ \putwordon\ #1}% + \defunargs{#3}% + \endgroup +} + +% @deftypeop CATEGORY CLASS TYPE OPERATION ARG... +% +\def\deftypeop #1 {\def\deftypeopcategory{#1}% + \deftypeopparsebody\Edeftypeop\deftypeopx\deftypeopheader + \deftypeopcategory} +% +% #1 is the class name, #2 the data type, #3 the operation name, #4 the args. +\def\deftypeopheader#1#2#3#4{% + \dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index + \begingroup + \defname{\defheaderxcond#2\relax$.$#3} + {\deftypeopcategory\ \putwordon\ \code{#1}}% + \deftypefunargs{#4}% + \endgroup +} + +% @deftypemethod CLASS TYPE METHOD ARG... +% +\def\deftypemethod{% + \deftypemethparsebody\Edeftypemethod\deftypemethodx\deftypemethodheader} +% +% #1 is the class name, #2 the data type, #3 the method name, #4 the args. +\def\deftypemethodheader#1#2#3#4{% + \dosubind{fn}{\code{#3}}{\putwordon\ \code{#1}}% entry in function index + \begingroup + \defname{\defheaderxcond#2\relax$.$#3}{\putwordMethodon\ \code{#1}}% + \deftypefunargs{#4}% + \endgroup +} + +% @deftypeivar CLASS TYPE VARNAME +% +\def\deftypeivar{% + \deftypemethparsebody\Edeftypeivar\deftypeivarx\deftypeivarheader} +% +% #1 is the class name, #2 the data type, #3 the variable name. +\def\deftypeivarheader#1#2#3{% + \dosubind{vr}{\code{#3}}{\putwordof\ \code{#1}}% entry in variable index + \begingroup + \defname{\defheaderxcond#2\relax$.$#3} + {\putwordInstanceVariableof\ \code{#1}}% + \defvarargs{#3}% + \endgroup +} + +% @defmethod == @defop Method +% +\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} +% +% #1 is the class name, #2 the method name, #3 the args. +\def\defmethodheader#1#2#3{% + \dosubind{fn}{\code{#2}}{\putwordon\ \code{#1}}% entry in function index + \begingroup + \defname{#2}{\putwordMethodon\ \code{#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}}{\putwordof\ \code{#1}}% variable index entry + \begingroup + \defname{#2}{\defcvtype\ \putwordof\ #1}% + \defvarargs{#3}% + \endgroup +} + +% @defivar CLASS VARNAME == @defcv {Instance Variable} CLASS VARNAME +% +\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} +% +\def\defivarheader#1#2#3{% + \dosubind{vr}{\code{#2}}{\putwordof\ \code{#1}}% entry in var index + \begingroup + \defname{#2}{\putwordInstanceVariableof\ #1}% + \defvarargs{#3}% + \endgroup +} + +% @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% + \defargscommonending +} + +% @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}{\putwordDefvar}% +\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}{\putwordDefopt}% +\defvarargs {#2}\endgroup % +} + +% @deftypevar int foobar + +\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} + +% #1 is the data type. #2 is the name, perhaps followed by text that +% is actually part of the data type, which should not be put into the index. +\def\deftypevarheader #1#2{% +\dovarind#2 \relax% Make entry in variables index +\begingroup\defname {\defheaderxcond#1\relax$.$#2}{\putwordDeftypevar}% + \defargscommonending +\endgroup} +\def\dovarind#1 #2\relax{\doind{vr}{\code{#1}}} + +% @deftypevr {Global Flag} int enable + +\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} + +\def\deftypevrheader #1#2#3{\dovarind#3 \relax% +\begingroup\defname {\defheaderxcond#2\relax$.$#3}{#1} + \defargscommonending +\endgroup} + +% 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} + +% These definitions are used if you use @defunx (etc.) +% anywhere other than immediately after a @defun or @defunx. +% +\def\defcvx#1 {\errmessage{@defcvx in invalid context}} +\def\deffnx#1 {\errmessage{@deffnx in invalid context}} +\def\defivarx#1 {\errmessage{@defivarx in invalid context}} +\def\defmacx#1 {\errmessage{@defmacx in invalid context}} +\def\defmethodx#1 {\errmessage{@defmethodx in invalid context}} +\def\defoptx #1 {\errmessage{@defoptx in invalid context}} +\def\defopx#1 {\errmessage{@defopx in invalid context}} +\def\defspecx#1 {\errmessage{@defspecx in invalid context}} +\def\deftpx#1 {\errmessage{@deftpx in invalid context}} +\def\deftypefnx#1 {\errmessage{@deftypefnx in invalid context}} +\def\deftypefunx#1 {\errmessage{@deftypefunx in invalid context}} +\def\deftypeivarx#1 {\errmessage{@deftypeivarx in invalid context}} +\def\deftypemethodx#1 {\errmessage{@deftypemethodx in invalid context}} +\def\deftypeopx#1 {\errmessage{@deftypeopx in invalid context}} +\def\deftypevarx#1 {\errmessage{@deftypevarx in invalid context}} +\def\deftypevrx#1 {\errmessage{@deftypevrx in invalid context}} +\def\defunx#1 {\errmessage{@defunx in invalid context}} +\def\defvarx#1 {\errmessage{@defvarx in invalid context}} +\def\defvrx#1 {\errmessage{@defvrx in invalid context}} + + +\message{macros,} +% @macro. + +% To do this right we need a feature of e-TeX, \scantokens, +% which we arrange to emulate with a temporary file in ordinary TeX. +\ifx\eTeXversion\undefined + \newwrite\macscribble + \def\scanmacro#1{% + \begingroup \newlinechar`\^^M + % Undo catcode changes of \startcontents and \doprintindex + \catcode`\@=0 \catcode`\\=\other \escapechar=`\@ + % Append \endinput to make sure that TeX does not see the ending newline. + \toks0={#1\endinput}% + \immediate\openout\macscribble=\jobname.tmp + \immediate\write\macscribble{\the\toks0}% + \immediate\closeout\macscribble + \let\xeatspaces\eatspaces + \input \jobname.tmp + \endgroup +} +\else +\def\scanmacro#1{% +\begingroup \newlinechar`\^^M +% Undo catcode changes of \startcontents and \doprintindex +\catcode`\@=0 \catcode`\\=\other \escapechar=`\@ +\let\xeatspaces\eatspaces\scantokens{#1\endinput}\endgroup} +\fi + +\newcount\paramno % Count of parameters +\newtoks\macname % Macro name +\newif\ifrecursive % Is it recursive? +\def\macrolist{} % List of all defined macros in the form + % \do\macro1\do\macro2... + +% Utility routines. +% Thisdoes \let #1 = #2, except with \csnames. +\def\cslet#1#2{% +\expandafter\expandafter +\expandafter\let +\expandafter\expandafter +\csname#1\endcsname +\csname#2\endcsname} + +% Trim leading and trailing spaces off a string. +% Concepts from aro-bend problem 15 (see CTAN). +{\catcode`\@=11 +\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }} +\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@} +\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @} +\def\unbrace#1{#1} +\unbrace{\gdef\trim@@@ #1 } #2@{#1} +} + +% Trim a single trailing ^^M off a string. +{\catcode`\^^M=\other \catcode`\Q=3% +\gdef\eatcr #1{\eatcra #1Q^^MQ}% +\gdef\eatcra#1^^MQ{\eatcrb#1Q}% +\gdef\eatcrb#1Q#2Q{#1}% +} + +% Macro bodies are absorbed as an argument in a context where +% all characters are catcode 10, 11 or 12, except \ which is active +% (as in normal texinfo). It is necessary to change the definition of \. + +% It's necessary to have hard CRs when the macro is executed. This is +% done by making ^^M (\endlinechar) catcode 12 when reading the macro +% body, and then making it the \newlinechar in \scanmacro. + +\def\macrobodyctxt{% + \catcode`\~=\other + \catcode`\^=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\+=\other + \catcode`\{=\other + \catcode`\}=\other + \catcode`\@=\other + \catcode`\^^M=\other + \usembodybackslash} + +\def\macroargctxt{% + \catcode`\~=\other + \catcode`\^=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\+=\other + \catcode`\@=\other + \catcode`\\=\other} + +% \mbodybackslash is the definition of \ in @macro bodies. +% It maps \foo\ => \csname macarg.foo\endcsname => #N +% where N is the macro parameter number. +% We define \csname macarg.\endcsname to be \realbackslash, so +% \\ in macro replacement text gets you a backslash. + +{\catcode`@=0 @catcode`@\=@active + @gdef@usembodybackslash{@let\=@mbodybackslash} + @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} +} +\expandafter\def\csname macarg.\endcsname{\realbackslash} + +\def\macro{\recursivefalse\parsearg\macroxxx} +\def\rmacro{\recursivetrue\parsearg\macroxxx} + +\def\macroxxx#1{% + \getargs{#1}% now \macname is the macname and \argl the arglist + \ifx\argl\empty % no arguments + \paramno=0% + \else + \expandafter\parsemargdef \argl;% + \fi + \if1\csname ismacro.\the\macname\endcsname + \message{Warning: redefining \the\macname}% + \else + \expandafter\ifx\csname \the\macname\endcsname \relax + \else \errmessage{Macro name \the\macname\space already defined}\fi + \global\cslet{macsave.\the\macname}{\the\macname}% + \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% + % Add the macroname to \macrolist + \toks0 = \expandafter{\macrolist\do}% + \xdef\macrolist{\the\toks0 + \expandafter\noexpand\csname\the\macname\endcsname}% + \fi + \begingroup \macrobodyctxt + \ifrecursive \expandafter\parsermacbody + \else \expandafter\parsemacbody + \fi} + +\def\unmacro{\parsearg\dounmacro} +\def\dounmacro#1{% + \if1\csname ismacro.#1\endcsname + \global\cslet{#1}{macsave.#1}% + \global\expandafter\let \csname ismacro.#1\endcsname=0% + % Remove the macro name from \macrolist: + \begingroup + \expandafter\let\csname#1\endcsname \relax + \let\do\unmacrodo + \xdef\macrolist{\macrolist}% + \endgroup + \else + \errmessage{Macro #1 not defined}% + \fi +} + +% Called by \do from \dounmacro on each macro. The idea is to omit any +% macro definitions that have been changed to \relax. +% +\def\unmacrodo#1{% + \ifx#1\relax + % remove this + \else + \noexpand\do \noexpand #1% + \fi +} + +% This makes use of the obscure feature that if the last token of a +% is #, then the preceding argument is delimited by +% an opening brace, and that opening brace is not consumed. +\def\getargs#1{\getargsxxx#1{}} +\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs} +\def\getmacname #1 #2\relax{\macname={#1}} +\def\getmacargs#1{\def\argl{#1}} + +% Parse the optional {params} list. Set up \paramno and \paramlist +% so \defmacro knows what to do. Define \macarg.blah for each blah +% in the params list, to be ##N where N is the position in that list. +% That gets used by \mbodybackslash (above). + +% We need to get `macro parameter char #' into several definitions. +% The technique used is stolen from LaTeX: let \hash be something +% unexpandable, insert that wherever you need a #, and then redefine +% it to # just before using the token list produced. +% +% The same technique is used to protect \eatspaces till just before +% the macro is used. + +\def\parsemargdef#1;{\paramno=0\def\paramlist{}% + \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,} +\def\parsemargdefxxx#1,{% + \if#1;\let\next=\relax + \else \let\next=\parsemargdefxxx + \advance\paramno by 1% + \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname + {\xeatspaces{\hash\the\paramno}}% + \edef\paramlist{\paramlist\hash\the\paramno,}% + \fi\next} + +% These two commands read recursive and nonrecursive macro bodies. +% (They're different since rec and nonrec macros end differently.) + +\long\def\parsemacbody#1@end macro% +{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% +\long\def\parsermacbody#1@end rmacro% +{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% + +% This defines the macro itself. There are six cases: recursive and +% nonrecursive macros of zero, one, and many arguments. +% Much magic with \expandafter here. +% \xdef is used so that macro definitions will survive the file +% they're defined in; @include reads the file inside a group. +\def\defmacro{% + \let\hash=##% convert placeholders to macro parameter chars + \ifrecursive + \ifcase\paramno + % 0 + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\scanmacro{\temp}}% + \or % 1 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\braceorline + \expandafter\noexpand\csname\the\macname xxx\endcsname}% + \expandafter\xdef\csname\the\macname xxx\endcsname##1{% + \egroup\noexpand\scanmacro{\temp}}% + \else % many + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\csname\the\macname xx\endcsname}% + \expandafter\xdef\csname\the\macname xx\endcsname##1{% + \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% + \expandafter\expandafter + \expandafter\xdef + \expandafter\expandafter + \csname\the\macname xxx\endcsname + \paramlist{\egroup\noexpand\scanmacro{\temp}}% + \fi + \else + \ifcase\paramno + % 0 + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \or % 1 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\braceorline + \expandafter\noexpand\csname\the\macname xxx\endcsname}% + \expandafter\xdef\csname\the\macname xxx\endcsname##1{% + \egroup + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \else % many + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \expandafter\noexpand\csname\the\macname xx\endcsname}% + \expandafter\xdef\csname\the\macname xx\endcsname##1{% + \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% + \expandafter\expandafter + \expandafter\xdef + \expandafter\expandafter + \csname\the\macname xxx\endcsname + \paramlist{% + \egroup + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \fi + \fi} + +\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} + +% \braceorline decides whether the next nonwhitespace character is a +% {. If so it reads up to the closing }, if not, it reads the whole +% line. Whatever was read is then fed to the next control sequence +% as an argument (by \parsebrace or \parsearg) +\def\braceorline#1{\let\next=#1\futurelet\nchar\braceorlinexxx} +\def\braceorlinexxx{% + \ifx\nchar\bgroup\else + \expandafter\parsearg + \fi \next} + +% We mant to disable all macros during \shipout so that they are not +% expanded by \write. +\def\turnoffmacros{\begingroup \def\do##1{\let\noexpand##1=\relax}% + \edef\next{\macrolist}\expandafter\endgroup\next} + + +% @alias. +% We need some trickery to remove the optional spaces around the equal +% sign. Just make them active and then expand them all to nothing. +\def\alias{\begingroup\obeyspaces\parsearg\aliasxxx} +\def\aliasxxx #1{\aliasyyy#1\relax} +\def\aliasyyy #1=#2\relax{\ignoreactivespaces +\edef\next{\global\let\expandafter\noexpand\csname#1\endcsname=% + \expandafter\noexpand\csname#2\endcsname}% +\expandafter\endgroup\next} + + +\message{cross references,} +% @xref etc. + +\newwrite\auxfile + +\newif\ifhavexrefs % True if xref values are known. +\newif\ifwarnedxrefs % True if we warned once that they aren't known. + +% @inforef is relatively simple. +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + +% @node's job is to define \lastnode. +\def\node{\ENVcheck\parsearg\nodezzz} +\def\nodezzz#1{\nodexxx [#1,]} +\def\nodexxx[#1,#2]{\gdef\lastnode{#1}} +\let\nwnode=\node +\let\lastnode=\relax + +% The sectioning commands (@chapter, etc.) call these. +\def\donoderef{% + \ifx\lastnode\relax\else + \expandafter\expandafter\expandafter\setref{\lastnode}% + {Ysectionnumberandtype}% + \global\let\lastnode=\relax + \fi +} +\def\unnumbnoderef{% + \ifx\lastnode\relax\else + \expandafter\expandafter\expandafter\setref{\lastnode}{Ynothing}% + \global\let\lastnode=\relax + \fi +} +\def\appendixnoderef{% + \ifx\lastnode\relax\else + \expandafter\expandafter\expandafter\setref{\lastnode}% + {Yappendixletterandtype}% + \global\let\lastnode=\relax + \fi +} + + +% @anchor{NAME} -- define xref target at arbitrary point. +% +\newcount\savesfregister +\gdef\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} +\gdef\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} +\gdef\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} + +% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an +% anchor), namely NAME-title (the corresponding @chapter/etc. name), +% NAME-pg (the page number), and NAME-snt (section number and type). +% Called from \foonoderef. +% +% We have to set \indexdummies so commands such as @code in a section +% title aren't expanded. It would be nicer not to expand the titles in +% the first place, but there's so many layers that that is hard to do. +% +% Likewise, use \turnoffactive so that punctuation chars such as underscore +% and backslash work in node names. +% +\def\setref#1#2{{% + \atdummies + \pdfmkdest{#1}% + % + \turnoffactive + \dosetq{#1-title}{Ytitle}% + \dosetq{#1-pg}{Ypagenumber}% + \dosetq{#1-snt}{#2}% +}} + +% @xref, @pxref, and @ref generate cross-references. 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 + \unsepspaces + \def\printedmanual{\ignorespaces #5}% + \def\printednodename{\ignorespaces #3}% + \setbox1=\hbox{\printedmanual}% + \setbox0=\hbox{\printednodename}% + \ifdim \wd0 = 0pt + % No printed node name was explicitly given. + \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax + % Use the node name inside the square brackets. + \def\printednodename{\ignorespaces #1}% + \else + % 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 + \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. + \ifpdf + \leavevmode + \getfilename{#4}% + {\turnoffactive \otherbackslash + \ifnum\filenamelength>0 + \startlink attr{/Border [0 0 0]}% + goto file{\the\filename.pdf} name{#1}% + \else + \startlink attr{/Border [0 0 0]}% + goto name{#1}% + \fi + }% + \linkcolor + \fi + % + \ifdim \wd1 > 0pt + \putwordsection{} ``\printednodename'' \putwordin{} \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 \otherbackslash + % Only output a following space if the -snt ref is nonempty; for + % @unnumbered and @anchor, it won't be. + \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% + \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi + }% + % [mynode], + [\printednodename],\space + % page 3 + \turnoffactive \otherbackslash \putwordpage\tie\refx{#1-pg}{}% + \fi + \endlink +\endgroup} + +% \dosetq is called from \setref to do the actual \write (\iflinks). +% +\def\dosetq#1#2{% + {\let\folio=0% + \edef\next{\write\auxfile{\internalsetq{#1}{#2}}}% + \iflinks \next \fi + }% +} + +% \internalsetq{foo}{page} expands into +% CHARACTERS @xrdef{foo}{...expansion of \page...} +\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@tie \the\chapno + \else \ifnum\subsecno=0 + \putwordSection@tie \the\chapno.\the\secno + \else \ifnum\subsubsecno=0 + \putwordSection@tie \the\chapno.\the\secno.\the\subsecno + \else + \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno + \fi\fi\fi +} + +\def\Yappendixletterandtype{% + \ifnum\secno=0 + \putwordAppendix@tie @char\the\appendixno{}% + \else \ifnum\subsecno=0 + \putwordSection@tie @char\the\appendixno.\the\secno + \else \ifnum\subsubsecno=0 + \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno + \else + \putwordSection@tie + @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno + \fi\fi\fi +} + +% 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 % Pre-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{% + {% + \indexnofonts + \otherbackslash + \expandafter\global\expandafter\let\expandafter\thisrefX + \csname X#1\endcsname + }% + \ifx\thisrefX\relax + % If not defined, say something at least. + \angleleft un\-de\-fined\angleright + \iflinks + \ifhavexrefs + \message{\linenumber Undefined cross reference `#1'.}% + \else + \ifwarnedxrefs\else + \global\warnedxrefstrue + \message{Cross reference values unknown; you must run TeX again.}% + \fi + \fi + \fi + \else + % It's defined, so just use it. + \thisrefX + \fi + #2% Output the suffix in any case. +} + +% This is the macro invoked by entries in the aux file. +% +\def\xrdef#1{\expandafter\gdef\csname X#1\endcsname} + +% Read the last existing aux file, if any. No error if none exists. +\def\readauxfile{\begingroup + \catcode`\^^@=\other + \catcode`\^^A=\other + \catcode`\^^B=\other + \catcode`\^^C=\other + \catcode`\^^D=\other + \catcode`\^^E=\other + \catcode`\^^F=\other + \catcode`\^^G=\other + \catcode`\^^H=\other + \catcode`\^^K=\other + \catcode`\^^L=\other + \catcode`\^^N=\other + \catcode`\^^P=\other + \catcode`\^^Q=\other + \catcode`\^^R=\other + \catcode`\^^S=\other + \catcode`\^^T=\other + \catcode`\^^U=\other + \catcode`\^^V=\other + \catcode`\^^W=\other + \catcode`\^^X=\other + \catcode`\^^Z=\other + \catcode`\^^[=\other + \catcode`\^^\=\other + \catcode`\^^]=\other + \catcode`\^^^=\other + \catcode`\^^_=\other + % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc. + % in xref tags, i.e., node names. But since ^^e4 notation isn't + % supported in the main text, it doesn't seem desirable. Furthermore, + % that is not enough: for node names that actually contain a ^ + % character, we would end up writing a line like this: 'xrdef {'hat + % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first + % argument, and \hat is not an expandable control sequence. It could + % all be worked out, but why? Either we support ^^ or we don't. + % + % The other change necessary for this was to define \auxhat: + % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter + % and then to call \auxhat in \setq. + % + \catcode`\^=\other + % + % Special characters. Should be turned off anyway, but... + \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 % avoid \+ for paranoia even though we've turned it off + % + % 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 + }% + }% + % + % 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`\\=\other + % + % @ is our escape character in .aux files. + \catcode`\{=1 + \catcode`\}=2 + \catcode`\@=0 + % + \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. (Generally, numeric constants should always be followed by a +% space to prevent strange expansion errors.) +\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 + \dofootnote +}% + +% 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. +% +% Oh yes, they do; otherwise, @ifset and anything else that uses +% \parseargline fail inside footnotes because the tokens are fixed when +% the footnote is read. --karl, 16nov96. +% +% The start of the footnote looks usually like this: +\gdef\startfootins{\insert\footins\bgroup} +% +% ... but this macro is redefined inside @multitable. +% +\gdef\dofootnote{% + \startfootins + % 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. + \hsize=\pagewidth + \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 + % + \smallfonts \rm + % + % Because we use hanging indentation in footnotes, a @noindent appears + % to exdent this text, so make it be a no-op. makeinfo does not use + % hanging indentation so @noindent can still be needed within footnote + % text after an @example or the like (not that this is good style). + \let\noindent = \relax + % + % Hang the footnote text off the number. Use \everypar in case the + % footnote extends for more than one paragraph. + \everypar = {\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 + \futurelet\next\fo@t +} +}%end \catcode `\@=11 + +% @| 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} + +% @image. We use the macros from epsf.tex to support this. +% If epsf.tex is not installed and @image is used, we complain. +% +% Check for and read epsf.tex up front. If we read it only at @image +% time, we might be inside a group, and then its definitions would get +% undone and the next image would fail. +\openin 1 = epsf.tex +\ifeof 1 \else + \closein 1 + % Do not bother showing banner with epsf.tex v2.7k (available in + % doc/epsf.tex and on ctan). + \def\epsfannounce{\toks0 = }% + \input epsf.tex +\fi +% +% We will only complain once about lack of epsf.tex. +\newif\ifwarnednoepsf +\newhelp\noepsfhelp{epsf.tex must be installed for images to + work. It is also included in the Texinfo distribution, or you can get + it from ftp://tug.org/tex/epsf.tex.} +% +\def\image#1{% + \ifx\epsfbox\undefined + \ifwarnednoepsf \else + \errhelp = \noepsfhelp + \errmessage{epsf.tex not found, images will be ignored}% + \global\warnednoepsftrue + \fi + \else + \imagexxx #1,,,,,\finish + \fi +} +% +% Arguments to @image: +% #1 is (mandatory) image filename; we tack on .eps extension. +% #2 is (optional) width, #3 is (optional) height. +% #4 is (ignored optional) html alt text. +% #5 is (ignored optional) extension. +% #6 is just the usual extra ignored arg for parsing this stuff. +\newif\ifimagevmode +\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup + \catcode`\^^M = 5 % in case we're inside an example + \normalturnoffactive % allow _ et al. in names + % If the image is by itself, center it. + \ifvmode + \imagevmodetrue + \nobreak\bigskip + % Usually we'll have text after the image which will insert + % \parskip glue, so insert it here too to equalize the space + % above and below. + \nobreak\vskip\parskip + \nobreak + \line\bgroup\hss + \fi + % + % Output the image. + \ifpdf + \dopdfimage{#1}{#2}{#3}% + \else + % \epsfbox itself resets \epsf?size at each figure. + \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi + \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi + \epsfbox{#1.eps}% + \fi + % + \ifimagevmode \hss \egroup \bigbreak \fi % space after the image +\endgroup} + + +\message{localization,} +% and i18n. + +% @documentlanguage is usually given very early, just after +% @setfilename. If done too late, it may not override everything +% properly. Single argument is the language abbreviation. +% It would be nice if we could set up a hyphenation file here. +% +\def\documentlanguage{\parsearg\dodocumentlanguage} +\def\dodocumentlanguage#1{% + \tex % read txi-??.tex file in plain TeX. + % Read the file if it exists. + \openin 1 txi-#1.tex + \ifeof1 + \errhelp = \nolanghelp + \errmessage{Cannot read language file txi-#1.tex}% + \let\temp = \relax + \else + \def\temp{\input txi-#1.tex }% + \fi + \temp + \endgroup +} +\newhelp\nolanghelp{The given language definition file cannot be found or +is empty. Maybe you need to install it? In the current directory +should work if nowhere else does.} + + +% @documentencoding should change something in TeX eventually, most +% likely, but for now just recognize it. +\let\documentencoding = \comment + + +% Page size parameters. +% +\newdimen\defaultparindent \defaultparindent = 15pt + +\chapheadingskip = 15pt plus 4pt minus 2pt +\secheadingskip = 12pt plus 3pt minus 2pt +\subsecheadingskip = 9pt plus 2pt minus 2pt + +% Prevent underfull vbox error messages. +\vbadness = 10000 + +% Don't be so finicky about underfull hboxes, either. +\hbadness = 2000 + +% 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. We call this whenever the paper size is set. +% +\def\setemergencystretch{% + \ifx\emergencystretch\thisisundefined + % Allow us to assign to \emergencystretch anyway. + \def\emergencystretch{\dimen0}% + \else + \emergencystretch = .15\hsize + \fi +} + +% Parameters in order: 1) textheight; 2) textwidth; 3) voffset; +% 4) hoffset; 5) binding offset; 6) topskip; 7) physical page height; 8) +% physical page width. +% +% We also call \setleading{\textleading}, so the caller should define +% \textleading. The caller should also set \parskip. +% +\def\internalpagesizes#1#2#3#4#5#6#7#8{% + \voffset = #3\relax + \topskip = #6\relax + \splittopskip = \topskip + % + \vsize = #1\relax + \advance\vsize by \topskip + \outervsize = \vsize + \advance\outervsize by 2\topandbottommargin + \pageheight = \vsize + % + \hsize = #2\relax + \outerhsize = \hsize + \advance\outerhsize by 0.5in + \pagewidth = \hsize + % + \normaloffset = #4\relax + \bindingoffset = #5\relax + % + \ifpdf + \pdfpageheight #7\relax + \pdfpagewidth #8\relax + \fi + % + \setleading{\textleading} + % + \parindent = \defaultparindent + \setemergencystretch +} + +% @letterpaper (the default). +\def\letterpaper{{\globaldefs = 1 + \parskip = 3pt plus 2pt minus 1pt + \textleading = 13.2pt + % + % If page is nothing but text, make it come out even. + \internalpagesizes{46\baselineskip}{6in}% + {\voffset}{.25in}% + {\bindingoffset}{36pt}% + {11in}{8.5in}% +}} + +% Use @smallbook to reset parameters for 7x9.5 (or so) format. +\def\smallbook{{\globaldefs = 1 + \parskip = 2pt plus 1pt + \textleading = 12pt + % + \internalpagesizes{7.5in}{5in}% + {\voffset}{.25in}% + {\bindingoffset}{16pt}% + {9.25in}{7in}% + % + \lispnarrowing = 0.3in + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = .5cm +}} + +% Use @afourpaper to print on European A4 paper. +\def\afourpaper{{\globaldefs = 1 + \parskip = 3pt plus 2pt minus 1pt + \textleading = 13.2pt + % + % Double-side printing via postscript on Laserjet 4050 + % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. + % To change the settings for a different printer or situation, adjust + % \normaloffset until the front-side and back-side texts align. Then + % do the same for \bindingoffset. You can set these for testing in + % your texinfo source file like this: + % @tex + % \global\normaloffset = -6mm + % \global\bindingoffset = 10mm + % @end tex + \internalpagesizes{51\baselineskip}{160mm} + {\voffset}{\hoffset}% + {\bindingoffset}{44pt}% + {297mm}{210mm}% + % + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = 5mm +}} + +% Use @afivepaper to print on European A5 paper. +% From romildo@urano.iceb.ufop.br, 2 July 2000. +% He also recommends making @example and @lisp be small. +\def\afivepaper{{\globaldefs = 1 + \parskip = 2pt plus 1pt minus 0.1pt + \textleading = 12.5pt + % + \internalpagesizes{160mm}{120mm}% + {\voffset}{\hoffset}% + {\bindingoffset}{8pt}% + {210mm}{148mm}% + % + \lispnarrowing = 0.2in + \tolerance = 800 + \hfuzz = 1.2pt + \contentsrightmargin = 0pt + \defbodyindent = 2mm + \tableindent = 12mm +}} + +% A specific text layout, 24x15cm overall, intended for A4 paper. +\def\afourlatex{{\globaldefs = 1 + \afourpaper + \internalpagesizes{237mm}{150mm}% + {\voffset}{4.6mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% + % + % Must explicitly reset to 0 because we call \afourpaper. + \globaldefs = 0 +}} + +% Use @afourwide to print on A4 paper in landscape format. +\def\afourwide{{\globaldefs = 1 + \afourpaper + \internalpagesizes{241mm}{165mm}% + {\voffset}{-2.95mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% + \globaldefs = 0 +}} + +% @pagesizes TEXTHEIGHT[,TEXTWIDTH] +% Perhaps we should allow setting the margins, \topskip, \parskip, +% and/or leading, also. Or perhaps we should compute them somehow. +% +\def\pagesizes{\parsearg\pagesizesxxx} +\def\pagesizesxxx#1{\pagesizesyyy #1,,\finish} +\def\pagesizesyyy#1,#2,#3\finish{{% + \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi + \globaldefs = 1 + % + \parskip = 3pt plus 2pt minus 1pt + \setleading{\textleading}% + % + \dimen0 = #1 + \advance\dimen0 by \voffset + % + \dimen2 = \hsize + \advance\dimen2 by \normaloffset + % + \internalpagesizes{#1}{\hsize}% + {\voffset}{\normaloffset}% + {\bindingoffset}{44pt}% + {\dimen0}{\dimen2}% +}} + +% Set default to letter. +% +\letterpaper + + +\message{and turning on texinfo input format.} + +% 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 +\catcode`\$=\other +\def\normaldoublequote{"} +\def\normaltilde{~} +\def\normalcaret{^} +\def\normalunderscore{_} +\def\normalverticalbar{|} +\def\normalless{<} +\def\normalgreater{>} +\def\normalplus{+} +\def\normaldollar{$}%$ font-lock fix + +% 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\font=0pt #1\else #2\fi} + +% Same as above, but check for italic font. Actually this also catches +% non-italic slanted fonts since it is impossible to distinguish them from +% italic fonts. But since this is only used by $ and it uses \sl anyway +% this is not a problem. +\def\ifusingit#1#2{\ifdim \fontdimen1\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\char34}} +\let"=\activedoublequote +\catcode`\~=\active +\def~{{\tt\char126}} +\chardef\hat=`\^ +\catcode`\^=\active +\def^{{\tt \hat}} + +\catcode`\_=\active +\def_{\ifusingtt\normalunderscore\_} +% Subroutine for the previous macro. +\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } + +\catcode`\|=\active +\def|{{\tt\char124}} +\chardef \less=`\< +\catcode`\<=\active +\def<{{\tt \less}} +\chardef \gtr=`\> +\catcode`\>=\active +\def>{{\tt \gtr}} +\catcode`\+=\active +\def+{{\tt \char 43}} +\catcode`\$=\active +\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix + +% 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 outputs one backslash character in current font, +% as in \char`\\. +\global\chardef\rawbackslashxx=`\\ + +% \rawbackslash defines an active \ to do \rawbackslashxx. +% \otherbackslash defines an active \ to be a literal `\' character with +% catcode other. +{\catcode`\\=\active + @gdef@rawbackslash{@let\=@rawbackslashxx} + @gdef@otherbackslash{@let\=@realbackslash} +} + +% \realbackslash is an actual character `\' with catcode other. +{\catcode`\\=\other @gdef@realbackslash{\}} + +% \normalbackslash outputs one backslash in fixed width font. +\def\normalbackslash{{\tt\rawbackslashxx}} + +\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 + @let$=@normaldollar %$ font-lock fix +} + +% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of +% the literal character `\'. (Thus, \ is not expandable when this is in +% effect.) +% +@def@normalturnoffactive{@turnoffactive @let\=@normalbackslash} + +% 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 +} + +% Say @foo, not \foo, in error messages. +@escapechar = `@@ + +% These look ok in all fonts, so just make them not special. +@catcode`@& = @other +@catcode`@# = @other +@catcode`@% = @other + +@c Set initial fonts. +@textfonts +@rm + + +@c Local variables: +@c eval: (add-hook 'write-file-hooks 'time-stamp) +@c page-delimiter: "^\\\\message" +@c time-stamp-start: "def\\\\texinfoversion{" +@c time-stamp-format: "%:y-%02m-%02d.%02H" +@c time-stamp-end: "}" +@c End: diff --git a/doc/version.texi b/doc/version.texi new file mode 100644 index 0000000..f769a19 --- /dev/null +++ b/doc/version.texi @@ -0,0 +1,10 @@ +@ignore +Copyright (C) 1988-2005 Free Software Foundation, Inc. +@end ignore + +@set LASTCHANGE Mon Sep 5 11:47:04 EDT 2005 + +@set EDITION 3.1-beta1 +@set VERSION 3.1-beta1 +@set UPDATED 5 September 2005 +@set UPDATED-MONTH September 2005 -- cgit v1.2.3