| 1 | .\"- |
| 2 | .\" Copyright (c) 1991, 1993 |
| 3 | .\" The Regents of the University of California. All rights reserved. |
| 4 | .\" |
| 5 | .\" This code is derived from software contributed to Berkeley by |
| 6 | .\" Kenneth Almquist. |
| 7 | .\" |
| 8 | .\" Redistribution and use in source and binary forms, with or without |
| 9 | .\" modification, are permitted provided that the following conditions |
| 10 | .\" are met: |
| 11 | .\" 1. Redistributions of source code must retain the above copyright |
| 12 | .\" notice, this list of conditions and the following disclaimer. |
| 13 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 14 | .\" notice, this list of conditions and the following disclaimer in the |
| 15 | .\" documentation and/or other materials provided with the distribution. |
| 16 | .\" 3. All advertising materials mentioning features or use of this software |
| 17 | .\" must display the following acknowledgement: |
| 18 | .\" This product includes software developed by the University of |
| 19 | .\" California, Berkeley and its contributors. |
| 20 | .\" 4. Neither the name of the University nor the names of its contributors |
| 21 | .\" may be used to endorse or promote products derived from this software |
| 22 | .\" without specific prior written permission. |
| 23 | .\" |
| 24 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| 25 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 26 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 27 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| 28 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 29 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 30 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 31 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 32 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 33 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 34 | .\" SUCH DAMAGE. |
| 35 | .\" |
| 36 | .\" from: @(#)sh.1 8.6 (Berkeley) 5/4/95 |
| 37 | .\" $FreeBSD: src/bin/sh/sh.1,v 1.161 2011/05/05 20:55:55 jilles Exp $ |
| 38 | .\" |
| 39 | .Dd July 2, 2011 |
| 40 | .Dt SH 1 |
| 41 | .Os |
| 42 | .Sh NAME |
| 43 | .Nm sh |
| 44 | .Nd command interpreter (shell) |
| 45 | .Sh SYNOPSIS |
| 46 | .Nm |
| 47 | .Op Fl /+abCEefIimnPpTuVvx |
| 48 | .Op Fl /+o Ar longname |
| 49 | .Oo |
| 50 | .Ar script |
| 51 | .Op Ar arg ... |
| 52 | .Oc |
| 53 | .Nm |
| 54 | .Op Fl /+abCEefIimnPpTuVvx |
| 55 | .Op Fl /+o Ar longname |
| 56 | .Fl c Ar string |
| 57 | .Oo |
| 58 | .Ar name |
| 59 | .Op Ar arg ... |
| 60 | .Oc |
| 61 | .Nm |
| 62 | .Op Fl /+abCEefIimnPpTuVvx |
| 63 | .Op Fl /+o Ar longname |
| 64 | .Fl s |
| 65 | .Op Ar arg ... |
| 66 | .Sh DESCRIPTION |
| 67 | The |
| 68 | .Nm |
| 69 | utility is the standard command interpreter for the system. |
| 70 | The current version of |
| 71 | .Nm |
| 72 | is close to the |
| 73 | .St -p1003.1 |
| 74 | specification for the shell. |
| 75 | It only supports features |
| 76 | designated by |
| 77 | .Tn POSIX , |
| 78 | plus a few Berkeley extensions. |
| 79 | This man page is not intended to be a tutorial nor a complete |
| 80 | specification of the shell. |
| 81 | .Ss Overview |
| 82 | The shell is a command that reads lines from |
| 83 | either a file or the terminal, interprets them, and |
| 84 | generally executes other commands. |
| 85 | It is the program that is started when a user logs into the system, |
| 86 | although a user can select a different shell with the |
| 87 | .Xr chsh 1 |
| 88 | command. |
| 89 | The shell |
| 90 | implements a language that has flow control constructs, |
| 91 | a macro facility that provides a variety of features in |
| 92 | addition to data storage, along with built-in history and line |
| 93 | editing capabilities. |
| 94 | It incorporates many features to |
| 95 | aid interactive use and has the advantage that the interpretative |
| 96 | language is common to both interactive and non-interactive |
| 97 | use (shell scripts). |
| 98 | That is, commands can be typed directly |
| 99 | to the running shell or can be put into a file, |
| 100 | which can be executed directly by the shell. |
| 101 | .Ss Invocation |
| 102 | .\" |
| 103 | .\" XXX This next sentence is incredibly confusing. |
| 104 | .\" |
| 105 | If no arguments are present and if the standard input of the shell |
| 106 | is connected to a terminal |
| 107 | (or if the |
| 108 | .Fl i |
| 109 | option is set), |
| 110 | the shell is considered an interactive shell. |
| 111 | An interactive shell |
| 112 | generally prompts before each command and handles programming |
| 113 | and command errors differently (as described below). |
| 114 | When first starting, the shell inspects argument 0, and |
| 115 | if it begins with a dash |
| 116 | .Pq Ql - , |
| 117 | the shell is also considered a login shell. |
| 118 | This is normally done automatically by the system |
| 119 | when the user first logs in. |
| 120 | A login shell first reads commands |
| 121 | from the files |
| 122 | .Pa /etc/profile |
| 123 | and then |
| 124 | .Pa .profile |
| 125 | in a user's home directory, |
| 126 | if they exist. |
| 127 | If the environment variable |
| 128 | .Ev ENV |
| 129 | is set on entry to a shell, or is set in the |
| 130 | .Pa .profile |
| 131 | of a login shell, the shell then reads commands from the file named in |
| 132 | .Ev ENV . |
| 133 | Therefore, a user should place commands that are to be executed only |
| 134 | at login time in the |
| 135 | .Pa .profile |
| 136 | file, and commands that are executed for every shell inside the |
| 137 | .Ev ENV |
| 138 | file. |
| 139 | The user can set the |
| 140 | .Ev ENV |
| 141 | variable to some file by placing the following line in the file |
| 142 | .Pa .profile |
| 143 | in the home directory, |
| 144 | substituting for |
| 145 | .Pa .shinit |
| 146 | the filename desired: |
| 147 | .Pp |
| 148 | .Dl "ENV=$HOME/.shinit; export ENV" |
| 149 | .Pp |
| 150 | The first non-option argument specified on the command line |
| 151 | will be treated as the |
| 152 | name of a file from which to read commands (a shell script), and |
| 153 | the remaining arguments are set as the positional parameters |
| 154 | of the shell |
| 155 | .Li ( $1 , $2 , |
| 156 | etc.). |
| 157 | Otherwise, the shell reads commands |
| 158 | from its standard input. |
| 159 | .Pp |
| 160 | Unlike older versions of |
| 161 | .Nm |
| 162 | the |
| 163 | .Ev ENV |
| 164 | script is only sourced on invocation of interactive shells. |
| 165 | This |
| 166 | closes a well-known, and sometimes easily exploitable security |
| 167 | hole related to poorly thought out |
| 168 | .Ev ENV |
| 169 | scripts. |
| 170 | .Ss Argument List Processing |
| 171 | All of the single letter options to |
| 172 | .Nm |
| 173 | have a corresponding long name, |
| 174 | with the exception of |
| 175 | .Fl c |
| 176 | and |
| 177 | .Fl /+o . |
| 178 | These long names are provided next to the single letter options |
| 179 | in the descriptions below. |
| 180 | The long name for an option may be specified as an argument to the |
| 181 | .Fl /+o |
| 182 | option of |
| 183 | .Nm . |
| 184 | Once the shell is running, |
| 185 | the long name for an option may be specified as an argument to the |
| 186 | .Fl /+o |
| 187 | option of the |
| 188 | .Ic set |
| 189 | built-in command |
| 190 | (described later in the section called |
| 191 | .Sx Built-in Commands ) . |
| 192 | Introducing an option with a dash |
| 193 | .Pq Ql - |
| 194 | enables the option, |
| 195 | while using a plus |
| 196 | .Pq Ql + |
| 197 | disables the option. |
| 198 | A |
| 199 | .Dq Li -- |
| 200 | or plain |
| 201 | .Ql - |
| 202 | will stop option processing and will force the remaining |
| 203 | words on the command line to be treated as arguments. |
| 204 | The |
| 205 | .Fl /+o |
| 206 | and |
| 207 | .Fl c |
| 208 | options do not have long names. |
| 209 | They take arguments and are described after the single letter options. |
| 210 | .Bl -tag -width indent |
| 211 | .It Fl a Li allexport |
| 212 | Flag variables for export when assignments are made to them. |
| 213 | .It Fl b Li notify |
| 214 | Enable asynchronous notification of background job |
| 215 | completion. |
| 216 | (UNIMPLEMENTED) |
| 217 | .It Fl C Li noclobber |
| 218 | Do not overwrite existing files with |
| 219 | .Ql > . |
| 220 | .It Fl E Li emacs |
| 221 | Enable the built-in |
| 222 | .Xr emacs 1 |
| 223 | command line editor (disables the |
| 224 | .Fl V |
| 225 | option if it has been set; |
| 226 | set automatically when interactive on terminals). |
| 227 | .It Fl e Li errexit |
| 228 | Exit immediately if any untested command fails in non-interactive mode. |
| 229 | The exit status of a command is considered to be |
| 230 | explicitly tested if the command is part of the list used to control |
| 231 | an |
| 232 | .Ic if , elif , while , |
| 233 | or |
| 234 | .Ic until ; |
| 235 | if the command is the left |
| 236 | hand operand of an |
| 237 | .Dq Li && |
| 238 | or |
| 239 | .Dq Li || |
| 240 | operator; or if the command is a pipeline preceded by the |
| 241 | .Ic !\& |
| 242 | operator. |
| 243 | If a shell function is executed and its exit status is explicitly |
| 244 | tested, all commands of the function are considered to be tested as |
| 245 | well. |
| 246 | .It Fl f Li noglob |
| 247 | Disable pathname expansion. |
| 248 | .It Fl I Li ignoreeof |
| 249 | Ignore |
| 250 | .Dv EOF Ap s |
| 251 | from input when in interactive mode. |
| 252 | .It Fl i Li interactive |
| 253 | Force the shell to behave interactively. |
| 254 | .It Fl m Li monitor |
| 255 | Turn on job control (set automatically when interactive). |
| 256 | .It Fl n Li noexec |
| 257 | If not interactive, read commands but do not |
| 258 | execute them. |
| 259 | This is useful for checking the |
| 260 | syntax of shell scripts. |
| 261 | .It Fl P Li physical |
| 262 | Change the default for the |
| 263 | .Ic cd |
| 264 | and |
| 265 | .Ic pwd |
| 266 | commands from |
| 267 | .Fl L |
| 268 | (logical directory layout) |
| 269 | to |
| 270 | .Fl P |
| 271 | (physical directory layout). |
| 272 | .It Fl p Li privileged |
| 273 | Turn on privileged mode. |
| 274 | This mode is enabled on startup |
| 275 | if either the effective user or group ID is not equal to the |
| 276 | real user or group ID. |
| 277 | Turning this mode off sets the |
| 278 | effective user and group IDs to the real user and group IDs. |
| 279 | When this mode is enabled for interactive shells, the file |
| 280 | .Pa /etc/suid_profile |
| 281 | is sourced instead of |
| 282 | .Pa ~/.profile |
| 283 | after |
| 284 | .Pa /etc/profile |
| 285 | is sourced, and the contents of the |
| 286 | .Ev ENV |
| 287 | variable are ignored. |
| 288 | .It Fl s Li stdin |
| 289 | Read commands from standard input (set automatically |
| 290 | if no file arguments are present). |
| 291 | This option has |
| 292 | no effect when set after the shell has already started |
| 293 | running (i.e., when set with the |
| 294 | .Ic set |
| 295 | command). |
| 296 | .It Fl T Li trapsasync |
| 297 | When waiting for a child, execute traps immediately. |
| 298 | If this option is not set, |
| 299 | traps are executed after the child exits, |
| 300 | as specified in |
| 301 | .St -p1003.2 . |
| 302 | This nonstandard option is useful for putting guarding shells around |
| 303 | children that block signals. |
| 304 | The surrounding shell may kill the child |
| 305 | or it may just return control to the tty and leave the child alone, |
| 306 | like this: |
| 307 | .Bd -literal -offset indent |
| 308 | sh -T -c "trap 'exit 1' 2 ; some-blocking-program" |
| 309 | .Ed |
| 310 | .It Fl u Li nounset |
| 311 | Write a message to standard error when attempting |
| 312 | to expand a variable, a positional parameter or |
| 313 | the special parameter |
| 314 | .Va \&! |
| 315 | that is not set, and if the |
| 316 | shell is not interactive, exit immediately. |
| 317 | .It Fl V Li vi |
| 318 | Enable the built-in |
| 319 | .Xr vi 1 |
| 320 | command line editor (disables |
| 321 | .Fl E |
| 322 | if it has been set). |
| 323 | .It Fl v Li verbose |
| 324 | The shell writes its input to standard error |
| 325 | as it is read. |
| 326 | Useful for debugging. |
| 327 | .It Fl x Li xtrace |
| 328 | Write each command |
| 329 | (preceded by the value of the |
| 330 | .Va PS4 |
| 331 | variable) |
| 332 | to standard error before it is executed. |
| 333 | Useful for debugging. |
| 334 | .It "\ \ " Em tabcomplete |
| 335 | Enables filename completion in the command line editor. |
| 336 | Typing a tab character will extend the current input word to match a |
| 337 | filename. |
| 338 | If more than one filename matches it is only extended to be the common prefix. |
| 339 | Typing a second tab character will list all the matching names. |
| 340 | Turned on by default in an interactive shell. |
| 341 | .El |
| 342 | .Pp |
| 343 | The |
| 344 | .Fl c |
| 345 | option causes the commands to be read from the |
| 346 | .Ar string |
| 347 | operand instead of from the standard input. |
| 348 | Keep in mind that this option only accepts a single string as its |
| 349 | argument, hence multi-word strings must be quoted. |
| 350 | .Pp |
| 351 | The |
| 352 | .Fl /+o |
| 353 | option takes as its only argument the long name of an option |
| 354 | to be enabled or disabled. |
| 355 | For example, the following two invocations of |
| 356 | .Nm |
| 357 | both enable the built-in |
| 358 | .Xr emacs 1 |
| 359 | command line editor: |
| 360 | .Bd -literal -offset indent |
| 361 | set -E |
| 362 | set -o emacs |
| 363 | .Ed |
| 364 | .Pp |
| 365 | If used without an argument, the |
| 366 | .Fl o |
| 367 | option displays the current option settings in a human-readable format. |
| 368 | If |
| 369 | .Cm +o |
| 370 | is used without an argument, the current option settings are output |
| 371 | in a format suitable for re-input into the shell. |
| 372 | .Ss Lexical Structure |
| 373 | The shell reads input in terms of lines from a file and breaks |
| 374 | it up into words at whitespace (blanks and tabs), and at |
| 375 | certain sequences of |
| 376 | characters called |
| 377 | .Dq operators , |
| 378 | which are special to the shell. |
| 379 | There are two types of operators: control operators and |
| 380 | redirection operators (their meaning is discussed later). |
| 381 | The following is a list of valid operators: |
| 382 | .Bl -tag -width indent |
| 383 | .It Control operators: |
| 384 | .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact |
| 385 | .It Li & Ta Li && Ta Li ( Ta Li ) Ta Li \en |
| 386 | .It Li ;; Ta Li ; Ta Li | Ta Li || |
| 387 | .El |
| 388 | .It Redirection operators: |
| 389 | .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact |
| 390 | .It Li < Ta Li > Ta Li << Ta Li >> Ta Li <> |
| 391 | .It Li <& Ta Li >& Ta Li <<- Ta Li >| |
| 392 | .El |
| 393 | .El |
| 394 | .Pp |
| 395 | The character |
| 396 | .Ql # |
| 397 | introduces a comment if used at the beginning of a word. |
| 398 | The word starting with |
| 399 | .Ql # |
| 400 | and the rest of the line are ignored. |
| 401 | .Pp |
| 402 | .Tn ASCII |
| 403 | .Dv NUL |
| 404 | characters (character code 0) are not allowed in shell input. |
| 405 | .Ss Quoting |
| 406 | Quoting is used to remove the special meaning of certain characters |
| 407 | or words to the shell, such as operators, whitespace, keywords, |
| 408 | or alias names. |
| 409 | .Pp |
| 410 | There are four types of quoting: matched single quotes, |
| 411 | dollar-single quotes, |
| 412 | matched double quotes, and backslash. |
| 413 | .Bl -tag -width indent |
| 414 | .It Single Quotes |
| 415 | Enclosing characters in single quotes preserves the literal |
| 416 | meaning of all the characters (except single quotes, making |
| 417 | it impossible to put single-quotes in a single-quoted string). |
| 418 | .It Dollar-Single Quotes |
| 419 | Enclosing characters between |
| 420 | .Li $' |
| 421 | and |
| 422 | .Li ' |
| 423 | preserves the literal meaning of all characters |
| 424 | except backslashes and single quotes. |
| 425 | A backslash introduces a C-style escape sequence: |
| 426 | .Bl -tag -width xUnnnnnnnn |
| 427 | .It \ea |
| 428 | Alert (ring the terminal bell) |
| 429 | .It \eb |
| 430 | Backspace |
| 431 | .It \ec Ns Ar c |
| 432 | The control character denoted by |
| 433 | .Li ^ Ns Ar c |
| 434 | in |
| 435 | .Xr stty 1 . |
| 436 | If |
| 437 | .Ar c |
| 438 | is a backslash, it must be doubled. |
| 439 | .It \ee |
| 440 | The ESC character |
| 441 | .Tn ( ASCII |
| 442 | 0x1b) |
| 443 | .It \ef |
| 444 | Formfeed |
| 445 | .It \en |
| 446 | Newline |
| 447 | .It \er |
| 448 | Carriage return |
| 449 | .It \et |
| 450 | Horizontal tab |
| 451 | .It \ev |
| 452 | Vertical tab |
| 453 | .It \e\e |
| 454 | Literal backslash |
| 455 | .It \e\&' |
| 456 | Literal single-quote |
| 457 | .It \e\&" |
| 458 | Literal double-quote |
| 459 | .It \e Ns Ar nnn |
| 460 | The byte whose octal value is |
| 461 | .Ar nnn |
| 462 | (one to three digits) |
| 463 | .It \ex Ns Ar nn |
| 464 | The byte whose hexadecimal value is |
| 465 | .Ar nn |
| 466 | (one or more digits only the last two of which are used) |
| 467 | .It \eu Ns Ar nnnn |
| 468 | The Unicode code point |
| 469 | .Ar nnnn |
| 470 | (four hexadecimal digits) |
| 471 | .It \eU Ns Ar nnnnnnnn |
| 472 | The Unicode code point |
| 473 | .Ar nnnnnnnn |
| 474 | (eight hexadecimal digits) |
| 475 | .El |
| 476 | .Pp |
| 477 | The sequences for Unicode code points currently only provide useful results |
| 478 | for values below 128. |
| 479 | They reject code point 0 and UTF-16 surrogates. |
| 480 | .Pp |
| 481 | If an escape sequence would produce a byte with value 0, |
| 482 | that byte and the rest of the string until the matching single-quote |
| 483 | are ignored. |
| 484 | .Pp |
| 485 | Any other string starting with a backslash is an error. |
| 486 | .It Double Quotes |
| 487 | Enclosing characters within double quotes preserves the literal |
| 488 | meaning of all characters except dollar sign |
| 489 | .Pq Ql $ , |
| 490 | backquote |
| 491 | .Pq Ql ` , |
| 492 | and backslash |
| 493 | .Pq Ql \e . |
| 494 | The backslash inside double quotes is historically weird. |
| 495 | It remains literal unless it precedes the following characters, |
| 496 | which it serves to quote: |
| 497 | .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact |
| 498 | .It Li $ Ta Li ` Ta Li \&" Ta Li \e\ Ta Li \en |
| 499 | .El |
| 500 | .It Backslash |
| 501 | A backslash preserves the literal meaning of the following |
| 502 | character, with the exception of the newline character |
| 503 | .Pq Ql \en . |
| 504 | A backslash preceding a newline is treated as a line continuation. |
| 505 | .El |
| 506 | .Ss Keywords |
| 507 | Keywords or reserved words are words that have special meaning to the |
| 508 | shell and are recognized at the beginning of a line and |
| 509 | after a control operator. |
| 510 | The following are keywords: |
| 511 | .Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center |
| 512 | .It Li \&! Ta { Ta } Ta Ic case Ta Ic do |
| 513 | .It Ic done Ta Ic elif Ta Ic else Ta Ic esac Ta Ic fi |
| 514 | .It Ic for Ta Ic if Ta Ic then Ta Ic until Ta Ic while |
| 515 | .El |
| 516 | .Ss Aliases |
| 517 | An alias is a name and corresponding value set using the |
| 518 | .Ic alias |
| 519 | built-in command. |
| 520 | Whenever a keyword may occur (see above), |
| 521 | and after checking for keywords, the shell |
| 522 | checks the word to see if it matches an alias. |
| 523 | If it does, it replaces it in the input stream with its value. |
| 524 | For example, if there is an alias called |
| 525 | .Dq Li lf |
| 526 | with the value |
| 527 | .Dq Li "ls -F" , |
| 528 | then the input |
| 529 | .Pp |
| 530 | .Dl "lf foobar" |
| 531 | .Pp |
| 532 | would become |
| 533 | .Pp |
| 534 | .Dl "ls -F foobar" |
| 535 | .Pp |
| 536 | Aliases provide a convenient way for naive users to |
| 537 | create shorthands for commands without having to learn how |
| 538 | to create functions with arguments. |
| 539 | Using aliases in scripts is discouraged |
| 540 | because the command that defines them must be executed |
| 541 | before the code that uses them is parsed. |
| 542 | This is fragile and not portable. |
| 543 | .Pp |
| 544 | An alias name may be escaped in a command line, so that it is not |
| 545 | replaced by its alias value, by using quoting characters within or |
| 546 | adjacent to the alias name. |
| 547 | This is most often done by prefixing |
| 548 | an alias name with a backslash to execute a function, built-in, or |
| 549 | normal program with the same name. |
| 550 | See the |
| 551 | .Sx Quoting |
| 552 | subsection. |
| 553 | .Ss Commands |
| 554 | The shell interprets the words it reads according to a |
| 555 | language, the specification of which is outside the scope |
| 556 | of this man page (refer to the BNF in the |
| 557 | .St -p1003.2 |
| 558 | document). |
| 559 | Essentially though, a line is read and if |
| 560 | the first word of the line (or after a control operator) |
| 561 | is not a keyword, then the shell has recognized a |
| 562 | simple command. |
| 563 | Otherwise, a complex command or some |
| 564 | other special construct may have been recognized. |
| 565 | .Ss Simple Commands |
| 566 | If a simple command has been recognized, the shell performs |
| 567 | the following actions: |
| 568 | .Bl -enum |
| 569 | .It |
| 570 | Leading words of the form |
| 571 | .Dq Li name=value |
| 572 | are stripped off and assigned to the environment of |
| 573 | the simple command. |
| 574 | Redirection operators and |
| 575 | their arguments (as described below) are stripped |
| 576 | off and saved for processing. |
| 577 | .It |
| 578 | The remaining words are expanded as described in |
| 579 | the section called |
| 580 | .Sx Word Expansions , |
| 581 | and the first remaining word is considered the command |
| 582 | name and the command is located. |
| 583 | The remaining |
| 584 | words are considered the arguments of the command. |
| 585 | If no command name resulted, then the |
| 586 | .Dq Li name=value |
| 587 | variable assignments recognized in 1) affect the |
| 588 | current shell. |
| 589 | .It |
| 590 | Redirections are performed as described in |
| 591 | the next section. |
| 592 | .El |
| 593 | .Ss Redirections |
| 594 | Redirections are used to change where a command reads its input |
| 595 | or sends its output. |
| 596 | In general, redirections open, close, or |
| 597 | duplicate an existing reference to a file. |
| 598 | The overall format |
| 599 | used for redirection is: |
| 600 | .Pp |
| 601 | .D1 Oo Ar n Oc Ar redir-op file |
| 602 | .Pp |
| 603 | The |
| 604 | .Ar redir-op |
| 605 | is one of the redirection operators mentioned |
| 606 | previously. |
| 607 | The following gives some examples of how these |
| 608 | operators can be used. |
| 609 | Note that stdin and stdout are commonly used abbreviations |
| 610 | for standard input and standard output respectively. |
| 611 | .Bl -tag -width "1234567890XX" -offset indent |
| 612 | .It Oo Ar n Oc Ns Li > Ar file |
| 613 | redirect stdout (or file descriptor |
| 614 | .Ar n ) |
| 615 | to |
| 616 | .Ar file |
| 617 | .It Oo Ar n Oc Ns Li >| Ar file |
| 618 | same as above, but override the |
| 619 | .Fl C |
| 620 | option |
| 621 | .It Oo Ar n Oc Ns Li >> Ar file |
| 622 | append stdout (or file descriptor |
| 623 | .Ar n ) |
| 624 | to |
| 625 | .Ar file |
| 626 | .It Oo Ar n Oc Ns Li < Ar file |
| 627 | redirect stdin (or file descriptor |
| 628 | .Ar n ) |
| 629 | from |
| 630 | .Ar file |
| 631 | .It Oo Ar n Oc Ns Li <> Ar file |
| 632 | redirect stdin (or file descriptor |
| 633 | .Ar n ) |
| 634 | to and from |
| 635 | .Ar file |
| 636 | .It Oo Ar n1 Oc Ns Li <& Ns Ar n2 |
| 637 | duplicate stdin (or file descriptor |
| 638 | .Ar n1 ) |
| 639 | from file descriptor |
| 640 | .Ar n2 |
| 641 | .It Oo Ar n Oc Ns Li <&- |
| 642 | close stdin (or file descriptor |
| 643 | .Ar n ) |
| 644 | .It Oo Ar n1 Oc Ns Li >& Ns Ar n2 |
| 645 | duplicate stdout (or file descriptor |
| 646 | .Ar n1 ) |
| 647 | to file descriptor |
| 648 | .Ar n2 |
| 649 | .It Oo Ar n Oc Ns Li >&- |
| 650 | close stdout (or file descriptor |
| 651 | .Ar n ) |
| 652 | .El |
| 653 | .Pp |
| 654 | The following redirection is often called a |
| 655 | .Dq here-document . |
| 656 | .Bd -unfilled -offset indent |
| 657 | .Oo Ar n Oc Ns Li << Ar delimiter |
| 658 | .D1 Ar here-doc-text |
| 659 | .D1 ... |
| 660 | .Ar delimiter |
| 661 | .Ed |
| 662 | .Pp |
| 663 | All the text on successive lines up to the delimiter is |
| 664 | saved away and made available to the command on standard |
| 665 | input, or file descriptor |
| 666 | .Ar n |
| 667 | if it is specified. |
| 668 | If the |
| 669 | .Ar delimiter |
| 670 | as specified on the initial line is quoted, then the |
| 671 | .Ar here-doc-text |
| 672 | is treated literally, otherwise the text is subjected to |
| 673 | parameter expansion, command substitution, and arithmetic |
| 674 | expansion (as described in the section on |
| 675 | .Sx Word Expansions ) . |
| 676 | If the operator is |
| 677 | .Dq Li <<- |
| 678 | instead of |
| 679 | .Dq Li << , |
| 680 | then leading tabs |
| 681 | in the |
| 682 | .Ar here-doc-text |
| 683 | are stripped. |
| 684 | .Ss Search and Execution |
| 685 | There are three types of commands: shell functions, |
| 686 | built-in commands, and normal programs. |
| 687 | The command is searched for (by name) in that order. |
| 688 | The three types of commands are all executed in a different way. |
| 689 | .Pp |
| 690 | When a shell function is executed, all of the shell positional |
| 691 | parameters (except |
| 692 | .Li $0 , |
| 693 | which remains unchanged) are |
| 694 | set to the arguments of the shell function. |
| 695 | The variables which are explicitly placed in the environment of |
| 696 | the command (by placing assignments to them before the |
| 697 | function name) are made local to the function and are set |
| 698 | to the values given. |
| 699 | Then the command given in the function definition is executed. |
| 700 | The positional parameters are restored to their original values |
| 701 | when the command completes. |
| 702 | This all occurs within the current shell. |
| 703 | .Pp |
| 704 | Shell built-in commands are executed internally to the shell, without |
| 705 | spawning a new process. |
| 706 | There are two kinds of built-in commands: regular and special. |
| 707 | Assignments before special builtins persist after they finish |
| 708 | executing and assignment errors, redirection errors and certain |
| 709 | operand errors cause a script to be aborted. |
| 710 | Special builtins cannot be overridden with a function. |
| 711 | Both regular and special builtins can affect the shell in ways |
| 712 | normal programs cannot. |
| 713 | .Pp |
| 714 | Otherwise, if the command name does not match a function |
| 715 | or built-in command, the command is searched for as a normal |
| 716 | program in the file system (as described in the next section). |
| 717 | When a normal program is executed, the shell runs the program, |
| 718 | passing the arguments and the environment to the program. |
| 719 | If the program is not a normal executable file |
| 720 | (i.e., if it does not begin with the |
| 721 | .Dq "magic number" |
| 722 | whose |
| 723 | .Tn ASCII |
| 724 | representation is |
| 725 | .Dq Li #! , |
| 726 | resulting in an |
| 727 | .Er ENOEXEC |
| 728 | return value from |
| 729 | .Xr execve 2 ) |
| 730 | but appears to be a text file, |
| 731 | the shell will run a new instance of |
| 732 | .Nm |
| 733 | to interpret it. |
| 734 | .Pp |
| 735 | Note that previous versions of this document |
| 736 | and the source code itself misleadingly and sporadically |
| 737 | refer to a shell script without a magic number |
| 738 | as a |
| 739 | .Dq "shell procedure" . |
| 740 | .Ss Path Search |
| 741 | When locating a command, the shell first looks to see if |
| 742 | it has a shell function by that name. |
| 743 | Then it looks for a |
| 744 | built-in command by that name. |
| 745 | If a built-in command is not found, |
| 746 | one of two things happen: |
| 747 | .Bl -enum |
| 748 | .It |
| 749 | Command names containing a slash are simply executed without |
| 750 | performing any searches. |
| 751 | .It |
| 752 | The shell searches each entry in the |
| 753 | .Va PATH |
| 754 | variable |
| 755 | in turn for the command. |
| 756 | The value of the |
| 757 | .Va PATH |
| 758 | variable should be a series of |
| 759 | entries separated by colons. |
| 760 | Each entry consists of a |
| 761 | directory name. |
| 762 | The current directory |
| 763 | may be indicated implicitly by an empty directory name, |
| 764 | or explicitly by a single period. |
| 765 | .El |
| 766 | .Ss Command Exit Status |
| 767 | Each command has an exit status that can influence the behavior |
| 768 | of other shell commands. |
| 769 | The paradigm is that a command exits |
| 770 | with zero for normal or success, and non-zero for failure, |
| 771 | error, or a false indication. |
| 772 | The man page for each command |
| 773 | should indicate the various exit codes and what they mean. |
| 774 | Additionally, the built-in commands return exit codes, as does |
| 775 | an executed shell function. |
| 776 | .Pp |
| 777 | If a command is terminated by a signal, its exit status is 128 plus |
| 778 | the signal number. |
| 779 | Signal numbers are defined in the header file |
| 780 | .In sys/signal.h . |
| 781 | .Ss Complex Commands |
| 782 | Complex commands are combinations of simple commands |
| 783 | with control operators or keywords, together creating a larger complex |
| 784 | command. |
| 785 | More generally, a command is one of the following: |
| 786 | .Bl -item -offset indent |
| 787 | .It |
| 788 | simple command |
| 789 | .It |
| 790 | pipeline |
| 791 | .It |
| 792 | list or compound-list |
| 793 | .It |
| 794 | compound command |
| 795 | .It |
| 796 | function definition |
| 797 | .El |
| 798 | .Pp |
| 799 | Unless otherwise stated, the exit status of a command is |
| 800 | that of the last simple command executed by the command. |
| 801 | .Ss Pipelines |
| 802 | A pipeline is a sequence of one or more commands separated |
| 803 | by the control operator |
| 804 | .Ql \&| . |
| 805 | The standard output of all but |
| 806 | the last command is connected to the standard input |
| 807 | of the next command. |
| 808 | The standard output of the last |
| 809 | command is inherited from the shell, as usual. |
| 810 | .Pp |
| 811 | The format for a pipeline is: |
| 812 | .Pp |
| 813 | .D1 Oo Li \&! Oc Ar command1 Op Li \&| Ar command2 ... |
| 814 | .Pp |
| 815 | The standard output of |
| 816 | .Ar command1 |
| 817 | is connected to the standard input of |
| 818 | .Ar command2 . |
| 819 | The standard input, standard output, or |
| 820 | both of a command is considered to be assigned by the |
| 821 | pipeline before any redirection specified by redirection |
| 822 | operators that are part of the command. |
| 823 | .Pp |
| 824 | Note that unlike some other shells, |
| 825 | .Nm |
| 826 | executes each process in a pipeline with more than one command |
| 827 | in a subshell environment and as a child of the |
| 828 | .Nm |
| 829 | process. |
| 830 | .Pp |
| 831 | If the pipeline is not in the background (discussed later), |
| 832 | the shell waits for all commands to complete. |
| 833 | .Pp |
| 834 | If the keyword |
| 835 | .Ic !\& |
| 836 | does not precede the pipeline, the |
| 837 | exit status is the exit status of the last command specified |
| 838 | in the pipeline. |
| 839 | Otherwise, the exit status is the logical |
| 840 | NOT of the exit status of the last command. |
| 841 | That is, if |
| 842 | the last command returns zero, the exit status is 1; if |
| 843 | the last command returns greater than zero, the exit status |
| 844 | is zero. |
| 845 | .Pp |
| 846 | Because pipeline assignment of standard input or standard |
| 847 | output or both takes place before redirection, it can be |
| 848 | modified by redirection. |
| 849 | For example: |
| 850 | .Pp |
| 851 | .Dl "command1 2>&1 | command2" |
| 852 | .Pp |
| 853 | sends both the standard output and standard error of |
| 854 | .Ar command1 |
| 855 | to the standard input of |
| 856 | .Ar command2 . |
| 857 | .Pp |
| 858 | A |
| 859 | .Ql \&; |
| 860 | or newline terminator causes the preceding |
| 861 | AND-OR-list |
| 862 | (described below in the section called |
| 863 | .Sx Short-Circuit List Operators ) |
| 864 | to be executed sequentially; |
| 865 | an |
| 866 | .Ql & |
| 867 | causes asynchronous execution of the preceding AND-OR-list. |
| 868 | .Ss Background Commands (&) |
| 869 | If a command is terminated by the control operator ampersand |
| 870 | .Pq Ql & , |
| 871 | the shell executes the command asynchronously; |
| 872 | the shell does not wait for the command to finish |
| 873 | before executing the next command. |
| 874 | .Pp |
| 875 | The format for running a command in background is: |
| 876 | .Pp |
| 877 | .D1 Ar command1 Li & Op Ar command2 Li & Ar ... |
| 878 | .Pp |
| 879 | If the shell is not interactive, the standard input of an |
| 880 | asynchronous command is set to |
| 881 | .Pa /dev/null . |
| 882 | .Ss Lists (Generally Speaking) |
| 883 | A list is a sequence of zero or more commands separated by |
| 884 | newlines, semicolons, or ampersands, |
| 885 | and optionally terminated by one of these three characters. |
| 886 | The commands in a |
| 887 | list are executed in the order they are written. |
| 888 | If command is followed by an ampersand, the shell starts the |
| 889 | command and immediately proceeds onto the next command; |
| 890 | otherwise it waits for the command to terminate before |
| 891 | proceeding to the next one. |
| 892 | .Ss Short-Circuit List Operators |
| 893 | .Dq Li && |
| 894 | and |
| 895 | .Dq Li || |
| 896 | are AND-OR list operators. |
| 897 | .Dq Li && |
| 898 | executes the first command, and then executes the second command |
| 899 | if the exit status of the first command is zero. |
| 900 | .Dq Li || |
| 901 | is similar, but executes the second command if the exit |
| 902 | status of the first command is nonzero. |
| 903 | .Dq Li && |
| 904 | and |
| 905 | .Dq Li || |
| 906 | both have the same priority. |
| 907 | .Ss Flow-Control Constructs (if, while, for, case) |
| 908 | The syntax of the |
| 909 | .Ic if |
| 910 | command is: |
| 911 | .Bd -unfilled -offset indent -compact |
| 912 | .Ic if Ar list |
| 913 | .Ic then Ar list |
| 914 | .Oo Ic elif Ar list |
| 915 | .Ic then Ar list Oc Ar ... |
| 916 | .Op Ic else Ar list |
| 917 | .Ic fi |
| 918 | .Ed |
| 919 | .Pp |
| 920 | The syntax of the |
| 921 | .Ic while |
| 922 | command is: |
| 923 | .Bd -unfilled -offset indent -compact |
| 924 | .Ic while Ar list |
| 925 | .Ic do Ar list |
| 926 | .Ic done |
| 927 | .Ed |
| 928 | .Pp |
| 929 | The two lists are executed repeatedly while the exit status of the |
| 930 | first list is zero. |
| 931 | The |
| 932 | .Ic until |
| 933 | command is similar, but has the word |
| 934 | .Ic until |
| 935 | in place of |
| 936 | .Ic while , |
| 937 | which causes it to |
| 938 | repeat until the exit status of the first list is zero. |
| 939 | .Pp |
| 940 | The syntax of the |
| 941 | .Ic for |
| 942 | command is: |
| 943 | .Bd -unfilled -offset indent -compact |
| 944 | .Ic for Ar variable Op Ic in Ar word ... |
| 945 | .Ic do Ar list |
| 946 | .Ic done |
| 947 | .Ed |
| 948 | .Pp |
| 949 | If |
| 950 | .Ic in |
| 951 | and the following words are omitted, |
| 952 | .Ic in Li \&"$@\&" |
| 953 | is used instead. |
| 954 | The words are expanded, and then the list is executed |
| 955 | repeatedly with the variable set to each word in turn. |
| 956 | The |
| 957 | .Ic do |
| 958 | and |
| 959 | .Ic done |
| 960 | commands may be replaced with |
| 961 | .Ql { |
| 962 | and |
| 963 | .Ql } . |
| 964 | .Pp |
| 965 | The syntax of the |
| 966 | .Ic break |
| 967 | and |
| 968 | .Ic continue |
| 969 | commands is: |
| 970 | .D1 Ic break Op Ar num |
| 971 | .D1 Ic continue Op Ar num |
| 972 | .Pp |
| 973 | The |
| 974 | .Ic break |
| 975 | command terminates the |
| 976 | .Ar num |
| 977 | innermost |
| 978 | .Ic for |
| 979 | or |
| 980 | .Ic while |
| 981 | loops. |
| 982 | The |
| 983 | .Ic continue |
| 984 | command continues with the next iteration of the innermost loop. |
| 985 | These are implemented as special built-in commands. |
| 986 | .Pp |
| 987 | The syntax of the |
| 988 | .Ic case |
| 989 | command is: |
| 990 | .Bd -unfilled -offset indent -compact |
| 991 | .Ic case Ar word Ic in |
| 992 | .Ar pattern Ns Li ) Ar list Li ;; |
| 993 | .Ar ... |
| 994 | .Ic esac |
| 995 | .Ed |
| 996 | .Pp |
| 997 | The pattern can actually be one or more patterns |
| 998 | (see |
| 999 | .Sx Shell Patterns |
| 1000 | described later), |
| 1001 | separated by |
| 1002 | .Ql \&| |
| 1003 | characters. |
| 1004 | The exit code of the |
| 1005 | .Ic case |
| 1006 | command is the exit code of the last command executed in the list or |
| 1007 | zero if no patterns were matched. |
| 1008 | .Ss Grouping Commands Together |
| 1009 | Commands may be grouped by writing either |
| 1010 | .Pp |
| 1011 | .D1 Li \&( Ns Ar list Ns Li \%) |
| 1012 | .Pp |
| 1013 | or |
| 1014 | .Pp |
| 1015 | .D1 Li { Ar list Ns Li \&; } |
| 1016 | .Pp |
| 1017 | The first form executes the commands in a subshell environment. |
| 1018 | Note that built-in commands thus executed do not affect the current shell. |
| 1019 | The second form never forks another shell, |
| 1020 | so it is slightly more efficient. |
| 1021 | Grouping commands together this way allows the user to |
| 1022 | redirect their output as though they were one program: |
| 1023 | .Bd -literal -offset indent |
| 1024 | { echo -n "hello"; echo " world"; } > greeting |
| 1025 | .Ed |
| 1026 | .Ss Functions |
| 1027 | The syntax of a function definition is |
| 1028 | .Pp |
| 1029 | .D1 Ar name Li \&( \&) Ar command |
| 1030 | .Pp |
| 1031 | A function definition is an executable statement; when |
| 1032 | executed it installs a function named |
| 1033 | .Ar name |
| 1034 | and returns an |
| 1035 | exit status of zero. |
| 1036 | The |
| 1037 | .Ar command |
| 1038 | is normally a list |
| 1039 | enclosed between |
| 1040 | .Ql { |
| 1041 | and |
| 1042 | .Ql } . |
| 1043 | .Pp |
| 1044 | Variables may be declared to be local to a function by |
| 1045 | using the |
| 1046 | .Ic local |
| 1047 | command. |
| 1048 | This should appear as the first statement of a function, |
| 1049 | and the syntax is: |
| 1050 | .Pp |
| 1051 | .D1 Ic local Oo Ar variable ... Oc Op Fl |
| 1052 | .Pp |
| 1053 | The |
| 1054 | .Ic local |
| 1055 | command is implemented as a built-in command. |
| 1056 | .Pp |
| 1057 | When a variable is made local, it inherits the initial |
| 1058 | value and exported and readonly flags from the variable |
| 1059 | with the same name in the surrounding scope, if there is |
| 1060 | one. |
| 1061 | Otherwise, the variable is initially unset. |
| 1062 | The shell |
| 1063 | uses dynamic scoping, so that if the variable |
| 1064 | .Va x |
| 1065 | is made local to function |
| 1066 | .Em f , |
| 1067 | which then calls function |
| 1068 | .Em g , |
| 1069 | references to the variable |
| 1070 | .Va x |
| 1071 | made inside |
| 1072 | .Em g |
| 1073 | will refer to the variable |
| 1074 | .Va x |
| 1075 | declared inside |
| 1076 | .Em f , |
| 1077 | not to the global variable named |
| 1078 | .Va x . |
| 1079 | .Pp |
| 1080 | The only special parameter that can be made local is |
| 1081 | .Ql - . |
| 1082 | Making |
| 1083 | .Ql - |
| 1084 | local causes any shell options that are |
| 1085 | changed via the |
| 1086 | .Ic set |
| 1087 | command inside the function to be |
| 1088 | restored to their original values when the function |
| 1089 | returns. |
| 1090 | .Pp |
| 1091 | The syntax of the |
| 1092 | .Ic return |
| 1093 | command is |
| 1094 | .Pp |
| 1095 | .D1 Ic return Op Ar exitstatus |
| 1096 | .Pp |
| 1097 | It terminates the current executional scope, returning from the previous |
| 1098 | nested function, sourced script, or shell instance, in that order. |
| 1099 | The |
| 1100 | .Ic return |
| 1101 | command is implemented as a special built-in command. |
| 1102 | .Ss Variables and Parameters |
| 1103 | The shell maintains a set of parameters. |
| 1104 | A parameter |
| 1105 | denoted by a name is called a variable. |
| 1106 | When starting up, |
| 1107 | the shell turns all the environment variables into shell |
| 1108 | variables. |
| 1109 | New variables can be set using the form |
| 1110 | .Pp |
| 1111 | .D1 Ar name Ns = Ns Ar value |
| 1112 | .Pp |
| 1113 | Variables set by the user must have a name consisting solely |
| 1114 | of alphabetics, numerics, and underscores. |
| 1115 | The first letter of a variable name must not be numeric. |
| 1116 | A parameter can also be denoted by a number |
| 1117 | or a special character as explained below. |
| 1118 | .Ss Positional Parameters |
| 1119 | A positional parameter is a parameter denoted by a number greater than zero. |
| 1120 | The shell sets these initially to the values of its command line |
| 1121 | arguments that follow the name of the shell script. |
| 1122 | The |
| 1123 | .Ic set |
| 1124 | built-in command can also be used to set or reset them. |
| 1125 | .Ss Special Parameters |
| 1126 | Special parameters are parameters denoted by a single special character |
| 1127 | or the digit zero. |
| 1128 | They are shown in the following list, exactly as they would appear in input |
| 1129 | typed by the user or in the source of a shell script. |
| 1130 | .Bl -hang |
| 1131 | .It Li $* |
| 1132 | Expands to the positional parameters, starting from one. |
| 1133 | When |
| 1134 | the expansion occurs within a double-quoted string |
| 1135 | it expands to a single field with the value of each parameter |
| 1136 | separated by the first character of the |
| 1137 | .Va IFS |
| 1138 | variable, |
| 1139 | or by a space if |
| 1140 | .Va IFS |
| 1141 | is unset. |
| 1142 | .It Li $@ |
| 1143 | Expands to the positional parameters, starting from one. |
| 1144 | When |
| 1145 | the expansion occurs within double-quotes, each positional |
| 1146 | parameter expands as a separate argument. |
| 1147 | If there are no positional parameters, the |
| 1148 | expansion of |
| 1149 | .Li @ |
| 1150 | generates zero arguments, even when |
| 1151 | .Li @ |
| 1152 | is double-quoted. |
| 1153 | What this basically means, for example, is |
| 1154 | if |
| 1155 | .Li $1 |
| 1156 | is |
| 1157 | .Dq Li abc |
| 1158 | and |
| 1159 | .Li $2 |
| 1160 | is |
| 1161 | .Dq Li "def ghi" , |
| 1162 | then |
| 1163 | .Li \&"$@\&" |
| 1164 | expands to |
| 1165 | the two arguments: |
| 1166 | .Bd -literal -offset indent |
| 1167 | "abc" "def ghi" |
| 1168 | .Ed |
| 1169 | .It Li $# |
| 1170 | Expands to the number of positional parameters. |
| 1171 | .It Li $? |
| 1172 | Expands to the exit status of the most recent pipeline. |
| 1173 | .It Li $- |
| 1174 | (hyphen) Expands to the current option flags (the single-letter |
| 1175 | option names concatenated into a string) as specified on |
| 1176 | invocation, by the |
| 1177 | .Ic set |
| 1178 | built-in command, or implicitly |
| 1179 | by the shell. |
| 1180 | .It Li $$ |
| 1181 | Expands to the process ID of the invoked shell. |
| 1182 | A subshell |
| 1183 | retains the same value of |
| 1184 | .Va $ |
| 1185 | as its parent. |
| 1186 | .It Li $! |
| 1187 | Expands to the process ID of the most recent background |
| 1188 | command executed from the current shell. |
| 1189 | For a |
| 1190 | pipeline, the process ID is that of the last command in the |
| 1191 | pipeline. |
| 1192 | If this parameter is referenced, the shell will remember |
| 1193 | the process ID and its exit status until the |
| 1194 | .Ic wait |
| 1195 | built-in command reports completion of the process. |
| 1196 | .It Li $0 |
| 1197 | (zero) Expands to the name of the shell script if passed on the command line, |
| 1198 | the |
| 1199 | .Ar name |
| 1200 | operand if given (with |
| 1201 | .Fl c ) |
| 1202 | or otherwise argument 0 passed to the shell. |
| 1203 | .El |
| 1204 | .Ss Special Variables |
| 1205 | The following variables are set by the shell or |
| 1206 | have special meaning to it: |
| 1207 | .Bl -tag -width ".Va HISTSIZE" |
| 1208 | .It Va CDPATH |
| 1209 | The search path used with the |
| 1210 | .Ic cd |
| 1211 | built-in. |
| 1212 | .It Va EDITOR |
| 1213 | The fallback editor used with the |
| 1214 | .Ic fc |
| 1215 | built-in. |
| 1216 | If not set, the default editor is |
| 1217 | .Xr ed 1 . |
| 1218 | .It Va FCEDIT |
| 1219 | The default editor used with the |
| 1220 | .Ic fc |
| 1221 | built-in. |
| 1222 | .It Va HISTSIZE |
| 1223 | The number of previous commands that are accessible. |
| 1224 | .It Va HOME |
| 1225 | The user's home directory, |
| 1226 | used in tilde expansion and as a default directory for the |
| 1227 | .Ic cd |
| 1228 | built-in. |
| 1229 | .It Va IFS |
| 1230 | Input Field Separators. |
| 1231 | This is normally set to |
| 1232 | .Aq space , |
| 1233 | .Aq tab , |
| 1234 | and |
| 1235 | .Aq newline . |
| 1236 | See the |
| 1237 | .Sx White Space Splitting |
| 1238 | section for more details. |
| 1239 | .It Va LINENO |
| 1240 | The current line number in the script or function. |
| 1241 | .It Va MAIL |
| 1242 | The name of a mail file, that will be checked for the arrival of new |
| 1243 | mail. |
| 1244 | Overridden by |
| 1245 | .Va MAILPATH . |
| 1246 | .It Va MAILPATH |
| 1247 | A colon |
| 1248 | .Pq Ql \&: |
| 1249 | separated list of file names, for the shell to check for incoming |
| 1250 | mail. |
| 1251 | This variable overrides the |
| 1252 | .Va MAIL |
| 1253 | setting. |
| 1254 | There is a maximum of 10 mailboxes that can be monitored at once. |
| 1255 | .It Va PATH |
| 1256 | The default search path for executables. |
| 1257 | See the |
| 1258 | .Sx Path Search |
| 1259 | section for details. |
| 1260 | .It Va PPID |
| 1261 | The parent process ID of the invoked shell. |
| 1262 | This is set at startup |
| 1263 | unless this variable is in the environment. |
| 1264 | A later change of parent process ID is not reflected. |
| 1265 | A subshell retains the same value of |
| 1266 | .Va PPID . |
| 1267 | .It Va PS1 |
| 1268 | The primary prompt string, which defaults to |
| 1269 | .Dq Li "$ " , |
| 1270 | unless you are the superuser, in which case it defaults to |
| 1271 | .Dq Li "# " . |
| 1272 | .It Va PS2 |
| 1273 | The secondary prompt string, which defaults to |
| 1274 | .Dq Li "> " . |
| 1275 | .It Va PS4 |
| 1276 | The prefix for the trace output (if |
| 1277 | .Fl x |
| 1278 | is active). |
| 1279 | The default is |
| 1280 | .Dq Li "+ " . |
| 1281 | .El |
| 1282 | .Ss Word Expansions |
| 1283 | This clause describes the various expansions that are |
| 1284 | performed on words. |
| 1285 | Not all expansions are performed on |
| 1286 | every word, as explained later. |
| 1287 | .Pp |
| 1288 | Tilde expansions, parameter expansions, command substitutions, |
| 1289 | arithmetic expansions, and quote removals that occur within |
| 1290 | a single word expand to a single field. |
| 1291 | It is only field |
| 1292 | splitting or pathname expansion that can create multiple |
| 1293 | fields from a single word. |
| 1294 | The single exception to this rule is |
| 1295 | the expansion of the special parameter |
| 1296 | .Va @ |
| 1297 | within double-quotes, |
| 1298 | as was described above. |
| 1299 | .Pp |
| 1300 | The order of word expansion is: |
| 1301 | .Bl -enum |
| 1302 | .It |
| 1303 | Tilde Expansion, Parameter Expansion, Command Substitution, |
| 1304 | Arithmetic Expansion (these all occur at the same time). |
| 1305 | .It |
| 1306 | Field Splitting is performed on fields generated by step (1) |
| 1307 | unless the |
| 1308 | .Va IFS |
| 1309 | variable is null. |
| 1310 | .It |
| 1311 | Pathname Expansion (unless the |
| 1312 | .Fl f |
| 1313 | option is in effect). |
| 1314 | .It |
| 1315 | Quote Removal. |
| 1316 | .El |
| 1317 | .Pp |
| 1318 | The |
| 1319 | .Ql $ |
| 1320 | character is used to introduce parameter expansion, command |
| 1321 | substitution, or arithmetic expansion. |
| 1322 | .Ss Tilde Expansion (substituting a user's home directory) |
| 1323 | A word beginning with an unquoted tilde character |
| 1324 | .Pq Ql ~ |
| 1325 | is |
| 1326 | subjected to tilde expansion. |
| 1327 | All the characters up to a slash |
| 1328 | .Pq Ql / |
| 1329 | or the end of the word are treated as a username |
| 1330 | and are replaced with the user's home directory. |
| 1331 | If the |
| 1332 | username is missing (as in |
| 1333 | .Pa ~/foobar ) , |
| 1334 | the tilde is replaced with the value of the |
| 1335 | .Va HOME |
| 1336 | variable (the current user's home directory). |
| 1337 | .Ss Parameter Expansion |
| 1338 | The format for parameter expansion is as follows: |
| 1339 | .Pp |
| 1340 | .D1 Li ${ Ns Ar expression Ns Li } |
| 1341 | .Pp |
| 1342 | where |
| 1343 | .Ar expression |
| 1344 | consists of all characters until the matching |
| 1345 | .Ql } . |
| 1346 | Any |
| 1347 | .Ql } |
| 1348 | escaped by a backslash or within a single-quoted or double-quoted |
| 1349 | string, and characters in |
| 1350 | embedded arithmetic expansions, command substitutions, and variable |
| 1351 | expansions, are not examined in determining the matching |
| 1352 | .Ql } . |
| 1353 | If the variants with |
| 1354 | .Ql + , |
| 1355 | .Ql - , |
| 1356 | .Ql = |
| 1357 | or |
| 1358 | .Ql ?\& |
| 1359 | occur within a double-quoted string, |
| 1360 | as an extension there may be unquoted parts |
| 1361 | (via double-quotes inside the expansion); |
| 1362 | .Ql } |
| 1363 | within such parts are also not examined in determining the matching |
| 1364 | .Ql } . |
| 1365 | .Pp |
| 1366 | The simplest form for parameter expansion is: |
| 1367 | .Pp |
| 1368 | .D1 Li ${ Ns Ar parameter Ns Li } |
| 1369 | .Pp |
| 1370 | The value, if any, of |
| 1371 | .Ar parameter |
| 1372 | is substituted. |
| 1373 | .Pp |
| 1374 | The parameter name or symbol can be enclosed in braces, which are |
| 1375 | optional except for positional parameters with more than one digit or |
| 1376 | when parameter is followed by a character that could be interpreted as |
| 1377 | part of the name. |
| 1378 | If a parameter expansion occurs inside double-quotes: |
| 1379 | .Bl -enum |
| 1380 | .It |
| 1381 | Pathname expansion is not performed on the results of the |
| 1382 | expansion. |
| 1383 | .It |
| 1384 | Field splitting is not performed on the results of the |
| 1385 | expansion, with the exception of the special parameter |
| 1386 | .Va @ . |
| 1387 | .El |
| 1388 | .Pp |
| 1389 | In addition, a parameter expansion can be modified by using one of the |
| 1390 | following formats. |
| 1391 | .Bl -tag -width indent |
| 1392 | .It Li ${ Ns Ar parameter Ns Li :- Ns Ar word Ns Li } |
| 1393 | Use Default Values. |
| 1394 | If |
| 1395 | .Ar parameter |
| 1396 | is unset or null, the expansion of |
| 1397 | .Ar word |
| 1398 | is substituted; otherwise, the value of |
| 1399 | .Ar parameter |
| 1400 | is substituted. |
| 1401 | .It Li ${ Ns Ar parameter Ns Li := Ns Ar word Ns Li } |
| 1402 | Assign Default Values. |
| 1403 | If |
| 1404 | .Ar parameter |
| 1405 | is unset or null, the expansion of |
| 1406 | .Ar word |
| 1407 | is assigned to |
| 1408 | .Ar parameter . |
| 1409 | In all cases, the |
| 1410 | final value of |
| 1411 | .Ar parameter |
| 1412 | is substituted. |
| 1413 | Quoting inside |
| 1414 | .Ar word |
| 1415 | does not prevent field splitting or pathname expansion. |
| 1416 | Only variables, not positional |
| 1417 | parameters or special parameters, can be |
| 1418 | assigned in this way. |
| 1419 | .It Li ${ Ns Ar parameter Ns Li :? Ns Oo Ar word Oc Ns Li } |
| 1420 | Indicate Error if Null or Unset. |
| 1421 | If |
| 1422 | .Ar parameter |
| 1423 | is unset or null, the expansion of |
| 1424 | .Ar word |
| 1425 | (or a message indicating it is unset if |
| 1426 | .Ar word |
| 1427 | is omitted) is written to standard |
| 1428 | error and the shell exits with a nonzero |
| 1429 | exit status. |
| 1430 | Otherwise, the value of |
| 1431 | .Ar parameter |
| 1432 | is substituted. |
| 1433 | An |
| 1434 | interactive shell need not exit. |
| 1435 | .It Li ${ Ns Ar parameter Ns Li :+ Ns Ar word Ns Li } |
| 1436 | Use Alternate Value. |
| 1437 | If |
| 1438 | .Ar parameter |
| 1439 | is unset or null, null is substituted; |
| 1440 | otherwise, the expansion of |
| 1441 | .Ar word |
| 1442 | is substituted. |
| 1443 | .El |
| 1444 | .Pp |
| 1445 | In the parameter expansions shown previously, use of the colon in the |
| 1446 | format results in a test for a parameter that is unset or null; omission |
| 1447 | of the colon results in a test for a parameter that is only unset. |
| 1448 | .Pp |
| 1449 | The |
| 1450 | .Ar word |
| 1451 | inherits the type of quoting |
| 1452 | (unquoted, double-quoted or here-document) |
| 1453 | from the surroundings, |
| 1454 | with the exception that a backslash that quotes a closing brace is removed |
| 1455 | during quote removal. |
| 1456 | .Bl -tag -width indent |
| 1457 | .It Li ${# Ns Ar parameter Ns Li } |
| 1458 | String Length. |
| 1459 | The length in characters of |
| 1460 | the value of |
| 1461 | .Ar parameter . |
| 1462 | .El |
| 1463 | .Pp |
| 1464 | The following four varieties of parameter expansion provide for substring |
| 1465 | processing. |
| 1466 | In each case, pattern matching notation |
| 1467 | (see |
| 1468 | .Sx Shell Patterns ) , |
| 1469 | rather than regular expression notation, |
| 1470 | is used to evaluate the patterns. |
| 1471 | If parameter is one of the special parameters |
| 1472 | .Va * |
| 1473 | or |
| 1474 | .Va @ , |
| 1475 | the result of the expansion is unspecified. |
| 1476 | Enclosing the full parameter expansion string in double-quotes does not |
| 1477 | cause the following four varieties of pattern characters to be quoted, |
| 1478 | whereas quoting characters within the braces has this effect. |
| 1479 | .Bl -tag -width indent |
| 1480 | .It Li ${ Ns Ar parameter Ns Li % Ns Ar word Ns Li } |
| 1481 | Remove Smallest Suffix Pattern. |
| 1482 | The |
| 1483 | .Ar word |
| 1484 | is expanded to produce a pattern. |
| 1485 | The |
| 1486 | parameter expansion then results in |
| 1487 | .Ar parameter , |
| 1488 | with the smallest portion of the |
| 1489 | suffix matched by the pattern deleted. |
| 1490 | .It Li ${ Ns Ar parameter Ns Li %% Ns Ar word Ns Li } |
| 1491 | Remove Largest Suffix Pattern. |
| 1492 | The |
| 1493 | .Ar word |
| 1494 | is expanded to produce a pattern. |
| 1495 | The |
| 1496 | parameter expansion then results in |
| 1497 | .Ar parameter , |
| 1498 | with the largest portion of the |
| 1499 | suffix matched by the pattern deleted. |
| 1500 | .It Li ${ Ns Ar parameter Ns Li # Ns Ar word Ns Li } |
| 1501 | Remove Smallest Prefix Pattern. |
| 1502 | The |
| 1503 | .Ar word |
| 1504 | is expanded to produce a pattern. |
| 1505 | The |
| 1506 | parameter expansion then results in |
| 1507 | .Ar parameter , |
| 1508 | with the smallest portion of the |
| 1509 | prefix matched by the pattern deleted. |
| 1510 | .It Li ${ Ns Ar parameter Ns Li ## Ns Ar word Ns Li } |
| 1511 | Remove Largest Prefix Pattern. |
| 1512 | The |
| 1513 | .Ar word |
| 1514 | is expanded to produce a pattern. |
| 1515 | The |
| 1516 | parameter expansion then results in |
| 1517 | .Ar parameter , |
| 1518 | with the largest portion of the |
| 1519 | prefix matched by the pattern deleted. |
| 1520 | .El |
| 1521 | .Ss Command Substitution |
| 1522 | Command substitution allows the output of a command to be substituted in |
| 1523 | place of the command name itself. |
| 1524 | Command substitution occurs when |
| 1525 | the command is enclosed as follows: |
| 1526 | .Pp |
| 1527 | .D1 Li $( Ns Ar command Ns Li )\& |
| 1528 | .Pp |
| 1529 | or the backquoted version: |
| 1530 | .Pp |
| 1531 | .D1 Li ` Ns Ar command Ns Li ` |
| 1532 | .Pp |
| 1533 | The shell expands the command substitution by executing command |
| 1534 | and replacing the command substitution |
| 1535 | with the standard output of the command, |
| 1536 | removing sequences of one or more newlines at the end of the substitution. |
| 1537 | Embedded newlines before the end of the output are not removed; |
| 1538 | however, during field splitting, they may be translated into spaces |
| 1539 | depending on the value of |
| 1540 | .Va IFS |
| 1541 | and the quoting that is in effect. |
| 1542 | The command is executed in a subshell environment, |
| 1543 | except that the built-in commands |
| 1544 | .Ic jobid , |
| 1545 | .Ic jobs , |
| 1546 | .Ic times |
| 1547 | and |
| 1548 | .Ic trap |
| 1549 | return information about the main shell environment |
| 1550 | if they are the only command in a command substitution |
| 1551 | and the substitutions in the command cannot cause side effects |
| 1552 | (such as from assigning values to variables or referencing |
| 1553 | .Li $! ). |
| 1554 | .Ss Arithmetic Expansion |
| 1555 | Arithmetic expansion provides a mechanism for evaluating an arithmetic |
| 1556 | expression and substituting its value. |
| 1557 | The format for arithmetic expansion is as follows: |
| 1558 | .Pp |
| 1559 | .D1 Li $(( Ns Ar expression Ns Li )) |
| 1560 | .Pp |
| 1561 | The |
| 1562 | .Ar expression |
| 1563 | is treated as if it were in double-quotes, except |
| 1564 | that a double-quote inside the expression is not treated specially. |
| 1565 | The |
| 1566 | shell expands all tokens in the |
| 1567 | .Ar expression |
| 1568 | for parameter expansion, |
| 1569 | command substitution, |
| 1570 | arithmetic expansion |
| 1571 | and quote removal. |
| 1572 | .Pp |
| 1573 | The allowed expressions are a subset of C expressions, |
| 1574 | summarized below. |
| 1575 | .Bl -tag -width "Variables" -offset indent |
| 1576 | .It Values |
| 1577 | All values are of type |
| 1578 | .Ft intmax_t . |
| 1579 | .It Constants |
| 1580 | Decimal, octal (starting with |
| 1581 | .Li 0 ) |
| 1582 | and hexadecimal (starting with |
| 1583 | .Li 0x ) |
| 1584 | integer constants. |
| 1585 | .It Variables |
| 1586 | Shell variables can be read and written |
| 1587 | and contain integer constants. |
| 1588 | .It Unary operators |
| 1589 | .Li "! ~ + -" |
| 1590 | .It Binary operators |
| 1591 | .Li "* / % + - << >> < <= > >= == != & ^ | && ||" |
| 1592 | .It Assignment operators |
| 1593 | .Li "= += -= *= /= %= <<= >>= &= ^= |=" |
| 1594 | .It Conditional operator |
| 1595 | .Li "? :" |
| 1596 | .El |
| 1597 | .Pp |
| 1598 | The result of the expression is substituted in decimal. |
| 1599 | .Ss White Space Splitting (Field Splitting) |
| 1600 | After parameter expansion, command substitution, and |
| 1601 | arithmetic expansion the shell scans the results of |
| 1602 | expansions and substitutions that did not occur in double-quotes for |
| 1603 | field splitting and multiple fields can result. |
| 1604 | .Pp |
| 1605 | The shell treats each character of the |
| 1606 | .Va IFS |
| 1607 | variable as a delimiter and uses |
| 1608 | the delimiters to split the results of parameter expansion and command |
| 1609 | substitution into fields. |
| 1610 | .Ss Pathname Expansion (File Name Generation) |
| 1611 | Unless the |
| 1612 | .Fl f |
| 1613 | option is set, |
| 1614 | file name generation is performed |
| 1615 | after word splitting is complete. |
| 1616 | Each word is |
| 1617 | viewed as a series of patterns, separated by slashes. |
| 1618 | The |
| 1619 | process of expansion replaces the word with the names of |
| 1620 | all existing files whose names can be formed by replacing |
| 1621 | each pattern with a string that matches the specified pattern. |
| 1622 | There are two restrictions on this: first, a pattern cannot match |
| 1623 | a string containing a slash, and second, |
| 1624 | a pattern cannot match a string starting with a period |
| 1625 | unless the first character of the pattern is a period. |
| 1626 | The next section describes the patterns used for both |
| 1627 | Pathname Expansion and the |
| 1628 | .Ic case |
| 1629 | command. |
| 1630 | .Ss Shell Patterns |
| 1631 | A pattern consists of normal characters, which match themselves, |
| 1632 | and meta-characters. |
| 1633 | The meta-characters are |
| 1634 | .Ql \&! , |
| 1635 | .Ql * , |
| 1636 | .Ql \&? , |
| 1637 | and |
| 1638 | .Ql \&[ . |
| 1639 | These characters lose their special meanings if they are quoted. |
| 1640 | When command or variable substitution is performed and the dollar sign |
| 1641 | or back quotes are not double-quoted, the value of the |
| 1642 | variable or the output of the command is scanned for these |
| 1643 | characters and they are turned into meta-characters. |
| 1644 | .Pp |
| 1645 | An asterisk |
| 1646 | .Pq Ql * |
| 1647 | matches any string of characters. |
| 1648 | A question mark |
| 1649 | .Pq Ql \&? |
| 1650 | matches any single character. |
| 1651 | A left bracket |
| 1652 | .Pq Ql \&[ |
| 1653 | introduces a character class. |
| 1654 | The end of the character class is indicated by a |
| 1655 | .Ql \&] ; |
| 1656 | if the |
| 1657 | .Ql \&] |
| 1658 | is missing then the |
| 1659 | .Ql \&[ |
| 1660 | matches a |
| 1661 | .Ql \&[ |
| 1662 | rather than introducing a character class. |
| 1663 | A character class matches any of the characters between the square brackets. |
| 1664 | A range of characters may be specified using a minus sign. |
| 1665 | The character class may be complemented by making an exclamation point |
| 1666 | .Pq Ql !\& |
| 1667 | or the caret |
| 1668 | .Pq Ql ^\& |
| 1669 | the first character of the character class. |
| 1670 | .Pp |
| 1671 | To include a |
| 1672 | .Ql \&] |
| 1673 | in a character class, make it the first character listed |
| 1674 | (after the |
| 1675 | .Ql \&! |
| 1676 | or |
| 1677 | .Ql \&^ , |
| 1678 | if any). |
| 1679 | To include a |
| 1680 | .Ql - , |
| 1681 | make it the first or last character listed. |
| 1682 | .Ss Built-in Commands |
| 1683 | This section lists the built-in commands. |
| 1684 | .Bl -tag -width indent |
| 1685 | .It Ic \&: |
| 1686 | A null command that returns a 0 (true) exit value. |
| 1687 | .It Ic \&. Ar file |
| 1688 | The commands in the specified file are read and executed by the shell. |
| 1689 | The |
| 1690 | .Ic return |
| 1691 | command may be used to return to the |
| 1692 | .Ic \&. |
| 1693 | command's caller. |
| 1694 | If |
| 1695 | .Ar file |
| 1696 | contains any |
| 1697 | .Ql / |
| 1698 | characters, it is used as is. |
| 1699 | Otherwise, the shell searches the |
| 1700 | .Va PATH |
| 1701 | for the file. |
| 1702 | If it is not found in the |
| 1703 | .Va PATH , |
| 1704 | it is sought in the current working directory. |
| 1705 | .It Ic \&[ |
| 1706 | A built-in equivalent of |
| 1707 | .Xr test 1 . |
| 1708 | .It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc Ar ... Oc |
| 1709 | If |
| 1710 | .Ar name Ns = Ns Ar string |
| 1711 | is specified, the shell defines the alias |
| 1712 | .Ar name |
| 1713 | with value |
| 1714 | .Ar string . |
| 1715 | If just |
| 1716 | .Ar name |
| 1717 | is specified, the value of the alias |
| 1718 | .Ar name |
| 1719 | is printed. |
| 1720 | With no arguments, the |
| 1721 | .Ic alias |
| 1722 | built-in command prints the names and values of all defined aliases |
| 1723 | (see |
| 1724 | .Ic unalias ) . |
| 1725 | Alias values are written with appropriate quoting so that they are |
| 1726 | suitable for re-input to the shell. |
| 1727 | Also see the |
| 1728 | .Sx Aliases |
| 1729 | subsection. |
| 1730 | .It Ic bg Op Ar job ... |
| 1731 | Continue the specified jobs |
| 1732 | (or the current job if no jobs are given) |
| 1733 | in the background. |
| 1734 | .It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc |
| 1735 | List or alter key bindings for the line editor. |
| 1736 | This command is documented in |
| 1737 | .Xr editrc 5 . |
| 1738 | .It Ic break Op Ar num |
| 1739 | See the |
| 1740 | .Sx Flow-Control Constructs |
| 1741 | subsection. |
| 1742 | .It Ic builtin Ar cmd Op Ar arg ... |
| 1743 | Execute the specified built-in command, |
| 1744 | .Ar cmd . |
| 1745 | This is useful when the user wishes to override a shell function |
| 1746 | with the same name as a built-in command. |
| 1747 | .It Ic cd Oo Fl L | P Oc Op Ar directory |
| 1748 | Switch to the specified |
| 1749 | .Ar directory , |
| 1750 | or to the directory specified in the |
| 1751 | .Va HOME |
| 1752 | environment variable if no |
| 1753 | .Ar directory |
| 1754 | is specified. |
| 1755 | If |
| 1756 | .Ar directory |
| 1757 | does not begin with |
| 1758 | .Pa / , \&. , |
| 1759 | or |
| 1760 | .Pa .. , |
| 1761 | then the directories listed in the |
| 1762 | .Va CDPATH |
| 1763 | variable will be |
| 1764 | searched for the specified |
| 1765 | .Ar directory . |
| 1766 | If |
| 1767 | .Va CDPATH |
| 1768 | is unset, the current directory is searched. |
| 1769 | The format of |
| 1770 | .Va CDPATH |
| 1771 | is the same as that of |
| 1772 | .Va PATH . |
| 1773 | In an interactive shell, |
| 1774 | the |
| 1775 | .Ic cd |
| 1776 | command will print out the name of the directory |
| 1777 | that it actually switched to |
| 1778 | if this is different from the name that the user gave. |
| 1779 | These may be different either because the |
| 1780 | .Va CDPATH |
| 1781 | mechanism was used or because a symbolic link was crossed. |
| 1782 | .Pp |
| 1783 | If the |
| 1784 | .Fl P |
| 1785 | option is specified, |
| 1786 | .Pa .. |
| 1787 | is handled physically and symbolic links are resolved before |
| 1788 | .Pa .. |
| 1789 | components are processed. |
| 1790 | If the |
| 1791 | .Fl L |
| 1792 | option is specified, |
| 1793 | .Pa .. |
| 1794 | is handled logically. |
| 1795 | This is the default. |
| 1796 | .It Ic chdir |
| 1797 | A synonym for the |
| 1798 | .Ic cd |
| 1799 | built-in command. |
| 1800 | .It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... |
| 1801 | .It Ic command Oo Fl p Oc Fl v Ar utility |
| 1802 | .It Ic command Oo Fl p Oc Fl V Ar utility |
| 1803 | The first form of invocation executes the specified |
| 1804 | .Ar utility , |
| 1805 | ignoring shell functions in the search. |
| 1806 | If |
| 1807 | .Ar utility |
| 1808 | is a special builtin, |
| 1809 | it is executed as if it were a regular builtin. |
| 1810 | .Pp |
| 1811 | If the |
| 1812 | .Fl p |
| 1813 | option is specified, the command search is performed using a |
| 1814 | default value of |
| 1815 | .Va PATH |
| 1816 | that is guaranteed to find all of the standard utilities. |
| 1817 | .Pp |
| 1818 | If the |
| 1819 | .Fl v |
| 1820 | option is specified, |
| 1821 | .Ar utility |
| 1822 | is not executed but a description of its interpretation by the shell is |
| 1823 | printed. |
| 1824 | For ordinary commands the output is the path name; for shell built-in |
| 1825 | commands, shell functions and keywords only the name is written. |
| 1826 | Aliases are printed as |
| 1827 | .Dq Ic alias Ar name Ns = Ns Ar value . |
| 1828 | .Pp |
| 1829 | The |
| 1830 | .Fl V |
| 1831 | option is identical to |
| 1832 | .Fl v |
| 1833 | except for the output. |
| 1834 | It prints |
| 1835 | .Dq Ar utility Ic is Ar description |
| 1836 | where |
| 1837 | .Ar description |
| 1838 | is either |
| 1839 | the path name to |
| 1840 | .Ar utility , |
| 1841 | a special shell builtin, |
| 1842 | a shell builtin, |
| 1843 | a shell function, |
| 1844 | a shell keyword |
| 1845 | or |
| 1846 | an alias for |
| 1847 | .Ar value . |
| 1848 | .It Ic continue Op Ar num |
| 1849 | See the |
| 1850 | .Sx Flow-Control Constructs |
| 1851 | subsection. |
| 1852 | .It Ic echo Oo Fl e | n Oc Op Ar string ... |
| 1853 | Print a space-separated list of the arguments to the standard output |
| 1854 | and append a newline character. |
| 1855 | .Bl -tag -width indent |
| 1856 | .It Fl n |
| 1857 | Suppress the output of the trailing newline. |
| 1858 | .It Fl e |
| 1859 | Process C-style backslash escape sequences. |
| 1860 | The |
| 1861 | .Ic echo |
| 1862 | command understands the following character escapes: |
| 1863 | .Bl -tag -width indent |
| 1864 | .It \ea |
| 1865 | Alert (ring the terminal bell) |
| 1866 | .It \eb |
| 1867 | Backspace |
| 1868 | .It \ec |
| 1869 | Suppress the trailing newline (this has the side-effect of truncating the |
| 1870 | line if it is not the last character) |
| 1871 | .It \ee |
| 1872 | The ESC character |
| 1873 | .Tn ( ASCII |
| 1874 | 0x1b) |
| 1875 | .It \ef |
| 1876 | Formfeed |
| 1877 | .It \en |
| 1878 | Newline |
| 1879 | .It \er |
| 1880 | Carriage return |
| 1881 | .It \et |
| 1882 | Horizontal tab |
| 1883 | .It \ev |
| 1884 | Vertical tab |
| 1885 | .It \e\e |
| 1886 | Literal backslash |
| 1887 | .It \e0nnn |
| 1888 | (Zero) The character whose octal value is |
| 1889 | .Ar nnn |
| 1890 | .El |
| 1891 | .Pp |
| 1892 | If |
| 1893 | .Ar string |
| 1894 | is not enclosed in quotes then the backslash itself must be escaped |
| 1895 | with a backslash to protect it from the shell. |
| 1896 | For example |
| 1897 | .Bd -literal -offset indent |
| 1898 | $ echo -e "a\evb" |
| 1899 | a |
| 1900 | b |
| 1901 | $ echo -e a\e\evb |
| 1902 | a |
| 1903 | b |
| 1904 | $ echo -e "a\e\eb" |
| 1905 | a\eb |
| 1906 | $ echo -e a\e\e\e\eb |
| 1907 | a\eb |
| 1908 | .Ed |
| 1909 | .El |
| 1910 | .Pp |
| 1911 | Only one of the |
| 1912 | .Fl e |
| 1913 | and |
| 1914 | .Fl n |
| 1915 | options may be specified. |
| 1916 | .It Ic eval Ar string ... |
| 1917 | Concatenate all the arguments with spaces. |
| 1918 | Then re-parse and execute the command. |
| 1919 | .It Ic exec Op Ar command Op Ar arg ... |
| 1920 | Unless |
| 1921 | .Ar command |
| 1922 | is omitted, |
| 1923 | the shell process is replaced with the specified program |
| 1924 | (which must be a real program, not a shell built-in command or function). |
| 1925 | Any redirections on the |
| 1926 | .Ic exec |
| 1927 | command are marked as permanent, |
| 1928 | so that they are not undone when the |
| 1929 | .Ic exec |
| 1930 | command finishes. |
| 1931 | .It Ic exit Op Ar exitstatus |
| 1932 | Terminate the shell process. |
| 1933 | If |
| 1934 | .Ar exitstatus |
| 1935 | is given |
| 1936 | it is used as the exit status of the shell. |
| 1937 | Otherwise, if the shell is executing an |
| 1938 | .Cm EXIT |
| 1939 | trap, the exit status of the last command before the trap is used; |
| 1940 | if the shell is executing a trap for a signal, |
| 1941 | the shell exits by resending the signal to itself. |
| 1942 | Otherwise, the exit status of the preceding command is used. |
| 1943 | The exit status should be an integer between 0 and 255. |
| 1944 | .It Ic export Ar name ... |
| 1945 | .It Ic export Op Fl p |
| 1946 | The specified names are exported so that they will |
| 1947 | appear in the environment of subsequent commands. |
| 1948 | The only way to un-export a variable is to |
| 1949 | .Ic unset |
| 1950 | it. |
| 1951 | The shell allows the value of a variable to be set |
| 1952 | at the same time as it is exported by writing |
| 1953 | .Pp |
| 1954 | .D1 Ic export Ar name Ns = Ns Ar value |
| 1955 | .Pp |
| 1956 | With no arguments the |
| 1957 | .Ic export |
| 1958 | command lists the names |
| 1959 | of all exported variables. |
| 1960 | If the |
| 1961 | .Fl p |
| 1962 | option is specified, the exported variables are printed as |
| 1963 | .Dq Ic export Ar name Ns = Ns Ar value |
| 1964 | lines, suitable for re-input to the shell. |
| 1965 | .It Ic false |
| 1966 | A null command that returns a non-zero (false) exit value. |
| 1967 | .It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last |
| 1968 | .It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last |
| 1969 | .It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first |
| 1970 | The |
| 1971 | .Ic fc |
| 1972 | built-in command lists, or edits and re-executes, |
| 1973 | commands previously entered to an interactive shell. |
| 1974 | .Bl -tag -width indent |
| 1975 | .It Fl e Ar editor |
| 1976 | Use the editor named by |
| 1977 | .Ar editor |
| 1978 | to edit the commands. |
| 1979 | The |
| 1980 | .Ar editor |
| 1981 | string is a command name, |
| 1982 | subject to search via the |
| 1983 | .Va PATH |
| 1984 | variable. |
| 1985 | The value in the |
| 1986 | .Va FCEDIT |
| 1987 | variable is used as a default when |
| 1988 | .Fl e |
| 1989 | is not specified. |
| 1990 | If |
| 1991 | .Va FCEDIT |
| 1992 | is null or unset, the value of the |
| 1993 | .Va EDITOR |
| 1994 | variable is used. |
| 1995 | If |
| 1996 | .Va EDITOR |
| 1997 | is null or unset, |
| 1998 | .Xr ed 1 |
| 1999 | is used as the editor. |
| 2000 | .It Fl l No (ell) |
| 2001 | List the commands rather than invoking |
| 2002 | an editor on them. |
| 2003 | The commands are written in the |
| 2004 | sequence indicated by the |
| 2005 | .Ar first |
| 2006 | and |
| 2007 | .Ar last |
| 2008 | operands, as affected by |
| 2009 | .Fl r , |
| 2010 | with each command preceded by the command number. |
| 2011 | .It Fl n |
| 2012 | Suppress command numbers when listing with |
| 2013 | .Fl l . |
| 2014 | .It Fl r |
| 2015 | Reverse the order of the commands listed |
| 2016 | (with |
| 2017 | .Fl l ) |
| 2018 | or edited |
| 2019 | (with neither |
| 2020 | .Fl l |
| 2021 | nor |
| 2022 | .Fl s ) . |
| 2023 | .It Fl s |
| 2024 | Re-execute the command without invoking an editor. |
| 2025 | .It Ar first |
| 2026 | .It Ar last |
| 2027 | Select the commands to list or edit. |
| 2028 | The number of previous commands that can be accessed |
| 2029 | are determined by the value of the |
| 2030 | .Va HISTSIZE |
| 2031 | variable. |
| 2032 | The value of |
| 2033 | .Ar first |
| 2034 | or |
| 2035 | .Ar last |
| 2036 | or both are one of the following: |
| 2037 | .Bl -tag -width indent |
| 2038 | .It Oo Cm + Oc Ns Ar num |
| 2039 | A positive number representing a command number; |
| 2040 | command numbers can be displayed with the |
| 2041 | .Fl l |
| 2042 | option. |
| 2043 | .It Fl Ar num |
| 2044 | A negative decimal number representing the |
| 2045 | command that was executed |
| 2046 | .Ar num |
| 2047 | of |
| 2048 | commands previously. |
| 2049 | For example, \-1 is the immediately previous command. |
| 2050 | .It Ar string |
| 2051 | A string indicating the most recently entered command |
| 2052 | that begins with that string. |
| 2053 | If the |
| 2054 | .Ar old Ns = Ns Ar new |
| 2055 | operand is not also specified with |
| 2056 | .Fl s , |
| 2057 | the string form of the first operand cannot contain an embedded equal sign. |
| 2058 | .El |
| 2059 | .El |
| 2060 | .Pp |
| 2061 | The following variables affect the execution of |
| 2062 | .Ic fc : |
| 2063 | .Bl -tag -width ".Va HISTSIZE" |
| 2064 | .It Va FCEDIT |
| 2065 | Name of the editor to use for history editing. |
| 2066 | .It Va HISTSIZE |
| 2067 | The number of previous commands that are accessible. |
| 2068 | .El |
| 2069 | .It Ic fg Op Ar job |
| 2070 | Move the specified |
| 2071 | .Ar job |
| 2072 | or the current job to the foreground. |
| 2073 | .It Ic getopts Ar optstring var |
| 2074 | The |
| 2075 | .Tn POSIX |
| 2076 | .Ic getopts |
| 2077 | command. |
| 2078 | The |
| 2079 | .Ic getopts |
| 2080 | command deprecates the older |
| 2081 | .Xr getopt 1 |
| 2082 | command. |
| 2083 | The first argument should be a series of letters, each possibly |
| 2084 | followed by a colon which indicates that the option takes an argument. |
| 2085 | The specified variable is set to the parsed option. |
| 2086 | The index of |
| 2087 | the next argument is placed into the shell variable |
| 2088 | .Va OPTIND . |
| 2089 | If an option takes an argument, it is placed into the shell variable |
| 2090 | .Va OPTARG . |
| 2091 | If an invalid option is encountered, |
| 2092 | .Ar var |
| 2093 | is set to |
| 2094 | .Ql \&? . |
| 2095 | It returns a false value (1) when it encounters the end of the options. |
| 2096 | .It Ic hash Oo Fl rv Oc Op Ar command ... |
| 2097 | The shell maintains a hash table which remembers the locations of commands. |
| 2098 | With no arguments whatsoever, the |
| 2099 | .Ic hash |
| 2100 | command prints out the contents of this table. |
| 2101 | Entries which have not been looked at since the last |
| 2102 | .Ic cd |
| 2103 | command are marked with an asterisk; |
| 2104 | it is possible for these entries to be invalid. |
| 2105 | .Pp |
| 2106 | With arguments, the |
| 2107 | .Ic hash |
| 2108 | command removes each specified |
| 2109 | .Ar command |
| 2110 | from the hash table (unless they are functions) and then locates it. |
| 2111 | With the |
| 2112 | .Fl v |
| 2113 | option, |
| 2114 | .Ic hash |
| 2115 | prints the locations of the commands as it finds them. |
| 2116 | The |
| 2117 | .Fl r |
| 2118 | option causes the |
| 2119 | .Ic hash |
| 2120 | command to delete all the entries in the hash table except for functions. |
| 2121 | .It Ic jobid Op Ar job |
| 2122 | Print the process IDs of the processes in the specified |
| 2123 | .Ar job . |
| 2124 | If the |
| 2125 | .Ar job |
| 2126 | argument is omitted, use the current job. |
| 2127 | .It Ic jobs Oo Fl lps Oc Op Ar job ... |
| 2128 | Print information about the specified jobs, or all jobs if no |
| 2129 | .Ar job |
| 2130 | argument is given. |
| 2131 | The information printed includes job ID, status and command name. |
| 2132 | .Pp |
| 2133 | If the |
| 2134 | .Fl l |
| 2135 | option is specified, the PID of each job is also printed. |
| 2136 | If the |
| 2137 | .Fl p |
| 2138 | option is specified, only the process IDs for the process group leaders |
| 2139 | are printed, one per line. |
| 2140 | If the |
| 2141 | .Fl s |
| 2142 | option is specified, only the PIDs of the job commands are printed, one per |
| 2143 | line. |
| 2144 | .It Ic kill |
| 2145 | A built-in equivalent of |
| 2146 | .Xr kill 1 |
| 2147 | that additionally supports sending signals to jobs. |
| 2148 | .It Ic local Oo Ar variable ... Oc Op Fl |
| 2149 | See the |
| 2150 | .Sx Functions |
| 2151 | subsection. |
| 2152 | .It Ic printf |
| 2153 | A built-in equivalent of |
| 2154 | .Xr printf 1 . |
| 2155 | .It Ic pwd Op Fl L | P |
| 2156 | Print the path of the current directory. |
| 2157 | The built-in command may |
| 2158 | differ from the program of the same name because the |
| 2159 | built-in command remembers what the current directory |
| 2160 | is rather than recomputing it each time. |
| 2161 | This makes |
| 2162 | it faster. |
| 2163 | However, if the current directory is |
| 2164 | renamed, |
| 2165 | the built-in version of |
| 2166 | .Xr pwd 1 |
| 2167 | will continue to print the old name for the directory. |
| 2168 | .Pp |
| 2169 | If the |
| 2170 | .Fl P |
| 2171 | option is specified, symbolic links are resolved. |
| 2172 | If the |
| 2173 | .Fl L |
| 2174 | option is specified, the shell's notion of the current directory |
| 2175 | is printed (symbolic links are not resolved). |
| 2176 | This is the default. |
| 2177 | .It Ic read Oo Fl p Ar prompt Oc Oo |
| 2178 | .Fl t Ar timeout Oc Oo Fl er Oc Ar variable ... |
| 2179 | The |
| 2180 | .Ar prompt |
| 2181 | is printed if the |
| 2182 | .Fl p |
| 2183 | option is specified |
| 2184 | and the standard input is a terminal. |
| 2185 | Then a line is |
| 2186 | read from the standard input. |
| 2187 | The trailing newline |
| 2188 | is deleted from the line and the line is split as |
| 2189 | described in the section on |
| 2190 | .Sx White Space Splitting (Field Splitting) |
| 2191 | above, and |
| 2192 | the pieces are assigned to the variables in order. |
| 2193 | If there are more pieces than variables, the remaining |
| 2194 | pieces (along with the characters in |
| 2195 | .Va IFS |
| 2196 | that separated them) |
| 2197 | are assigned to the last variable. |
| 2198 | If there are more variables than pieces, the remaining |
| 2199 | variables are assigned the null string. |
| 2200 | .Pp |
| 2201 | Backslashes are treated specially, unless the |
| 2202 | .Fl r |
| 2203 | option is |
| 2204 | specified. |
| 2205 | If a backslash is followed by |
| 2206 | a newline, the backslash and the newline will be |
| 2207 | deleted. |
| 2208 | If a backslash is followed by any other |
| 2209 | character, the backslash will be deleted and the following |
| 2210 | character will be treated as though it were not in |
| 2211 | .Va IFS , |
| 2212 | even if it is. |
| 2213 | .Pp |
| 2214 | If the |
| 2215 | .Fl t |
| 2216 | option is specified and the |
| 2217 | .Ar timeout |
| 2218 | elapses before a complete line of input is supplied, |
| 2219 | the |
| 2220 | .Ic read |
| 2221 | command will return an exit status of 1 without assigning any values. |
| 2222 | The |
| 2223 | .Ar timeout |
| 2224 | value may optionally be followed by one of |
| 2225 | .Ql s , |
| 2226 | .Ql m |
| 2227 | or |
| 2228 | .Ql h |
| 2229 | to explicitly specify seconds, minutes or hours. |
| 2230 | If none is supplied, |
| 2231 | .Ql s |
| 2232 | is assumed. |
| 2233 | .Pp |
| 2234 | The |
| 2235 | .Fl e |
| 2236 | option exists only for backward compatibility with older scripts. |
| 2237 | .It Ic readonly Oo Fl p Oc Op Ar name ... |
| 2238 | Each specified |
| 2239 | .Ar name |
| 2240 | is marked as read only, |
| 2241 | so that it cannot be subsequently modified or unset. |
| 2242 | The shell allows the value of a variable to be set |
| 2243 | at the same time as it is marked read only |
| 2244 | by using the following form: |
| 2245 | .Pp |
| 2246 | .D1 Ic readonly Ar name Ns = Ns Ar value |
| 2247 | .Pp |
| 2248 | With no arguments the |
| 2249 | .Ic readonly |
| 2250 | command lists the names of all read only variables. |
| 2251 | If the |
| 2252 | .Fl p |
| 2253 | option is specified, the read-only variables are printed as |
| 2254 | .Dq Ic readonly Ar name Ns = Ns Ar value |
| 2255 | lines, suitable for re-input to the shell. |
| 2256 | .It Ic return Op Ar exitstatus |
| 2257 | See the |
| 2258 | .Sx Functions |
| 2259 | subsection. |
| 2260 | .It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo |
| 2261 | .Fl c Ar string Oc Op Fl - Ar arg ... |
| 2262 | The |
| 2263 | .Ic set |
| 2264 | command performs three different functions: |
| 2265 | .Bl -item |
| 2266 | .It |
| 2267 | With no arguments, it lists the values of all shell variables. |
| 2268 | .It |
| 2269 | If options are given, |
| 2270 | either in short form or using the long |
| 2271 | .Dq Fl /+o Ar longname |
| 2272 | form, |
| 2273 | it sets or clears the specified options as described in the section called |
| 2274 | .Sx Argument List Processing . |
| 2275 | .It |
| 2276 | If the |
| 2277 | .Dq Fl - |
| 2278 | option is specified, |
| 2279 | .Ic set |
| 2280 | will replace the shell's positional parameters with the subsequent |
| 2281 | arguments. |
| 2282 | If no arguments follow the |
| 2283 | .Dq Fl - |
| 2284 | option, |
| 2285 | all the positional parameters will be cleared, |
| 2286 | which is equivalent to executing the command |
| 2287 | .Dq Li "shift $#" . |
| 2288 | The |
| 2289 | .Dq Fl - |
| 2290 | flag may be omitted when specifying arguments to be used |
| 2291 | as positional replacement parameters. |
| 2292 | This is not recommended, |
| 2293 | because the first argument may begin with a dash |
| 2294 | .Pq Ql - |
| 2295 | or a plus |
| 2296 | .Pq Ql + , |
| 2297 | which the |
| 2298 | .Ic set |
| 2299 | command will interpret as a request to enable or disable options. |
| 2300 | .El |
| 2301 | .It Ic setvar Ar variable value |
| 2302 | Assigns the specified |
| 2303 | .Ar value |
| 2304 | to the specified |
| 2305 | .Ar variable . |
| 2306 | The |
| 2307 | .Ic setvar |
| 2308 | command is intended to be used in functions that |
| 2309 | assign values to variables whose names are passed as parameters. |
| 2310 | In general it is better to write |
| 2311 | .Dq Ar variable Ns = Ns Ar value |
| 2312 | rather than using |
| 2313 | .Ic setvar . |
| 2314 | .It Ic shift Op Ar n |
| 2315 | Shift the positional parameters |
| 2316 | .Ar n |
| 2317 | times, or once if |
| 2318 | .Ar n |
| 2319 | is not specified. |
| 2320 | A shift sets the value of |
| 2321 | .Li $1 |
| 2322 | to the value of |
| 2323 | .Li $2 , |
| 2324 | the value of |
| 2325 | .Li $2 |
| 2326 | to the value of |
| 2327 | .Li $3 , |
| 2328 | and so on, |
| 2329 | decreasing the value of |
| 2330 | .Li $# |
| 2331 | by one. |
| 2332 | If there are zero positional parameters, shifting does not do anything. |
| 2333 | .It Ic test |
| 2334 | A built-in equivalent of |
| 2335 | .Xr test 1 . |
| 2336 | .It Ic times |
| 2337 | Print the amount of time spent executing the shell and its children. |
| 2338 | The first output line shows the user and system times for the shell |
| 2339 | itself, the second one contains the user and system times for the |
| 2340 | children. |
| 2341 | .It Ic trap Oo Ar action Oc Ar signal ... |
| 2342 | .It Ic trap Fl l |
| 2343 | Cause the shell to parse and execute |
| 2344 | .Ar action |
| 2345 | when any specified |
| 2346 | .Ar signal |
| 2347 | is received. |
| 2348 | The signals are specified by name or number. |
| 2349 | In addition, the pseudo-signal |
| 2350 | .Cm EXIT |
| 2351 | may be used to specify an |
| 2352 | .Ar action |
| 2353 | that is performed when the shell terminates. |
| 2354 | The |
| 2355 | .Ar action |
| 2356 | may be an empty string or a dash |
| 2357 | .Pq Ql - ; |
| 2358 | the former causes the specified signal to be ignored |
| 2359 | and the latter causes the default action to be taken. |
| 2360 | Omitting the |
| 2361 | .Ar action |
| 2362 | is another way to request the default action, for compatibility reasons this |
| 2363 | usage is not recommended though. |
| 2364 | In a subshell environment, |
| 2365 | the shell resets trapped (but not ignored) signals to the default action. |
| 2366 | The |
| 2367 | .Ic trap |
| 2368 | command has no effect on signals that were ignored on entry to the shell. |
| 2369 | .Pp |
| 2370 | Option |
| 2371 | .Fl l |
| 2372 | causes the |
| 2373 | .Ic trap |
| 2374 | command to display a list of valid signal names. |
| 2375 | .It Ic true |
| 2376 | A null command that returns a 0 (true) exit value. |
| 2377 | .It Ic type Op Ar name ... |
| 2378 | Interpret each |
| 2379 | .Ar name |
| 2380 | as a command and print the resolution of the command search. |
| 2381 | Possible resolutions are: |
| 2382 | shell keyword, alias, special shell builtin, shell builtin, command, |
| 2383 | tracked alias |
| 2384 | and not found. |
| 2385 | For aliases the alias expansion is printed; |
| 2386 | for commands and tracked aliases |
| 2387 | the complete pathname of the command is printed. |
| 2388 | .It Ic ulimit Oo Fl HSabcdflmnstuv Oc Op Ar limit |
| 2389 | Set or display resource limits (see |
| 2390 | .Xr getrlimit 2 ) . |
| 2391 | If |
| 2392 | .Ar limit |
| 2393 | is specified, the named resource will be set; |
| 2394 | otherwise the current resource value will be displayed. |
| 2395 | .Pp |
| 2396 | If |
| 2397 | .Fl H |
| 2398 | is specified, the hard limits will be set or displayed. |
| 2399 | While everybody is allowed to reduce a hard limit, |
| 2400 | only the superuser can increase it. |
| 2401 | The |
| 2402 | .Fl S |
| 2403 | option |
| 2404 | specifies the soft limits instead. |
| 2405 | When displaying limits, |
| 2406 | only one of |
| 2407 | .Fl S |
| 2408 | or |
| 2409 | .Fl H |
| 2410 | can be given. |
| 2411 | The default is to display the soft limits, |
| 2412 | and to set both the hard and the soft limits. |
| 2413 | .Pp |
| 2414 | Option |
| 2415 | .Fl a |
| 2416 | causes the |
| 2417 | .Ic ulimit |
| 2418 | command to display all resources. |
| 2419 | The parameter |
| 2420 | .Ar limit |
| 2421 | is not acceptable in this mode. |
| 2422 | .Pp |
| 2423 | The remaining options specify which resource value is to be |
| 2424 | displayed or modified. |
| 2425 | They are mutually exclusive. |
| 2426 | .Bl -tag -width indent |
| 2427 | .It Fl b Ar sbsize |
| 2428 | The maximum size of socket buffer usage, in bytes. |
| 2429 | .It Fl c Ar coredumpsize |
| 2430 | The maximal size of core dump files, in 512-byte blocks. |
| 2431 | .It Fl d Ar datasize |
| 2432 | The maximal size of the data segment of a process, in kilobytes. |
| 2433 | .It Fl f Ar filesize |
| 2434 | The maximal size of a file, in 512-byte blocks. |
| 2435 | .It Fl l Ar lockedmem |
| 2436 | The maximal size of memory that can be locked by a process, in |
| 2437 | kilobytes. |
| 2438 | .It Fl m Ar memoryuse |
| 2439 | The maximal resident set size of a process, in kilobytes. |
| 2440 | .It Fl n Ar nofiles |
| 2441 | The maximal number of descriptors that could be opened by a process. |
| 2442 | .It Fl s Ar stacksize |
| 2443 | The maximal size of the stack segment, in kilobytes. |
| 2444 | .It Fl t Ar time |
| 2445 | The maximal amount of CPU time to be used by each process, in seconds. |
| 2446 | .It Fl u Ar userproc |
| 2447 | The maximal number of simultaneous processes for this user ID. |
| 2448 | .It Fl v Ar virtualmem |
| 2449 | The maximal virtual size of a process, in kilobytes. |
| 2450 | .El |
| 2451 | .It Ic umask Oo Fl S Oc Op Ar mask |
| 2452 | Set the file creation mask (see |
| 2453 | .Xr umask 2 ) |
| 2454 | to the octal or symbolic (see |
| 2455 | .Xr chmod 1 ) |
| 2456 | value specified by |
| 2457 | .Ar mask . |
| 2458 | If the argument is omitted, the current mask value is printed. |
| 2459 | If the |
| 2460 | .Fl S |
| 2461 | option is specified, the output is symbolic, otherwise the output is octal. |
| 2462 | .It Ic unalias Oo Fl a Oc Op Ar name ... |
| 2463 | The specified alias names are removed. |
| 2464 | If |
| 2465 | .Fl a |
| 2466 | is specified, all aliases are removed. |
| 2467 | .It Ic unset Oo Fl fv Oc Ar name ... |
| 2468 | The specified variables or functions are unset and unexported. |
| 2469 | If the |
| 2470 | .Fl v |
| 2471 | option is specified or no options are given, the |
| 2472 | .Ar name |
| 2473 | arguments are treated as variable names. |
| 2474 | If the |
| 2475 | .Fl f |
| 2476 | option is specified, the |
| 2477 | .Ar name |
| 2478 | arguments are treated as function names. |
| 2479 | .It Ic wait Op Ar job |
| 2480 | Wait for the specified |
| 2481 | .Ar job |
| 2482 | to complete and return the exit status of the last process in the |
| 2483 | .Ar job . |
| 2484 | If the argument is omitted, wait for all jobs to complete |
| 2485 | and return an exit status of zero. |
| 2486 | .El |
| 2487 | .Ss Commandline Editing |
| 2488 | When |
| 2489 | .Nm |
| 2490 | is being used interactively from a terminal, the current command |
| 2491 | and the command history |
| 2492 | (see |
| 2493 | .Ic fc |
| 2494 | in |
| 2495 | .Sx Built-in Commands ) |
| 2496 | can be edited using |
| 2497 | .Nm vi Ns -mode |
| 2498 | command line editing. |
| 2499 | This mode uses commands similar |
| 2500 | to a subset of those described in the |
| 2501 | .Xr vi 1 |
| 2502 | man page. |
| 2503 | The command |
| 2504 | .Dq Li "set -o vi" |
| 2505 | (or |
| 2506 | .Dq Li "set -V" ) |
| 2507 | enables |
| 2508 | .Nm vi Ns -mode |
| 2509 | editing and places |
| 2510 | .Nm |
| 2511 | into |
| 2512 | .Nm vi |
| 2513 | insert mode. |
| 2514 | With |
| 2515 | .Nm vi Ns -mode |
| 2516 | enabled, |
| 2517 | .Nm |
| 2518 | can be switched between insert mode and command mode by typing |
| 2519 | .Aq ESC . |
| 2520 | Hitting |
| 2521 | .Aq return |
| 2522 | while in command mode will pass the line to the shell. |
| 2523 | .Pp |
| 2524 | Similarly, the |
| 2525 | .Dq Li "set -o emacs" |
| 2526 | (or |
| 2527 | .Dq Li "set -E" ) |
| 2528 | command can be used to enable a subset of |
| 2529 | .Nm emacs Ns -style |
| 2530 | command line editing features. |
| 2531 | .Sh ENVIRONMENT |
| 2532 | The following environment variables affect the execution of |
| 2533 | .Nm : |
| 2534 | .Bl -tag -width ".Ev LANGXXXXXX" |
| 2535 | .It Ev ENV |
| 2536 | Initialization file for interactive shells. |
| 2537 | .It Ev LANG , Ev LC_* |
| 2538 | Locale settings. |
| 2539 | These are inherited by children of the shell, |
| 2540 | and is used in a limited manner by the shell itself. |
| 2541 | .It Ev PWD |
| 2542 | An absolute pathname for the current directory, |
| 2543 | possibly containing symbolic links. |
| 2544 | This is used and updated by the shell. |
| 2545 | .It Ev TERM |
| 2546 | The default terminal setting for the shell. |
| 2547 | This is inherited by children of the shell, and is used in the history |
| 2548 | editing modes. |
| 2549 | .El |
| 2550 | .Pp |
| 2551 | Additionally, all environment variables are turned into shell variables |
| 2552 | at startup, |
| 2553 | which may affect the shell as described under |
| 2554 | .Sx Special Variables . |
| 2555 | .Sh EXIT STATUS |
| 2556 | Errors that are detected by the shell, such as a syntax error, will |
| 2557 | cause the shell to exit with a non-zero exit status. |
| 2558 | If the shell is not an interactive shell, the execution of the shell |
| 2559 | file will be aborted. |
| 2560 | Otherwise the shell will return the exit status of the last command |
| 2561 | executed, or if the |
| 2562 | .Ic exit |
| 2563 | builtin is used with a numeric argument, it |
| 2564 | will return the argument. |
| 2565 | .Sh SEE ALSO |
| 2566 | .Xr builtin 1 , |
| 2567 | .Xr chsh 1 , |
| 2568 | .Xr echo 1 , |
| 2569 | .Xr ed 1 , |
| 2570 | .Xr emacs 1 Pq Pa pkgsrc/editors/emacs , |
| 2571 | .Xr kill 1 , |
| 2572 | .Xr printf 1 , |
| 2573 | .Xr pwd 1 , |
| 2574 | .Xr test 1 , |
| 2575 | .Xr vi 1 , |
| 2576 | .Xr execve 2 , |
| 2577 | .Xr getrlimit 2 , |
| 2578 | .Xr umask 2 , |
| 2579 | .Xr editrc 5 , |
| 2580 | .Xr script 7 |
| 2581 | .Sh HISTORY |
| 2582 | A |
| 2583 | .Nm |
| 2584 | command, the Thompson shell, appeared in |
| 2585 | .At v1 . |
| 2586 | It was superseded in |
| 2587 | .At v7 |
| 2588 | by the Bourne shell, which inherited the name |
| 2589 | .Nm . |
| 2590 | .Pp |
| 2591 | This version of |
| 2592 | .Nm |
| 2593 | was rewritten in 1989 under the |
| 2594 | .Bx |
| 2595 | license after the Bourne shell from |
| 2596 | .At V.4 . |
| 2597 | .Sh AUTHORS |
| 2598 | This version of |
| 2599 | .Nm |
| 2600 | was originally written by |
| 2601 | .An Kenneth Almquist . |
| 2602 | .Sh BUGS |
| 2603 | The |
| 2604 | .Nm |
| 2605 | utility does not recognize multibyte characters. |
| 2606 | .Pp |
| 2607 | The characters generated by filename completion should probably be quoted |
| 2608 | to ensure that the filename is still valid after the input line has been |
| 2609 | processed. |