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 BSD 4 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.Pq UNIMPLEMENTED 195.It Fl C Li noclobber 196Do not overwrite existing files with 197.Dq Li > . 198.Pq UNIMPLEMENTED 199.It Fl E Li emacs 200Enable the builtin 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 privileged 230Turn on privileged mode. This mode is enabled on startup 231if either the effective user or group id is not equal to the 232real user or group id. Turning this mode off sets the 233effective user and group ids to the real user and group ids. 234When this mode is enabled for interactive shells, the file 235.Pa /etc/suid_profile 236is sourced instead of 237.Pa ~/.profile 238after 239.Pa /etc/profile 240is sourced, and the contents of the 241.Ev ENV 242variable are ignored. 243.It Fl s Li stdin 244Read commands from standard input (set automatically 245if no file arguments are present). This option has 246no effect when set after the shell has already started 247running (i.e. when set with the 248.Ic set 249command). 250.It Fl T Li asynctraps 251When waiting for a child, execute traps immediately. 252If this option is not set, 253traps are executed after the child exits, 254as specified in 255.St -p1003.2 256This nonstandard option is useful for putting guarding shells around 257children that block signals. The surrounding shell may kill the child 258or it may just return control to the tty and leave the child alone, 259like this: 260.Bd -literal -offset indent 261sh -T -c "trap 'exit 1' 2 ; some-blocking-program" 262.Ed 263.Pp 264.It Fl u Li nounset 265Write a message to standard error when attempting 266to expand a variable that is not set, and if the 267shell is not interactive, exit immediately. 268.Pq UNIMPLEMENTED 269.It Fl V Li vi 270Enable the builtin 271.Xr vi 1 272command line editor (disables 273.Fl E 274if it has been set). 275.It Fl v Li verbose 276The shell writes its input to standard error 277as it is read. Useful for debugging. 278.It Fl x Li xtrace 279Write each command 280(preceded by 281.Dq Li +\ ) 282to standard error before it is executed. 283Useful for debugging. 284.El 285.Pp 286The 287.Fl c 288option may be used to pass its string argument to the shell 289to be interpreted as input. 290Keep in mind that this option only accepts a single string as its 291argument, hence multi-word strings must be quoted. 292.Pp 293The 294.Fl /+o 295option takes as its only argument the long name of an option 296to be enabled or disabled. 297For example, the following two invocations of 298.Nm 299both enable the builtin 300.Xr emacs 1 301command line editor: 302.Bd -literal -offset indent 303set -E 304set -o emacs 305.Ed 306.Ss Lexical Structure 307The shell reads input in terms of lines from a file and breaks 308it up into words at whitespace (blanks and tabs), and at 309certain sequences of 310characters called 311.Dq operators , 312which are special to the shell. 313There are two types of operators: control operators and 314redirection operators (their meaning is discussed later). 315The following is a list of valid operators: 316.Bl -tag -width Ds 317.It Control operators: 318.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact 319.It Xo 320.Li & Ta Xo 321.Li && Ta Xo 322.Li ( Ta Xo 323.Li ) Ta Xo 324.Li \en 325.Xc Xc Xc Xc Xc 326.It Xo 327.Li ;; Ta Xo 328.Li ; Ta Xo 329.Li | Ta Xo 330.Li || 331.Xc Xc Xc Xc 332.El 333.It Redirection operators: 334.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact 335.It Xo 336.Li < Ta Xo 337.Li > Ta Xo 338.Li << Ta Xo 339.Li >> Ta Xo 340.Li <> 341.Xc Xc Xc Xc Xc 342.It Xo 343.Li <& Ta Xo 344.Li >& Ta Xo 345.Li <<- Ta Xo 346.Li >| 347.Xc Xc Xc Xc 348.El 349.El 350.Ss Quoting 351Quoting is used to remove the special meaning of certain characters 352or words to the shell, such as operators, whitespace, or 353keywords. There are three types of quoting: matched single quotes, 354matched double quotes, and backslash. 355.Bl -tag -width Ds 356.It Single Quotes 357Enclosing characters in single quotes preserves the literal 358meaning of all the characters (except single quotes, making 359it impossible to put single-quotes in a single-quoted string). 360.It Double Quotes 361Enclosing characters within double quotes preserves the literal 362meaning of all characters except dollarsign 363.Pq Li $ , 364backquote 365.Pq Li ` , 366and backslash 367.Po Li \e\" 368.Pc . 369The backslash inside double quotes is historically weird. 370It remains literal unless it precedes the following characters, 371which it serves to quote: 372.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact 373.It Xo 374.Li $ Ta Xo 375.Li ` Ta Xo 376.Li \&" Ta Xo 377.Li \e\ Ta Xo 378.Li \en 379.Xc Xc Xc Xc Xc 380.El 381.It Backslash 382A backslash preserves the literal meaning of the following 383character, with the exception of the newline character 384.Pq Li \en . 385A backslash preceding a newline is treated as a line continuation. 386.El 387.Ss Reserved Words 388Reserved words are words that have special meaning to the 389shell and are recognized at the beginning of a line and 390after a control operator. The following are reserved words: 391.Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center 392.It Xo 393.Li \&! Ta Xo 394.Li { Ta Xo 395.Li } Ta Xo 396.Ic case Ta Xo 397.Ic do 398.Xc Xc Xc Xc Xc 399.It Xo 400.Ic done Ta Xo 401.Ic elif Ta Xo 402.Ic else Ta Xo 403.Ic esac Ta Xo 404.Ic fi 405.Xc Xc Xc Xc Xc 406.It Xo 407.Ic for Ta Xo 408.Ic if Ta Xo 409.Ic then Ta Xo 410.Ic until Ta Xo 411.Ic while 412.Xc Xc Xc Xc Xc 413.El 414.Ss Aliases 415An alias is a name and corresponding value set using the 416.Ic alias 417builtin command. Whenever a reserved word may occur (see above), 418and after checking for reserved words, the shell 419checks the word to see if it matches an alias. 420If it does, it replaces it in the input stream with its value. 421For example, if there is an alias called 422.Dq Li lf 423with the value 424.Dq Li ls -F , 425then the input 426.Bd -literal -offset indent 427lf foobar 428.Ed 429.Pp 430would become 431.Bd -literal -offset indent 432ls -F foobar 433.Ed 434.Pp 435Aliases provide a convenient way for naive users to 436create shorthands for commands without having to learn how 437to create functions with arguments. They can also be 438used to create lexically obscure code. This use is discouraged. 439.Ss Commands 440The shell interprets the words it reads according to a 441language, the specification of which is outside the scope 442of this man page (refer to the BNF in the 443.St -p1003.2 444document). Essentially though, a line is read and if 445the first word of the line (or after a control operator) 446is not a reserved word, then the shell has recognized a 447simple command. Otherwise, a complex command or some 448other special construct may have been recognized. 449.Ss Simple Commands 450If a simple command has been recognized, the shell performs 451the following actions: 452.Bl -enum 453.It 454Leading words of the form 455.Dq Li name=value 456are stripped off and assigned to the environment of 457the simple command. Redirection operators and 458their arguments (as described below) are stripped 459off and saved for processing. 460.It 461The remaining words are expanded as described in 462the section called 463.Sx Word Expansions , 464and the first remaining word is considered the command 465name and the command is located. The remaining 466words are considered the arguments of the command. 467If no command name resulted, then the 468.Dq Li name=value 469variable assignments recognized in 1) affect the 470current shell. 471.It 472Redirections are performed as described in 473the next section. 474.El 475.Ss Redirections 476Redirections are used to change where a command reads its input 477or sends its output. In general, redirections open, close, or 478duplicate an existing reference to a file. The overall format 479used for redirection is: 480.Pp 481.Dl [n] redir-op file 482.Pp 483The 484.Ql redir-op 485is one of the redirection operators mentioned 486previously. The following gives some examples of how these 487operators can be used. 488Note that stdin and stdout are commonly used abbreviations 489for standard input and standard output respectively. 490.Bl -tag -width "1234567890XX" -offset indent 491.It Li [n]> file 492redirect stdout (or file descriptor n) to file 493.It Li [n]>| file 494same as above, but override the 495.Fl C 496option 497.It Li [n]>> file 498append stdout (or file descriptor n) to file 499.It Li [n]< file 500redirect stdin (or file descriptor n) from file 501.It Li [n]<> file 502redirect stdin (or file descriptor n) to and from file 503.It Li [n1]<&n2 504duplicate stdin (or file descriptor n1) from file descriptor n2 505.It Li [n]<&- 506close stdin (or file descriptor n) 507.It Li [n1]>&n2 508duplicate stdout (or file descriptor n1) to file descriptor n2 509.It Li [n]>&- 510close stdout (or file descriptor n) 511.El 512.Pp 513The following redirection is often called a 514.Dq here-document . 515.Bd -literal -offset indent 516[n]<< delimiter 517 here-doc-text 518 ... 519delimiter 520.Ed 521.Pp 522All the text on successive lines up to the delimiter is 523saved away and made available to the command on standard 524input, or file descriptor n if it is specified. If the delimiter 525as specified on the initial line is quoted, then the here-doc-text 526is treated literally, otherwise the text is subjected to 527parameter expansion, command substitution, and arithmetic 528expansion (as described in the section on 529.Sx Word Expansions ) . 530If the operator is 531.Dq Li <<- 532instead of 533.Dq Li << , 534then leading tabs 535in the here-doc-text are stripped. 536.Ss Search and Execution 537There are three types of commands: shell functions, 538builtin commands, and normal programs. 539The command is searched for (by name) in that order. 540The three types of commands are all executed in a different way. 541.Pp 542When a shell function is executed, all of the shell positional 543parameters (except $0, which remains unchanged) are 544set to the arguments of the shell function. 545The variables which are explicitly placed in the environment of 546the command (by placing assignments to them before the 547function name) are made local to the function and are set 548to the values given. 549Then the command given in the function definition is executed. 550The positional parameters are restored to their original values 551when the command completes. 552This all occurs within the current shell. 553.Pp 554Shell builtin commands are executed internally to the shell, without 555spawning a new process. 556.Pp 557Otherwise, if the command name does not match a function 558or builtin command, the command is searched for as a normal 559program in the filesystem (as described in the next section). 560When a normal program is executed, the shell runs the program, 561passing the arguments and the environment to the program. 562If the program is not a normal executable file 563(i.e. if it does not begin with the 564.Qq magic number 565whose 566.Tn ASCII 567representation is 568.Qq #! , 569resulting in an 570.Er ENOEXEC 571return value from 572.Xr execve 2 ) 573the shell will interpret the program in a subshell. 574The child shell will reinitialize itself in this case, 575so that the effect will be 576as if a new shell had been invoked to handle the ad-hoc shell script, 577except that the location of hashed commands located in 578the parent shell will be remembered by the child. 579.Pp 580Note that previous versions of this document 581and the source code itself misleadingly and sporadically 582refer to a shell script without a magic number 583as a 584.Qq shell procedure . 585.Ss Path Search 586When locating a command, the shell first looks to see if 587it has a shell function by that name. Then it looks for a 588builtin command by that name. If a builtin command is not found, 589one of two things happen: 590.Bl -enum 591.It 592Command names containing a slash are simply executed without 593performing any searches. 594.It 595The shell searches each entry in 596.Ev PATH 597in turn for the command. The value of the 598.Ev PATH 599variable should be a series of 600entries separated by colons. Each entry consists of a 601directory name. 602The current directory 603may be indicated implicitly by an empty directory name, 604or explicitly by a single period. 605.El 606.Ss Command Exit Status 607Each command has an exit status that can influence the behavior 608of other shell commands. The paradigm is that a command exits 609with zero for normal or success, and non-zero for failure, 610error, or a false indication. The man page for each command 611should indicate the various exit codes and what they mean. 612Additionally, the builtin commands return exit codes, as does 613an executed shell function. 614.Pp 615If a command is terminated by a signal, its exit status is 128 plus 616the signal number. Signal numbers are defined in the header file 617.Aq Pa sys/signal.h . 618.Ss Complex Commands 619Complex commands are combinations of simple commands 620with control operators or reserved words, together creating a larger complex 621command. More generally, a command is one of the following: 622.Bl -item -offset indent 623.It 624simple command 625.It 626pipeline 627.It 628list or compound-list 629.It 630compound command 631.It 632function definition 633.El 634.Pp 635Unless otherwise stated, the exit status of a command is 636that of the last simple command executed by the command. 637.Ss Pipelines 638A pipeline is a sequence of one or more commands separated 639by the control operator |. The standard output of all but 640the last command is connected to the standard input 641of the next command. The standard output of the last 642command is inherited from the shell, as usual. 643.Pp 644The format for a pipeline is: 645.Pp 646.Dl [!] command1 [ | command2 ...] 647.Pp 648The standard output of command1 is connected to the standard 649input of command2. The standard input, standard output, or 650both of a command is considered to be assigned by the 651pipeline before any redirection specified by redirection 652operators that are part of the command. 653.Pp 654If the pipeline is not in the background (discussed later), 655the shell waits for all commands to complete. 656.Pp 657If the reserved word ! does not precede the pipeline, the 658exit status is the exit status of the last command specified 659in the pipeline. Otherwise, the exit status is the logical 660NOT of the exit status of the last command. That is, if 661the last command returns zero, the exit status is 1; if 662the last command returns greater than zero, the exit status 663is zero. 664.Pp 665Because pipeline assignment of standard input or standard 666output or both takes place before redirection, it can be 667modified by redirection. For example: 668.Pp 669.Dl $ command1 2>&1 | command2 670.Pp 671sends both the standard output and standard error of 672.Ql command1 673to the standard input of 674.Ql command2 . 675.Pp 676A 677.Dq Li \&; 678or newline terminator causes the preceding 679AND-OR-list 680(described below in the section called 681.Sx Short-Circuit List Operators ) 682to be executed sequentially; 683an 684.Dq Li & 685causes asynchronous execution of the preceding AND-OR-list. 686.Pp 687Note that unlike some other shells, 688.Nm 689executes each process in the pipeline as a child of the 690.Nm 691process. 692Shell builtin commands are the exception to this rule. 693They are executed in the current shell, although they do not affect its 694environment when used in pipelines. 695.Ss Background Commands (&) 696If a command is terminated by the control operator ampersand 697.Pq Li & , 698the shell executes the command asynchronously; 699the shell does not wait for the command to finish 700before executing the next command. 701.Pp 702The format for running a command in background is: 703.Bd -literal -offset indent 704command1 & [command2 & ...] 705.Ed 706.Pp 707If the shell is not interactive, the standard input of an 708asynchronous command is set to /dev/null. 709.Ss Lists (Generally Speaking) 710A list is a sequence of zero or more commands separated by 711newlines, semicolons, or ampersands, 712and optionally terminated by one of these three characters. 713The commands in a 714list are executed in the order they are written. 715If command is followed by an ampersand, the shell starts the 716command and immediately proceed onto the next command; 717otherwise it waits for the command to terminate before 718proceeding to the next one. 719.Ss Short-Circuit List Operators 720.Dq Li && 721and 722.Dq Li || 723are AND-OR list operators. 724.Dq Li && 725executes the first command, and then executes the second command 726if the exit status of the first command is zero. 727.Dq Li || 728is similar, but executes the second command if the exit 729status of the first command is nonzero. 730.Dq Li && 731and 732.Dq Li || 733both have the same priority. 734.Ss Flow-Control Constructs (if, while, for, case) 735The syntax of the 736.Ic if 737command is: 738.\" 739.\" XXX Use .Dl to work around broken handling of .Ic inside .Bd and .Ed . 740.\" 741.Dl Ic if Ar list 742.Dl Ic then Ar list 743.Dl [ Ic elif Ar list 744.Dl Ic then Ar list ] ... 745.Dl [ Ic else Ar list ] 746.Dl Ic fi 747.Pp 748The syntax of the 749.Ic while 750command is: 751.Dl Ic while Ar list 752.Dl Ic do Ar list 753.Dl Ic done 754.Pp 755The two lists are executed repeatedly while the exit status of the 756first list is zero. 757The 758.Ic until 759command is similar, but has the word 760.Ic until 761in place of 762.Ic while , 763which causes it to 764repeat until the exit status of the first list is zero. 765.Pp 766The syntax of the 767.Ic for 768command is: 769.Dl Ic for Ar variable Ic in Ar word ... 770.Dl Ic do Ar list 771.Dl Ic done 772.Pp 773The words are expanded, and then the list is executed 774repeatedly with the variable set to each word in turn. 775The 776.Ic do 777and 778.Ic done 779commands may be replaced with 780.Dq Li { 781and 782.Dq Li } . 783.Pp 784The syntax of the 785.Ic break 786and 787.Ic continue 788commands is: 789.Dl Ic break Op Ar num 790.Dl Ic continue Op Ar num 791.Pp 792The 793.Ic break 794command terminates the 795.Ar num 796innermost 797.Ic for 798or 799.Ic while 800loops. 801The 802.Ic continue 803command continues with the next iteration of the innermost loop. 804These are implemented as builtin commands. 805.Pp 806The syntax of the 807.Ic case 808command is 809.Dl Ic case Ar word Ic in 810.Dl pattern) list ;; 811.Dl ... 812.Dl Ic esac 813.Pp 814The pattern can actually be one or more patterns 815(see 816.Sx Shell Patterns 817described later), 818separated by 819.Dq Li \&| 820characters. 821.Ss Grouping Commands Together 822Commands may be grouped by writing either 823.Bd -literal -offset indent 824(list) 825.Ed 826.Pp 827or 828.Bd -literal -offset indent 829{ list; } 830.Ed 831.Pp 832The first form executes the commands in a subshell. 833Note that builtin commands thus executed do not affect the current shell. 834The second form does not fork another shell, 835so it is slightly more efficient. 836Grouping commands together this way allows the user to 837redirect their output as though they were one program: 838.Bd -literal -offset indent 839{ echo -n "hello"; echo " world"; } > greeting 840.Ed 841.Ss Functions 842The syntax of a function definition is 843.Bd -literal -offset indent 844name ( ) command 845.Ed 846.Pp 847A function definition is an executable statement; when 848executed it installs a function named name and returns an 849exit status of zero. The command is normally a list 850enclosed between 851.Dq Li { 852and 853.Dq Li } . 854.Pp 855Variables may be declared to be local to a function by 856using the 857.Ic local 858command. 859This should appear as the first statement of a function, 860and the syntax is: 861.Bd -ragged -offset indent 862.Ic local 863.Op Ar variable ...\& 864.Op Ar - 865.Ed 866.Pp 867The 868.Ic local 869command is implemented as a builtin command. 870.Pp 871When a variable is made local, it inherits the initial 872value and exported and readonly flags from the variable 873with the same name in the surrounding scope, if there is 874one. Otherwise, the variable is initially unset. The shell 875uses dynamic scoping, so that if the variable 876.Em x 877is made local to function 878.Em f , 879which then calls function 880.Em g , 881references to the variable 882.Em x 883made inside 884.Em g 885will refer to the variable 886.Em x 887declared inside 888.Em f , 889not to the global variable named 890.Em x . 891.Pp 892The only special parameter than can be made local is 893.Dq Li - . 894Making 895.Dq Li - 896local causes any shell options that are 897changed via the set command inside the function to be 898restored to their original values when the function 899returns. 900.Pp 901The syntax of the 902.Ic return 903command is 904.Bd -ragged -offset indent 905.Ic return 906.Op Ar exitstatus 907.Ed 908.Pp 909It terminates the currently executing function. 910The 911.Ic return 912command is implemented as a builtin command. 913.Ss Variables and Parameters 914The shell maintains a set of parameters. A parameter 915denoted by a name is called a variable. When starting up, 916the shell turns all the environment variables into shell 917variables. New variables can be set using the form 918.Bd -literal -offset indent 919name=value 920.Ed 921.Pp 922Variables set by the user must have a name consisting solely 923of alphabetics, numerics, and underscores. 924The first letter of a variable name must not be numeric. 925A parameter can also be denoted by a number 926or a special character as explained below. 927.Ss Positional Parameters 928A positional parameter is a parameter denoted by a number greater than zero. 929The shell sets these initially to the values of its command line 930arguments that follow the name of the shell script. The 931.Ic set 932builtin command can also be used to set or reset them. 933.Ss Special Parameters 934A special parameter is a parameter denoted by one of the following 935special characters. The value of the parameter is listed 936next to its character. 937.Bl -hang 938.It Li * 939Expands to the positional parameters, starting from one. When 940the expansion occurs within a double-quoted string 941it expands to a single field with the value of each parameter 942separated by the first character of the 943.Ev IFS 944variable, 945or by a 946.Aq space 947if 948.Ev IFS 949is unset. 950.It Li @ 951Expands to the positional parameters, starting from one. When 952the expansion occurs within double-quotes, each positional 953parameter expands as a separate argument. 954If there are no positional parameters, the 955expansion of 956.Li @ 957generates zero arguments, even when 958.Li @ 959is double-quoted. What this basically means, for example, is 960if $1 is 961.Dq abc 962and $2 is 963.Dq def ghi , 964then 965.Qq Li $@ 966expands to 967the two arguments: 968.Bd -literal -offset indent 969"abc" "def ghi" 970.Ed 971.It Li # 972Expands to the number of positional parameters. 973.It Li \&? 974Expands to the exit status of the most recent pipeline. 975.It Li - 976(hyphen) Expands to the current option flags (the single-letter 977option names concatenated into a string) as specified on 978invocation, by the set builtin command, or implicitly 979by the shell. 980.It Li $ 981Expands to the process ID of the invoked shell. A subshell 982retains the same value of $ as its parent. 983.It Li \&! 984Expands to the process ID of the most recent background 985command executed from the current shell. For a 986pipeline, the process ID is that of the last command in the 987pipeline. 988.It Li 0 989(zero) Expands to the name of the shell or shell script. 990.El 991.Ss Word Expansions 992This clause describes the various expansions that are 993performed on words. Not all expansions are performed on 994every word, as explained later. 995.Pp 996Tilde expansions, parameter expansions, command substitutions, 997arithmetic expansions, and quote removals that occur within 998a single word expand to a single field. It is only field 999splitting or pathname expansion that can create multiple 1000fields from a single word. 1001The single exception to this rule is 1002the expansion of the special parameter 1003.Li @ 1004within double-quotes, 1005as was described above. 1006.Pp 1007The order of word expansion is: 1008.Bl -enum 1009.It 1010Tilde Expansion, Parameter Expansion, Command Substitution, 1011Arithmetic Expansion (these all occur at the same time). 1012.It 1013Field Splitting is performed on fields generated by step (1) 1014unless the 1015.Ev IFS 1016variable is null. 1017.It 1018Pathname Expansion (unless the 1019.Fl f 1020option is in effect). 1021.It 1022Quote Removal. 1023.El 1024.Pp 1025The 1026.Dq Li $ 1027character is used to introduce parameter expansion, command 1028substitution, or arithmetic evaluation. 1029.Ss Tilde Expansion (substituting a user's home directory) 1030A word beginning with an unquoted tilde character 1031.Pq Li ~ 1032is 1033subjected to tilde expansion. 1034All the characters up to a slash 1035.Pq Li / 1036or the end of the word are treated as a username 1037and are replaced with the user's home directory. If the 1038username is missing (as in ~/foobar), the tilde is replaced 1039with the value of the HOME variable (the current user's 1040home directory). 1041.Ss Parameter Expansion 1042The format for parameter expansion is as follows: 1043.Bd -literal -offset indent 1044${expression} 1045.Ed 1046.Pp 1047where expression consists of all characters until the matching 1048.Dq Li } . 1049Any 1050.Dq Li } 1051escaped by a backslash or within a quoted string, and characters in 1052embedded arithmetic expansions, command substitutions, and variable 1053expansions, are not examined in determining the matching 1054.Dq Li } . 1055.Pp 1056The simplest form for parameter expansion is: 1057.Bd -literal -offset indent 1058${parameter} 1059.Ed 1060.Pp 1061The value, if any, of parameter is substituted. 1062.Pp 1063The parameter name or symbol can be enclosed in braces, which are 1064optional except for positional parameters with more than one digit or 1065when parameter is followed by a character that could be interpreted as 1066part of the name. 1067If a parameter expansion occurs inside double-quotes: 1068.Bl -enum 1069.It 1070Pathname expansion is not performed on the results of the 1071expansion. 1072.It 1073Field splitting is not performed on the results of the 1074expansion, with the exception of the special parameter 1075.Li @ . 1076.El 1077.Pp 1078In addition, a parameter expansion can be modified by using one of the 1079following formats. 1080.Bl -tag -width Ds 1081.It Li ${parameter:-word} 1082Use Default Values. If parameter is unset or 1083null, the expansion of word is 1084substituted; otherwise, the value of 1085parameter is substituted. 1086.It Li ${parameter:=word} 1087Assign Default Values. If parameter is unset 1088or null, the expansion of word is 1089assigned to parameter. In all cases, the 1090final value of parameter is 1091substituted. Only variables, not positional 1092parameters or special parameters, can be 1093assigned in this way. 1094.It Li ${parameter:?[word]} 1095Indicate Error if Null or Unset. If 1096parameter is unset or null, the expansion of 1097word (or a message indicating it is unset if 1098word is omitted) is written to standard 1099error and the shell exits with a nonzero 1100exit status. 1101Otherwise, the value of 1102parameter is substituted. An 1103interactive shell need not exit. 1104.It Li ${parameter:+word} 1105Use Alternate Value. If parameter is unset 1106or null, null is substituted; 1107otherwise, the expansion of word is 1108substituted. 1109.Pp 1110In the parameter expansions shown previously, use of the colon in the 1111format results in a test for a parameter that is unset or null; omission 1112of the colon results in a test for a parameter that is only unset. 1113.It Li ${#parameter} 1114String Length. The length in characters of 1115the value of parameter. 1116.Pp 1117The following four varieties of parameter expansion provide for substring 1118processing. 1119In each case, pattern matching notation 1120(see 1121.Sx Shell Patterns ) , 1122rather than regular expression notation, 1123is used to evaluate the patterns. 1124If parameter is one of the special parameters 1125.Li * 1126or 1127.Li @ , 1128the result of the expansion is unspecified. 1129Enclosing the full parameter expansion string in double-quotes does not 1130cause the following four varieties of pattern characters to be quoted, 1131whereas quoting characters within the braces has this effect. 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 can not be performed by a separate process. In addition to 1275these, a builtin version of the 1276.Xr printf 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 Xo 1356.Ic echo 1357.Op Fl en 1358.Ar string 1359.Xc 1360Print 1361.Ar string 1362to the standard output with a newline appended. 1363.Bl -tag -width Ds 1364.It Fl n 1365Suppress the output of the trailing newline. 1366.It Fl e 1367Process C-style backslash escape sequences. 1368.Ic echo 1369understands the following character escapes: 1370.Bl -tag -width Ds 1371.It \ea 1372Alert (ring the terminal bell) 1373.It \eb 1374Backspace 1375.It \ec 1376Suppress the trailing newline (this has the side-effect of truncating the 1377line if it is not the last character) 1378.It \ee 1379The ESC character (ASCII 0x1b) 1380.It \ef 1381Formfeed 1382.It \en 1383Newline 1384.It \er 1385Carriage return 1386.It \et 1387Horizontal tab 1388.It \ev 1389Vertical tab 1390.It \e\e 1391Literal backslash 1392.It \e0nnn 1393(Zero) The character whose octal value is nnn 1394.El 1395.Pp 1396If 1397.Ar string 1398is not enclosed in quotes then the backslash itself must be escaped 1399with a backslash to protect it from the shell. For example 1400.Bd -literal -offset indent 1401$ echo -e "a\evb" 1402a 1403 b 1404$ echo -e a\e\evb 1405a 1406 b 1407$ echo -e "a\e\eb" 1408a\eb 1409$ echo -e a\e\e\e\eb 1410a\eb 1411.Ed 1412.El 1413.It Ic eval Ar string ... 1414Concatenate all the arguments with spaces. 1415Then re-parse and execute the command. 1416.It Ic exec Op Ar command Op arg ... 1417Unless 1418.Ar command 1419is omitted, 1420the shell process is replaced with the specified program 1421(which must be a real program, not a shell builtin command or function). 1422Any redirections on the 1423.Ic exec 1424command are marked as permanent, 1425so that they are not undone when the 1426.Ic exec 1427command finishes. 1428.It Ic exit Op Ar exitstatus 1429Terminate the shell process. 1430If 1431.Ar exitstatus 1432is given 1433it is used as the exit status of the shell; 1434otherwise the exit status of the preceding command is used. 1435.It Ic export Ar name ... 1436The specified names are exported so that they will 1437appear in the environment of subsequent commands. 1438The only way to un-export a variable is to 1439.Ic unset 1440it. 1441The shell allows the value of a variable to be set 1442at the same time as it is exported by writing 1443.Bd -literal -offset indent 1444export name=value 1445.Ed 1446.Pp 1447With no arguments the export command lists the names 1448of all exported variables. 1449.It Xo 1450.Ic fc 1451.Op Fl e Ar editor 1452.Op Ar first Op Ar last 1453.Xc 1454.It Xo 1455.Ic fc 1456.Fl l 1457.Op Fl nr 1458.Op Ar first Op Ar last 1459.Xc 1460.It Xo 1461.Ic fc 1462.Fl s 1463.Op Ar old=new 1464.Op Ar first 1465.Xc 1466The 1467.Ic fc 1468builtin command lists, or edits and re-executes, 1469commands previously entered to an interactive shell. 1470.Bl -tag -width Ds 1471.It Fl e Ar editor 1472Use the editor named by 1473.Ar editor 1474to edit the commands. 1475The editor string is a command name, 1476subject to search via the 1477.Ev PATH 1478variable. 1479The value in the 1480.Ev FCEDIT 1481variable is used as a default when 1482.Fl e 1483is not specified. 1484If 1485.Ev FCEDIT 1486is null or unset, the value of the 1487.Ev EDITOR 1488variable is used. 1489If 1490.Ev EDITOR 1491is null or unset, 1492.Xr ed 1 1493is used as the editor. 1494.It Fl l No (ell) 1495List the commands rather than invoking 1496an editor on them. The commands are written in the 1497sequence indicated by the first and last operands, as 1498affected by 1499.Fl r , 1500with each command preceded by the command number. 1501.It Fl n 1502Suppress command numbers when listing with 1503.Fl l . 1504.It Fl r 1505Reverse the order of the commands listed 1506(with 1507.Fl l ) 1508or edited 1509(with neither 1510.Fl l 1511nor 1512.Fl s ) . 1513.It Fl s 1514Re-execute the command without invoking an editor. 1515.It Ar first 1516.It Ar last 1517Select the commands to list or edit. 1518The number of previous commands that can be accessed 1519are determined by the value of the 1520.Ev HISTSIZE 1521variable. 1522The value of 1523.Ar first 1524or 1525.Ar last 1526or both are one of the following: 1527.Bl -tag -width Ds 1528.It Ar [+]num 1529A positive number representing a command number; 1530command numbers can be displayed with the 1531.Fl l 1532option. 1533.It Ar -num 1534A negative decimal number representing the 1535command that was executed 1536.Ar num 1537of 1538commands previously. 1539For example, -1 is the immediately previous command. 1540.It Ar string 1541A string indicating the most recently entered command 1542that begins with that string. 1543If the 1544.Ar old=new 1545operand is not also specified with 1546.Fl s , 1547the string form of the first operand cannot contain an embedded equal sign. 1548.El 1549.El 1550.Pp 1551The following environment variables affect the execution of 1552.Ic fc : 1553.Bl -tag -width Ds 1554.It Ev FCEDIT 1555Name of the editor to use. 1556.It Ev HISTSIZE 1557The number of previous commands that are accessible. 1558.El 1559.It Ic fg Op Ar job 1560Move the specified 1561.Ar job 1562or the current job to the foreground. 1563.It Ic getopts Ar optstring Ar var 1564The POSIX 1565.Ic getopts 1566command. 1567The 1568.Ic getopts 1569command deprecates the older 1570.Xr getopt 1 1571command. 1572The first argument should be a series of letters, each possibly 1573followed by a colon which indicates that the option takes an argument. 1574The specified variable is set to the parsed option. The index of 1575the next argument is placed into the shell variable 1576.Ev OPTIND . 1577If an option takes an argument, it is placed into the shell variable 1578.Ev OPTARG . 1579If an invalid option is encountered, 1580.Ev var 1581is set to 1582.Dq Li \&? . 1583It returns a false value (1) when it encounters the end of the options. 1584.It Xo 1585.Ic hash 1586.Op Fl rv 1587.Op Ar command ... 1588.Xc 1589The shell maintains a hash table which remembers the locations of commands. 1590With no arguments whatsoever, the 1591.Ic hash 1592command prints out the contents of this table. 1593Entries which have not been looked at since the last 1594.Ic cd 1595command are marked with an asterisk; 1596it is possible for these entries to be invalid. 1597.Pp 1598With arguments, the 1599.Ic hash 1600command removes each specified 1601.Ar command 1602from the hash table (unless they are functions) and then locates it. 1603With the 1604.Fl v 1605option, 1606.Ic hash 1607prints the locations of the commands as it finds them. 1608The 1609.Fl r 1610option causes the 1611.Ic hash 1612command to delete all the entries in the hash table except for functions. 1613.It Ic jobid Op Ar job 1614Print the process id's of the processes in the specified 1615.Ar job . 1616If the 1617.Ar job 1618argument is omitted, use the current job. 1619.It Ic jobs 1620This command lists out all the background processes 1621which are children of the current shell process. 1622.It Ic pwd 1623Print the path of the current directory. The builtin command may 1624differ from the program of the same name because the 1625builtin command remembers what the current directory 1626is rather than recomputing it each time. This makes 1627it faster. However, if the current directory is 1628renamed, 1629the builtin version of 1630.Xr pwd 1 1631will continue to print the old name for the directory. 1632.It Xo 1633.Ic read 1634.Op Fl p Ar prompt 1635.Op Fl t Ar timeout 1636.Op Fl er 1637.Ar variable ... 1638.Xc 1639The 1640.Ar prompt 1641is printed if the 1642.Fl p 1643option is specified 1644and the standard input is a terminal. Then a line is 1645read from the standard input. The trailing newline 1646is deleted from the line and the line is split as 1647described in the section on 1648.Sx White Space Splitting (Field Splitting) 1649above, and 1650the pieces are assigned to the variables in order. 1651If there are more pieces than variables, the remaining 1652pieces (along with the characters in 1653.Ev IFS 1654that separated them) 1655are assigned to the last variable. 1656If there are more variables than pieces, the remaining 1657variables are assigned the null string. 1658.Pp 1659Backslashes are treated specially, unless the 1660.Fl r 1661option is 1662specified. If a backslash is followed by 1663a newline, the backslash and the newline will be 1664deleted. If a backslash is followed by any other 1665character, the backslash will be deleted and the following 1666character will be treated as though it were not in 1667.Ev IFS , 1668even if it is. 1669.Pp 1670If the 1671.Fl t 1672option is specified and the 1673.Ar timeout 1674elapses before any input is supplied, 1675the 1676.Ic read 1677command will return without assigning any values. 1678The 1679.Ar timeout 1680value may optionally be followed by one of 1681.Dq s , 1682.Dq m 1683or 1684.Dq h 1685to explicitly specify seconds, minutes or or hours. 1686If none is supplied, 1687.Dq s 1688is assumed. 1689.Pp 1690The 1691.Fl e 1692option exists only for backward compatibility with older scripts. 1693.It Ic readonly Ar name ... 1694Each specified 1695.Ar name 1696is marked as read only, 1697so that it cannot be subsequently modified or unset. 1698The shell allows the value of a variable to be set 1699at the same time as it is marked read only 1700by using the following form: 1701.Bd -literal -offset indent 1702readonly name=value 1703.Ed 1704.Pp 1705With no arguments the 1706.Ic readonly 1707command lists the names of all read only variables. 1708.It Xo 1709.Ic set 1710.Op Fl /+abCEefIimnpTuVvx 1711.Op Fl /+o Ar longname 1712.Op Fl c Ar string 1713.Op Fl - Ar arg ... 1714.Xc 1715The 1716.Ic set 1717command performs three different functions: 1718.Bl -item 1719.It 1720With no arguments, it lists the values of all shell variables. 1721.It 1722If options are given, 1723either in short form or using the long 1724.Dq Fl /+o Ar longname 1725form, 1726it sets or clears the specified options as described in the section called 1727.Sx Argument List Processing . 1728.It 1729If the 1730.Dq Fl - 1731option is specified, 1732.Ic set 1733will replace the shell's positional parameters with the subsequent 1734arguments. 1735If no arguments follow the 1736.Dq Fl - 1737option, 1738all the positional parameters will be cleared, 1739which is equivalent to executing the command 1740.Dq Li shift $# . 1741The 1742.Dq Fl - 1743flag may be ommitted when specifying arguments to be used 1744as positional replacement parameters. 1745This is not recommended, 1746because the first argument may begin with a dash 1747.Pq Li - 1748or a plus 1749.Pq Li + , 1750which the 1751.Ic set 1752command will interpret as a request to enable or disable options. 1753.El 1754.It Ic setvar Ar variable Ar value 1755Assigns the specified 1756.Ar value 1757to the specified 1758.Ar variable . 1759.Ic Setvar 1760is intended to be used in functions that 1761assign values to variables whose names are passed as parameters. 1762In general it is better to write 1763.Bd -literal -offset indent 1764variable=value 1765.Ed 1766rather than using 1767.Ic setvar . 1768.It Ic shift Op Ar n 1769Shift the positional parameters 1770.Ar n 1771times, or once if 1772.Ar n 1773is not specified. 1774A shift sets the value of $1 to the value of $2, 1775the value of $2 to the value of $3, and so on, 1776decreasing the value of $# by one. 1777If there are zero positional parameters, shifting does not do anything. 1778.It Xo 1779.Ic trap 1780.Op Ar action 1781.Ar signal ... 1782.Xc 1783Cause the shell to parse and execute 1784.Ar action 1785when any specified 1786.Ar signal 1787is received. 1788The signals are specified by signal number. 1789The 1790.Ar action 1791may be null or omitted; 1792the former causes the specified signal to be ignored 1793and the latter causes the default action to be taken. 1794When the shell forks off a subshell, 1795it resets trapped (but not ignored) signals to the default action. 1796The 1797.Ic trap 1798command has no effect on signals that were ignored on entry to the shell. 1799.It Ic type Op Ar name ... 1800Interpret each 1801.Ar name 1802as a command and print the resolution of the command search. 1803Possible resolutions are: 1804shell keyword, alias, shell builtin command, command, tracked alias 1805and not found. 1806For aliases the alias expansion is printed; 1807for commands and tracked aliases 1808the complete pathname of the command is printed. 1809.It Xo 1810.Ic ulimit 1811.Op Fl HSabcdflmnust 1812.Op Ar limit 1813.Xc 1814Set or display resource limits (see 1815.Xr getrlimit 2 ) . 1816If 1817.Ar limit 1818is specified, the named resource will be set; 1819otherwise the current resource value will be displayed. 1820.Pp 1821If 1822.Fl H 1823is specified, the hard limits will be set or displayed. 1824While everybody is allowed to reduce a hard limit, 1825only the superuser can increase it. 1826The 1827.Fl S 1828option 1829specifies the soft limits instead. When displaying limits, 1830only one of 1831.Fl S 1832or 1833.Fl H 1834can be given. 1835The default is to display the soft limits, 1836and to set both the hard and the soft limits. 1837.Pp 1838Option 1839.Fl a 1840causes the 1841.Ic ulimit 1842command to display all resources. 1843The parameter 1844.Ar limit 1845is not acceptable in this mode. 1846.Pp 1847The remaining options specify which resource value is to be 1848displayed or modified. 1849They are mutually exclusive. 1850.Bl -tag -width Ds 1851.It Fl b Ar sbsize 1852The maximum size of socket buffer usage, in bytes. 1853.It Fl c Ar coredumpsize 1854The maximal size of core dump files, in 512-byte blocks. 1855.It Fl d Ar datasize 1856The maximal size of the data segment of a process, in kilobytes. 1857.It Fl f Ar filesize 1858The maximal size of a file, in 512-byte blocks. 1859.It Fl l Ar lockedmem 1860The maximal size of memory that can be locked by a process, in 1861kilobytes. 1862.It Fl m Ar memoryuse 1863The maximal resident set size of a process, in kilobytes. 1864.It Fl n Ar nofiles 1865The maximal number of descriptors that could be opened by a process. 1866.It Fl s Ar stacksize 1867The maximal size of the stack segment, in kilobytes. 1868.It Fl t Ar time 1869The maximal amount of CPU time to be used by each process, in seconds. 1870.It Fl u Ar userproc 1871The maximal number of simultaneous processes for this user ID. 1872.El 1873.It Ic umask Op Ar mask 1874Set the file creation mask (see 1875.Xr umask 2 ) 1876to the octal value specified by 1877.Ar mask . 1878If the argument is omitted, the current mask value is printed. 1879.It Xo 1880.Ic unalias 1881.Op Fl a 1882.Op Ar name 1883.Xc 1884If 1885.Ar name 1886is specified, the shell removes that alias. 1887If 1888.Fl a 1889is specified, all aliases are removed. 1890.It Ic unset Ar name ... 1891The specified variables and functions are unset and unexported. 1892If a given 1893.Ar name 1894corresponds to both a variable and a function, 1895both the variable and the function are unset. 1896.It Ic wait Op Ar job 1897Wait for the specified 1898.Ar job 1899to complete and return the exit status of the last process in the 1900.Ar job . 1901If the argument is omitted, wait for all jobs to complete 1902and return an exit status of zero. 1903.El 1904.Ss Commandline Editing 1905When 1906.Nm 1907is being used interactively from a terminal, the current command 1908and the command history 1909(see 1910.Ic fc 1911in 1912.Sx Builtin Commands ) 1913can be edited using vi-mode command line editing. 1914This mode uses commands similar 1915to a subset of those described in the vi man page. 1916The command 1917.Dq Li set -o vi 1918(or 1919.Dq Li set -V ) 1920enables vi-mode editing and places 1921.Nm 1922into vi insert mode. With vi-mode enabled, 1923.Nm 1924can be switched between insert mode and command mode by typing 1925.Aq ESC . 1926Hitting 1927.Aq return 1928while in command mode will pass the line to the shell. 1929.Pp 1930Similarly, the 1931.Dq Li set -o emacs 1932(or 1933.Dq Li set -E ) 1934command can be used to enable a subset of 1935emacs-style command line editing features. 1936.Sh SEE ALSO 1937.Xr builtin 1 , 1938.Xr echo 1 , 1939.Xr expr 1 , 1940.Xr pwd 1 , 1941.Xr printf 1 , 1942.Xr test 1 1943.Sh HISTORY 1944A 1945.Nm 1946command appeared in 1947.At V.1 . 1948