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