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