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