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