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 October 7, 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, built-in versions of essential utilities 1365are provided for efficiency. 1366.Bl -tag -width indent 1367.It Ic \&: 1368A null command that returns a 0 (true) exit value. 1369.It Ic \&. Ar file 1370The commands in the specified file are read and executed by the shell. 1371The 1372.Ic return 1373command may be used to return to the 1374.Ic \&. 1375command's caller. 1376If 1377.Ar file 1378contains any 1379.Dq / 1380characters, it is used as is. 1381Otherwise, the shell searches the 1382.Ev PATH 1383for the file. 1384If it is not found in the 1385.Ev PATH , 1386it is sought in the current working directory. 1387.It Ic \&[ 1388A built-in equivalent of 1389.Xr test 1 . 1390.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc ... Oc 1391If 1392.Ar name Ns = Ns Ar string 1393is specified, the shell defines the alias 1394.Ar name 1395with value 1396.Ar string . 1397If just 1398.Ar name 1399is specified, the value of the alias 1400.Ar name 1401is printed. 1402With no arguments, the 1403.Ic alias 1404built-in command prints the names and values of all defined aliases 1405(see 1406.Ic unalias ) . 1407Alias values are written with appropriate quoting so that they are 1408suitable for re-input to the shell. 1409Also see the 1410.Sx Aliases 1411subsection. 1412.It Ic bg Op Ar job ... 1413Continue the specified jobs 1414(or the current job if no jobs are given) 1415in the background. 1416.It Ic builtin Ar cmd Op Ar arg ... 1417Execute the specified built-in command, 1418.Ar cmd . 1419This is useful when the user wishes to override a shell function 1420with the same name as a built-in command. 1421.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc 1422List or alter key bindings for the line editor. 1423This command is documented in 1424.Xr editrc 5 . 1425.It Ic cd Oo Fl L | P Oc Op Ar directory 1426Switch to the specified 1427.Ar directory , 1428or to the directory specified in the 1429.Ev HOME 1430environment variable if no 1431.Ar directory 1432is specified. 1433If 1434.Ar directory 1435does not begin with 1436.Pa / , \&. , 1437or 1438.Pa .. , 1439then the directories listed in the 1440.Ev CDPATH 1441variable will be 1442searched for the specified 1443.Ar directory . 1444If 1445.Ev CDPATH 1446is unset, the current directory is searched. 1447The format of 1448.Ar CDPATH 1449is the same as that of 1450.Ev PATH . 1451In an interactive shell, 1452the 1453.Ic cd 1454command will print out the name of the directory 1455that it actually switched to 1456if this is different from the name that the user gave. 1457These may be different either because the 1458.Ev CDPATH 1459mechanism was used or because a symbolic link was crossed. 1460.Pp 1461If the 1462.Fl P 1463option is specified, 1464.Pa .. 1465is handled physically and symbolic links are resolved before 1466.Pa .. 1467components are processed. 1468If the 1469.Fl L 1470option is specified, 1471.Pa .. 1472is handled logically. 1473This is the default. 1474.It Ic chdir 1475A synonym for the 1476.Ic cd 1477built-in command. 1478.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... 1479.It Ic command Oo Fl v | V Oc Op Ar utility 1480The first form of invocation executes the specified 1481.Ar utility 1482as a simple command (see the 1483.Sx Simple Commands 1484section). 1485.Pp 1486If the 1487.Fl p 1488option is specified, the command search is performed using a 1489default value of 1490.Ev PATH 1491that is guaranteed to find all of the standard utilities. 1492.Pp 1493If the 1494.Fl v 1495option is specified, 1496.Ar utility 1497is not executed but a description of its interpretation by the shell is 1498printed. 1499For ordinary commands the output is the path name; for shell built-in 1500commands, shell functions and keywords only the name is written. 1501Aliases are printed as 1502.Dq Ic alias Ar name Ns = Ns Ar value . 1503.Pp 1504The 1505.Fl V 1506option is identical to 1507.Fl v 1508except for the output. 1509It prints 1510.Dq Ar utility Ic is Ar description 1511where 1512.Ar description 1513is either 1514the path name to 1515.Ar utility , 1516a shell builtin, 1517a shell function, 1518a shell keyword 1519or 1520an alias for 1521. Ar value . 1522.It Ic echo Oo Fl e | n Oc Op Ar string ... 1523Print a space-separated list of the arguments to the standard output 1524and append a newline character. 1525.Bl -tag -width indent 1526.It Fl n 1527Suppress the output of the trailing newline. 1528.It Fl e 1529Process C-style backslash escape sequences. 1530.Ic echo 1531understands the following character escapes: 1532.Bl -tag -width indent 1533.It \ea 1534Alert (ring the terminal bell) 1535.It \eb 1536Backspace 1537.It \ec 1538Suppress the trailing newline (this has the side-effect of truncating the 1539line if it is not the last character) 1540.It \ee 1541The ESC character (ASCII 0x1b) 1542.It \ef 1543Formfeed 1544.It \en 1545Newline 1546.It \er 1547Carriage return 1548.It \et 1549Horizontal tab 1550.It \ev 1551Vertical tab 1552.It \e\e 1553Literal backslash 1554.It \e0nnn 1555(Zero) The character whose octal value is nnn 1556.El 1557.Pp 1558If 1559.Ar string 1560is not enclosed in quotes then the backslash itself must be escaped 1561with a backslash to protect it from the shell. 1562For example 1563.Bd -literal -offset indent 1564$ echo -e "a\evb" 1565a 1566 b 1567$ echo -e a\e\evb 1568a 1569 b 1570$ echo -e "a\e\eb" 1571a\eb 1572$ echo -e a\e\e\e\eb 1573a\eb 1574.Ed 1575.El 1576.Pp 1577Only one of the 1578.Fl e 1579and 1580.Fl n 1581options may be specified. 1582.It Ic eval Ar string ... 1583Concatenate all the arguments with spaces. 1584Then re-parse and execute the command. 1585.It Ic exec Op Ar command Op arg ... 1586Unless 1587.Ar command 1588is omitted, 1589the shell process is replaced with the specified program 1590(which must be a real program, not a shell built-in command or function). 1591Any redirections on the 1592.Ic exec 1593command are marked as permanent, 1594so that they are not undone when the 1595.Ic exec 1596command finishes. 1597.It Ic exit Op Ar exitstatus 1598Terminate the shell process. 1599If 1600.Ar exitstatus 1601is given 1602it is used as the exit status of the shell; 1603otherwise the exit status of the preceding command is used. 1604.It Ic export Ar name ... 1605.It Ic export Op Fl p 1606The specified names are exported so that they will 1607appear in the environment of subsequent commands. 1608The only way to un-export a variable is to 1609.Ic unset 1610it. 1611The shell allows the value of a variable to be set 1612at the same time as it is exported by writing 1613.Bd -literal -offset indent 1614export name=value 1615.Ed 1616.Pp 1617With no arguments the export command lists the names 1618of all exported variables. 1619If the 1620.Fl p 1621option is specified, the exported variables are printed as 1622.Dq Ic export Ar name Ns = Ns Ar value 1623lines, suitable for re-input to the shell. 1624.It Ic false 1625A null command that returns a non-zero (false) exit value. 1626.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last 1627.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last 1628.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first 1629The 1630.Ic fc 1631built-in command lists, or edits and re-executes, 1632commands previously entered to an interactive shell. 1633.Bl -tag -width indent 1634.It Fl e Ar editor 1635Use the editor named by 1636.Ar editor 1637to edit the commands. 1638The editor string is a command name, 1639subject to search via the 1640.Ev PATH 1641variable. 1642The value in the 1643.Ev FCEDIT 1644variable is used as a default when 1645.Fl e 1646is not specified. 1647If 1648.Ev FCEDIT 1649is null or unset, the value of the 1650.Ev EDITOR 1651variable is used. 1652If 1653.Ev EDITOR 1654is null or unset, 1655.Xr ed 1 1656is used as the editor. 1657.It Fl l No (ell) 1658List the commands rather than invoking 1659an editor on them. 1660The commands are written in the 1661sequence indicated by the first and last operands, as 1662affected by 1663.Fl r , 1664with each command preceded by the command number. 1665.It Fl n 1666Suppress command numbers when listing with 1667.Fl l . 1668.It Fl r 1669Reverse the order of the commands listed 1670(with 1671.Fl l ) 1672or edited 1673(with neither 1674.Fl l 1675nor 1676.Fl s ) . 1677.It Fl s 1678Re-execute the command without invoking an editor. 1679.It Ar first 1680.It Ar last 1681Select the commands to list or edit. 1682The number of previous commands that can be accessed 1683are determined by the value of the 1684.Ev HISTSIZE 1685variable. 1686The value of 1687.Ar first 1688or 1689.Ar last 1690or both are one of the following: 1691.Bl -tag -width indent 1692.It Ar [+]num 1693A positive number representing a command number; 1694command numbers can be displayed with the 1695.Fl l 1696option. 1697.It Ar -num 1698A negative decimal number representing the 1699command that was executed 1700.Ar num 1701of 1702commands previously. 1703For example, -1 is the immediately previous command. 1704.It Ar string 1705A string indicating the most recently entered command 1706that begins with that string. 1707If the 1708.Ar old=new 1709operand is not also specified with 1710.Fl s , 1711the string form of the first operand cannot contain an embedded equal sign. 1712.El 1713.El 1714.Pp 1715The following environment variables affect the execution of 1716.Ic fc : 1717.Bl -tag -width ".Ev HISTSIZE" 1718.It Ev FCEDIT 1719Name of the editor to use for history editing. 1720.It Ev HISTSIZE 1721The number of previous commands that are accessible. 1722.El 1723.It Ic fg Op Ar job 1724Move the specified 1725.Ar job 1726or the current job to the foreground. 1727.It Ic getopts Ar optstring Ar var 1728The POSIX 1729.Ic getopts 1730command. 1731The 1732.Ic getopts 1733command deprecates the older 1734.Xr getopt 1 1735command. 1736The first argument should be a series of letters, each possibly 1737followed by a colon which indicates that the option takes an argument. 1738The specified variable is set to the parsed option. 1739The index of 1740the next argument is placed into the shell variable 1741.Ev OPTIND . 1742If an option takes an argument, it is placed into the shell variable 1743.Ev OPTARG . 1744If an invalid option is encountered, 1745.Ev var 1746is set to 1747.Dq Li \&? . 1748It returns a false value (1) when it encounters the end of the options. 1749.It Ic hash Oo Fl rv Oc Op Ar command ... 1750The shell maintains a hash table which remembers the locations of commands. 1751With no arguments whatsoever, the 1752.Ic hash 1753command prints out the contents of this table. 1754Entries which have not been looked at since the last 1755.Ic cd 1756command are marked with an asterisk; 1757it is possible for these entries to be invalid. 1758.Pp 1759With arguments, the 1760.Ic hash 1761command removes each specified 1762.Ar command 1763from the hash table (unless they are functions) and then locates it. 1764With the 1765.Fl v 1766option, 1767.Ic hash 1768prints the locations of the commands as it finds them. 1769The 1770.Fl r 1771option causes the 1772.Ic hash 1773command to delete all the entries in the hash table except for functions. 1774.It Ic jobid Op Ar job 1775Print the process id's of the processes in the specified 1776.Ar job . 1777If the 1778.Ar job 1779argument is omitted, use the current job. 1780.It Ic jobs Oo Fl lps Oc Op Ar job ... 1781Print information about the specified jobs, or all jobs if no 1782.Ar job 1783argument is given. 1784The information printed includes job ID, status and command name. 1785.Pp 1786If the 1787.Fl l 1788option is specified, the PID of each job is also printed. 1789If the 1790.Fl p 1791option is specified, only the process IDs for the process group leaders 1792are printed, one per line. 1793If the 1794.Fl s 1795option is specified, only the PIDs of the job commands are printed, one per 1796line. 1797.It Ic local Oo Ar variable ... Oc Op Fl 1798See the 1799.Sx Functions 1800subsection. 1801.It Ic pwd Op Fl L | P 1802Print the path of the current directory. 1803The built-in command may 1804differ from the program of the same name because the 1805built-in command remembers what the current directory 1806is rather than recomputing it each time. 1807This makes 1808it faster. 1809However, if the current directory is 1810renamed, 1811the built-in version of 1812.Xr pwd 1 1813will continue to print the old name for the directory. 1814.Pp 1815If the 1816.Fl P 1817option is specified, symbolic links are resolved. 1818If the 1819.Fl L 1820option is specified, the shell's notion of the current directory 1821is printed (symbolic links are not resolved). 1822This is the default. 1823.It Ic read Oo Fl p Ar prompt Oc Oo Fl t Ar timeout Oc Oo Fl er Oc Ar variable ... 1824The 1825.Ar prompt 1826is printed if the 1827.Fl p 1828option is specified 1829and the standard input is a terminal. 1830Then a line is 1831read from the standard input. 1832The trailing newline 1833is deleted from the line and the line is split as 1834described in the section on 1835.Sx White Space Splitting (Field Splitting) 1836above, and 1837the pieces are assigned to the variables in order. 1838If there are more pieces than variables, the remaining 1839pieces (along with the characters in 1840.Ev IFS 1841that separated them) 1842are assigned to the last variable. 1843If there are more variables than pieces, the remaining 1844variables are assigned the null string. 1845.Pp 1846Backslashes are treated specially, unless the 1847.Fl r 1848option is 1849specified. 1850If a backslash is followed by 1851a newline, the backslash and the newline will be 1852deleted. 1853If a backslash is followed by any other 1854character, the backslash will be deleted and the following 1855character will be treated as though it were not in 1856.Ev IFS , 1857even if it is. 1858.Pp 1859If the 1860.Fl t 1861option is specified and the 1862.Ar timeout 1863elapses before any input is supplied, 1864the 1865.Ic read 1866command will return an exit status of 1 without assigning any values. 1867The 1868.Ar timeout 1869value may optionally be followed by one of 1870.Dq s , 1871.Dq m 1872or 1873.Dq h 1874to explicitly specify seconds, minutes or hours. 1875If none is supplied, 1876.Dq s 1877is assumed. 1878.Pp 1879The 1880.Fl e 1881option exists only for backward compatibility with older scripts. 1882.It Ic readonly Oo Fl p Oc Op Ar name ... 1883Each specified 1884.Ar name 1885is marked as read only, 1886so that it cannot be subsequently modified or unset. 1887The shell allows the value of a variable to be set 1888at the same time as it is marked read only 1889by using the following form: 1890.Bd -literal -offset indent 1891readonly name=value 1892.Ed 1893.Pp 1894With no arguments the 1895.Ic readonly 1896command lists the names of all read only variables. 1897If the 1898.Fl p 1899option is specified, the read-only variables are printed as 1900.Dq Ic readonly Ar name Ns = Ns Ar value 1901lines, suitable for re-input to the shell. 1902.It Ic return Op Ar exitstatus 1903See the 1904.Sx Functions 1905subsection. 1906.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo 1907.Fl c Ar string Oc Op Fl - Ar arg ... 1908The 1909.Ic set 1910command performs three different functions: 1911.Bl -item 1912.It 1913With no arguments, it lists the values of all shell variables. 1914.It 1915If options are given, 1916either in short form or using the long 1917.Dq Fl /+o Ar longname 1918form, 1919it sets or clears the specified options as described in the section called 1920.Sx Argument List Processing . 1921.It 1922If the 1923.Dq Fl - 1924option is specified, 1925.Ic set 1926will replace the shell's positional parameters with the subsequent 1927arguments. 1928If no arguments follow the 1929.Dq Fl - 1930option, 1931all the positional parameters will be cleared, 1932which is equivalent to executing the command 1933.Dq Li shift $# . 1934The 1935.Dq Fl - 1936flag may be omitted when specifying arguments to be used 1937as positional replacement parameters. 1938This is not recommended, 1939because the first argument may begin with a dash 1940.Pq Ql - 1941or a plus 1942.Pq Ql + , 1943which the 1944.Ic set 1945command will interpret as a request to enable or disable options. 1946.El 1947.It Ic setvar Ar variable Ar value 1948Assigns the specified 1949.Ar value 1950to the specified 1951.Ar variable . 1952.Ic Setvar 1953is intended to be used in functions that 1954assign values to variables whose names are passed as parameters. 1955In general it is better to write 1956.Bd -literal -offset indent 1957variable=value 1958.Ed 1959rather than using 1960.Ic setvar . 1961.It Ic shift Op Ar n 1962Shift the positional parameters 1963.Ar n 1964times, or once if 1965.Ar n 1966is not specified. 1967A shift sets the value of $1 to the value of $2, 1968the value of $2 to the value of $3, and so on, 1969decreasing the value of $# by one. 1970If there are zero positional parameters, shifting does not do anything. 1971.It Ic test 1972A built-in equivalent of 1973.Xr test 1 . 1974.It Ic times 1975Print the amount of time spent executing the shell and its children. 1976The first output line shows the user and system times for the shell 1977itself, the second one contains the user and system times for the 1978children. 1979.It Ic trap Oo Ar action Oc Ar signal ... 1980.It Ic trap Fl l 1981Cause the shell to parse and execute 1982.Ar action 1983when any specified 1984.Ar signal 1985is received. 1986The signals are specified by name or number. 1987In addition, the pseudo-signal 1988.Cm EXIT 1989may be used to specify an action that is performed when the shell terminates. 1990The 1991.Ar action 1992may be an empty string or a dash 1993.Pq Ql - ; 1994the former causes the specified signal to be ignored 1995and the latter causes the default action to be taken. 1996Omitting the 1997.Ar action 1998is another way to request the default action, for compatibility reasons this 1999usage is not recommended though. 2000When the shell forks off a subshell, 2001it resets trapped (but not ignored) signals to the default action. 2002The 2003.Ic trap 2004command has no effect on signals that were ignored on entry to the shell. 2005.Pp 2006Option 2007.Fl l 2008causes the 2009.Ic trap 2010command to display a list of valid signal names. 2011.It Ic true 2012A null command that returns a 0 (true) exit value. 2013.It Ic type Op Ar name ... 2014Interpret each 2015.Ar name 2016as a command and print the resolution of the command search. 2017Possible resolutions are: 2018shell keyword, alias, shell built-in command, command, tracked alias 2019and not found. 2020For aliases the alias expansion is printed; 2021for commands and tracked aliases 2022the complete pathname of the command is printed. 2023.It Ic ulimit Oo Fl HSabcdflmnstuv Oc Op Ar limit 2024Set or display resource limits (see 2025.Xr getrlimit 2 ) . 2026If 2027.Ar limit 2028is specified, the named resource will be set; 2029otherwise the current resource value will be displayed. 2030.Pp 2031If 2032.Fl H 2033is specified, the hard limits will be set or displayed. 2034While everybody is allowed to reduce a hard limit, 2035only the superuser can increase it. 2036The 2037.Fl S 2038option 2039specifies the soft limits instead. 2040When displaying limits, 2041only one of 2042.Fl S 2043or 2044.Fl H 2045can be given. 2046The default is to display the soft limits, 2047and to set both the hard and the soft limits. 2048.Pp 2049Option 2050.Fl a 2051causes the 2052.Ic ulimit 2053command to display all resources. 2054The parameter 2055.Ar limit 2056is not acceptable in this mode. 2057.Pp 2058The remaining options specify which resource value is to be 2059displayed or modified. 2060They are mutually exclusive. 2061.Bl -tag -width indent 2062.It Fl b Ar sbsize 2063The maximum size of socket buffer usage, in bytes. 2064.It Fl c Ar coredumpsize 2065The maximal size of core dump files, in 512-byte blocks. 2066.It Fl d Ar datasize 2067The maximal size of the data segment of a process, in kilobytes. 2068.It Fl f Ar filesize 2069The maximal size of a file, in 512-byte blocks. 2070.It Fl l Ar lockedmem 2071The maximal size of memory that can be locked by a process, in 2072kilobytes. 2073.It Fl m Ar memoryuse 2074The maximal resident set size of a process, in kilobytes. 2075.It Fl n Ar nofiles 2076The maximal number of descriptors that could be opened by a process. 2077.It Fl s Ar stacksize 2078The maximal size of the stack segment, in kilobytes. 2079.It Fl t Ar time 2080The maximal amount of CPU time to be used by each process, in seconds. 2081.It Fl u Ar userproc 2082The maximal number of simultaneous processes for this user ID. 2083.It Fl v Ar virtualmem 2084The maximal virtual size of a process, in kilobytes. 2085.El 2086.It Ic umask Oo Fl S Oc Op Ar mask 2087Set the file creation mask (see 2088.Xr umask 2 ) 2089to the octal or symbolic (see 2090.Xr chmod 1 ) 2091value specified by 2092.Ar mask . 2093If the argument is omitted, the current mask value is printed. 2094If the 2095.Fl S 2096option is specified, the output is symbolic, otherwise the output is octal. 2097.It Ic unalias Oo Fl a Oc Op Ar name ... 2098The specified alias names are removed. 2099If 2100.Fl a 2101is specified, all aliases are removed. 2102.It Ic unset Oo Fl fv Oc Ar name ... 2103The specified variables or functions are unset and unexported. 2104If the 2105.Fl v 2106option is specified or no options are given, the 2107.Ar name 2108arguments are treated as variable names. 2109If the 2110.Fl f 2111option is specified, the 2112.Ar name 2113arguments are treated as function names. 2114.It Ic wait Op Ar job 2115Wait for the specified 2116.Ar job 2117to complete and return the exit status of the last process in the 2118.Ar job . 2119If the argument is omitted, wait for all jobs to complete 2120and return an exit status of zero. 2121.El 2122.Ss Commandline Editing 2123When 2124.Nm 2125is being used interactively from a terminal, the current command 2126and the command history 2127(see 2128.Ic fc 2129in 2130.Sx Built-in Commands ) 2131can be edited using vi-mode command line editing. 2132This mode uses commands similar 2133to a subset of those described in the vi man page. 2134The command 2135.Dq Li set -o vi 2136(or 2137.Dq Li set -V ) 2138enables vi-mode editing and places 2139.Nm 2140into vi insert mode. 2141With vi-mode enabled, 2142.Nm 2143can be switched between insert mode and command mode by typing 2144.Aq ESC . 2145Hitting 2146.Aq return 2147while in command mode will pass the line to the shell. 2148.Pp 2149Similarly, the 2150.Dq Li set -o emacs 2151(or 2152.Dq Li set -E ) 2153command can be used to enable a subset of 2154emacs-style command line editing features. 2155.Sh ENVIRONMENT 2156The following environment variables affect the execution of 2157.Nm : 2158.Bl -tag -width ".Ev HISTSIZE" 2159.It Ev CDPATH 2160The search path used with the 2161.Ic cd 2162built-in. 2163.It Ev EDITOR 2164The fallback editor used with the 2165.Ic fc 2166built-in. 2167If not set, the default editor is 2168.Xr ed 1 . 2169.It Ev FCEDIT 2170The default editor used with the 2171.Ic fc 2172built-in. 2173.It Ev HISTSIZE 2174The number of previous commands that are accessible. 2175.It Ev HOME 2176The starting directory of 2177.Nm . 2178.It Ev IFS 2179Input Field Separators. 2180This is normally set to 2181.Aq space , 2182.Aq tab , 2183and 2184.Aq newline . 2185See the 2186.Sx White Space Splitting 2187section for more details. 2188.It Ev MAIL 2189The name of a mail file, that will be checked for the arrival of new 2190mail. 2191Overridden by 2192.Ev MAILPATH . 2193.It Ev MAILPATH 2194A colon 2195.Pq Ql \&: 2196separated list of file names, for the shell to check for incoming 2197mail. 2198This environment setting overrides the 2199.Ev MAIL 2200setting. 2201There is a maximum of 10 mailboxes that can be monitored at once. 2202.It Ev PATH 2203The default search path for executables. 2204See the 2205.Sx Path Search 2206section for details. 2207.It Ev PS1 2208The primary prompt string, which defaults to 2209.Dq Li "$ " , 2210unless you are the superuser, in which case it defaults to 2211.Dq Li "# " . 2212.It Ev PS2 2213The secondary prompt string, which defaults to 2214.Dq Li "> " . 2215.It Ev PS4 2216The prefix for the trace output (if 2217.Fl x 2218is active). 2219The default is 2220.Dq Li "+ " . 2221.It Ev TERM 2222The default terminal setting for the shell. 2223This is inherited by children of the shell, and is used in the history 2224editing modes. 2225.El 2226.Sh EXIT STATUS 2227Errors that are detected by the shell, such as a syntax error, will 2228cause the shell to exit with a non-zero exit status. 2229If the shell is not an interactive shell, the execution of the shell 2230file will be aborted. 2231Otherwise the shell will return the exit status of the last command 2232executed, or if the exit builtin is used with a numeric argument, it 2233will return the argument. 2234.Sh SEE ALSO 2235.Xr builtin 1 , 2236.Xr chsh 1 , 2237.Xr echo 1 , 2238.Xr ed 1 , 2239.Xr emacs 1 , 2240.Xr expr 1 , 2241.Xr getopt 1 , 2242.Xr pwd 1 , 2243.Xr test 1 , 2244.Xr vi 1 , 2245.Xr execve 2 , 2246.Xr getrlimit 2 , 2247.Xr umask 2 , 2248.Xr editrc 5 2249.Sh HISTORY 2250A 2251.Nm 2252command, the Thompson shell, appeared in 2253.At v1 . 2254It was superseded in 2255.At v7 2256by the Bourne shell, which inherited the name 2257.Nm . 2258.Pp 2259This version of 2260.Nm 2261was rewritten in 1989 under the 2262.Bx 2263license after the Bourne shell from 2264.At V.4 . 2265.Sh AUTHORS 2266This version of 2267.Nm 2268was originally written by 2269.An Kenneth Almquist . 2270.Sh BUGS 2271The 2272.Nm 2273utility does not recognize multibyte characters. 2274