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