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