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