bash.1

android-w.song.android.widget

.\"
.\" MAN PAGE COMMENTS to
.\"
.\"	Chet Ramey
.\"	Case Western Reserve University
.\"	[e-mail]
.\"
.\"	Last Change: Tue Dec 28 13:41:43 EST 2010
.\"
.\" bash_builtins, strip all but Built-Ins section
.if \n(zZ=1 .ig zZ
.if \n(zY=1 .ig zY
.TH BASH 1 "2010 December 28" "GNU Bash-4.2"
.\"
.\" 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-2011 by the Free Software Foundation, Inc.
.if t Bash is Copyright \(co 1989-2011 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
Shell and Utilities portion of the IEEE POSIX specification
(IEEE Standard 1003.1).
.B Bash
can be configured to be POSIX-conformant by default.
.SH OPTIONS
All of the  single-character shell options documented in the
description of the \fBset\fR builtin command can be used as options
when the shell is invoked.
In addition, \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).
.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 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 with its standard input
connected to a network connection, as when executed by the remote shell
daemon, usually \fIrshd\fP, or the secure shell daemon \fIsshd\fP.
If
.B bash
determines it is being run in this fashion, 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
.BR SHELLOPTS ,
.SM
.BR BASHOPTS ,
.SM
.BR CDPATH ,
and
.SM
.B GLOBIGNORE
variables, if they appear in the environment, are 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