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 May 10, 2021 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 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. 362See also 363.Xr mac_veriexec 4 . 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 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.El 1450.It Va PS2 1451The secondary prompt string, which defaults to 1452.Dq Li "> " . 1453.Va PS2 1454may include any of the formatting sequences from 1455.Va PS1 . 1456.It Va PS4 1457The prefix for the trace output (if 1458.Fl x 1459is active). 1460The default is 1461.Dq Li "+ " . 1462.El 1463.Ss Word Expansions 1464This clause describes the various expansions that are 1465performed on words. 1466Not all expansions are performed on 1467every word, as explained later. 1468.Pp 1469Tilde expansions, parameter expansions, command substitutions, 1470arithmetic expansions, and quote removals that occur within 1471a single word expand to a single field. 1472It is only field 1473splitting or pathname expansion that can create multiple 1474fields from a single word. 1475The single exception to this rule is 1476the expansion of the special parameter 1477.Va @ 1478within double-quotes, 1479as was described above. 1480.Pp 1481The order of word expansion is: 1482.Bl -enum 1483.It 1484Tilde Expansion, Parameter Expansion, Command Substitution, 1485Arithmetic Expansion (these all occur at the same time). 1486.It 1487Field Splitting is performed on fields generated by step (1) 1488unless the 1489.Va IFS 1490variable is null. 1491.It 1492Pathname Expansion (unless the 1493.Fl f 1494option is in effect). 1495.It 1496Quote Removal. 1497.El 1498.Pp 1499The 1500.Ql $ 1501character is used to introduce parameter expansion, command 1502substitution, or arithmetic expansion. 1503.Ss Tilde Expansion (substituting a user's home directory) 1504A word beginning with an unquoted tilde character 1505.Pq Ql ~ 1506is 1507subjected to tilde expansion. 1508All the characters up to a slash 1509.Pq Ql / 1510or the end of the word are treated as a username 1511and are replaced with the user's home directory. 1512If the 1513username is missing (as in 1514.Pa ~/foobar ) , 1515the tilde is replaced with the value of the 1516.Va HOME 1517variable (the current user's home directory). 1518.Ss Parameter Expansion 1519The format for parameter expansion is as follows: 1520.Pp 1521.D1 Li ${ Ns Ar expression Ns Li } 1522.Pp 1523where 1524.Ar expression 1525consists of all characters until the matching 1526.Ql } . 1527Any 1528.Ql } 1529escaped by a backslash or within a single-quoted or double-quoted 1530string, and characters in 1531embedded arithmetic expansions, command substitutions, and variable 1532expansions, are not examined in determining the matching 1533.Ql } . 1534If the variants with 1535.Ql + , 1536.Ql - , 1537.Ql = 1538or 1539.Ql ?\& 1540occur within a double-quoted string, 1541as an extension there may be unquoted parts 1542(via double-quotes inside the expansion); 1543.Ql } 1544within such parts are also not examined in determining the matching 1545.Ql } . 1546.Pp 1547The simplest form for parameter expansion is: 1548.Pp 1549.D1 Li ${ Ns Ar parameter Ns Li } 1550.Pp 1551The value, if any, of 1552.Ar parameter 1553is substituted. 1554.Pp 1555The parameter name or symbol can be enclosed in braces, which are 1556optional except for positional parameters with more than one digit or 1557when parameter is followed by a character that could be interpreted as 1558part of the name. 1559If a parameter expansion occurs inside double-quotes: 1560.Bl -enum 1561.It 1562Field splitting is not performed on the results of the 1563expansion, with the exception of the special parameter 1564.Va @ . 1565.It 1566Pathname expansion is not performed on the results of the 1567expansion. 1568.El 1569.Pp 1570In addition, a parameter expansion can be modified by using one of the 1571following formats. 1572.Bl -tag -width indent 1573.It Li ${ Ns Ar parameter Ns Li :- Ns Ar word Ns Li } 1574Use Default Values. 1575If 1576.Ar parameter 1577is unset or null, the expansion of 1578.Ar word 1579is substituted; otherwise, the value of 1580.Ar parameter 1581is substituted. 1582.It Li ${ Ns Ar parameter Ns Li := Ns Ar word Ns Li } 1583Assign Default Values. 1584If 1585.Ar parameter 1586is unset or null, the expansion of 1587.Ar word 1588is assigned to 1589.Ar parameter . 1590In all cases, the 1591final value of 1592.Ar parameter 1593is substituted. 1594Quoting inside 1595.Ar word 1596does not prevent field splitting or pathname expansion. 1597Only variables, not positional 1598parameters or special parameters, can be 1599assigned in this way. 1600.It Li ${ Ns Ar parameter Ns Li :? Ns Oo Ar word Oc Ns Li } 1601Indicate Error if Null or Unset. 1602If 1603.Ar parameter 1604is unset or null, the expansion of 1605.Ar word 1606(or a message indicating it is unset if 1607.Ar word 1608is omitted) is written to standard 1609error and the shell exits with a nonzero 1610exit status. 1611Otherwise, the value of 1612.Ar parameter 1613is substituted. 1614An 1615interactive shell need not exit. 1616.It Li ${ Ns Ar parameter Ns Li :+ Ns Ar word Ns Li } 1617Use Alternate Value. 1618If 1619.Ar parameter 1620is unset or null, null is substituted; 1621otherwise, the expansion of 1622.Ar word 1623is substituted. 1624.El 1625.Pp 1626In the parameter expansions shown previously, use of the colon in the 1627format results in a test for a parameter that is unset or null; omission 1628of the colon results in a test for a parameter that is only unset. 1629.Pp 1630The 1631.Ar word 1632inherits the type of quoting 1633(unquoted, double-quoted or here-document) 1634from the surroundings, 1635with the exception that a backslash that quotes a closing brace is removed 1636during quote removal. 1637.Bl -tag -width indent 1638.It Li ${# Ns Ar parameter Ns Li } 1639String Length. 1640The length in characters of 1641the value of 1642.Ar parameter . 1643.El 1644.Pp 1645The following four varieties of parameter expansion provide for substring 1646processing. 1647In each case, pattern matching notation 1648(see 1649.Sx Shell Patterns ) , 1650rather than regular expression notation, 1651is used to evaluate the patterns. 1652If parameter is one of the special parameters 1653.Va * 1654or 1655.Va @ , 1656the result of the expansion is unspecified. 1657Enclosing the full parameter expansion string in double-quotes does not 1658cause the following four varieties of pattern characters to be quoted, 1659whereas quoting characters within the braces has this effect. 1660.Bl -tag -width indent 1661.It Li ${ Ns Ar parameter Ns Li % Ns Ar word Ns Li } 1662Remove Smallest Suffix Pattern. 1663The 1664.Ar word 1665is expanded to produce a pattern. 1666The 1667parameter expansion then results in 1668.Ar parameter , 1669with the smallest portion of the 1670suffix matched by the pattern deleted. 1671.It Li ${ Ns Ar parameter Ns Li %% Ns Ar word Ns Li } 1672Remove Largest Suffix Pattern. 1673The 1674.Ar word 1675is expanded to produce a pattern. 1676The 1677parameter expansion then results in 1678.Ar parameter , 1679with the largest portion of the 1680suffix matched by the pattern deleted. 1681.It Li ${ Ns Ar parameter Ns Li # Ns Ar word Ns Li } 1682Remove Smallest Prefix Pattern. 1683The 1684.Ar word 1685is expanded to produce a pattern. 1686The 1687parameter expansion then results in 1688.Ar parameter , 1689with the smallest portion of the 1690prefix matched by the pattern deleted. 1691.It Li ${ Ns Ar parameter Ns Li ## Ns Ar word Ns Li } 1692Remove Largest Prefix Pattern. 1693The 1694.Ar word 1695is expanded to produce a pattern. 1696The 1697parameter expansion then results in 1698.Ar parameter , 1699with the largest portion of the 1700prefix matched by the pattern deleted. 1701.El 1702.Ss Command Substitution 1703Command substitution allows the output of a command to be substituted in 1704place of the command name itself. 1705Command substitution occurs when 1706the command is enclosed as follows: 1707.Pp 1708.D1 Li $( Ns Ar command Ns Li )\& 1709.Pp 1710or the backquoted version: 1711.Pp 1712.D1 Li ` Ns Ar command Ns Li ` 1713.Pp 1714The shell expands the command substitution by executing command 1715and replacing the command substitution 1716with the standard output of the command, 1717removing sequences of one or more newlines at the end of the substitution. 1718Embedded newlines before the end of the output are not removed; 1719however, during field splitting, they may be translated into spaces 1720depending on the value of 1721.Va IFS 1722and the quoting that is in effect. 1723The command is executed in a subshell environment, 1724except that the built-in commands 1725.Ic jobid , 1726.Ic jobs , 1727and 1728.Ic trap 1729return information about the parent shell environment 1730and 1731.Ic times 1732returns information about the same process 1733if they are the only command in a command substitution. 1734.Pp 1735If a command substitution of the 1736.Li $( 1737form begins with a subshell, 1738the 1739.Li $( 1740and 1741.Li (\& 1742must be separated by whitespace 1743to avoid ambiguity with arithmetic expansion. 1744.Ss Arithmetic Expansion 1745Arithmetic expansion provides a mechanism for evaluating an arithmetic 1746expression and substituting its value. 1747The format for arithmetic expansion is as follows: 1748.Pp 1749.D1 Li $(( Ns Ar expression Ns Li )) 1750.Pp 1751The 1752.Ar expression 1753is treated as if it were in double-quotes, except 1754that a double-quote inside the expression is not treated specially. 1755The 1756shell expands all tokens in the 1757.Ar expression 1758for parameter expansion, 1759command substitution, 1760arithmetic expansion 1761and quote removal. 1762.Pp 1763The allowed expressions are a subset of C expressions, 1764summarized below. 1765.Bl -tag -width "Variables" -offset indent 1766.It Values 1767All values are of type 1768.Ft intmax_t . 1769.It Constants 1770Decimal, octal (starting with 1771.Li 0 ) 1772and hexadecimal (starting with 1773.Li 0x ) 1774integer constants. 1775.It Variables 1776Shell variables can be read and written 1777and contain integer constants. 1778.It Unary operators 1779.Li "! ~ + -" 1780.It Binary operators 1781.Li "* / % + - << >> < <= > >= == != & ^ | && ||"\& 1782.It Assignment operators 1783.Li "= += -= *= /= %= <<= >>= &= ^= |=" 1784.It Conditional operator 1785.Li "? :"\& 1786.El 1787.Pp 1788The result of the expression is substituted in decimal. 1789.Ss White Space Splitting (Field Splitting) 1790In certain contexts, 1791after parameter expansion, command substitution, and 1792arithmetic expansion the shell scans the results of 1793expansions and substitutions that did not occur in double-quotes for 1794field splitting and multiple fields can result. 1795.Pp 1796Characters in 1797.Va IFS 1798that are whitespace 1799.Po 1800.Aq space , 1801.Aq tab , 1802and 1803.Aq newline 1804.Pc 1805are treated differently from other characters in 1806.Va IFS . 1807.Pp 1808Whitespace in 1809.Va IFS 1810at the beginning or end of a word is discarded. 1811.Pp 1812Subsequently, a field is delimited by either 1813.Bl -enum 1814.It 1815a non-whitespace character in 1816.Va IFS 1817with any whitespace in 1818.Va IFS 1819surrounding it, or 1820.It 1821one or more whitespace characters in 1822.Va IFS . 1823.El 1824.Pp 1825If a word ends with a non-whitespace character in 1826.Va IFS , 1827there is no empty field after this character. 1828.Pp 1829If no field is delimited, the word is discarded. 1830In particular, if a word consists solely of an unquoted substitution 1831and the result of the substitution is null, 1832it is removed by field splitting even if 1833.Va IFS 1834is null. 1835.Ss Pathname Expansion (File Name Generation) 1836Unless the 1837.Fl f 1838option is set, 1839file name generation is performed 1840after word splitting is complete. 1841Each word is 1842viewed as a series of patterns, separated by slashes. 1843The 1844process of expansion replaces the word with the names of 1845all existing files whose names can be formed by replacing 1846each pattern with a string that matches the specified pattern. 1847There are two restrictions on this: first, a pattern cannot match 1848a string containing a slash, and second, 1849a pattern cannot match a string starting with a period 1850unless the first character of the pattern is a period. 1851The next section describes the patterns used for 1852Pathname Expansion, 1853the four varieties of parameter expansion for substring processing and the 1854.Ic case 1855command. 1856.Ss Shell Patterns 1857A pattern consists of normal characters, which match themselves, 1858and meta-characters. 1859The meta-characters are 1860.Ql * , 1861.Ql \&? , 1862and 1863.Ql \&[ . 1864These characters lose their special meanings if they are quoted. 1865When command or variable substitution is performed and the dollar sign 1866or back quotes are not double-quoted, the value of the 1867variable or the output of the command is scanned for these 1868characters and they are turned into meta-characters. 1869.Pp 1870An asterisk 1871.Pq Ql * 1872matches any string of characters. 1873A question mark 1874.Pq Ql \&? 1875matches any single character. 1876A left bracket 1877.Pq Ql \&[ 1878introduces a character class. 1879The end of the character class is indicated by a 1880.Ql \&] ; 1881if the 1882.Ql \&] 1883is missing then the 1884.Ql \&[ 1885matches a 1886.Ql \&[ 1887rather than introducing a character class. 1888A character class matches any of the characters between the square brackets. 1889A locale-dependent range of characters may be specified using a minus sign. 1890A named class of characters (see 1891.Xr wctype 3 ) 1892may be specified by surrounding the name with 1893.Ql \&[:\& 1894and 1895.Ql :\&] . 1896For example, 1897.Ql \&[\&[:alpha:\&]\&] 1898is a shell pattern that matches a single letter. 1899The character class may be complemented by making an exclamation point 1900.Pq Ql !\& 1901the first character of the character class. 1902A caret 1903.Pq Ql ^ 1904has the same effect but is non-standard. 1905.Pp 1906To include a 1907.Ql \&] 1908in a character class, make it the first character listed 1909(after the 1910.Ql \&! 1911or 1912.Ql ^ , 1913if any). 1914To include a 1915.Ql - , 1916make it the first or last character listed. 1917.Ss Built-in Commands 1918This section lists the built-in commands. 1919.Bl -tag -width indent 1920.It Ic \&: 1921A null command that returns a 0 (true) exit value. 1922.It Ic \&. Ar file 1923The commands in the specified file are read and executed by the shell. 1924The 1925.Ic return 1926command may be used to return to the 1927.Ic \&. 1928command's caller. 1929If 1930.Ar file 1931contains any 1932.Ql / 1933characters, it is used as is. 1934Otherwise, the shell searches the 1935.Va PATH 1936for the file. 1937If it is not found in the 1938.Va PATH , 1939it is sought in the current working directory. 1940.It Ic \&[ 1941A built-in equivalent of 1942.Xr test 1 . 1943.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc ... Oc 1944If 1945.Ar name Ns = Ns Ar string 1946is specified, the shell defines the alias 1947.Ar name 1948with value 1949.Ar string . 1950If just 1951.Ar name 1952is specified, the value of the alias 1953.Ar name 1954is printed. 1955With no arguments, the 1956.Ic alias 1957built-in command prints the names and values of all defined aliases 1958(see 1959.Ic unalias ) . 1960Alias values are written with appropriate quoting so that they are 1961suitable for re-input to the shell. 1962Also see the 1963.Sx Aliases 1964subsection. 1965.It Ic bg Op Ar job ... 1966Continue the specified jobs 1967(or the current job if no jobs are given) 1968in the background. 1969.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc 1970List or alter key bindings for the line editor. 1971This command is documented in 1972.Xr editrc 5 . 1973.It Ic break Op Ar num 1974See the 1975.Sx Flow-Control Constructs 1976subsection. 1977.It Ic builtin Ar cmd Op Ar arg ... 1978Execute the specified built-in command, 1979.Ar cmd . 1980This is useful when the user wishes to override a shell function 1981with the same name as a built-in command. 1982.It Ic cd Oo Fl L | P Oc Oo Fl e Oc Op Ar directory 1983.It Ic cd Fl 1984Switch to the specified 1985.Ar directory , 1986to the directory specified in the 1987.Va HOME 1988environment variable if no 1989.Ar directory 1990is specified or 1991to the directory specified in the 1992.Va OLDPWD 1993environment variable if 1994.Ar directory 1995is 1996.Fl . 1997If 1998.Ar directory 1999does not begin with 2000.Pa / , \&. , 2001or 2002.Pa .. , 2003then the directories listed in the 2004.Va CDPATH 2005variable will be 2006searched for the specified 2007.Ar directory . 2008If 2009.Va CDPATH 2010is unset, the current directory is searched. 2011The format of 2012.Va CDPATH 2013is the same as that of 2014.Va PATH . 2015In an interactive shell, 2016the 2017.Ic cd 2018command will print out the name of the directory 2019that it actually switched to 2020if the 2021.Va CDPATH 2022mechanism was used or if 2023.Ar directory 2024was 2025.Fl . 2026.Pp 2027If the 2028.Fl P 2029option is specified, 2030.Pa .. 2031is handled physically and symbolic links are resolved before 2032.Pa .. 2033components are processed. 2034If the 2035.Fl L 2036option is specified, 2037.Pa .. 2038is handled logically. 2039This is the default. 2040.Pp 2041The 2042.Fl e 2043option causes 2044.Ic cd 2045to return exit status 1 if the full pathname of the new directory 2046cannot be determined reliably or at all. 2047Normally this is not considered an error, 2048although a warning is printed. 2049.Pp 2050If changing the directory fails, the exit status is greater than 1. 2051If the directory is changed, the exit status is 0, or also 1 if 2052.Fl e 2053was given. 2054.It Ic chdir 2055A synonym for the 2056.Ic cd 2057built-in command. 2058.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... 2059.It Ic command Oo Fl p Oc Fl v Ar utility 2060.It Ic command Oo Fl p Oc Fl V Ar utility 2061The first form of invocation executes the specified 2062.Ar utility , 2063ignoring shell functions in the search. 2064If 2065.Ar utility 2066is a special builtin, 2067it is executed as if it were a regular builtin. 2068.Pp 2069If the 2070.Fl p 2071option is specified, the command search is performed using a 2072default value of 2073.Va PATH 2074that is guaranteed to find all of the standard utilities. 2075.Pp 2076If the 2077.Fl v 2078option is specified, 2079.Ar utility 2080is not executed but a description of its interpretation by the shell is 2081printed. 2082For ordinary commands the output is the path name; for shell built-in 2083commands, shell functions and keywords only the name is written. 2084Aliases are printed as 2085.Dq Ic alias Ar name Ns = Ns Ar value . 2086.Pp 2087The 2088.Fl V 2089option is identical to 2090.Fl v 2091except for the output. 2092It prints 2093.Dq Ar utility Ic is Ar description 2094where 2095.Ar description 2096is either 2097the path name to 2098.Ar utility , 2099a special shell builtin, 2100a shell builtin, 2101a shell function, 2102a shell keyword 2103or 2104an alias for 2105.Ar value . 2106.It Ic continue Op Ar num 2107See the 2108.Sx Flow-Control Constructs 2109subsection. 2110.It Ic echo Oo Fl e | n Oc Op Ar string ... 2111Print a space-separated list of the arguments to the standard output 2112and append a newline character. 2113.Bl -tag -width indent 2114.It Fl n 2115Suppress the output of the trailing newline. 2116.It Fl e 2117Process C-style backslash escape sequences. 2118The 2119.Ic echo 2120command understands the following character escapes: 2121.Bl -tag -width indent 2122.It \ea 2123Alert (ring the terminal bell) 2124.It \eb 2125Backspace 2126.It \ec 2127Suppress the trailing newline (this has the side-effect of truncating the 2128line if it is not the last character) 2129.It \ee 2130The ESC character (ASCII 0x1b) 2131.It \ef 2132Formfeed 2133.It \en 2134Newline 2135.It \er 2136Carriage return 2137.It \et 2138Horizontal tab 2139.It \ev 2140Vertical tab 2141.It \e\e 2142Literal backslash 2143.It \e0nnn 2144(Zero) The character whose octal value is 2145.Ar nnn 2146.El 2147.Pp 2148If 2149.Ar string 2150is not enclosed in quotes then the backslash itself must be escaped 2151with a backslash to protect it from the shell. 2152For example 2153.Bd -literal -offset indent 2154$ echo -e "a\evb" 2155a 2156 b 2157$ echo -e a\e\evb 2158a 2159 b 2160$ echo -e "a\e\eb" 2161a\eb 2162$ echo -e a\e\e\e\eb 2163a\eb 2164.Ed 2165.El 2166.Pp 2167Only one of the 2168.Fl e 2169and 2170.Fl n 2171options may be specified. 2172.It Ic eval Ar string ... 2173Concatenate all the arguments with spaces. 2174Then re-parse and execute the command. 2175.It Ic exec Op Ar command Op arg ... 2176Unless 2177.Ar command 2178is omitted, 2179the shell process is replaced with the specified program 2180(which must be a real program, not a shell built-in command or function). 2181Any redirections on the 2182.Ic exec 2183command are marked as permanent, 2184so that they are not undone when the 2185.Ic exec 2186command finishes. 2187.It Ic exit Op Ar exitstatus 2188Terminate the shell process. 2189If 2190.Ar exitstatus 2191is given 2192it is used as the exit status of the shell. 2193Otherwise, if the shell is executing an 2194.Cm EXIT 2195trap, the exit status of the last command before the trap is used; 2196if the shell is executing a trap for a signal, 2197the shell exits by resending the signal to itself. 2198Otherwise, the exit status of the preceding command is used. 2199The exit status should be an integer between 0 and 255. 2200.It Ic export Ar name ... 2201.It Ic export Op Fl p 2202The specified names are exported so that they will 2203appear in the environment of subsequent commands. 2204The only way to un-export a variable is to 2205.Ic unset 2206it. 2207The shell allows the value of a variable to be set 2208at the same time as it is exported by writing 2209.Pp 2210.D1 Ic export Ar name Ns = Ns Ar value 2211.Pp 2212With no arguments the 2213.Ic export 2214command lists the names 2215of all exported variables. 2216If the 2217.Fl p 2218option is specified, the exported variables are printed as 2219.Dq Ic export Ar name Ns = Ns Ar value 2220lines, suitable for re-input to the shell. 2221.It Ic false 2222A null command that returns a non-zero (false) exit value. 2223.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last 2224.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last 2225.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first 2226The 2227.Ic fc 2228built-in command lists, or edits and re-executes, 2229commands previously entered to an interactive shell. 2230.Bl -tag -width indent 2231.It Fl e Ar editor 2232Use the editor named by 2233.Ar editor 2234to edit the commands. 2235The 2236.Ar editor 2237string is a command name, 2238subject to search via the 2239.Va PATH 2240variable. 2241The value in the 2242.Va FCEDIT 2243variable is used as a default when 2244.Fl e 2245is not specified. 2246If 2247.Va FCEDIT 2248is null or unset, the value of the 2249.Va EDITOR 2250variable is used. 2251If 2252.Va EDITOR 2253is null or unset, 2254.Xr ed 1 2255is used as the editor. 2256.It Fl l No (ell) 2257List the commands rather than invoking 2258an editor on them. 2259The commands are written in the 2260sequence indicated by the 2261.Ar first 2262and 2263.Ar last 2264operands, as affected by 2265.Fl r , 2266with each command preceded by the command number. 2267.It Fl n 2268Suppress command numbers when listing with 2269.Fl l . 2270.It Fl r 2271Reverse the order of the commands listed 2272(with 2273.Fl l ) 2274or edited 2275(with neither 2276.Fl l 2277nor 2278.Fl s ) . 2279.It Fl s 2280Re-execute the command without invoking an editor. 2281.It Ar first 2282.It Ar last 2283Select the commands to list or edit. 2284The number of previous commands that can be accessed 2285are determined by the value of the 2286.Va HISTSIZE 2287variable. 2288The value of 2289.Ar first 2290or 2291.Ar last 2292or both are one of the following: 2293.Bl -tag -width indent 2294.It Oo Cm + Oc Ns Ar num 2295A positive number representing a command number; 2296command numbers can be displayed with the 2297.Fl l 2298option. 2299.It Fl Ar num 2300A negative decimal number representing the 2301command that was executed 2302.Ar num 2303of 2304commands previously. 2305For example, \-1 is the immediately previous command. 2306.It Ar string 2307A string indicating the most recently entered command 2308that begins with that string. 2309If the 2310.Ar old Ns = Ns Ar new 2311operand is not also specified with 2312.Fl s , 2313the string form of the first operand cannot contain an embedded equal sign. 2314.El 2315.El 2316.Pp 2317The following variables affect the execution of 2318.Ic fc : 2319.Bl -tag -width ".Va HISTSIZE" 2320.It Va FCEDIT 2321Name of the editor to use for history editing. 2322.It Va HISTSIZE 2323The number of previous commands that are accessible. 2324.El 2325.It Ic fg Op Ar job 2326Move the specified 2327.Ar job 2328or the current job to the foreground. 2329.It Ic getopts Ar optstring var 2330The POSIX 2331.Ic getopts 2332command. 2333The 2334.Ic getopts 2335command deprecates the older 2336.Xr getopt 1 2337command. 2338The first argument should be a series of letters, each possibly 2339followed by a colon which indicates that the option takes an argument. 2340The specified variable is set to the parsed option. 2341The index of 2342the next argument is placed into the shell variable 2343.Va OPTIND . 2344If an option takes an argument, it is placed into the shell variable 2345.Va OPTARG . 2346If an invalid option is encountered, 2347.Ar var 2348is set to 2349.Ql \&? . 2350It returns a false value (1) when it encounters the end of the options. 2351A new set of arguments may be parsed by assigning 2352.Li OPTIND=1 . 2353.It Ic hash Oo Fl rv Oc Op Ar command ... 2354The shell maintains a hash table which remembers the locations of commands. 2355With no arguments whatsoever, the 2356.Ic hash 2357command prints out the contents of this table. 2358.Pp 2359With arguments, the 2360.Ic hash 2361command removes each specified 2362.Ar command 2363from the hash table (unless they are functions) and then locates it. 2364With the 2365.Fl v 2366option, 2367.Ic hash 2368prints the locations of the commands as it finds them. 2369The 2370.Fl r 2371option causes the 2372.Ic hash 2373command to delete all the entries in the hash table except for functions. 2374.It Ic jobid Op Ar job 2375Print the process IDs of the processes in the specified 2376.Ar job . 2377If the 2378.Ar job 2379argument is omitted, use the current job. 2380.It Ic jobs Oo Fl lps Oc Op Ar job ... 2381Print information about the specified jobs, or all jobs if no 2382.Ar job 2383argument is given. 2384The information printed includes job ID, status and command name. 2385.Pp 2386If the 2387.Fl l 2388option is specified, the PID of each job is also printed. 2389If the 2390.Fl p 2391option is specified, only the process IDs for the process group leaders 2392are printed, one per line. 2393If the 2394.Fl s 2395option is specified, only the PIDs of the job commands are printed, one per 2396line. 2397.It Ic kill 2398A built-in equivalent of 2399.Xr kill 1 2400that additionally supports sending signals to jobs. 2401.It Ic local Oo Ar variable ... Oc Op Fl 2402See the 2403.Sx Functions 2404subsection. 2405.It Ic printf 2406A built-in equivalent of 2407.Xr printf 1 . 2408.It Ic pwd Op Fl L | P 2409Print the path of the current directory. 2410The built-in command may 2411differ from the program of the same name because the 2412built-in command remembers what the current directory 2413is rather than recomputing it each time. 2414This makes 2415it faster. 2416However, if the current directory is 2417renamed, 2418the built-in version of 2419.Xr pwd 1 2420will continue to print the old name for the directory. 2421.Pp 2422If the 2423.Fl P 2424option is specified, symbolic links are resolved. 2425If the 2426.Fl L 2427option is specified, the shell's notion of the current directory 2428is printed (symbolic links are not resolved). 2429This is the default. 2430.It Ic read Oo Fl p Ar prompt Oc Oo 2431.Fl t Ar timeout Oc Oo Fl er Oc Ar variable ... 2432The 2433.Ar prompt 2434is printed if the 2435.Fl p 2436option is specified 2437and the standard input is a terminal. 2438Then a line is 2439read from the standard input. 2440The trailing newline 2441is deleted from the line and the line is split as 2442described in the section on 2443.Sx White Space Splitting (Field Splitting)\& 2444above, and 2445the pieces are assigned to the variables in order. 2446If there are more pieces than variables, the remaining 2447pieces (along with the characters in 2448.Va IFS 2449that separated them) 2450are assigned to the last variable. 2451If there are more variables than pieces, the remaining 2452variables are assigned the null string. 2453.Pp 2454Backslashes are treated specially, unless the 2455.Fl r 2456option is 2457specified. 2458If a backslash is followed by 2459a newline, the backslash and the newline will be 2460deleted. 2461If a backslash is followed by any other 2462character, the backslash will be deleted and the following 2463character will be treated as though it were not in 2464.Va IFS , 2465even if it is. 2466.Pp 2467If the 2468.Fl t 2469option is specified and the 2470.Ar timeout 2471elapses before a complete line of input is supplied, 2472the 2473.Ic read 2474command will return an exit status as if terminated by 2475.Dv SIGALRM 2476without assigning any values. 2477The 2478.Ar timeout 2479value may optionally be followed by one of 2480.Ql s , 2481.Ql m 2482or 2483.Ql h 2484to explicitly specify seconds, minutes or hours. 2485If none is supplied, 2486.Ql s 2487is assumed. 2488.Pp 2489The 2490.Fl e 2491option exists only for backward compatibility with older scripts. 2492.Pp 2493The exit status is 0 on success, 1 on end of file, 2494between 2 and 128 if an error occurs 2495and greater than 128 if a trapped signal interrupts 2496.Ic read . 2497.It Ic readonly Oo Fl p Oc Op Ar name ... 2498Each specified 2499.Ar name 2500is marked as read only, 2501so that it cannot be subsequently modified or unset. 2502The shell allows the value of a variable to be set 2503at the same time as it is marked read only 2504by using the following form: 2505.Pp 2506.D1 Ic readonly Ar name Ns = Ns Ar value 2507.Pp 2508With no arguments the 2509.Ic readonly 2510command lists the names of all read only variables. 2511If the 2512.Fl p 2513option is specified, the read-only variables are printed as 2514.Dq Ic readonly Ar name Ns = Ns Ar value 2515lines, suitable for re-input to the shell. 2516.It Ic return Op Ar exitstatus 2517See the 2518.Sx Functions 2519subsection. 2520.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname 2521.Oc Op Fl - Ar arg ... 2522The 2523.Ic set 2524command performs three different functions: 2525.Bl -item 2526.It 2527With no arguments, it lists the values of all shell variables. 2528.It 2529If options are given, 2530either in short form or using the long 2531.Dq Fl /+o Ar longname 2532form, 2533it sets or clears the specified options as described in the section called 2534.Sx Argument List Processing . 2535.It 2536If the 2537.Dq Fl - 2538option is specified, 2539.Ic set 2540will replace the shell's positional parameters with the subsequent 2541arguments. 2542If no arguments follow the 2543.Dq Fl - 2544option, 2545all the positional parameters will be cleared, 2546which is equivalent to executing the command 2547.Dq Li "shift $#" . 2548The 2549.Dq Fl - 2550flag may be omitted when specifying arguments to be used 2551as positional replacement parameters. 2552This is not recommended, 2553because the first argument may begin with a dash 2554.Pq Ql - 2555or a plus 2556.Pq Ql + , 2557which the 2558.Ic set 2559command will interpret as a request to enable or disable options. 2560.El 2561.It Ic setvar Ar variable value 2562Assigns the specified 2563.Ar value 2564to the specified 2565.Ar variable . 2566The 2567.Ic setvar 2568command is intended to be used in functions that 2569assign values to variables whose names are passed as parameters. 2570In general it is better to write 2571.Dq Ar variable Ns = Ns Ar value 2572rather than using 2573.Ic setvar . 2574.It Ic shift Op Ar n 2575Shift the positional parameters 2576.Ar n 2577times, or once if 2578.Ar n 2579is not specified. 2580A shift sets the value of 2581.Li $1 2582to the value of 2583.Li $2 , 2584the value of 2585.Li $2 2586to the value of 2587.Li $3 , 2588and so on, 2589decreasing the value of 2590.Li $# 2591by one. 2592For portability, shifting if there are zero positional parameters 2593should be avoided, since the shell may abort. 2594.It Ic test 2595A built-in equivalent of 2596.Xr test 1 . 2597.It Ic times 2598Print the amount of time spent executing the shell process and its children. 2599The first output line shows the user and system times for the shell process 2600itself, the second one contains the user and system times for the 2601children. 2602.It Ic trap Oo Ar action Oc Ar signal ... 2603.It Ic trap Fl l 2604Cause the shell to parse and execute 2605.Ar action 2606when any specified 2607.Ar signal 2608is received. 2609The signals are specified by name or number. 2610In addition, the pseudo-signal 2611.Cm EXIT 2612may be used to specify an 2613.Ar action 2614that is performed when the shell terminates. 2615The 2616.Ar action 2617may be an empty string or a dash 2618.Pq Ql - ; 2619the former causes the specified signal to be ignored 2620and the latter causes the default action to be taken. 2621Omitting the 2622.Ar action 2623and using only signal numbers is another way to request the default action. 2624In a subshell or utility environment, 2625the shell resets trapped (but not ignored) signals to the default action. 2626The 2627.Ic trap 2628command has no effect on signals that were ignored on entry to the shell. 2629.Pp 2630Option 2631.Fl l 2632causes the 2633.Ic trap 2634command to display a list of valid signal names. 2635.It Ic true 2636A null command that returns a 0 (true) exit value. 2637.It Ic type Op Ar name ... 2638Interpret each 2639.Ar name 2640as a command and print the resolution of the command search. 2641Possible resolutions are: 2642shell keyword, alias, special shell builtin, shell builtin, command, 2643tracked alias 2644and not found. 2645For aliases the alias expansion is printed; 2646for commands and tracked aliases 2647the complete pathname of the command is printed. 2648.It Ic ulimit Oo Fl HSabcdfklmnopstuvw Oc Op Ar limit 2649Set or display resource limits (see 2650.Xr getrlimit 2 ) . 2651If 2652.Ar limit 2653is specified, the named resource will be set; 2654otherwise the current resource value will be displayed. 2655.Pp 2656If 2657.Fl H 2658is specified, the hard limits will be set or displayed. 2659While everybody is allowed to reduce a hard limit, 2660only the superuser can increase it. 2661The 2662.Fl S 2663option 2664specifies the soft limits instead. 2665When displaying limits, 2666only one of 2667.Fl S 2668or 2669.Fl H 2670can be given. 2671The default is to display the soft limits, 2672and to set both the hard and the soft limits. 2673.Pp 2674Option 2675.Fl a 2676causes the 2677.Ic ulimit 2678command to display all resources. 2679The parameter 2680.Ar limit 2681is not acceptable in this mode. 2682.Pp 2683The remaining options specify which resource value is to be 2684displayed or modified. 2685They are mutually exclusive. 2686.Bl -tag -width indent 2687.It Fl b Ar sbsize 2688The maximum size of socket buffer usage, in bytes. 2689.It Fl c Ar coredumpsize 2690The maximal size of core dump files, in 512-byte blocks. 2691Setting 2692.Ar coredumpsize 2693to 0 prevents core dump files from being created. 2694.It Fl d Ar datasize 2695The maximal size of the data segment of a process, in kilobytes. 2696.It Fl f Ar filesize 2697The maximal size of a file, in 512-byte blocks. 2698.It Fl k Ar kqueues 2699The maximal number of kqueues 2700(see 2701.Xr kqueue 2 ) 2702for this user ID. 2703.It Fl l Ar lockedmem 2704The maximal size of memory that can be locked by a process, in 2705kilobytes. 2706.It Fl m Ar memoryuse 2707The maximal resident set size of a process, in kilobytes. 2708.It Fl n Ar nofiles 2709The maximal number of descriptors that could be opened by a process. 2710.It Fl o Ar umtxp 2711The maximal number of process-shared locks 2712(see 2713.Xr pthread 3 ) 2714for this user ID. 2715.It Fl p Ar pseudoterminals 2716The maximal number of pseudo-terminals for this user ID. 2717.It Fl s Ar stacksize 2718The maximal size of the stack segment, in kilobytes. 2719.It Fl t Ar time 2720The maximal amount of CPU time to be used by each process, in seconds. 2721.It Fl u Ar userproc 2722The maximal number of simultaneous processes for this user ID. 2723.It Fl v Ar virtualmem 2724The maximal virtual size of a process, in kilobytes. 2725.It Fl w Ar swapuse 2726The maximum amount of swap space reserved or used for this user ID, 2727in kilobytes. 2728.El 2729.It Ic umask Oo Fl S Oc Op Ar mask 2730Set the file creation mask (see 2731.Xr umask 2 ) 2732to the octal or symbolic (see 2733.Xr chmod 1 ) 2734value specified by 2735.Ar mask . 2736If the argument is omitted, the current mask value is printed. 2737If the 2738.Fl S 2739option is specified, the output is symbolic, otherwise the output is octal. 2740.It Ic unalias Oo Fl a Oc Op Ar name ... 2741The specified alias names are removed. 2742If 2743.Fl a 2744is specified, all aliases are removed. 2745.It Ic unset Oo Fl fv Oc Ar name ... 2746The specified variables or functions are unset and unexported. 2747If the 2748.Fl v 2749option is specified or no options are given, the 2750.Ar name 2751arguments are treated as variable names. 2752If the 2753.Fl f 2754option is specified, the 2755.Ar name 2756arguments are treated as function names. 2757.It Ic wait Op Ar job ... 2758Wait for each specified 2759.Ar job 2760to complete and return the exit status of the last process in the 2761last specified 2762.Ar job . 2763If any 2764.Ar job 2765specified is unknown to the shell, it is treated as if it 2766were a known job that exited with exit status 127. 2767If no operands are given, wait for all jobs to complete 2768and return an exit status of zero. 2769.El 2770.Ss Command Line Editing 2771When 2772.Nm 2773is being used interactively from a terminal, the current command 2774and the command history 2775(see 2776.Ic fc 2777in 2778.Sx Built-in Commands ) 2779can be edited using 2780.Nm vi Ns -mode 2781command line editing. 2782This mode uses commands similar 2783to a subset of those described in the 2784.Xr vi 1 2785man page. 2786The command 2787.Dq Li "set -o vi" 2788(or 2789.Dq Li "set -V" ) 2790enables 2791.Nm vi Ns -mode 2792editing and places 2793.Nm 2794into 2795.Nm vi 2796insert mode. 2797With 2798.Nm vi Ns -mode 2799enabled, 2800.Nm 2801can be switched between insert mode and command mode by typing 2802.Aq ESC . 2803Hitting 2804.Aq return 2805while in command mode will pass the line to the shell. 2806.Pp 2807Similarly, the 2808.Dq Li "set -o emacs" 2809(or 2810.Dq Li "set -E" ) 2811command can be used to enable a subset of 2812.Nm emacs Ns -style 2813command line editing features. 2814.Sh ENVIRONMENT 2815The following environment variables affect the execution of 2816.Nm : 2817.Bl -tag -width ".Ev LANGXXXXXX" 2818.It Ev ENV 2819Initialization file for interactive shells. 2820.It Ev LANG , Ev LC_* 2821Locale settings. 2822These are inherited by children of the shell, 2823and is used in a limited manner by the shell itself. 2824.It Ev OLDPWD 2825The previous current directory. 2826This is used and updated by 2827.Ic cd . 2828.It Ev PWD 2829An absolute pathname for the current directory, 2830possibly containing symbolic links. 2831This is used and updated by the shell. 2832.It Ev TERM 2833The default terminal setting for the shell. 2834This is inherited by children of the shell, and is used in the history 2835editing modes. 2836.El 2837.Pp 2838Additionally, environment variables are turned into shell variables 2839at startup, 2840which may affect the shell as described under 2841.Sx Special Variables . 2842.Sh FILES 2843.Bl -tag -width "/etc/suid_profileXX" -compact 2844.It Pa ~/.profile 2845User's login profile. 2846.It Pa /etc/profile 2847System login profile. 2848.It Pa /etc/shells 2849Shell database. 2850.It Pa /etc/suid_profile 2851Privileged shell profile. 2852.El 2853.Sh EXIT STATUS 2854If the 2855.Ar script 2856cannot be found, the exit status will be 127; 2857if it cannot be opened for another reason, the exit status will be 126. 2858Other errors that are detected by the shell, such as a syntax error, will 2859cause the shell to exit with a non-zero exit status. 2860If the shell is not an interactive shell, the execution of the shell 2861file will be aborted. 2862Otherwise the shell will return the exit status of the last command 2863executed, or if the 2864.Ic exit 2865builtin is used with a numeric argument, it 2866will return the argument. 2867.Sh SEE ALSO 2868.Xr builtin 1 , 2869.Xr chsh 1 , 2870.Xr echo 1 , 2871.Xr ed 1 , 2872.Xr emacs 1 , 2873.Xr kill 1 , 2874.Xr printf 1 , 2875.Xr pwd 1 , 2876.Xr test 1 , 2877.Xr vi 1 , 2878.Xr execve 2 , 2879.Xr getrlimit 2 , 2880.Xr umask 2 , 2881.Xr wctype 3 , 2882.Xr editrc 5 , 2883.Xr shells 5 2884.Sh HISTORY 2885A 2886.Nm 2887command, the Thompson shell, appeared in 2888.At v1 . 2889It was superseded in 2890.At v7 2891by the Bourne shell, which inherited the name 2892.Nm . 2893.Pp 2894This version of 2895.Nm 2896was rewritten in 1989 under the 2897.Bx 2898license after the Bourne shell from 2899.At V.4 . 2900.Sh AUTHORS 2901This version of 2902.Nm 2903was originally written by 2904.An Kenneth Almquist . 2905.Sh BUGS 2906The 2907.Nm 2908utility does not recognize multibyte characters other than UTF-8. 2909Splitting using 2910.Va IFS 2911does not recognize multibyte characters. 2912