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