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