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