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