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