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