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