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