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