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