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