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