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