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