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