builtins/reserved.def

   1 This file is reserved.def, in which the shell reserved words are defined.
   2 It has no direct C file production, but defines builtins for the Bash
   3 builtin help command.
   4
   5 Copyright (C) 1987-2009 Free Software Foundation, Inc.
   6
   7 This file is part of GNU Bash, the Bourne Again SHell.
   8
   9 Bash is free software: you can redistribute it and/or modify
  10 it under the terms of the GNU General Public License as published by
  11 the Free Software Foundation, either version 3 of the License, or
  12 (at your option) any later version.
  13
  14 Bash is distributed in the hope that it will be useful,
  15 but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 GNU General Public License for more details.
  18
  19 You should have received a copy of the GNU General Public License
  20 along with Bash.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 $BUILTIN for
  23 $SHORT_DOC for NAME [in WORDS ... ] ; do COMMANDS; done
  24 Execute commands for each member in a list.
  25
  26 The `for' loop executes a sequence of commands for each member in a
  27 list of items.  If `in WORDS ...;' is not present, then `in "$@"' is
  28 assumed.  For each element in WORDS, NAME is set to that element, and
  29 the COMMANDS are executed.
  30
  31 Exit Status:
  32 Returns the status of the last command executed.
  33 $END
  34
  35 $BUILTIN for ((
  36 $DOCNAME arith_for
  37 $SHORT_DOC for (( exp1; exp2; exp3 )); do COMMANDS; done
  38 Arithmetic for loop.
  39
  40 Equivalent to
  41         (( EXP1 ))
  42         while (( EXP2 )); do
  43                 COMMANDS
  44                 (( EXP3 ))
  45         done
  46 EXP1, EXP2, and EXP3 are arithmetic expressions.  If any expression is
  47 omitted, it behaves as if it evaluates to 1.
  48
  49 Exit Status:
  50 Returns the status of the last command executed.
  51 $END
  52
  53 $BUILTIN select
  54 $SHORT_DOC select NAME [in WORDS ... ;] do COMMANDS; done
  55 Select words from a list and execute commands.
  56
  57 The WORDS are expanded, generating a list of words.  The
  58 set of expanded words is printed on the standard error, each
  59 preceded by a number.  If `in WORDS' is not present, `in "$@"'
  60 is assumed.  The PS3 prompt is then displayed and a line read
  61 from the standard input.  If the line consists of the number
  62 corresponding to one of the displayed words, then NAME is set
  63 to that word.  If the line is empty, WORDS and the prompt are
  64 redisplayed.  If EOF is read, the command completes.  Any other
  65 value read causes NAME to be set to null.  The line read is saved
  66 in the variable REPLY.  COMMANDS are executed after each selection
  67 until a break command is executed.
  68
  69 Exit Status:
  70 Returns the status of the last command executed.
  71 $END
  72
  73 $BUILTIN time
  74 $SHORT_DOC time [-p] pipeline
  75 Report time consumed by pipeline's execution.
  76
  77 Execute PIPELINE and print a summary of the real time, user CPU time,
  78 and system CPU time spent executing PIPELINE when it terminates.
  79
  80 Options:
  81   -p    print the timing summary in the portable Posix format
  82
  83 The value of the TIMEFORMAT variable is used as the output format.
  84
  85 Exit Status:
  86 The return status is the return status of PIPELINE.
  87 $END
  88
  89 $BUILTIN case
  90 $SHORT_DOC case WORD in [PATTERN [| PATTERN]...) COMMANDS ;;]... esac
  91 Execute commands based on pattern matching.
  92
  93 Selectively execute COMMANDS based upon WORD matching PATTERN.  The
  94 `|' is used to separate multiple patterns.
  95
  96 Exit Status:
  97 Returns the status of the last command executed.
  98 $END
  99
 100 $BUILTIN if
 101 $SHORT_DOC if COMMANDS; then COMMANDS; [ elif COMMANDS; then COMMANDS; ]... [ else COMMANDS; ] fi
 102 Execute commands based on conditional.
 103
 104 The `if COMMANDS' list is executed.  If its exit status is zero, then the
 105 `then COMMANDS' list is executed.  Otherwise, each `elif COMMANDS' list is
 106 executed in turn, and if its exit status is zero, the corresponding
 107 `then COMMANDS' list is executed and the if command completes.  Otherwise,
 108 the `else COMMANDS' list is executed, if present.  The exit status of the
 109 entire construct is the exit status of the last command executed, or zero
 110 if no condition tested true.
 111
 112 Exit Status:
 113 Returns the status of the last command executed.
 114 $END
 115
 116 $BUILTIN while
 117 $SHORT_DOC while COMMANDS; do COMMANDS; done
 118 Execute commands as long as a test succeeds.
 119
 120 Expand and execute COMMANDS as long as the final command in the
 121 `while' COMMANDS has an exit status of zero.
 122
 123 Exit Status:
 124 Returns the status of the last command executed.
 125 $END
 126
 127 $BUILTIN until
 128 $SHORT_DOC until COMMANDS; do COMMANDS; done
 129 Execute commands as long as a test does not succeed.
 130
 131 Expand and execute COMMANDS as long as the final command in the
 132 `until' COMMANDS has an exit status which is not zero.
 133
 134 Exit Status:
 135 Returns the status of the last command executed.
 136 $END
 137
 138 $BUILTIN coproc
 139 $SHORT_DOC coproc [NAME] command [redirections]
 140 Create a coprocess named NAME.
 141
 142 Execute COMMAND asynchronously, with the standard output and standard
 143 input of the command connected via a pipe to file descriptors assigned
 144 to indices 0 and 1 of an array variable NAME in the executing shell.
 145 The default NAME is "COPROC".
 146
 147 Exit Status:
 148 Returns the exit status of COMMAND.
 149 $END
 150
 151 $BUILTIN function
 152 $SHORT_DOC function name { COMMANDS ; } or name () { COMMANDS ; }
 153 Define shell function.
 154
 155 Create a shell function named NAME.  When invoked as a simple command,
 156 NAME runs COMMANDs in the calling shell's context.  When NAME is invoked,
 157 the arguments are passed to the function as $1...$n, and the function's
 158 name is in $FUNCNAME.
 159
 160 Exit Status:
 161 Returns success unless NAME is readonly.
 162 $END
 163
 164 $BUILTIN { ... }
 165 $DOCNAME grouping_braces
 166 $SHORT_DOC { COMMANDS ; }
 167 Group commands as a unit.
 168
 169 Run a set of commands in a group.  This is one way to redirect an
 170 entire set of commands.
 171
 172 Exit Status:
 173 Returns the status of the last command executed.
 174 $END
 175
 176 $BUILTIN %
 177 $DOCNAME fg_percent
 178 $SHORT_DOC job_spec [&]
 179 Resume job in foreground.
 180
 181 Equivalent to the JOB_SPEC argument to the `fg' command.  Resume a
 182 stopped or background job.  JOB_SPEC can specify either a job name
 183 or a job number.  Following JOB_SPEC with a `&' places the job in
 184 the background, as if the job specification had been supplied as an
 185 argument to `bg'.
 186
 187 Exit Status:
 188 Returns the status of the resumed job.
 189 $END
 190
 191 $BUILTIN (( ... ))
 192 $DOCNAME arith
 193 $SHORT_DOC (( expression ))
 194 Evaluate arithmetic expression.
 195
 196 The EXPRESSION is evaluated according to the rules for arithmetic
 197 evaluation.  Equivalent to "let EXPRESSION".
 198
 199 Exit Status:
 200 Returns 1 if EXPRESSION evaluates to 0; returns 0 otherwise.
 201 $END
 202
 203 $BUILTIN [[ ... ]]
 204 $DOCNAME conditional
 205 $SHORT_DOC [[ expression ]]
 206 Execute conditional command.
 207
 208 Returns a status of 0 or 1 depending on the evaluation of the conditional
 209 expression EXPRESSION.  Expressions are composed of the same primaries used
 210 by the `test' builtin, and may be combined using the following operators:
 211
 212   ( EXPRESSION )        Returns the value of EXPRESSION
 213   ! EXPRESSION          True if EXPRESSION is false; else false
 214   EXPR1 && EXPR2        True if both EXPR1 and EXPR2 are true; else false
 215   EXPR1 || EXPR2        True if either EXPR1 or EXPR2 is true; else false
 216
 217 When the `==' and `!=' operators are used, the string to the right of
 218 the operator is used as a pattern and pattern matching is performed.
 219 When the `=~' operator is used, the string to the right of the operator
 220 is matched as a regular expression.
 221
 222 The && and || operators do not evaluate EXPR2 if EXPR1 is sufficient to
 223 determine the expression's value.
 224
 225 Exit Status:
 226 0 or 1 depending on value of EXPRESSION.
 227 $END
 228
 229 $BUILTIN variables
 230 $DOCNAME variable_help
 231 $SHORT_DOC variables - Names and meanings of some shell variables
 232 Common shell variable names and usage.
 233
 234 BASH_VERSION    Version information for this Bash.
 235 CDPATH  A colon-separated list of directories to search
 236                 for directories given as arguments to `cd'.
 237 GLOBIGNORE      A colon-separated list of patterns describing filenames to
 238                 be ignored by pathname expansion.
 239 #if defined (HISTORY)
 240 HISTFILE        The name of the file where your command history is stored.
 241 HISTFILESIZE    The maximum number of lines this file can contain.
 242 HISTSIZE        The maximum number of history lines that a running
 243                 shell can access.
 244 #endif /* HISTORY */
 245 HOME    The complete pathname to your login directory.
 246 HOSTNAME        The name of the current host.
 247 HOSTTYPE        The type of CPU this version of Bash is running under.
 248 IGNOREEOF       Controls the action of the shell on receipt of an EOF
 249                 character as the sole input.  If set, then the value
 250                 of it is the number of EOF characters that can be seen
 251                 in a row on an empty line before the shell will exit
 252                 (default 10).  When unset, EOF signifies the end of input.
 253 MACHTYPE        A string describing the current system Bash is running on.
 254 MAILCHECK       How often, in seconds, Bash checks for new mail.
 255 MAILPATH        A colon-separated list of filenames which Bash checks
 256                 for new mail.
 257 OSTYPE  The version of Unix this version of Bash is running on.
 258 PATH    A colon-separated list of directories to search when
 259                 looking for commands.
 260 PROMPT_COMMAND  A command to be executed before the printing of each
 261                 primary prompt.
 262 PS1             The primary prompt string.
 263 PS2             The secondary prompt string.
 264 PWD             The full pathname of the current directory.
 265 SHELLOPTS       A colon-separated list of enabled shell options.
 266 TERM    The name of the current terminal type.
 267 TIMEFORMAT      The output format for timing statistics displayed by the
 268                 `time' reserved word.
 269 auto_resume     Non-null means a command word appearing on a line by
 270                 itself is first looked for in the list of currently
 271                 stopped jobs.  If found there, that job is foregrounded.
 272                 A value of `exact' means that the command word must
 273                 exactly match a command in the list of stopped jobs.  A
 274                 value of `substring' means that the command word must
 275                 match a substring of the job.  Any other value means that
 276                 the command must be a prefix of a stopped job.
 277 #if defined (HISTORY)
 278 #  if defined (BANG_HISTORY)
 279 histchars       Characters controlling history expansion and quick
 280                 substitution.  The first character is the history
 281                 substitution character, usually `!'.  The second is
 282                 the `quick substitution' character, usually `^'.  The
 283                 third is the `history comment' character, usually `#'.
 284 #  endif /* BANG_HISTORY */
 285 HISTIGNORE      A colon-separated list of patterns used to decide which
 286                 commands should be saved on the history list.
 287 #endif /* HISTORY */
 288 $END