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