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