1.\"- 2.\" SPDX-License-Identifier: BSD-3-Clause 3.\" 4.\" Copyright (c) 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" Kenneth Almquist. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd March 8, 2025 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 /+abCEefhIilmnPpTuVvx 43.Op Fl /+o Ar longname 44.Oo 45.Ar script 46.Op Ar arg ... 47.Oc 48.Nm 49.Op Fl /+abCEefhIilmnPpTuVvx 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 /+abCEefhIilmnPpTuVvx 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 241Note that many commands return non-zero values to convey information other 242than errors, which can cause unexpected program termination with 243.Fl e . 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 l 255Force the shell to act as if it has been invoked as a login shell. 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.Sm off 1078.Bd -literal -offset indent 1079.Po Ar list Pc 1080.Ed 1081.Sm on 1082.Pp 1083or 1084.Bd -literal -offset indent 1085.No { Ar list ; } 1086.Ed 1087.Pp 1088The first form executes the commands in a subshell environment. 1089A subshell environment has its own copy of: 1090.Bl -enum 1091.It 1092The current working directory as set by 1093.Ic cd . 1094.It 1095The file creation mask as set by 1096.Ic umask . 1097.It 1098Resource limits as set by 1099.Ic ulimit . 1100.It 1101References to open files. 1102.It 1103Traps as set by 1104.Ic trap . 1105.It 1106Known jobs. 1107.It 1108Positional parameters and variables. 1109.It 1110Shell options. 1111.It 1112Shell functions. 1113.It 1114Shell aliases. 1115.El 1116.Pp 1117These are copied from the parent shell environment, 1118except that trapped (but not ignored) signals are reset to the default action 1119and known jobs are cleared. 1120Any changes do not affect the parent shell environment. 1121.Pp 1122A subshell environment may be implemented as a child process or differently. 1123If job control is enabled in an interactive shell, 1124commands grouped in parentheses can be suspended and continued as a unit. 1125.Pp 1126For compatibility with other shells, 1127two open parentheses in sequence should be separated by whitespace. 1128.Pp 1129The second form never forks another shell, 1130so it is slightly more efficient. 1131Grouping commands together this way allows the user to 1132redirect their output as though they were one program: 1133.Bd -literal -offset indent 1134{ echo -n "hello"; echo " world"; } > greeting 1135.Ed 1136.Ss Functions 1137The syntax of a function definition is 1138.Pp 1139.D1 Ar name Li \&( \&) Ar command 1140.Pp 1141A function definition is an executable statement; when 1142executed it installs a function named 1143.Ar name 1144and returns an 1145exit status of zero. 1146The 1147.Ar command 1148is normally a list 1149enclosed between 1150.Ql { 1151and 1152.Ql } . 1153.Pp 1154Variables may be declared to be local to a function by 1155using the 1156.Ic local 1157command. 1158This should appear as the first statement of a function, 1159and the syntax is: 1160.Pp 1161.D1 Ic local Oo Ar variable ... Oc Op Fl 1162.Pp 1163The 1164.Ic local 1165command is implemented as a built-in command. 1166The exit status is zero 1167unless the command is not in a function or a variable name is invalid. 1168.Pp 1169When a variable is made local, it inherits the initial 1170value and exported and readonly flags from the variable 1171with the same name in the surrounding scope, if there is 1172one. 1173Otherwise, the variable is initially unset. 1174The shell 1175uses dynamic scoping, so that if the variable 1176.Va x 1177is made local to function 1178.Em f , 1179which then calls function 1180.Em g , 1181references to the variable 1182.Va x 1183made inside 1184.Em g 1185will refer to the variable 1186.Va x 1187declared inside 1188.Em f , 1189not to the global variable named 1190.Va x . 1191.Pp 1192The only special parameter that can be made local is 1193.Ql - . 1194Making 1195.Ql - 1196local causes any shell options 1197(including those that only have long names) 1198that are 1199changed via the 1200.Ic set 1201command inside the function to be 1202restored to their original values when the function 1203returns. 1204.Pp 1205The syntax of the 1206.Ic return 1207command is 1208.Pp 1209.D1 Ic return Op Ar exitstatus 1210.Pp 1211It terminates the current executional scope, returning from the closest 1212nested function or sourced script; 1213if no function or sourced script is being executed, 1214it exits the shell instance. 1215The 1216.Ic return 1217command is implemented as a special built-in command. 1218.Ss Variables and Parameters 1219The shell maintains a set of parameters. 1220A parameter 1221denoted by a name 1222(consisting solely 1223of alphabetics, numerics, and underscores, 1224and starting with an alphabetic or an underscore) 1225is called a variable. 1226When starting up, 1227the shell turns all environment variables with valid names into shell 1228variables. 1229New variables can be set using the form 1230.Pp 1231.D1 Ar name Ns = Ns Ar value 1232.Pp 1233A parameter can also be denoted by a number 1234or a special character as explained below. 1235.Pp 1236Assignments are expanded differently from other words: 1237tilde expansion is also performed after the equals sign and after any colon 1238and usernames are also terminated by colons, 1239and field splitting and pathname expansion are not performed. 1240.Pp 1241This special expansion applies not only to assignments that form a simple 1242command by themselves or precede a command word, 1243but also to words passed to the 1244.Ic export , 1245.Ic local 1246or 1247.Ic readonly 1248built-in commands that have this form. 1249For this, the builtin's name must be literal 1250(not the result of an expansion) 1251and may optionally be preceded by one or more literal instances of 1252.Ic command 1253without options. 1254.Ss Positional Parameters 1255A positional parameter is a parameter denoted by a number greater than zero. 1256The shell sets these initially to the values of its command line 1257arguments that follow the name of the shell script. 1258The 1259.Ic set 1260built-in command can also be used to set or reset them. 1261.Ss Special Parameters 1262Special parameters are parameters denoted by a single special character 1263or the digit zero. 1264They are shown in the following list, exactly as they would appear in input 1265typed by the user or in the source of a shell script. 1266.Bl -hang 1267.It Li $* 1268Expands to the positional parameters, starting from one. 1269When 1270the expansion occurs within a double-quoted string 1271it expands to a single field with the value of each parameter 1272separated by the first character of the 1273.Va IFS 1274variable, 1275or by a space if 1276.Va IFS 1277is unset. 1278.It Li $@ 1279Expands to the positional parameters, starting from one. 1280When 1281the expansion occurs within double-quotes, each positional 1282parameter expands as a separate argument. 1283If there are no positional parameters, the 1284expansion of 1285.Li @ 1286generates zero arguments, even when 1287.Li @ 1288is double-quoted. 1289What this basically means, for example, is 1290if 1291.Li $1 1292is 1293.Dq Li abc 1294and 1295.Li $2 1296is 1297.Dq Li "def ghi" , 1298then 1299.Li \&"$@\&" 1300expands to 1301the two arguments: 1302.Bd -literal -offset indent 1303"abc" "def ghi" 1304.Ed 1305.It Li $# 1306Expands to the number of positional parameters. 1307.It Li $? 1308Expands to the exit status of the most recent pipeline. 1309.It Li $- 1310(hyphen) Expands to the current option flags (the single-letter 1311option names concatenated into a string) as specified on 1312invocation, by the 1313.Ic set 1314built-in command, or implicitly 1315by the shell. 1316.It Li $$ 1317Expands to the process ID of the invoked shell. 1318A subshell 1319retains the same value of 1320.Va $ 1321as its parent. 1322.It Li $! 1323Expands to the process ID of the most recent background 1324command executed from the current shell. 1325For a 1326pipeline, the process ID is that of the last command in the 1327pipeline. 1328If this parameter is referenced, the shell will remember 1329the process ID and its exit status until the 1330.Ic wait 1331built-in command reports completion of the process. 1332.It Li $0 1333(zero) Expands to the name of the shell script if passed on the command line, 1334the 1335.Ar name 1336operand if given (with 1337.Fl c ) 1338or otherwise argument 0 passed to the shell. 1339.El 1340.Ss Special Variables 1341The following variables are set by the shell or 1342have special meaning to it: 1343.Bl -tag -width ".Va HISTSIZE" 1344.It Va CDPATH 1345The search path used with the 1346.Ic cd 1347built-in. 1348.It Va EDITOR 1349The fallback editor used with the 1350.Ic fc 1351built-in. 1352If not set, the default editor is 1353.Xr ed 1 . 1354.It Va FCEDIT 1355The default editor used with the 1356.Ic fc 1357built-in. 1358.It Va HISTFILE 1359File used for persistent history storage. 1360If unset 1361.Pa ~/.sh_history 1362will be used. 1363If set but empty or 1364.Va HISTSIZE 1365is set to 0 1366the shell will not load and save the history. 1367.It Va HISTSIZE 1368The number of previous commands that are accessible. 1369.It Va HOME 1370The user's home directory, 1371used in tilde expansion and as a default directory for the 1372.Ic cd 1373built-in. 1374.It Va IFS 1375Input Field Separators. 1376This is initialized at startup to 1377.Aq space , 1378.Aq tab , 1379and 1380.Aq newline 1381in that order. 1382This value also applies if 1383.Va IFS 1384is unset, but not if it is set to the empty string. 1385See the 1386.Sx White Space Splitting 1387section for more details. 1388.It Va LINENO 1389The current line number in the script or function. 1390.It Va MAIL 1391The name of a mail file, that will be checked for the arrival of new 1392mail. 1393Overridden by 1394.Va MAILPATH . 1395.It Va MAILPATH 1396A colon 1397.Pq Ql \&: 1398separated list of file names, for the shell to check for incoming 1399mail. 1400This variable overrides the 1401.Va MAIL 1402setting. 1403There is a maximum of 10 mailboxes that can be monitored at once. 1404.It Va OPTIND 1405The index of the next argument to be processed by 1406.Ic getopts . 1407This is initialized to 1 at startup. 1408.It Va PATH 1409The default search path for executables. 1410See the 1411.Sx Path Search 1412section for details. 1413.It Va PPID 1414The parent process ID of the invoked shell. 1415This is set at startup 1416unless this variable is in the environment. 1417A later change of parent process ID is not reflected. 1418A subshell retains the same value of 1419.Va PPID . 1420.It Va PS1 1421The primary prompt string, which defaults to 1422.Dq Li "$ " , 1423unless you are the superuser, in which case it defaults to 1424.Dq Li "# " . 1425.Va PS1 1426may include any of the following formatting sequences, 1427which are replaced by the given information: 1428.Bl -tag -width indent 1429.It Li \eD{format} 1430The current time in 1431.Xr strftime 3 1432.Ar format . 1433The braces are required. 1434Empty 1435.Ar format 1436is equivalent to 1437\&%X, 1438national representation of the time. 1439.It Li \eH 1440This system's fully-qualified hostname (FQDN). 1441.It Li \eh 1442This system's hostname. 1443.It Li \eu 1444User name. 1445.It Li \eW 1446The final component of the current working directory. 1447.It Li \ew 1448The entire path of the current working directory. 1449.It Li \e$ 1450Superuser status. 1451.Dq Li "$" 1452for normal users and 1453.Dq Li "#" 1454for superusers. 1455.It Li \e\e 1456A literal backslash. 1457.It Li \e[ 1458Start of a sequence of non-printing characters (used, for example, 1459to embed ANSI CSI sequences into the prompt). 1460.It Li \e] 1461End of a sequence of non-printing characters. 1462.El 1463.Pp 1464The following special and non-printing characters are supported 1465within the sequence of non-printing characters: 1466.Bl -tag -width indent 1467.It Li \ea 1468Emits ASCII BEL (0x07, 007) character. 1469.It Li \ee 1470Emits ASCII ESC (0x1b, 033) character. 1471.It Li \er 1472Emits ASCII CR (0x0d, 015) character. 1473.It Li \en 1474Emits CRLF sequence. 1475.El 1476.It Va PS2 1477The secondary prompt string, which defaults to 1478.Dq Li "> " . 1479.Va PS2 1480may include any of the formatting sequences from 1481.Va PS1 . 1482.It Va PS4 1483The prefix for the trace output (if 1484.Fl x 1485is active). 1486The default is 1487.Dq Li "+ " . 1488.El 1489.Ss Word Expansions 1490This clause describes the various expansions that are 1491performed on words. 1492Not all expansions are performed on 1493every word, as explained later. 1494.Pp 1495Tilde expansions, parameter expansions, command substitutions, 1496arithmetic expansions, and quote removals that occur within 1497a single word expand to a single field. 1498It is only field 1499splitting or pathname expansion that can create multiple 1500fields from a single word. 1501The single exception to this rule is 1502the expansion of the special parameter 1503.Va @ 1504within double-quotes, 1505as was described above. 1506.Pp 1507The order of word expansion is: 1508.Bl -enum 1509.It 1510Tilde Expansion, Parameter Expansion, Command Substitution, 1511Arithmetic Expansion (these all occur at the same time). 1512.It 1513Field Splitting is performed on fields generated by step (1) 1514unless the 1515.Va IFS 1516variable is null. 1517.It 1518Pathname Expansion (unless the 1519.Fl f 1520option is in effect). 1521.It 1522Quote Removal. 1523.El 1524.Pp 1525The 1526.Ql $ 1527character is used to introduce parameter expansion, command 1528substitution, or arithmetic expansion. 1529.Ss Tilde Expansion (substituting a user's home directory) 1530A word beginning with an unquoted tilde character 1531.Pq Ql ~ 1532is 1533subjected to tilde expansion. 1534All the characters up to a slash 1535.Pq Ql / 1536or the end of the word are treated as a username 1537and are replaced with the user's home directory. 1538If the 1539username is missing (as in 1540.Pa ~/foobar ) , 1541the tilde is replaced with the value of the 1542.Va HOME 1543variable (the current user's home directory). 1544.Ss Parameter Expansion 1545The format for parameter expansion is as follows: 1546.Pp 1547.D1 Li ${ Ns Ar expression Ns Li } 1548.Pp 1549where 1550.Ar expression 1551consists of all characters until the matching 1552.Ql } . 1553Any 1554.Ql } 1555escaped by a backslash or within a single-quoted or double-quoted 1556string, and characters in 1557embedded arithmetic expansions, command substitutions, and variable 1558expansions, are not examined in determining the matching 1559.Ql } . 1560If the variants with 1561.Ql + , 1562.Ql - , 1563.Ql = 1564or 1565.Ql ?\& 1566occur within a double-quoted string, 1567as an extension there may be unquoted parts 1568(via double-quotes inside the expansion); 1569.Ql } 1570within such parts are also not examined in determining the matching 1571.Ql } . 1572.Pp 1573The simplest form for parameter expansion is: 1574.Pp 1575.D1 Li ${ Ns Ar parameter Ns Li } 1576.Pp 1577The value, if any, of 1578.Ar parameter 1579is substituted. 1580.Pp 1581The parameter name or symbol can be enclosed in braces, which are 1582optional except for positional parameters with more than one digit or 1583when parameter is followed by a character that could be interpreted as 1584part of the name. 1585If a parameter expansion occurs inside double-quotes: 1586.Bl -enum 1587.It 1588Field splitting is not performed on the results of the 1589expansion, with the exception of the special parameter 1590.Va @ . 1591.It 1592Pathname expansion is not performed on the results of the 1593expansion. 1594.El 1595.Pp 1596In addition, a parameter expansion can be modified by using one of the 1597following formats. 1598.Bl -tag -width indent 1599.It Li ${ Ns Ar parameter Ns Li :- Ns Ar word Ns Li } 1600Use Default Values. 1601If 1602.Ar parameter 1603is unset or null, the expansion of 1604.Ar word 1605is substituted; otherwise, the value of 1606.Ar parameter 1607is substituted. 1608.It Li ${ Ns Ar parameter Ns Li := Ns Ar word Ns Li } 1609Assign Default Values. 1610If 1611.Ar parameter 1612is unset or null, the expansion of 1613.Ar word 1614is assigned to 1615.Ar parameter . 1616In all cases, the 1617final value of 1618.Ar parameter 1619is substituted. 1620Quoting inside 1621.Ar word 1622does not prevent field splitting or pathname expansion. 1623Only variables, not positional 1624parameters or special parameters, can be 1625assigned in this way. 1626.It Li ${ Ns Ar parameter Ns Li :? Ns Oo Ar word Oc Ns Li } 1627Indicate Error if Null or Unset. 1628If 1629.Ar parameter 1630is unset or null, the expansion of 1631.Ar word 1632(or a message indicating it is unset if 1633.Ar word 1634is omitted) is written to standard 1635error and the shell exits with a nonzero 1636exit status. 1637Otherwise, the value of 1638.Ar parameter 1639is substituted. 1640An 1641interactive shell need not exit. 1642.It Li ${ Ns Ar parameter Ns Li :+ Ns Ar word Ns Li } 1643Use Alternate Value. 1644If 1645.Ar parameter 1646is unset or null, null is substituted; 1647otherwise, the expansion of 1648.Ar word 1649is substituted. 1650.El 1651.Pp 1652In the parameter expansions shown previously, use of the colon in the 1653format results in a test for a parameter that is unset or null; omission 1654of the colon results in a test for a parameter that is only unset. 1655.Pp 1656The 1657.Ar word 1658inherits the type of quoting 1659(unquoted, double-quoted or here-document) 1660from the surroundings, 1661with the exception that a backslash that quotes a closing brace is removed 1662during quote removal. 1663.Bl -tag -width indent 1664.It Li ${# Ns Ar parameter Ns Li } 1665String Length. 1666The length in characters of 1667the value of 1668.Ar parameter . 1669.El 1670.Pp 1671The following four varieties of parameter expansion provide for substring 1672processing. 1673In each case, pattern matching notation 1674(see 1675.Sx Shell Patterns ) , 1676rather than regular expression notation, 1677is used to evaluate the patterns. 1678If parameter is one of the special parameters 1679.Va * 1680or 1681.Va @ , 1682the result of the expansion is unspecified. 1683Enclosing the full parameter expansion string in double-quotes does not 1684cause the following four varieties of pattern characters to be quoted, 1685whereas quoting characters within the braces has this effect. 1686.Bl -tag -width indent 1687.It Li ${ Ns Ar parameter Ns Li % Ns Ar word Ns Li } 1688Remove Smallest Suffix Pattern. 1689The 1690.Ar word 1691is expanded to produce a pattern. 1692The 1693parameter expansion then results in 1694.Ar parameter , 1695with the smallest portion of the 1696suffix matched by the pattern deleted. 1697.It Li ${ Ns Ar parameter Ns Li %% Ns Ar word Ns Li } 1698Remove Largest Suffix Pattern. 1699The 1700.Ar word 1701is expanded to produce a pattern. 1702The 1703parameter expansion then results in 1704.Ar parameter , 1705with the largest portion of the 1706suffix matched by the pattern deleted. 1707.It Li ${ Ns Ar parameter Ns Li # Ns Ar word Ns Li } 1708Remove Smallest Prefix Pattern. 1709The 1710.Ar word 1711is expanded to produce a pattern. 1712The 1713parameter expansion then results in 1714.Ar parameter , 1715with the smallest portion of the 1716prefix matched by the pattern deleted. 1717.It Li ${ Ns Ar parameter Ns Li ## Ns Ar word Ns Li } 1718Remove Largest Prefix Pattern. 1719The 1720.Ar word 1721is expanded to produce a pattern. 1722The 1723parameter expansion then results in 1724.Ar parameter , 1725with the largest portion of the 1726prefix matched by the pattern deleted. 1727.El 1728.Ss Command Substitution 1729Command substitution allows the output of a command to be substituted in 1730place of the command name itself. 1731Command substitution occurs when 1732the command is enclosed as follows: 1733.Pp 1734.D1 Li $( Ns Ar command Ns Li )\& 1735.Pp 1736or the backquoted version: 1737.Pp 1738.D1 Li ` Ns Ar command Ns Li ` 1739.Pp 1740The shell expands the command substitution by executing command 1741and replacing the command substitution 1742with the standard output of the command, 1743removing sequences of one or more newlines at the end of the substitution. 1744Embedded newlines before the end of the output are not removed; 1745however, during field splitting, they may be translated into spaces 1746depending on the value of 1747.Va IFS 1748and the quoting that is in effect. 1749The command is executed in a subshell environment, 1750except that the built-in commands 1751.Ic jobid , 1752.Ic jobs , 1753and 1754.Ic trap 1755return information about the parent shell environment 1756and 1757.Ic times 1758returns information about the same process 1759if they are the only command in a command substitution. 1760.Pp 1761If a command substitution of the 1762.Li $( 1763form begins with a subshell, 1764the 1765.Li $( 1766and 1767.Li (\& 1768must be separated by whitespace 1769to avoid ambiguity with arithmetic expansion. 1770.Ss Arithmetic Expansion 1771Arithmetic expansion provides a mechanism for evaluating an arithmetic 1772expression and substituting its value. 1773The format for arithmetic expansion is as follows: 1774.Pp 1775.D1 Li $(( Ns Ar expression Ns Li )) 1776.Pp 1777The 1778.Ar expression 1779is treated as if it were in double-quotes, except 1780that a double-quote inside the expression is not treated specially. 1781The 1782shell expands all tokens in the 1783.Ar expression 1784for parameter expansion, 1785command substitution, 1786arithmetic expansion 1787and quote removal. 1788.Pp 1789The allowed expressions are a subset of C expressions, 1790summarized below. 1791.Bl -tag -width "Variables" -offset indent 1792.It Values 1793All values are of type 1794.Ft intmax_t . 1795.It Constants 1796Decimal, octal (starting with 1797.Li 0 ) 1798and hexadecimal (starting with 1799.Li 0x ) 1800integer constants. 1801.It Variables 1802Shell variables can be read and written 1803and contain integer constants. 1804.It Unary operators 1805.Li "! ~ + -" 1806.It Binary operators 1807.Li "* / % + - << >> < <= > >= == != & ^ | && ||"\& 1808.It Assignment operators 1809.Li "= += -= *= /= %= <<= >>= &= ^= |=" 1810.It Conditional operator 1811.Li "? :"\& 1812.El 1813.Pp 1814The result of the expression is substituted in decimal. 1815.Ss White Space Splitting (Field Splitting) 1816In certain contexts, 1817after parameter expansion, command substitution, and 1818arithmetic expansion the shell scans the results of 1819expansions and substitutions that did not occur in double-quotes for 1820field splitting and multiple fields can result. 1821.Pp 1822Characters in 1823.Va IFS 1824that are whitespace 1825.Po 1826.Aq space , 1827.Aq tab , 1828and 1829.Aq newline 1830.Pc 1831are treated differently from other characters in 1832.Va IFS . 1833.Pp 1834Whitespace in 1835.Va IFS 1836at the beginning or end of a word is discarded. 1837.Pp 1838Subsequently, a field is delimited by either 1839.Bl -enum 1840.It 1841a non-whitespace character in 1842.Va IFS 1843with any whitespace in 1844.Va IFS 1845surrounding it, or 1846.It 1847one or more whitespace characters in 1848.Va IFS . 1849.El 1850.Pp 1851If a word ends with a non-whitespace character in 1852.Va IFS , 1853there is no empty field after this character. 1854.Pp 1855If no field is delimited, the word is discarded. 1856In particular, if a word consists solely of an unquoted substitution 1857and the result of the substitution is null, 1858it is removed by field splitting even if 1859.Va IFS 1860is null. 1861.Ss Pathname Expansion (File Name Generation) 1862Unless the 1863.Fl f 1864option is set, 1865file name generation is performed 1866after word splitting is complete. 1867Each word is 1868viewed as a series of patterns, separated by slashes. 1869The 1870process of expansion replaces the word with the names of 1871all existing files whose names can be formed by replacing 1872each pattern with a string that matches the specified pattern. 1873There are two restrictions on this: first, a pattern cannot match 1874a string containing a slash, and second, 1875a pattern cannot match a string starting with a period 1876unless the first character of the pattern is a period. 1877The next section describes the patterns used for 1878Pathname Expansion, 1879the four varieties of parameter expansion for substring processing and the 1880.Ic case 1881command. 1882.Ss Shell Patterns 1883A pattern consists of normal characters, which match themselves, 1884and meta-characters. 1885The meta-characters are 1886.Ql * , 1887.Ql \&? , 1888and 1889.Ql \&[ . 1890These characters lose their special meanings if they are quoted. 1891When command or variable substitution is performed and the dollar sign 1892or back quotes are not double-quoted, the value of the 1893variable or the output of the command is scanned for these 1894characters and they are turned into meta-characters. 1895.Pp 1896An asterisk 1897.Pq Ql * 1898matches any string of characters. 1899A question mark 1900.Pq Ql \&? 1901matches any single character. 1902A left bracket 1903.Pq Ql \&[ 1904introduces a character class. 1905The end of the character class is indicated by a 1906.Ql \&] ; 1907if the 1908.Ql \&] 1909is missing then the 1910.Ql \&[ 1911matches a 1912.Ql \&[ 1913rather than introducing a character class. 1914A character class matches any of the characters between the square brackets. 1915A locale-dependent range of characters may be specified using a minus sign. 1916A named class of characters (see 1917.Xr wctype 3 ) 1918may be specified by surrounding the name with 1919.Ql \&[:\& 1920and 1921.Ql :\&] . 1922For example, 1923.Ql \&[\&[:alpha:\&]\&] 1924is a shell pattern that matches a single letter. 1925The character class may be complemented by making an exclamation point 1926.Pq Ql !\& 1927the first character of the character class. 1928A caret 1929.Pq Ql ^ 1930has the same effect but is non-standard. 1931.Pp 1932To include a 1933.Ql \&] 1934in a character class, make it the first character listed 1935(after the 1936.Ql \&! 1937or 1938.Ql ^ , 1939if any). 1940To include a 1941.Ql - , 1942make it the first or last character listed. 1943.Ss Built-in Commands 1944This section lists the built-in commands. 1945.Bl -tag -width indent 1946.It Ic \&: Op Ar arg Ar ... 1947A null command that returns a 0 (true) exit value. 1948Any arguments are discarded. 1949.It Ic \&. Ar file 1950The commands in the specified file are read and executed by the shell. 1951The 1952.Ic return 1953command may be used to return to the 1954.Ic \&. 1955command's caller. 1956If 1957.Ar file 1958contains any 1959.Ql / 1960characters, it is used as is. 1961Otherwise, the shell searches the 1962.Va PATH 1963for the file. 1964If it is not found in the 1965.Va PATH , 1966it is sought in the current working directory. 1967.It Ic \&[ 1968A built-in equivalent of 1969.Xr test 1 . 1970.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc Ar ... Oc 1971If 1972.Ar name Ns = Ns Ar string 1973is specified, the shell defines the alias 1974.Ar name 1975with value 1976.Ar string . 1977If just 1978.Ar name 1979is specified, the value of the alias 1980.Ar name 1981is printed. 1982With no arguments, the 1983.Ic alias 1984built-in command prints the names and values of all defined aliases 1985(see 1986.Ic unalias ) . 1987Alias values are written with appropriate quoting so that they are 1988suitable for re-input to the shell. 1989Also see the 1990.Sx Aliases 1991subsection. 1992.It Ic bg Op Ar job ... 1993Continue the specified jobs 1994(or the current job if no jobs are given) 1995in the background. 1996.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc 1997List or alter key bindings for the line editor. 1998This command is documented in 1999.Xr editrc 5 . 2000.It Ic break Op Ar num 2001See the 2002.Sx Flow-Control Constructs 2003subsection. 2004.It Ic builtin Ar cmd Op Ar arg ... 2005Execute the specified built-in command, 2006.Ar cmd . 2007This is useful when the user wishes to override a shell function 2008with the same name as a built-in command. 2009.It Ic cd Oo Fl L | P Oc Oo Fl e Oc Op Ar directory 2010.It Ic cd Fl 2011Switch to the specified 2012.Ar directory , 2013to the directory specified in the 2014.Va HOME 2015environment variable if no 2016.Ar directory 2017is specified or 2018to the directory specified in the 2019.Va OLDPWD 2020environment variable if 2021.Ar directory 2022is 2023.Fl . 2024If 2025.Ar directory 2026does not begin with 2027.Pa / , \&. , 2028or 2029.Pa .. , 2030then the directories listed in the 2031.Va CDPATH 2032variable will be 2033searched for the specified 2034.Ar directory . 2035If 2036.Va CDPATH 2037is unset, the current directory is searched. 2038The format of 2039.Va CDPATH 2040is the same as that of 2041.Va PATH . 2042In an interactive shell, 2043the 2044.Ic cd 2045command will print out the name of the directory 2046that it actually switched to 2047if the 2048.Va CDPATH 2049mechanism was used or if 2050.Ar directory 2051was 2052.Fl . 2053.Pp 2054If the 2055.Fl P 2056option is specified, 2057.Pa .. 2058is handled physically and symbolic links are resolved before 2059.Pa .. 2060components are processed. 2061If the 2062.Fl L 2063option is specified, 2064.Pa .. 2065is handled logically. 2066This is the default. 2067.Pp 2068The 2069.Fl e 2070option causes 2071.Ic cd 2072to return exit status 1 if the full pathname of the new directory 2073cannot be determined reliably or at all. 2074Normally this is not considered an error, 2075although a warning is printed. 2076.Pp 2077If changing the directory fails, the exit status is greater than 1. 2078If the directory is changed, the exit status is 0, or also 1 if 2079.Fl e 2080was given. 2081.It Ic chdir 2082A synonym for the 2083.Ic cd 2084built-in command. 2085.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... 2086.It Ic command Oo Fl p Oc Fl v Ar utility 2087.It Ic command Oo Fl p Oc Fl V Ar utility 2088The first form of invocation executes the specified 2089.Ar utility , 2090ignoring shell functions in the search. 2091If 2092.Ar utility 2093is a special builtin, 2094it is executed as if it were a regular builtin. 2095.Pp 2096If the 2097.Fl p 2098option is specified, the command search is performed using a 2099default value of 2100.Va PATH 2101that is guaranteed to find all of the standard utilities. 2102.Pp 2103If the 2104.Fl v 2105option is specified, 2106.Ar utility 2107is not executed but a description of its interpretation by the shell is 2108printed. 2109For ordinary commands the output is the path name; for shell built-in 2110commands, shell functions and keywords only the name is written. 2111Aliases are printed as 2112.Dq Ic alias Ar name Ns = Ns Ar value . 2113.Pp 2114The 2115.Fl V 2116option is identical to 2117.Fl v 2118except for the output. 2119It prints 2120.Dq Ar utility Ic is Ar description 2121where 2122.Ar description 2123is either 2124the path name to 2125.Ar utility , 2126a special shell builtin, 2127a shell builtin, 2128a shell function, 2129a shell keyword 2130or 2131an alias for 2132.Ar value . 2133.It Ic continue Op Ar num 2134See the 2135.Sx Flow-Control Constructs 2136subsection. 2137.It Ic echo Oo Fl e | n Oc Op Ar string ... 2138Print a space-separated list of the arguments to the standard output 2139and append a newline character. 2140.Bl -tag -width indent 2141.It Fl n 2142Suppress the output of the trailing newline. 2143.It Fl e 2144Process C-style backslash escape sequences. 2145The 2146.Ic echo 2147command understands the following character escapes: 2148.Bl -tag -width indent 2149.It \ea 2150Alert (ring the terminal bell) 2151.It \eb 2152Backspace 2153.It \ec 2154Suppress the trailing newline (this has the side-effect of truncating the 2155line if it is not the last character) 2156.It \ee 2157The ESC character (ASCII 0x1b) 2158.It \ef 2159Formfeed 2160.It \en 2161Newline 2162.It \er 2163Carriage return 2164.It \et 2165Horizontal tab 2166.It \ev 2167Vertical tab 2168.It \e\e 2169Literal backslash 2170.It \e0nnn 2171(Zero) The character whose octal value is 2172.Ar nnn 2173.El 2174.Pp 2175If 2176.Ar string 2177is not enclosed in quotes then the backslash itself must be escaped 2178with a backslash to protect it from the shell. 2179For example 2180.Bd -literal -offset indent 2181$ echo -e "a\evb" 2182a 2183 b 2184$ echo -e a\e\evb 2185a 2186 b 2187$ echo -e "a\e\eb" 2188a\eb 2189$ echo -e a\e\e\e\eb 2190a\eb 2191.Ed 2192.El 2193.Pp 2194Only one of the 2195.Fl e 2196and 2197.Fl n 2198options may be specified. 2199.It Ic eval Ar string ... 2200Concatenate all the arguments with spaces. 2201Then re-parse and execute the command. 2202.It Ic exec Op Ar command Op arg ... 2203Unless 2204.Ar command 2205is omitted, 2206the shell process is replaced with the specified program 2207(which must be a real program, not a shell built-in command or function). 2208Any redirections on the 2209.Ic exec 2210command are marked as permanent, 2211so that they are not undone when the 2212.Ic exec 2213command finishes. 2214.It Ic exit Op Ar exitstatus 2215Terminate the shell process. 2216If 2217.Ar exitstatus 2218is given 2219it is used as the exit status of the shell. 2220Otherwise, if the shell is executing an 2221.Cm EXIT 2222trap, the exit status of the last command before the trap is used; 2223if the shell is executing a trap for a signal, 2224the shell exits by resending the signal to itself. 2225Otherwise, the exit status of the preceding command is used. 2226The exit status should be an integer between 0 and 255. 2227.It Ic export Ar name ... 2228.It Ic export Op Fl p 2229The specified names are exported so that they will 2230appear in the environment of subsequent commands. 2231The only way to un-export a variable is to 2232.Ic unset 2233it. 2234The shell allows the value of a variable to be set 2235at the same time as it is exported by writing 2236.Pp 2237.D1 Ic export Ar name Ns = Ns Ar value 2238.Pp 2239With no arguments the 2240.Ic export 2241command lists the names 2242of all exported variables. 2243If the 2244.Fl p 2245option is specified, the exported variables are printed as 2246.Dq Ic export Ar name Ns = Ns Ar value 2247lines, suitable for re-input to the shell. 2248.It Ic false 2249A null command that returns a non-zero (false) exit value. 2250.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last 2251.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last 2252.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first 2253The 2254.Ic fc 2255built-in command lists, or edits and re-executes, 2256commands previously entered to an interactive shell. 2257.Bl -tag -width indent 2258.It Fl e Ar editor 2259Use the editor named by 2260.Ar editor 2261to edit the commands. 2262The 2263.Ar editor 2264string is a command name, 2265subject to search via the 2266.Va PATH 2267variable. 2268The value in the 2269.Va FCEDIT 2270variable is used as a default when 2271.Fl e 2272is not specified. 2273If 2274.Va FCEDIT 2275is null or unset, the value of the 2276.Va EDITOR 2277variable is used. 2278If 2279.Va EDITOR 2280is null or unset, 2281.Xr ed 1 2282is used as the editor. 2283.It Fl l No (ell) 2284List the commands rather than invoking 2285an editor on them. 2286The commands are written in the 2287sequence indicated by the 2288.Ar first 2289and 2290.Ar last 2291operands, as affected by 2292.Fl r , 2293with each command preceded by the command number. 2294.It Fl n 2295Suppress command numbers when listing with 2296.Fl l . 2297.It Fl r 2298Reverse the order of the commands listed 2299(with 2300.Fl l ) 2301or edited 2302(with neither 2303.Fl l 2304nor 2305.Fl s ) . 2306.It Fl s 2307Re-execute the command without invoking an editor. 2308.It Ar first 2309.It Ar last 2310Select the commands to list or edit. 2311The number of previous commands that can be accessed 2312are determined by the value of the 2313.Va HISTSIZE 2314variable. 2315The value of 2316.Ar first 2317or 2318.Ar last 2319or both are one of the following: 2320.Bl -tag -width indent 2321.It Oo Cm + Oc Ns Ar num 2322A positive number representing a command number; 2323command numbers can be displayed with the 2324.Fl l 2325option. 2326.It Fl Ar num 2327A negative decimal number representing the 2328command that was executed 2329.Ar num 2330of 2331commands previously. 2332For example, \-1 is the immediately previous command. 2333.It Ar string 2334A string indicating the most recently entered command 2335that begins with that string. 2336If the 2337.Ar old Ns = Ns Ar new 2338operand is not also specified with 2339.Fl s , 2340the string form of the first operand cannot contain an embedded equal sign. 2341.El 2342.El 2343.Pp 2344The following variables affect the execution of 2345.Ic fc : 2346.Bl -tag -width ".Va HISTSIZE" 2347.It Va FCEDIT 2348Name of the editor to use for history editing. 2349.It Va HISTSIZE 2350The number of previous commands that are accessible. 2351.El 2352.It Ic fg Op Ar job 2353Move the specified 2354.Ar job 2355or the current job to the foreground. 2356.It Ic getopts Ar optstring var 2357Parse command-line options and arguments. 2358The first argument 2359.Va optstring 2360should be a series of letters, each possibly 2361followed by a colon which indicates that the option takes an argument. 2362The specified variable 2363.Va var 2364is set to the parsed option. 2365The index of 2366the next argument is placed into the shell variable 2367.Va OPTIND . 2368If an option takes an argument, it is placed into the shell variable 2369.Va OPTARG . 2370.Pp 2371If the found character 2372is not specified by 2373.Va optstring 2374or if it is missing a required argument, 2375the option is considered invalid and: 2376.Bl -offset indent 2377.It 2378If the first character of 2379.Va optstring 2380is not a colon then 2381.Va OPTARG 2382is unset, 2383.Ar var 2384is set to 2385.Ql \&? 2386and a diagnostic message is written to stderr. 2387.It 2388If the first character of 2389.Va optstring 2390is a colon then 2391.Va OPTARG 2392is set to the the option character found, 2393.Ar var 2394is set to 2395.Ql \&: 2396when a required argument is missing or to 2397.Ql \&? 2398when the option was not specified by 2399.Va optstring , 2400and no diagnostic message is written to stderr. 2401.El 2402.Pp 2403.Ic getopts 2404returns a false value (1) when it encounters the end of the options. 2405A new set of arguments may be parsed by assigning 2406.Li OPTIND=1 . 2407The POSIX 2408.Ic getopts 2409command deprecates the older 2410.Xr getopt 1 2411command. 2412.It Ic hash Oo Fl rv Oc Op Ar command ... 2413The shell maintains a hash table which remembers the locations of commands. 2414With no arguments whatsoever, the 2415.Ic hash 2416command prints out the contents of this table. 2417.Pp 2418With arguments, the 2419.Ic hash 2420command removes each specified 2421.Ar command 2422from the hash table (unless they are functions) and then locates it. 2423With the 2424.Fl v 2425option, 2426.Ic hash 2427prints the locations of the commands as it finds them. 2428The 2429.Fl r 2430option causes the 2431.Ic hash 2432command to delete all the entries in the hash table except for functions. 2433.It Ic jobid Op Ar job 2434Print the process IDs of the processes in the specified 2435.Ar job . 2436If the 2437.Ar job 2438argument is omitted, use the current job. 2439.It Ic jobs Oo Fl lps Oc Op Ar job ... 2440Print information about the specified jobs, or all jobs if no 2441.Ar job 2442argument is given. 2443The information printed includes job ID, status and command name. 2444.Pp 2445If the 2446.Fl l 2447option is specified, the PID of each job is also printed. 2448If the 2449.Fl p 2450option is specified, only the process IDs for the process group leaders 2451are printed, one per line. 2452If the 2453.Fl s 2454option is specified, only the PIDs of the job commands are printed, one per 2455line. 2456.It Ic kill 2457A built-in equivalent of 2458.Xr kill 1 2459that additionally supports sending signals to jobs. 2460.It Ic local Oo Ar variable ... Oc Op Fl 2461See the 2462.Sx Functions 2463subsection. 2464.It Ic printf 2465A built-in equivalent of 2466.Xr printf 1 . 2467.It Ic pwd Op Fl L | P 2468Print the path of the current directory. 2469The built-in command may 2470differ from the program of the same name because the 2471built-in command remembers what the current directory 2472is rather than recomputing it each time. 2473This makes 2474it faster. 2475However, if the current directory is 2476renamed, 2477the built-in version of 2478.Xr pwd 1 2479will continue to print the old name for the directory. 2480.Pp 2481If the 2482.Fl P 2483option is specified, symbolic links are resolved. 2484If the 2485.Fl L 2486option is specified, the shell's notion of the current directory 2487is printed (symbolic links are not resolved). 2488This is the default. 2489.It Ic read Oo Fl p Ar prompt Oc Oo 2490.Fl t Ar timeout Oc Oo Fl er Oc Ar variable ... 2491The 2492.Ar prompt 2493is printed if the 2494.Fl p 2495option is specified 2496and the standard input is a terminal. 2497Then a line is 2498read from the standard input. 2499The trailing newline 2500is deleted from the line and the line is split as 2501described in the section on 2502.Sx White Space Splitting (Field Splitting)\& 2503above, and 2504the pieces are assigned to the variables in order. 2505If there are more pieces than variables, the remaining 2506pieces (along with the characters in 2507.Va IFS 2508that separated them) 2509are assigned to the last variable. 2510If there are more variables than pieces, the remaining 2511variables are assigned the null string. 2512.Pp 2513Backslashes are treated specially, unless the 2514.Fl r 2515option is 2516specified. 2517If a backslash is followed by 2518a newline, the backslash and the newline will be 2519deleted. 2520If a backslash is followed by any other 2521character, the backslash will be deleted and the following 2522character will be treated as though it were not in 2523.Va IFS , 2524even if it is. 2525.Pp 2526If the 2527.Fl t 2528option is specified and the 2529.Ar timeout 2530elapses before a complete line of input is supplied, 2531the 2532.Ic read 2533command will return an exit status as if terminated by 2534.Dv SIGALRM 2535without assigning any values. 2536The 2537.Ar timeout 2538value may optionally be followed by one of 2539.Ql s , 2540.Ql m 2541or 2542.Ql h 2543to explicitly specify seconds, minutes or hours. 2544If none is supplied, 2545.Ql s 2546is assumed. 2547.Pp 2548The 2549.Fl e 2550option exists only for backward compatibility with older scripts. 2551.Pp 2552The exit status is 0 on success, 1 on end of file, 2553between 2 and 128 if an error occurs 2554and greater than 128 if a trapped signal interrupts 2555.Ic read . 2556.It Ic readonly Oo Fl p Oc Op Ar name ... 2557Each specified 2558.Ar name 2559is marked as read only, 2560so that it cannot be subsequently modified or unset. 2561The shell allows the value of a variable to be set 2562at the same time as it is marked read only 2563by using the following form: 2564.Pp 2565.D1 Ic readonly Ar name Ns = Ns Ar value 2566.Pp 2567With no arguments the 2568.Ic readonly 2569command lists the names of all read only variables. 2570If the 2571.Fl p 2572option is specified, the read-only variables are printed as 2573.Dq Ic readonly Ar name Ns = Ns Ar value 2574lines, suitable for re-input to the shell. 2575.It Ic return Op Ar exitstatus 2576See the 2577.Sx Functions 2578subsection. 2579.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname 2580.Oc Op Fl - Ar arg ... 2581The 2582.Ic set 2583command performs three different functions: 2584.Bl -item 2585.It 2586With no arguments, it lists the values of all shell variables. 2587.It 2588If options are given, 2589either in short form or using the long 2590.Dq Fl /+o Ar longname 2591form, 2592it sets or clears the specified options as described in the section called 2593.Sx Argument List Processing . 2594.It 2595If the 2596.Dq Fl - 2597option is specified, 2598.Ic set 2599will replace the shell's positional parameters with the subsequent 2600arguments. 2601If no arguments follow the 2602.Dq Fl - 2603option, 2604all the positional parameters will be cleared, 2605which is equivalent to executing the command 2606.Dq Li "shift $#" . 2607The 2608.Dq Fl - 2609flag may be omitted when specifying arguments to be used 2610as positional replacement parameters. 2611This is not recommended, 2612because the first argument may begin with a dash 2613.Pq Ql - 2614or a plus 2615.Pq Ql + , 2616which the 2617.Ic set 2618command will interpret as a request to enable or disable options. 2619.El 2620.It Ic setvar Ar variable value 2621Assigns the specified 2622.Ar value 2623to the specified 2624.Ar variable . 2625The 2626.Ic setvar 2627command is intended to be used in functions that 2628assign values to variables whose names are passed as parameters. 2629In general it is better to write 2630.Dq Ar variable Ns = Ns Ar value 2631rather than using 2632.Ic setvar . 2633.It Ic shift Op Ar n 2634Shift the positional parameters 2635.Ar n 2636times, or once if 2637.Ar n 2638is not specified. 2639A shift sets the value of 2640.Li $1 2641to the value of 2642.Li $2 , 2643the value of 2644.Li $2 2645to the value of 2646.Li $3 , 2647and so on, 2648decreasing the value of 2649.Li $# 2650by one. 2651For portability, shifting if there are zero positional parameters 2652should be avoided, since the shell may abort. 2653.It Ic test 2654A built-in equivalent of 2655.Xr test 1 . 2656.It Ic times 2657Print the amount of time spent executing the shell process and its children. 2658The first output line shows the user and system times for the shell process 2659itself, the second one contains the user and system times for the 2660children. 2661.It Ic trap Oo Ar action Oc Ar signal ... 2662.It Ic trap Fl l 2663Cause the shell to parse and execute 2664.Ar action 2665when any specified 2666.Ar signal 2667is received. 2668The signals are specified by name or number. 2669In addition, the pseudo-signal 2670.Cm EXIT 2671may be used to specify an 2672.Ar action 2673that is performed when the shell terminates. 2674The 2675.Ar action 2676may be an empty string or a dash 2677.Pq Ql - ; 2678the former causes the specified signal to be ignored 2679and the latter causes the default action to be taken. 2680Omitting the 2681.Ar action 2682and using only signal numbers is another way to request the default action. 2683In a subshell or utility environment, 2684the shell resets trapped (but not ignored) signals to the default action. 2685The 2686.Ic trap 2687command has no effect on signals that were ignored on entry to the shell. 2688.Pp 2689Option 2690.Fl l 2691causes the 2692.Ic trap 2693command to display a list of valid signal names. 2694.It Ic true 2695A null command that returns a 0 (true) exit value. 2696.It Ic type Op Ar name ... 2697Interpret each 2698.Ar name 2699as a command and print the resolution of the command search. 2700Possible resolutions are: 2701shell keyword, alias, special shell builtin, shell builtin, command, 2702tracked alias 2703and not found. 2704For aliases the alias expansion is printed; 2705for commands and tracked aliases 2706the complete pathname of the command is printed. 2707.It Ic ulimit Oo Fl HSabcdfklmnopstuvw Oc Op Ar limit 2708Set or display resource limits (see 2709.Xr getrlimit 2 ) . 2710If 2711.Ar limit 2712is specified, the named resource will be set; 2713otherwise the current resource value will be displayed. 2714.Pp 2715If 2716.Fl H 2717is specified, the hard limits will be set or displayed. 2718While everybody is allowed to reduce a hard limit, 2719only the superuser can increase it. 2720The 2721.Fl S 2722option 2723specifies the soft limits instead. 2724When displaying limits, 2725only one of 2726.Fl S 2727or 2728.Fl H 2729can be given. 2730The default is to display the soft limits, 2731and to set both the hard and the soft limits. 2732.Pp 2733Option 2734.Fl a 2735causes the 2736.Ic ulimit 2737command to display all resources. 2738The parameter 2739.Ar limit 2740is not acceptable in this mode. 2741.Pp 2742The remaining options specify which resource value is to be 2743displayed or modified. 2744They are mutually exclusive. 2745.Bl -tag -width indent 2746.It Fl b Ar sbsize 2747The maximum size of socket buffer usage, in bytes. 2748.It Fl c Ar coredumpsize 2749The maximal size of core dump files, in 512-byte blocks. 2750Setting 2751.Ar coredumpsize 2752to 0 prevents core dump files from being created. 2753.It Fl d Ar datasize 2754The maximal size of the data segment of a process, in kilobytes. 2755.It Fl f Ar filesize 2756The maximal size of a file, in 512-byte blocks. 2757.It Fl k Ar kqueues 2758The maximal number of kqueues 2759(see 2760.Xr kqueue 2 ) 2761for this user ID. 2762.It Fl l Ar lockedmem 2763The maximal size of memory that can be locked by a process, in 2764kilobytes. 2765.It Fl m Ar memoryuse 2766The maximal resident set size of a process, in kilobytes. 2767.It Fl n Ar nofiles 2768The maximal number of descriptors that could be opened by a process. 2769.It Fl o Ar umtxp 2770The maximal number of process-shared locks 2771(see 2772.Xr pthread 3 ) 2773for this user ID. 2774.It Fl p Ar pseudoterminals 2775The maximal number of pseudo-terminals for this user ID. 2776.It Fl s Ar stacksize 2777The maximal size of the stack segment, in kilobytes. 2778.It Fl t Ar time 2779The maximal amount of CPU time to be used by each process, in seconds. 2780.It Fl u Ar userproc 2781The maximal number of simultaneous processes for this user ID. 2782.It Fl v Ar virtualmem 2783The maximal virtual size of a process, in kilobytes. 2784.It Fl w Ar swapuse 2785The maximum amount of swap space reserved or used for this user ID, 2786in kilobytes. 2787.El 2788.It Ic umask Oo Fl S Oc Op Ar mask 2789Set the file creation mask (see 2790.Xr umask 2 ) 2791to the octal or symbolic (see 2792.Xr chmod 1 ) 2793value specified by 2794.Ar mask . 2795If the argument is omitted, the current mask value is printed. 2796If the 2797.Fl S 2798option is specified, the output is symbolic, otherwise the output is octal. 2799.It Ic unalias Oo Fl a Oc Op Ar name ... 2800The specified alias names are removed. 2801If 2802.Fl a 2803is specified, all aliases are removed. 2804.It Ic unset Oo Fl fv Oc Ar name ... 2805The specified variables or functions are unset and unexported. 2806If the 2807.Fl v 2808option is specified or no options are given, the 2809.Ar name 2810arguments are treated as variable names. 2811If the 2812.Fl f 2813option is specified, the 2814.Ar name 2815arguments are treated as function names. 2816.It Ic wait Op Ar job ... 2817Wait for each specified 2818.Ar job 2819to complete and return the exit status of the last process in the 2820last specified 2821.Ar job . 2822If any 2823.Ar job 2824specified is unknown to the shell, it is treated as if it 2825were a known job that exited with exit status 127. 2826If no operands are given, wait for all jobs to complete 2827and return an exit status of zero. 2828.El 2829.Ss Command Line Editing 2830When 2831.Nm 2832is being used interactively from a terminal, the current command 2833and the command history 2834(see 2835.Ic fc 2836in 2837.Sx Built-in Commands ) 2838can be edited using 2839.Nm vi Ns -mode 2840command line editing. 2841This mode uses commands similar 2842to a subset of those described in the 2843.Xr vi 1 2844man page. 2845The command 2846.Dq Li "set -o vi" 2847(or 2848.Dq Li "set -V" ) 2849enables 2850.Nm vi Ns -mode 2851editing and places 2852.Nm 2853into 2854.Nm vi 2855insert mode. 2856With 2857.Nm vi Ns -mode 2858enabled, 2859.Nm 2860can be switched between insert mode and command mode by typing 2861.Aq ESC . 2862Hitting 2863.Aq return 2864while in command mode will pass the line to the shell. 2865.Pp 2866Similarly, the 2867.Dq Li "set -o emacs" 2868(or 2869.Dq Li "set -E" ) 2870command can be used to enable a subset of 2871.Nm emacs Ns -style 2872command line editing features. 2873.Sh ENVIRONMENT 2874The following environment variables affect the execution of 2875.Nm : 2876.Bl -tag -width ".Ev LANGXXXXXX" 2877.It Ev ENV 2878Initialization file for interactive shells. 2879.It Ev LANG , Ev LC_* 2880Locale settings. 2881These are inherited by children of the shell, 2882and is used in a limited manner by the shell itself. 2883.It Ev OLDPWD 2884The previous current directory. 2885This is used and updated by 2886.Ic cd . 2887.It Ev PWD 2888An absolute pathname for the current directory, 2889possibly containing symbolic links. 2890This is used and updated by the shell. 2891.It Ev TERM 2892The default terminal setting for the shell. 2893This is inherited by children of the shell, and is used in the history 2894editing modes. 2895.El 2896.Pp 2897Additionally, environment variables are turned into shell variables 2898at startup, 2899which may affect the shell as described under 2900.Sx Special Variables . 2901.Sh FILES 2902.Bl -tag -width "/etc/suid_profileXX" -compact 2903.It Pa ~/.profile 2904User's login profile. 2905.It Pa /etc/profile 2906System login profile. 2907.It Pa /etc/shells 2908Shell database. 2909.It Pa /etc/suid_profile 2910Privileged shell profile. 2911.El 2912.Sh EXIT STATUS 2913If the 2914.Ar script 2915cannot be found, the exit status will be 127; 2916if it cannot be opened for another reason, the exit status will be 126. 2917Other errors that are detected by the shell, such as a syntax error, will 2918cause the shell to exit with a non-zero exit status. 2919If the shell is not an interactive shell, the execution of the shell 2920file will be aborted. 2921Otherwise the shell will return the exit status of the last command 2922executed, or if the 2923.Ic exit 2924builtin is used with a numeric argument, it 2925will return the argument. 2926.Sh SEE ALSO 2927.Xr builtin 1 , 2928.Xr chsh 1 , 2929.Xr echo 1 , 2930.Xr ed 1 , 2931.Xr emacs 1 Pq Pa ports/editors/emacs , 2932.Xr kill 1 , 2933.Xr printf 1 , 2934.Xr pwd 1 , 2935.Xr test 1 , 2936.Xr vi 1 , 2937.Xr execve 2 , 2938.Xr getrlimit 2 , 2939.Xr umask 2 , 2940.Xr wctype 3 , 2941.Xr editrc 5 , 2942.Xr shells 5 2943.Sh HISTORY 2944A 2945.Nm 2946command, the Thompson shell, appeared in 2947.At v1 . 2948It was superseded in 2949.At v7 2950by the Bourne shell, which inherited the name 2951.Nm . 2952.Pp 2953This version of 2954.Nm 2955was rewritten in 1989 under the 2956.Bx 2957license after the Bourne shell from 2958.At V.4 2959and first appeared in 2960.Bx 4.3 Net/2 . 2961.Sh AUTHORS 2962This version of 2963.Nm 2964was originally written by 2965.An Kenneth Almquist . 2966.Sh BUGS 2967The 2968.Nm 2969utility does not recognize multibyte characters other than UTF-8. 2970Splitting using 2971.Va IFS 2972does not recognize multibyte characters. 2973