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