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.2 2003/06/17 04:22:50 dillon 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.Aq Pa 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 !\& 1235the first character of the character class. 1236.Pp 1237To include a 1238.Dq Li \&] 1239in a character class, make it the first character listed 1240(after the 1241.Dq Li \&! , 1242if any). 1243To include a 1244.Dq Li - , 1245make it the first or last character listed. 1246.Ss Built-in Commands 1247This section lists the commands which 1248are built-in because they need to perform some operation 1249that cannot be performed by a separate process. In addition to 1250these, built-in versions of the 1251.Xr printf 1 1252and 1253.Xr test 1 1254commands are provided for efficiency. 1255.Bl -tag -width indent 1256.It Ic \&: 1257A null command that returns a 0 (true) exit value. 1258.It Ic \&. Ar file 1259The commands in the specified file are read and executed by the shell. 1260If 1261.Ar file 1262contains any 1263.Dq / 1264characters, it is used as is. Otherwise, the shell searches the 1265.Ev PATH 1266for the file. If it is not found in the 1267.Ev PATH , 1268it is sought in the current working directory. 1269.It Ic alias Op Ar name ... 1270.It Ic alias Op Ar name Ns = Ns Ar string ... 1271If 1272.Ar name Ns = Ns Ar string 1273is specified, the shell defines the alias 1274.Ar name 1275with value 1276.Ar string . 1277If just 1278.Ar name 1279is specified, the value of the alias 1280.Ar name 1281is printed. 1282With no arguments, the 1283.Ic alias 1284built-in command prints the names and values of all defined aliases 1285(see 1286.Ic unalias ) . 1287Alias values are written with appropriate quoting so that they are 1288suitable for re-input to the shell. 1289.It Ic bg Op Ar job ... 1290Continue the specified jobs 1291(or the current job if no jobs are given) 1292in the background. 1293.It Ic builtin Ar cmd Op Ar arg ... 1294Execute the specified built-in command, 1295.Ar cmd . 1296This is useful when the user wishes to override a shell function 1297with the same name as a built-in command. 1298.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc 1299List or alter key bindings for the line editor. 1300This command is documented in 1301.Xr editrc 5 . 1302.It Ic cd Oo Fl LP Oc Op Ar directory 1303Switch to the specified 1304.Ar directory , 1305or to the directory specified in the 1306.Ev HOME 1307environment variable if no 1308.Ar directory 1309is specified. 1310If 1311.Ar directory 1312does not begin with 1313.Pa / , \&. , 1314or 1315.Pa .. , 1316then the directories listed in the 1317.Ev CDPATH 1318variable will be 1319searched for the specified 1320.Ar directory . 1321If 1322.Ev CDPATH 1323is unset, the current directory is searched. 1324The format of 1325.Ar CDPATH 1326is the same as that of 1327.Ev PATH . 1328In an interactive shell, 1329the 1330.Ic cd 1331command will print out the name of the directory 1332that it actually switched to 1333if this is different from the name that the user gave. 1334These may be different either because the 1335.Ev CDPATH 1336mechanism was used or because a symbolic link was crossed. 1337.Pp 1338If the 1339.Fl P 1340option is specified, 1341.Pa .. 1342is handled physically and symbolic links are resolved before 1343.Pa .. 1344components are processed. 1345If the 1346.Fl L 1347option is specified, 1348.Pa .. 1349is handled logically. 1350This is the default. 1351.It Ic chdir 1352A synonym for the 1353.Ic cd 1354built-in command. 1355.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... 1356Execute the specified 1357.Ar utility 1358as a simple command (see the 1359.Sx Simple Commands 1360section). 1361.Pp 1362If the 1363.Fl p 1364option is specified, the command search is performed using a 1365default value of 1366.Ev PATH 1367that is guaranteed to find all of the standard utilities. 1368.It Ic echo Oo Fl e | n Oc Op Ar string 1369Print 1370.Ar string 1371to the standard output with a newline appended. 1372.Bl -tag -width indent 1373.It Fl n 1374Suppress the output of the trailing newline. 1375.It Fl e 1376Process C-style backslash escape sequences. 1377.Ic echo 1378understands the following character escapes: 1379.Bl -tag -width indent 1380.It \ea 1381Alert (ring the terminal bell) 1382.It \eb 1383Backspace 1384.It \ec 1385Suppress the trailing newline (this has the side-effect of truncating the 1386line if it is not the last character) 1387.It \ee 1388The ESC character (ASCII 0x1b) 1389.It \ef 1390Formfeed 1391.It \en 1392Newline 1393.It \er 1394Carriage return 1395.It \et 1396Horizontal tab 1397.It \ev 1398Vertical tab 1399.It \e\e 1400Literal backslash 1401.It \e0nnn 1402(Zero) The character whose octal value is nnn 1403.El 1404.Pp 1405If 1406.Ar string 1407is not enclosed in quotes then the backslash itself must be escaped 1408with a backslash to protect it from the shell. For example 1409.Bd -literal -offset indent 1410$ echo -e "a\evb" 1411a 1412 b 1413$ echo -e a\e\evb 1414a 1415 b 1416$ echo -e "a\e\eb" 1417a\eb 1418$ echo -e a\e\e\e\eb 1419a\eb 1420.Ed 1421.El 1422.Pp 1423Only one of the 1424.Fl e 1425and 1426.Fl n 1427options may be specified. 1428.It Ic eval Ar string ... 1429Concatenate all the arguments with spaces. 1430Then re-parse and execute the command. 1431.It Ic exec Op Ar command Op arg ... 1432Unless 1433.Ar command 1434is omitted, 1435the shell process is replaced with the specified program 1436(which must be a real program, not a shell built-in command or function). 1437Any redirections on the 1438.Ic exec 1439command are marked as permanent, 1440so that they are not undone when the 1441.Ic exec 1442command finishes. 1443.It Ic exit Op Ar exitstatus 1444Terminate the shell process. 1445If 1446.Ar exitstatus 1447is given 1448it is used as the exit status of the shell; 1449otherwise the exit status of the preceding command is used. 1450.It Ic export Oo Fl p Oc Op Ar name ... 1451The specified names are exported so that they will 1452appear in the environment of subsequent commands. 1453The only way to un-export a variable is to 1454.Ic unset 1455it. 1456The shell allows the value of a variable to be set 1457at the same time as it is exported by writing 1458.Bd -literal -offset indent 1459export name=value 1460.Ed 1461.Pp 1462With no arguments the export command lists the names 1463of all exported variables. 1464If the 1465.Fl p 1466option is specified, the exported variables are printed as 1467.Dq Ic export Ar name Ns = Ns Ar value 1468lines, suitable for re-input to the shell. 1469.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last 1470.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last 1471.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first 1472The 1473.Ic fc 1474built-in command lists, or edits and re-executes, 1475commands previously entered to an interactive shell. 1476.Bl -tag -width indent 1477.It Fl e Ar editor 1478Use the editor named by 1479.Ar editor 1480to edit the commands. 1481The editor string is a command name, 1482subject to search via the 1483.Ev PATH 1484variable. 1485The value in the 1486.Ev FCEDIT 1487variable is used as a default when 1488.Fl e 1489is not specified. 1490If 1491.Ev FCEDIT 1492is null or unset, the value of the 1493.Ev EDITOR 1494variable is used. 1495If 1496.Ev EDITOR 1497is null or unset, 1498.Xr ed 1 1499is used as the editor. 1500.It Fl l No (ell) 1501List the commands rather than invoking 1502an editor on them. The commands are written in the 1503sequence indicated by the first and last operands, as 1504affected by 1505.Fl r , 1506with each command preceded by the command number. 1507.It Fl n 1508Suppress command numbers when listing with 1509.Fl l . 1510.It Fl r 1511Reverse the order of the commands listed 1512(with 1513.Fl l ) 1514or edited 1515(with neither 1516.Fl l 1517nor 1518.Fl s ) . 1519.It Fl s 1520Re-execute the command without invoking an editor. 1521.It Ar first 1522.It Ar last 1523Select the commands to list or edit. 1524The number of previous commands that can be accessed 1525are determined by the value of the 1526.Ev HISTSIZE 1527variable. 1528The value of 1529.Ar first 1530or 1531.Ar last 1532or both are one of the following: 1533.Bl -tag -width indent 1534.It Ar [+]num 1535A positive number representing a command number; 1536command numbers can be displayed with the 1537.Fl l 1538option. 1539.It Ar -num 1540A negative decimal number representing the 1541command that was executed 1542.Ar num 1543of 1544commands previously. 1545For example, -1 is the immediately previous command. 1546.It Ar string 1547A string indicating the most recently entered command 1548that begins with that string. 1549If the 1550.Ar old=new 1551operand is not also specified with 1552.Fl s , 1553the string form of the first operand cannot contain an embedded equal sign. 1554.El 1555.El 1556.Pp 1557The following environment variables affect the execution of 1558.Ic fc : 1559.Bl -tag -width indent 1560.It Ev FCEDIT 1561Name of the editor to use. 1562.It Ev HISTSIZE 1563The number of previous commands that are accessible. 1564.El 1565.It Ic fg Op Ar job 1566Move the specified 1567.Ar job 1568or the current job to the foreground. 1569.It Ic getopts Ar optstring Ar var 1570The POSIX 1571.Ic getopts 1572command. 1573The 1574.Ic getopts 1575command deprecates the older 1576.Xr getopt 1 1577command. 1578The first argument should be a series of letters, each possibly 1579followed by a colon which indicates that the option takes an argument. 1580The specified variable is set to the parsed option. The index of 1581the next argument is placed into the shell variable 1582.Ev OPTIND . 1583If an option takes an argument, it is placed into the shell variable 1584.Ev OPTARG . 1585If an invalid option is encountered, 1586.Ev var 1587is set to 1588.Dq Li \&? . 1589It returns a false value (1) when it encounters the end of the options. 1590.It Ic hash Oo Fl rv Oc Op Ar command ... 1591The shell maintains a hash table which remembers the locations of commands. 1592With no arguments whatsoever, the 1593.Ic hash 1594command prints out the contents of this table. 1595Entries which have not been looked at since the last 1596.Ic cd 1597command are marked with an asterisk; 1598it is possible for these entries to be invalid. 1599.Pp 1600With arguments, the 1601.Ic hash 1602command removes each specified 1603.Ar command 1604from the hash table (unless they are functions) and then locates it. 1605With the 1606.Fl v 1607option, 1608.Ic hash 1609prints the locations of the commands as it finds them. 1610The 1611.Fl r 1612option causes the 1613.Ic hash 1614command to delete all the entries in the hash table except for functions. 1615.It Ic jobid Op Ar job 1616Print the process id's of the processes in the specified 1617.Ar job . 1618If the 1619.Ar job 1620argument is omitted, use the current job. 1621.It Ic jobs Oo Fl ls Oc Op Ar job ... 1622Print information about the specified jobs, or all jobs if no 1623.Ar job 1624argument is given. 1625The information printed includes job ID, status and command name. 1626.Pp 1627If the 1628.Fl l 1629option is specified, the PID of each job is also printed. 1630If the 1631.Fl s 1632option is specified, only the PIDs of the jobs are printed, one per line. 1633.It Ic pwd Op Fl LP 1634Print the path of the current directory. The built-in command may 1635differ from the program of the same name because the 1636built-in command remembers what the current directory 1637is rather than recomputing it each time. This makes 1638it faster. However, if the current directory is 1639renamed, 1640the built-in version of 1641.Xr pwd 1 1642will continue to print the old name for the directory. 1643.Pp 1644If the 1645.Fl P 1646option is specified, symbolic links are resolved. 1647If the 1648.Fl L 1649option is specified, the shell's notion of the current directory 1650is printed (symbolic links are not resolved). 1651This is the default. 1652.It Ic read Oo Fl p Ar prompt Oc Oo Fl t Ar timeout Oc Oo Fl er Oc Ar variable ... 1653The 1654.Ar prompt 1655is printed if the 1656.Fl p 1657option is specified 1658and the standard input is a terminal. Then a line is 1659read from the standard input. The trailing newline 1660is deleted from the line and the line is split as 1661described in the section on 1662.Sx White Space Splitting (Field Splitting) 1663above, and 1664the pieces are assigned to the variables in order. 1665If there are more pieces than variables, the remaining 1666pieces (along with the characters in 1667.Ev IFS 1668that separated them) 1669are assigned to the last variable. 1670If there are more variables than pieces, the remaining 1671variables are assigned the null string. 1672.Pp 1673Backslashes are treated specially, unless the 1674.Fl r 1675option is 1676specified. If a backslash is followed by 1677a newline, the backslash and the newline will be 1678deleted. If a backslash is followed by any other 1679character, the backslash will be deleted and the following 1680character will be treated as though it were not in 1681.Ev IFS , 1682even if it is. 1683.Pp 1684If the 1685.Fl t 1686option is specified and the 1687.Ar timeout 1688elapses before any input is supplied, 1689the 1690.Ic read 1691command will return without assigning any values. 1692The 1693.Ar timeout 1694value may optionally be followed by one of 1695.Dq s , 1696.Dq m 1697or 1698.Dq h 1699to explicitly specify seconds, minutes or hours. 1700If none is supplied, 1701.Dq s 1702is assumed. 1703.Pp 1704The 1705.Fl e 1706option exists only for backward compatibility with older scripts. 1707.It Ic readonly Oo Fl p Oc Op Ar name ... 1708Each specified 1709.Ar name 1710is marked as read only, 1711so that it cannot be subsequently modified or unset. 1712The shell allows the value of a variable to be set 1713at the same time as it is marked read only 1714by using the following form: 1715.Bd -literal -offset indent 1716readonly name=value 1717.Ed 1718.Pp 1719With no arguments the 1720.Ic readonly 1721command lists the names of all read only variables. 1722If the 1723.Fl p 1724option is specified, the read-only variables are printed as 1725.Dq Ic readonly Ar name Ns = Ns Ar value 1726lines, suitable for re-input to the shell. 1727.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo 1728.Fl c Ar string Oc Op Fl - Ar arg ... 1729The 1730.Ic set 1731command performs three different functions: 1732.Bl -item 1733.It 1734With no arguments, it lists the values of all shell variables. 1735.It 1736If options are given, 1737either in short form or using the long 1738.Dq Fl /+o Ar longname 1739form, 1740it sets or clears the specified options as described in the section called 1741.Sx Argument List Processing . 1742.It 1743If the 1744.Dq Fl - 1745option is specified, 1746.Ic set 1747will replace the shell's positional parameters with the subsequent 1748arguments. 1749If no arguments follow the 1750.Dq Fl - 1751option, 1752all the positional parameters will be cleared, 1753which is equivalent to executing the command 1754.Dq Li shift $# . 1755The 1756.Dq Fl - 1757flag may be omitted when specifying arguments to be used 1758as positional replacement parameters. 1759This is not recommended, 1760because the first argument may begin with a dash 1761.Pq Li - 1762or a plus 1763.Pq Li + , 1764which the 1765.Ic set 1766command will interpret as a request to enable or disable options. 1767.El 1768.It Ic setvar Ar variable Ar value 1769Assigns the specified 1770.Ar value 1771to the specified 1772.Ar variable . 1773.Ic Setvar 1774is intended to be used in functions that 1775assign values to variables whose names are passed as parameters. 1776In general it is better to write 1777.Bd -literal -offset indent 1778variable=value 1779.Ed 1780rather than using 1781.Ic setvar . 1782.It Ic shift Op Ar n 1783Shift the positional parameters 1784.Ar n 1785times, or once if 1786.Ar n 1787is not specified. 1788A shift sets the value of $1 to the value of $2, 1789the value of $2 to the value of $3, and so on, 1790decreasing the value of $# by one. 1791If there are zero positional parameters, shifting does not do anything. 1792.It Ic trap Oo Ar action Oc Ar signal ... 1793Cause the shell to parse and execute 1794.Ar action 1795when any specified 1796.Ar signal 1797is received. 1798The signals are specified by name or number. 1799In addition, the pseudo-signal 1800.Cm EXIT 1801may be used to specify an action that is performed when the shell terminates. 1802The 1803.Ar action 1804may be null or omitted; 1805the former causes the specified signal to be ignored 1806and the latter causes the default action to be taken. 1807When the shell forks off a subshell, 1808it resets trapped (but not ignored) signals to the default action. 1809The 1810.Ic trap 1811command has no effect on signals that were ignored on entry to the shell. 1812.It Ic type Op Ar name ... 1813Interpret each 1814.Ar name 1815as a command and print the resolution of the command search. 1816Possible resolutions are: 1817shell keyword, alias, shell built-in command, command, tracked alias 1818and not found. 1819For aliases the alias expansion is printed; 1820for commands and tracked aliases 1821the complete pathname of the command is printed. 1822.It Ic ulimit Oo Fl HSabcdflmnstuv Oc Op Ar limit 1823Set or display resource limits (see 1824.Xr getrlimit 2 ) . 1825If 1826.Ar limit 1827is specified, the named resource will be set; 1828otherwise the current resource value will be displayed. 1829.Pp 1830If 1831.Fl H 1832is specified, the hard limits will be set or displayed. 1833While everybody is allowed to reduce a hard limit, 1834only the superuser can increase it. 1835The 1836.Fl S 1837option 1838specifies the soft limits instead. When displaying limits, 1839only one of 1840.Fl S 1841or 1842.Fl H 1843can be given. 1844The default is to display the soft limits, 1845and to set both the hard and the soft limits. 1846.Pp 1847Option 1848.Fl a 1849causes the 1850.Ic ulimit 1851command to display all resources. 1852The parameter 1853.Ar limit 1854is not acceptable in this mode. 1855.Pp 1856The remaining options specify which resource value is to be 1857displayed or modified. 1858They are mutually exclusive. 1859.Bl -tag -width indent 1860.It Fl b Ar sbsize 1861The maximum size of socket buffer usage, in bytes. 1862.It Fl c Ar coredumpsize 1863The maximal size of core dump files, in 512-byte blocks. 1864.It Fl d Ar datasize 1865The maximal size of the data segment of a process, in kilobytes. 1866.It Fl f Ar filesize 1867The maximal size of a file, in 512-byte blocks. 1868.It Fl l Ar lockedmem 1869The maximal size of memory that can be locked by a process, in 1870kilobytes. 1871.It Fl m Ar memoryuse 1872The maximal resident set size of a process, in kilobytes. 1873.It Fl n Ar nofiles 1874The maximal number of descriptors that could be opened by a process. 1875.It Fl s Ar stacksize 1876The maximal size of the stack segment, in kilobytes. 1877.It Fl t Ar time 1878The maximal amount of CPU time to be used by each process, in seconds. 1879.It Fl u Ar userproc 1880The maximal number of simultaneous processes for this user ID. 1881.It Fl v Ar virtualmem 1882The maximal virtual size of a process, in kilobytes. 1883.El 1884.It Ic umask Op Ar mask 1885Set the file creation mask (see 1886.Xr umask 2 ) 1887to the octal value specified by 1888.Ar mask . 1889If the argument is omitted, the current mask value is printed. 1890.It Ic unalias Oo Fl a Oc Op Ar name 1891If 1892.Ar name 1893is specified, the shell removes that alias. 1894If 1895.Fl a 1896is specified, all aliases are removed. 1897.It Ic unset Oo Fl fv Oc Ar name ... 1898The specified variables or functions are unset and unexported. 1899If the 1900.Fl v 1901option is specified or no options are given, the 1902.Ar name 1903arguments are treated as variable names. 1904If the 1905.Fl f 1906option is specified, the 1907.Ar name 1908arguments are treated as function names. 1909.It Ic wait Op Ar job 1910Wait for the specified 1911.Ar job 1912to complete and return the exit status of the last process in the 1913.Ar job . 1914If the argument is omitted, wait for all jobs to complete 1915and return an exit status of zero. 1916.El 1917.Ss Commandline Editing 1918When 1919.Nm 1920is being used interactively from a terminal, the current command 1921and the command history 1922(see 1923.Ic fc 1924in 1925.Sx Built-in Commands ) 1926can be edited using vi-mode command line editing. 1927This mode uses commands similar 1928to a subset of those described in the vi man page. 1929The command 1930.Dq Li set -o vi 1931(or 1932.Dq Li set -V ) 1933enables vi-mode editing and places 1934.Nm 1935into vi insert mode. With vi-mode enabled, 1936.Nm 1937can be switched between insert mode and command mode by typing 1938.Aq ESC . 1939Hitting 1940.Aq return 1941while in command mode will pass the line to the shell. 1942.Pp 1943Similarly, the 1944.Dq Li set -o emacs 1945(or 1946.Dq Li set -E ) 1947command can be used to enable a subset of 1948emacs-style command line editing features. 1949.Sh SEE ALSO 1950.Xr builtin 1 , 1951.Xr echo 1 , 1952.Xr expr 1 , 1953.Xr printf 1 , 1954.Xr pwd 1 , 1955.Xr test 1 1956.Sh HISTORY 1957A 1958.Nm 1959command appeared in 1960.At v1 . 1961