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