1.\"- 2.\" Copyright (c) 1991, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" Kenneth Almquist. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" from: @(#)sh.1 8.6 (Berkeley) 5/4/95 33.\" $FreeBSD$ 34.\" 35.Dd August 29, 2015 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 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 Ns Li ) 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. 1352The default value is 1353.Aq space , 1354.Aq tab , 1355and 1356.Aq newline 1357in that order. 1358This default 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 1406The local hostname. 1407.It Li \eh 1408The fully-qualified 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 1955Switch to the specified 1956.Ar directory , 1957or to the directory specified in the 1958.Va HOME 1959environment variable if no 1960.Ar directory 1961is specified. 1962If 1963.Ar directory 1964does not begin with 1965.Pa / , \&. , 1966or 1967.Pa .. , 1968then the directories listed in the 1969.Va CDPATH 1970variable will be 1971searched for the specified 1972.Ar directory . 1973If 1974.Va CDPATH 1975is unset, the current directory is searched. 1976The format of 1977.Va CDPATH 1978is the same as that of 1979.Va PATH . 1980In an interactive shell, 1981the 1982.Ic cd 1983command will print out the name of the directory 1984that it actually switched to 1985if this is different from the name that the user gave. 1986These may be different either because the 1987.Va CDPATH 1988mechanism was used or because a symbolic link was crossed. 1989.Pp 1990If the 1991.Fl P 1992option is specified, 1993.Pa .. 1994is handled physically and symbolic links are resolved before 1995.Pa .. 1996components are processed. 1997If the 1998.Fl L 1999option is specified, 2000.Pa .. 2001is handled logically. 2002This is the default. 2003.Pp 2004The 2005.Fl e 2006option causes 2007.Ic cd 2008to return exit status 1 if the full pathname of the new directory 2009cannot be determined reliably or at all. 2010Normally this is not considered an error, 2011although a warning is printed. 2012.It Ic chdir 2013A synonym for the 2014.Ic cd 2015built-in command. 2016.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... 2017.It Ic command Oo Fl p Oc Fl v Ar utility 2018.It Ic command Oo Fl p Oc Fl V Ar utility 2019The first form of invocation executes the specified 2020.Ar utility , 2021ignoring shell functions in the search. 2022If 2023.Ar utility 2024is a special builtin, 2025it is executed as if it were a regular builtin. 2026.Pp 2027If the 2028.Fl p 2029option is specified, the command search is performed using a 2030default value of 2031.Va PATH 2032that is guaranteed to find all of the standard utilities. 2033.Pp 2034If the 2035.Fl v 2036option is specified, 2037.Ar utility 2038is not executed but a description of its interpretation by the shell is 2039printed. 2040For ordinary commands the output is the path name; for shell built-in 2041commands, shell functions and keywords only the name is written. 2042Aliases are printed as 2043.Dq Ic alias Ar name Ns = Ns Ar value . 2044.Pp 2045The 2046.Fl V 2047option is identical to 2048.Fl v 2049except for the output. 2050It prints 2051.Dq Ar utility Ic is Ar description 2052where 2053.Ar description 2054is either 2055the path name to 2056.Ar utility , 2057a special shell builtin, 2058a shell builtin, 2059a shell function, 2060a shell keyword 2061or 2062an alias for 2063.Ar value . 2064.It Ic continue Op Ar num 2065See the 2066.Sx Flow-Control Constructs 2067subsection. 2068.It Ic echo Oo Fl e | n Oc Op Ar string ... 2069Print a space-separated list of the arguments to the standard output 2070and append a newline character. 2071.Bl -tag -width indent 2072.It Fl n 2073Suppress the output of the trailing newline. 2074.It Fl e 2075Process C-style backslash escape sequences. 2076The 2077.Ic echo 2078command understands the following character escapes: 2079.Bl -tag -width indent 2080.It \ea 2081Alert (ring the terminal bell) 2082.It \eb 2083Backspace 2084.It \ec 2085Suppress the trailing newline (this has the side-effect of truncating the 2086line if it is not the last character) 2087.It \ee 2088The ESC character 2089.Tn ( ASCII 20900x1b) 2091.It \ef 2092Formfeed 2093.It \en 2094Newline 2095.It \er 2096Carriage return 2097.It \et 2098Horizontal tab 2099.It \ev 2100Vertical tab 2101.It \e\e 2102Literal backslash 2103.It \e0nnn 2104(Zero) The character whose octal value is 2105.Ar nnn 2106.El 2107.Pp 2108If 2109.Ar string 2110is not enclosed in quotes then the backslash itself must be escaped 2111with a backslash to protect it from the shell. 2112For example 2113.Bd -literal -offset indent 2114$ echo -e "a\evb" 2115a 2116 b 2117$ echo -e a\e\evb 2118a 2119 b 2120$ echo -e "a\e\eb" 2121a\eb 2122$ echo -e a\e\e\e\eb 2123a\eb 2124.Ed 2125.El 2126.Pp 2127Only one of the 2128.Fl e 2129and 2130.Fl n 2131options may be specified. 2132.It Ic eval Ar string ... 2133Concatenate all the arguments with spaces. 2134Then re-parse and execute the command. 2135.It Ic exec Op Ar command Op arg ... 2136Unless 2137.Ar command 2138is omitted, 2139the shell process is replaced with the specified program 2140(which must be a real program, not a shell built-in command or function). 2141Any redirections on the 2142.Ic exec 2143command are marked as permanent, 2144so that they are not undone when the 2145.Ic exec 2146command finishes. 2147.It Ic exit Op Ar exitstatus 2148Terminate the shell process. 2149If 2150.Ar exitstatus 2151is given 2152it is used as the exit status of the shell. 2153Otherwise, if the shell is executing an 2154.Cm EXIT 2155trap, the exit status of the last command before the trap is used; 2156if the shell is executing a trap for a signal, 2157the shell exits by resending the signal to itself. 2158Otherwise, the exit status of the preceding command is used. 2159The exit status should be an integer between 0 and 255. 2160.It Ic export Ar name ... 2161.It Ic export Op Fl p 2162The specified names are exported so that they will 2163appear in the environment of subsequent commands. 2164The only way to un-export a variable is to 2165.Ic unset 2166it. 2167The shell allows the value of a variable to be set 2168at the same time as it is exported by writing 2169.Pp 2170.D1 Ic export Ar name Ns = Ns Ar value 2171.Pp 2172With no arguments the 2173.Ic export 2174command lists the names 2175of all exported variables. 2176If the 2177.Fl p 2178option is specified, the exported variables are printed as 2179.Dq Ic export Ar name Ns = Ns Ar value 2180lines, suitable for re-input to the shell. 2181.It Ic false 2182A null command that returns a non-zero (false) exit value. 2183.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last 2184.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last 2185.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first 2186The 2187.Ic fc 2188built-in command lists, or edits and re-executes, 2189commands previously entered to an interactive shell. 2190.Bl -tag -width indent 2191.It Fl e Ar editor 2192Use the editor named by 2193.Ar editor 2194to edit the commands. 2195The 2196.Ar editor 2197string is a command name, 2198subject to search via the 2199.Va PATH 2200variable. 2201The value in the 2202.Va FCEDIT 2203variable is used as a default when 2204.Fl e 2205is not specified. 2206If 2207.Va FCEDIT 2208is null or unset, the value of the 2209.Va EDITOR 2210variable is used. 2211If 2212.Va EDITOR 2213is null or unset, 2214.Xr ed 1 2215is used as the editor. 2216.It Fl l No (ell) 2217List the commands rather than invoking 2218an editor on them. 2219The commands are written in the 2220sequence indicated by the 2221.Ar first 2222and 2223.Ar last 2224operands, as affected by 2225.Fl r , 2226with each command preceded by the command number. 2227.It Fl n 2228Suppress command numbers when listing with 2229.Fl l . 2230.It Fl r 2231Reverse the order of the commands listed 2232(with 2233.Fl l ) 2234or edited 2235(with neither 2236.Fl l 2237nor 2238.Fl s ) . 2239.It Fl s 2240Re-execute the command without invoking an editor. 2241.It Ar first 2242.It Ar last 2243Select the commands to list or edit. 2244The number of previous commands that can be accessed 2245are determined by the value of the 2246.Va HISTSIZE 2247variable. 2248The value of 2249.Ar first 2250or 2251.Ar last 2252or both are one of the following: 2253.Bl -tag -width indent 2254.It Oo Cm + Oc Ns Ar num 2255A positive number representing a command number; 2256command numbers can be displayed with the 2257.Fl l 2258option. 2259.It Fl Ar num 2260A negative decimal number representing the 2261command that was executed 2262.Ar num 2263of 2264commands previously. 2265For example, \-1 is the immediately previous command. 2266.It Ar string 2267A string indicating the most recently entered command 2268that begins with that string. 2269If the 2270.Ar old Ns = Ns Ar new 2271operand is not also specified with 2272.Fl s , 2273the string form of the first operand cannot contain an embedded equal sign. 2274.El 2275.El 2276.Pp 2277The following variables affect the execution of 2278.Ic fc : 2279.Bl -tag -width ".Va HISTSIZE" 2280.It Va FCEDIT 2281Name of the editor to use for history editing. 2282.It Va HISTSIZE 2283The number of previous commands that are accessible. 2284.El 2285.It Ic fg Op Ar job 2286Move the specified 2287.Ar job 2288or the current job to the foreground. 2289.It Ic getopts Ar optstring var 2290The 2291.Tn POSIX 2292.Ic getopts 2293command. 2294The 2295.Ic getopts 2296command deprecates the older 2297.Xr getopt 1 2298command. 2299The first argument should be a series of letters, each possibly 2300followed by a colon which indicates that the option takes an argument. 2301The specified variable is set to the parsed option. 2302The index of 2303the next argument is placed into the shell variable 2304.Va OPTIND . 2305If an option takes an argument, it is placed into the shell variable 2306.Va OPTARG . 2307If an invalid option is encountered, 2308.Ar var 2309is set to 2310.Ql \&? . 2311It returns a false value (1) when it encounters the end of the options. 2312A new set of arguments may be parsed by assigning 2313.Li OPTIND=1 . 2314.It Ic hash Oo Fl rv Oc Op Ar command ... 2315The shell maintains a hash table which remembers the locations of commands. 2316With no arguments whatsoever, the 2317.Ic hash 2318command prints out the contents of this table. 2319.Pp 2320With arguments, the 2321.Ic hash 2322command removes each specified 2323.Ar command 2324from the hash table (unless they are functions) and then locates it. 2325With the 2326.Fl v 2327option, 2328.Ic hash 2329prints the locations of the commands as it finds them. 2330The 2331.Fl r 2332option causes the 2333.Ic hash 2334command to delete all the entries in the hash table except for functions. 2335.It Ic jobid Op Ar job 2336Print the process IDs of the processes in the specified 2337.Ar job . 2338If the 2339.Ar job 2340argument is omitted, use the current job. 2341.It Ic jobs Oo Fl lps Oc Op Ar job ... 2342Print information about the specified jobs, or all jobs if no 2343.Ar job 2344argument is given. 2345The information printed includes job ID, status and command name. 2346.Pp 2347If the 2348.Fl l 2349option is specified, the PID of each job is also printed. 2350If the 2351.Fl p 2352option is specified, only the process IDs for the process group leaders 2353are printed, one per line. 2354If the 2355.Fl s 2356option is specified, only the PIDs of the job commands are printed, one per 2357line. 2358.It Ic kill 2359A built-in equivalent of 2360.Xr kill 1 2361that additionally supports sending signals to jobs. 2362.It Ic local Oo Ar variable ... Oc Op Fl 2363See the 2364.Sx Functions 2365subsection. 2366.It Ic printf 2367A built-in equivalent of 2368.Xr printf 1 . 2369.It Ic pwd Op Fl L | P 2370Print the path of the current directory. 2371The built-in command may 2372differ from the program of the same name because the 2373built-in command remembers what the current directory 2374is rather than recomputing it each time. 2375This makes 2376it faster. 2377However, if the current directory is 2378renamed, 2379the built-in version of 2380.Xr pwd 1 2381will continue to print the old name for the directory. 2382.Pp 2383If the 2384.Fl P 2385option is specified, symbolic links are resolved. 2386If the 2387.Fl L 2388option is specified, the shell's notion of the current directory 2389is printed (symbolic links are not resolved). 2390This is the default. 2391.It Ic read Oo Fl p Ar prompt Oc Oo 2392.Fl t Ar timeout Oc Oo Fl er Oc Ar variable ... 2393The 2394.Ar prompt 2395is printed if the 2396.Fl p 2397option is specified 2398and the standard input is a terminal. 2399Then a line is 2400read from the standard input. 2401The trailing newline 2402is deleted from the line and the line is split as 2403described in the section on 2404.Sx White Space Splitting (Field Splitting) 2405above, and 2406the pieces are assigned to the variables in order. 2407If there are more pieces than variables, the remaining 2408pieces (along with the characters in 2409.Va IFS 2410that separated them) 2411are assigned to the last variable. 2412If there are more variables than pieces, the remaining 2413variables are assigned the null string. 2414.Pp 2415Backslashes are treated specially, unless the 2416.Fl r 2417option is 2418specified. 2419If a backslash is followed by 2420a newline, the backslash and the newline will be 2421deleted. 2422If a backslash is followed by any other 2423character, the backslash will be deleted and the following 2424character will be treated as though it were not in 2425.Va IFS , 2426even if it is. 2427.Pp 2428If the 2429.Fl t 2430option is specified and the 2431.Ar timeout 2432elapses before a complete line of input is supplied, 2433the 2434.Ic read 2435command will return an exit status as if terminated by 2436.Dv SIGALRM 2437without assigning any values. 2438The 2439.Ar timeout 2440value may optionally be followed by one of 2441.Ql s , 2442.Ql m 2443or 2444.Ql h 2445to explicitly specify seconds, minutes or hours. 2446If none is supplied, 2447.Ql s 2448is assumed. 2449.Pp 2450The 2451.Fl e 2452option exists only for backward compatibility with older scripts. 2453.Pp 2454The exit status is 0 on success, 1 on end of file, 2455between 2 and 128 if an error occurs 2456and greater than 128 if a trapped signal interrupts 2457.Ic read . 2458.It Ic readonly Oo Fl p Oc Op Ar name ... 2459Each specified 2460.Ar name 2461is marked as read only, 2462so that it cannot be subsequently modified or unset. 2463The shell allows the value of a variable to be set 2464at the same time as it is marked read only 2465by using the following form: 2466.Pp 2467.D1 Ic readonly Ar name Ns = Ns Ar value 2468.Pp 2469With no arguments the 2470.Ic readonly 2471command lists the names of all read only variables. 2472If the 2473.Fl p 2474option is specified, the read-only variables are printed as 2475.Dq Ic readonly Ar name Ns = Ns Ar value 2476lines, suitable for re-input to the shell. 2477.It Ic return Op Ar exitstatus 2478See the 2479.Sx Functions 2480subsection. 2481.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo 2482.Fl c Ar string Oc Op Fl - Ar arg ... 2483The 2484.Ic set 2485command performs three different functions: 2486.Bl -item 2487.It 2488With no arguments, it lists the values of all shell variables. 2489.It 2490If options are given, 2491either in short form or using the long 2492.Dq Fl /+o Ar longname 2493form, 2494it sets or clears the specified options as described in the section called 2495.Sx Argument List Processing . 2496.It 2497If the 2498.Dq Fl - 2499option is specified, 2500.Ic set 2501will replace the shell's positional parameters with the subsequent 2502arguments. 2503If no arguments follow the 2504.Dq Fl - 2505option, 2506all the positional parameters will be cleared, 2507which is equivalent to executing the command 2508.Dq Li "shift $#" . 2509The 2510.Dq Fl - 2511flag may be omitted when specifying arguments to be used 2512as positional replacement parameters. 2513This is not recommended, 2514because the first argument may begin with a dash 2515.Pq Ql - 2516or a plus 2517.Pq Ql + , 2518which the 2519.Ic set 2520command will interpret as a request to enable or disable options. 2521.El 2522.It Ic setvar Ar variable value 2523Assigns the specified 2524.Ar value 2525to the specified 2526.Ar variable . 2527The 2528.Ic setvar 2529command is intended to be used in functions that 2530assign values to variables whose names are passed as parameters. 2531In general it is better to write 2532.Dq Ar variable Ns = Ns Ar value 2533rather than using 2534.Ic setvar . 2535.It Ic shift Op Ar n 2536Shift the positional parameters 2537.Ar n 2538times, or once if 2539.Ar n 2540is not specified. 2541A shift sets the value of 2542.Li $1 2543to the value of 2544.Li $2 , 2545the value of 2546.Li $2 2547to the value of 2548.Li $3 , 2549and so on, 2550decreasing the value of 2551.Li $# 2552by one. 2553For portability, shifting if there are zero positional parameters 2554should be avoided, since the shell may abort. 2555.It Ic test 2556A built-in equivalent of 2557.Xr test 1 . 2558.It Ic times 2559Print the amount of time spent executing the shell process and its children. 2560The first output line shows the user and system times for the shell process 2561itself, the second one contains the user and system times for the 2562children. 2563.It Ic trap Oo Ar action Oc Ar signal ... 2564.It Ic trap Fl l 2565Cause the shell to parse and execute 2566.Ar action 2567when any specified 2568.Ar signal 2569is received. 2570The signals are specified by name or number. 2571In addition, the pseudo-signal 2572.Cm EXIT 2573may be used to specify an 2574.Ar action 2575that is performed when the shell terminates. 2576The 2577.Ar action 2578may be an empty string or a dash 2579.Pq Ql - ; 2580the former causes the specified signal to be ignored 2581and the latter causes the default action to be taken. 2582Omitting the 2583.Ar action 2584and using only signal numbers is another way to request the default action. 2585In a subshell or utility environment, 2586the shell resets trapped (but not ignored) signals to the default action. 2587The 2588.Ic trap 2589command has no effect on signals that were ignored on entry to the shell. 2590.Pp 2591Option 2592.Fl l 2593causes the 2594.Ic trap 2595command to display a list of valid signal names. 2596.It Ic true 2597A null command that returns a 0 (true) exit value. 2598.It Ic type Op Ar name ... 2599Interpret each 2600.Ar name 2601as a command and print the resolution of the command search. 2602Possible resolutions are: 2603shell keyword, alias, special shell builtin, shell builtin, command, 2604tracked alias 2605and not found. 2606For aliases the alias expansion is printed; 2607for commands and tracked aliases 2608the complete pathname of the command is printed. 2609.It Ic ulimit Oo Fl HSabcdfklmnpstuvw Oc Op Ar limit 2610Set or display resource limits (see 2611.Xr getrlimit 2 ) . 2612If 2613.Ar limit 2614is specified, the named resource will be set; 2615otherwise the current resource value will be displayed. 2616.Pp 2617If 2618.Fl H 2619is specified, the hard limits will be set or displayed. 2620While everybody is allowed to reduce a hard limit, 2621only the superuser can increase it. 2622The 2623.Fl S 2624option 2625specifies the soft limits instead. 2626When displaying limits, 2627only one of 2628.Fl S 2629or 2630.Fl H 2631can be given. 2632The default is to display the soft limits, 2633and to set both the hard and the soft limits. 2634.Pp 2635Option 2636.Fl a 2637causes the 2638.Ic ulimit 2639command to display all resources. 2640The parameter 2641.Ar limit 2642is not acceptable in this mode. 2643.Pp 2644The remaining options specify which resource value is to be 2645displayed or modified. 2646They are mutually exclusive. 2647.Bl -tag -width indent 2648.It Fl b Ar sbsize 2649The maximum size of socket buffer usage, in bytes. 2650.It Fl c Ar coredumpsize 2651The maximal size of core dump files, in 512-byte blocks. 2652.It Fl d Ar datasize 2653The maximal size of the data segment of a process, in kilobytes. 2654.It Fl f Ar filesize 2655The maximal size of a file, in 512-byte blocks. 2656.It Fl k Ar kqueues 2657The maximal number of kqueues 2658(see 2659.Xr kqueue 2 ) 2660for this user ID. 2661.It Fl l Ar lockedmem 2662The maximal size of memory that can be locked by a process, in 2663kilobytes. 2664.It Fl m Ar memoryuse 2665The maximal resident set size of a process, in kilobytes. 2666.It Fl n Ar nofiles 2667The maximal number of descriptors that could be opened by a process. 2668.It Fl p Ar pseudoterminals 2669The maximal number of pseudo-terminals for this user ID. 2670.It Fl s Ar stacksize 2671The maximal size of the stack segment, in kilobytes. 2672.It Fl t Ar time 2673The maximal amount of CPU time to be used by each process, in seconds. 2674.It Fl u Ar userproc 2675The maximal number of simultaneous processes for this user ID. 2676.It Fl v Ar virtualmem 2677The maximal virtual size of a process, in kilobytes. 2678.It Fl w Ar swapuse 2679The maximum amount of swap space reserved or used for this user ID, 2680in kilobytes. 2681.El 2682.It Ic umask Oo Fl S Oc Op Ar mask 2683Set the file creation mask (see 2684.Xr umask 2 ) 2685to the octal or symbolic (see 2686.Xr chmod 1 ) 2687value specified by 2688.Ar mask . 2689If the argument is omitted, the current mask value is printed. 2690If the 2691.Fl S 2692option is specified, the output is symbolic, otherwise the output is octal. 2693.It Ic unalias Oo Fl a Oc Op Ar name ... 2694The specified alias names are removed. 2695If 2696.Fl a 2697is specified, all aliases are removed. 2698.It Ic unset Oo Fl fv Oc Ar name ... 2699The specified variables or functions are unset and unexported. 2700If the 2701.Fl v 2702option is specified or no options are given, the 2703.Ar name 2704arguments are treated as variable names. 2705If the 2706.Fl f 2707option is specified, the 2708.Ar name 2709arguments are treated as function names. 2710.It Ic wait Op Ar job ... 2711Wait for each specified 2712.Ar job 2713to complete and return the exit status of the last process in the 2714last specified 2715.Ar job . 2716If any 2717.Ar job 2718specified is unknown to the shell, it is treated as if it 2719were a known job that exited with exit status 127. 2720If no operands are given, wait for all jobs to complete 2721and return an exit status of zero. 2722.El 2723.Ss Commandline Editing 2724When 2725.Nm 2726is being used interactively from a terminal, the current command 2727and the command history 2728(see 2729.Ic fc 2730in 2731.Sx Built-in Commands ) 2732can be edited using 2733.Nm vi Ns -mode 2734command line editing. 2735This mode uses commands similar 2736to a subset of those described in the 2737.Xr vi 1 2738man page. 2739The command 2740.Dq Li "set -o vi" 2741(or 2742.Dq Li "set -V" ) 2743enables 2744.Nm vi Ns -mode 2745editing and places 2746.Nm 2747into 2748.Nm vi 2749insert mode. 2750With 2751.Nm vi Ns -mode 2752enabled, 2753.Nm 2754can be switched between insert mode and command mode by typing 2755.Aq ESC . 2756Hitting 2757.Aq return 2758while in command mode will pass the line to the shell. 2759.Pp 2760Similarly, the 2761.Dq Li "set -o emacs" 2762(or 2763.Dq Li "set -E" ) 2764command can be used to enable a subset of 2765.Nm emacs Ns -style 2766command line editing features. 2767.Sh ENVIRONMENT 2768The following environment variables affect the execution of 2769.Nm : 2770.Bl -tag -width ".Ev LANGXXXXXX" 2771.It Ev ENV 2772Initialization file for interactive shells. 2773.It Ev LANG , Ev LC_* 2774Locale settings. 2775These are inherited by children of the shell, 2776and is used in a limited manner by the shell itself. 2777.It Ev PWD 2778An absolute pathname for the current directory, 2779possibly containing symbolic links. 2780This is used and updated by the shell. 2781.It Ev TERM 2782The default terminal setting for the shell. 2783This is inherited by children of the shell, and is used in the history 2784editing modes. 2785.El 2786.Pp 2787Additionally, environment variables are turned into shell variables 2788at startup, 2789which may affect the shell as described under 2790.Sx Special Variables . 2791.Sh FILES 2792.Bl -tag -width "/etc/suid_profileXX" -compact 2793.It Pa ~/.profile 2794User's login profile. 2795.It Pa /etc/profile 2796System login profile. 2797.It Pa /etc/shells 2798Shell database. 2799.It Pa /etc/suid_profile 2800Privileged shell profile. 2801.El 2802.Sh EXIT STATUS 2803Errors that are detected by the shell, such as a syntax error, will 2804cause the shell to exit with a non-zero exit status. 2805If the shell is not an interactive shell, the execution of the shell 2806file will be aborted. 2807Otherwise the shell will return the exit status of the last command 2808executed, or if the 2809.Ic exit 2810builtin is used with a numeric argument, it 2811will return the argument. 2812.Sh SEE ALSO 2813.Xr builtin 1 , 2814.Xr chsh 1 , 2815.Xr echo 1 , 2816.Xr ed 1 , 2817.Xr emacs 1 , 2818.Xr kill 1 , 2819.Xr printf 1 , 2820.Xr pwd 1 , 2821.Xr test 1 , 2822.Xr vi 1 , 2823.Xr execve 2 , 2824.Xr getrlimit 2 , 2825.Xr umask 2 , 2826.Xr wctype 3 , 2827.Xr editrc 5 , 2828.Xr shells 5 2829.Sh HISTORY 2830A 2831.Nm 2832command, the Thompson shell, appeared in 2833.At v1 . 2834It was superseded in 2835.At v7 2836by the Bourne shell, which inherited the name 2837.Nm . 2838.Pp 2839This version of 2840.Nm 2841was rewritten in 1989 under the 2842.Bx 2843license after the Bourne shell from 2844.At V.4 . 2845.Sh AUTHORS 2846This version of 2847.Nm 2848was originally written by 2849.An Kenneth Almquist . 2850.Sh BUGS 2851The 2852.Nm 2853utility does not recognize multibyte characters other than UTF-8. 2854Splitting using 2855.Va IFS 2856does not recognize multibyte characters. 2857