1.\" $NetBSD: sh.1,v 1.115 2015/05/26 21:35:15 christos Exp $ 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.\" @(#)sh.1 8.6 (Berkeley) 5/4/95 33.\" 34.Dd May 26, 2015 35.Dt SH 1 36.Os 37.Sh NAME 38.Nm sh 39.Nd command interpreter (shell) 40.Sh SYNOPSIS 41.Nm 42.Bk -words 43.Op Fl aCefnuvxIimqVEb 44.Op Cm +aCefnuvxIimqVEb 45.Ek 46.Bk -words 47.Op Fl o Ar option_name 48.Op Cm +o Ar option_name 49.Ek 50.Bk -words 51.Op Ar command_file Oo Ar argument ... Oc 52.Ek 53.Nm 54.Fl c 55.Bk -words 56.Op Fl abCEefnuvxIimpqV 57.Op Cm +abCEefnuvxIimpqV 58.Ek 59.Bk -words 60.Op Fl o Ar option_name 61.Op Cm +o Ar option_name 62.Ek 63.Bk -words 64.Ar command_string 65.Op Ar command_name Oo Ar argument ... Oc 66.Ek 67.Nm 68.Fl s 69.Bk -words 70.Op Fl abCEefnuvxIimpqV 71.Op Cm +abCEefnuvxIimpqV 72.Ek 73.Bk -words 74.Op Fl o Ar option_name 75.Op Cm +o Ar option_name 76.Ek 77.Bk -words 78.Op Ar argument ... 79.Ek 80.Sh DESCRIPTION 81.Nm 82is the standard command interpreter for the system. 83The current version of 84.Nm 85is in the process of being changed to conform with the 86.Tn POSIX 871003.2 and 1003.2a specifications for the shell. 88This version has many 89features which make it appear similar in some respects to the Korn shell, 90but it is not a Korn shell clone (see 91.Xr ksh 1 ) . 92Only features designated by 93.Tn POSIX , 94plus a few Berkeley extensions, are being incorporated into this shell. 95.\" We expect 96.\" .Tn POSIX 97.\" conformance by the time 4.4 BSD is released. 98This man page is not intended 99to be a tutorial or a complete specification of the shell. 100.Ss Overview 101The shell is a command that reads lines from either a file or the 102terminal, interprets them, and generally executes other commands. 103It is the program that is running when a user logs into the system 104(although a user can select a different shell with the 105.Xr chsh 1 106command). 107The shell implements a language that has flow control 108constructs, a macro facility that provides a variety of features in 109addition to data storage, along with built in history and line editing 110capabilities. 111It incorporates many features to aid interactive use and 112has the advantage that the interpretative language is common to both 113interactive and non-interactive use (shell scripts). 114That is, commands 115can be typed directly to the running shell or can be put into a file and 116the file can be executed directly by the shell. 117.Ss Invocation 118If no arguments are present and if the standard input of the shell 119is connected to a terminal (or if the 120.Fl i 121flag is set), 122and the 123.Fl c 124option is not present, the shell is considered an interactive shell. 125An interactive shell generally prompts before each command and handles 126programming and command errors differently (as described below). 127When first starting, 128the shell inspects argument 0, and if it begins with a dash 129.Sq - , 130the shell is also considered 131a login shell. 132This is normally done automatically by the system 133when the user first logs in. 134A login shell first reads commands 135from the files 136.Pa /etc/profile 137and 138.Pa .profile 139if they exist. 140If the environment variable 141.Ev ENV 142is set on entry to a shell, or is set in the 143.Pa .profile 144of a login shell, the shell next reads 145commands from the file named in 146.Ev ENV . 147Therefore, a user should place commands that are to be executed only at 148login time in the 149.Pa .profile 150file, and commands that are executed for every shell inside the 151.Ev ENV 152file. 153To set the 154.Ev ENV 155variable to some file, place the following line in your 156.Pa .profile 157of your home directory 158.Pp 159.Dl ENV=$HOME/.shinit; export ENV 160.Pp 161substituting for 162.Dq .shinit 163any filename you wish. 164Since the 165.Ev ENV 166file is read for every invocation of the shell, including shell scripts 167and non-interactive shells, the following paradigm is useful for 168restricting commands in the 169.Ev ENV 170file to interactive invocations. 171Place commands within the 172.Dq case 173and 174.Dq esac 175below (these commands are described later): 176.Pp 177.Bl -item -compact -offset indent 178.It 179.Li case $- in *i*) 180.Bl -item -compact -offset indent 181.It 182.Li # commands for interactive use only 183.It 184.Li ... 185.El 186.It 187.Li esac 188.El 189.Pp 190If command line arguments besides the options have been specified, then 191the shell treats the first argument as the name of a file from which to 192read commands (a shell script), and the remaining arguments are set as the 193positional parameters of the shell ($1, $2, etc). 194Otherwise, the shell 195reads commands from its standard input. 196.Ss Argument List Processing 197All of the single letter options have a corresponding name that can be 198used as an argument to the 199.Fl o 200option. 201The set 202.Fl o 203name is provided next to the single letter option in 204the description below. 205Specifying a dash 206.Dq - 207turns the option on, while using a plus 208.Dq + 209disables the option. 210The following options can be set from the command line or 211with the 212.Ic set 213built-in (described later). 214.Bl -tag -width aaaallexportfoo -offset indent 215.It Fl a Em allexport 216Export all variables assigned to. 217.It Fl c 218Read commands from the 219.Ar command_string 220operand instead of from the standard input. 221Special parameter 0 will be set from the 222.Ar command_name 223operand and the positional parameters ($1, $2, etc.) 224set from the remaining argument operands. 225.It Fl C Em noclobber 226Don't overwrite existing files with 227.Dq \*[Gt] . 228.It Fl e Em errexit 229If not interactive, exit immediately if any untested command fails. 230The exit status of a command is considered to be 231explicitly tested if the command is used to control an 232.Ic if , 233.Ic elif , 234.Ic while , 235or 236.Ic until , 237or if the command is the left hand operand of an 238.Dq \*[Am]\*[Am] 239or 240.Dq || 241operator. 242.It Fl f Em noglob 243Disable pathname expansion. 244.It Fl n Em noexec 245If not interactive, read commands but do not execute them. 246This is useful for checking the syntax of shell scripts. 247.It Fl u Em nounset 248Write a message to standard error when attempting to expand a variable 249that is not set, and if the shell is not interactive, exit immediately. 250.It Fl v Em verbose 251The shell writes its input to standard error as it is read. 252Useful for debugging. 253.It Fl x Em xtrace 254Write each command to standard error (preceded by a 255.Sq +\ ) 256before it is executed. 257Useful for debugging. 258.It Fl q Em quietprofile 259If the 260.Fl v 261or 262.Fl x 263options have been set, do not apply them when reading 264initialization files, these being 265.Pa /etc/profile , 266.Pa .profile , 267and the file specified by the 268.Ev ENV 269environment variable. 270.It Fl I Em ignoreeof 271Ignore EOFs from input when interactive. 272.It Fl i Em interactive 273Force the shell to behave interactively. 274.It Fl m Em monitor 275Turn on job control (set automatically when interactive). 276.It Fl s Em stdin 277Read commands from standard input (set automatically if no file arguments 278are present). 279This option has no effect when set after the shell has 280already started running (i.e. with 281.Ic set ) . 282.It Fl V Em vi 283Enable the built-in 284.Xr vi 1 285command line editor (disables 286.Fl E 287if it has been set). 288(See the 289.Sx Command Line Editing 290section below.) 291.It Fl E Em emacs 292Enable the built-in emacs style 293command line editor (disables 294.Fl V 295if it has been set). 296(See the 297.Sx Command Line Editing 298section below.) 299.It Fl b Em notify 300Enable asynchronous notification of background job completion. 301(Not implemented.) 302.It Fl p Em nopriv 303Do not attempt to reset effective uid if it does not match uid. 304This is not set by default to help avoid incorrect usage by setuid 305root programs via 306.Xr system 3 307or 308.Xr popen 3 . 309.It "\ \ " Em cdprint 310Make an interactive shell always print the new directory name when 311changed by the 312.Ic cd 313command. 314.It "\ \ " Em tabcomplete 315Enables filename completion in the command line editor. 316Typing a tab character will extend the current input word to match a 317filename. 318If more than one filename matches it is only extended to be the common prefix. 319Typing a second tab character will list all the matching names. 320One of the editing modes, either 321.Fl E 322or 323.Fl V , 324must be enabled for this to work. 325.El 326.Ss Lexical Structure 327The shell reads input in terms of lines from a file and breaks it up into 328words at whitespace (blanks and tabs), and at certain sequences of 329characters that are special to the shell called 330.Dq operators . 331There are two types of operators: control operators and redirection 332operators (their meaning is discussed later). 333Following is a list of operators: 334.Bl -ohang -offset indent 335.It "Control operators:" 336.Dl \*[Am] \*[Am]\*[Am] \&( \&) \&; ;; | || \*[Lt]newline\*[Gt] 337.It "Redirection operators:" 338.Dl \*[Lt] \*[Gt] \*[Gt]| \*[Lt]\*[Lt] \*[Gt]\*[Gt] \*[Lt]\*[Am] \*[Gt]\*[Am] \*[Lt]\*[Lt]- \*[Lt]\*[Gt] 339.El 340.Ss Quoting 341Quoting is used to remove the special meaning of certain characters or 342words to the shell, such as operators, whitespace, or keywords. 343There are three types of quoting: matched single quotes, 344matched double quotes, and backslash. 345.Ss Backslash 346A backslash preserves the literal meaning of the following 347character, with the exception of 348.Aq newline . 349A backslash preceding a 350.Aq newline 351is treated as a line continuation. 352.Ss Single Quotes 353Enclosing characters in single quotes preserves the literal meaning of all 354the characters (except single quotes, making it impossible to put 355single quotes in a single-quoted string). 356.Ss Double Quotes 357Enclosing characters within double quotes preserves the literal 358meaning of all characters except dollar sign 359.Pq $ , 360backquote 361.Pq ` , 362and backslash 363.Pq \e . 364The backslash inside double quotes is historically weird, and serves to 365quote only the following characters: 366.Dl $ ` \*q \e \*[Lt]newline\*[Gt] . 367Otherwise it remains literal. 368.Ss Reserved Words 369Reserved words are words that have special meaning to the 370shell and are recognized at the beginning of a line and 371after a control operator. 372The following are reserved words: 373.Bl -column while while while while while -offset indent 374.It ! Ta elif Ta fi Ta while Ta case 375.It else Ta for Ta then Ta { Ta } 376.It do Ta done Ta until Ta if Ta esac 377.El 378.Pp 379Their meaning is discussed later. 380.Ss Aliases 381An alias is a name and corresponding value set using the 382.Ic alias 383built-in command. 384Whenever a reserved word may occur (see above), 385and after checking for reserved words, the shell 386checks the word to see if it matches an alias. 387If it does, it replaces it in the input stream with its value. 388For example, if there is an alias called 389.Dq lf 390with the value 391.Dq "ls -F" , 392then the input: 393.Pp 394.Dl lf foobar Aq return 395.Pp 396would become 397.Pp 398.Dl ls -F foobar Aq return 399.Pp 400Aliases provide a convenient way for naive users to create shorthands for 401commands without having to learn how to create functions with arguments. 402They can also be used to create lexically obscure code. 403This use is discouraged. 404.Ss Commands 405The shell interprets the words it reads according to a language, the 406specification of which is outside the scope of this man page (refer to the 407BNF in the 408.Tn POSIX 4091003.2 document). 410Essentially though, a line is read and if the first 411word of the line (or after a control operator) is not a reserved word, 412then the shell has recognized a simple command. 413Otherwise, a complex 414command or some other special construct may have been recognized. 415.Ss Simple Commands 416If a simple command has been recognized, the shell performs 417the following actions: 418.Bl -enum -offset indent 419.It 420Leading words of the form 421.Dq name=value 422are stripped off and assigned to the environment of the simple command. 423Redirection operators and their arguments (as described below) are 424stripped off and saved for processing. 425.It 426The remaining words are expanded as described in the 427.Sx Word Expansions 428section below, 429and the first remaining word is considered the command name and the 430command is located. 431The remaining words are considered the arguments of the command. 432If no command name resulted, then the 433.Dq name=value 434variable assignments recognized in item 1 affect the current shell. 435.It 436Redirections are performed as described in the next section. 437.El 438.Ss Redirections 439Redirections are used to change where a command reads its input or sends 440its output. 441In general, redirections open, close, or duplicate an 442existing reference to a file. 443The overall format used for redirection is: 444.Pp 445.Dl [n] Va redir-op Ar file 446.Pp 447where 448.Va redir-op 449is one of the redirection operators mentioned previously. 450Following is a list of the possible redirections. 451The 452.Bq n 453is an optional number, as in 454.Sq 3 455(not 456.Sq Bq 3 ) , 457that refers to a file descriptor. 458.Bl -tag -width aaabsfiles -offset indent 459.It [n] Ns \*[Gt] file 460Redirect standard output (or n) to file. 461.It [n] Ns \*[Gt]| file 462Same, but override the 463.Fl C 464option. 465.It [n] Ns \*[Gt]\*[Gt] file 466Append standard output (or n) to file. 467.It [n] Ns \*[Lt] file 468Redirect standard input (or n) from file. 469.It [n1] Ns \*[Lt]\*[Am] Ns n2 470Duplicate standard input (or n1) from file descriptor n2. 471.It [n] Ns \*[Lt]\*[Am]- 472Close standard input (or n). 473.It [n1] Ns \*[Gt]\*[Am] Ns n2 474Duplicate standard output (or n1) to n2. 475.It [n] Ns \*[Gt]\*[Am]- 476Close standard output (or n). 477.It [n] Ns \*[Lt]\*[Gt] file 478Open file for reading and writing on standard input (or n). 479.El 480.Pp 481The following redirection is often called a 482.Dq here-document . 483.Bl -item -offset indent 484.It 485.Li [n]\*[Lt]\*[Lt] delimiter 486.Dl here-doc-text ... 487.Li delimiter 488.El 489.Pp 490All the text on successive lines up to the delimiter, or to an EOF, is 491saved away and made available to the command on standard input, or file 492descriptor n if it is specified. 493If the delimiter as specified on the initial line is 494quoted, then the here-doc-text is treated literally; otherwise, the text is 495subjected to parameter expansion, command substitution, and arithmetic 496expansion as described in the 497.Sx Word Expansions 498section below. 499If the operator is 500.Dq \*[Lt]\*[Lt]- 501instead of 502.Dq \*[Lt]\*[Lt] , 503then leading tabs in the here-doc-text are stripped. 504.Ss Search and Execution 505There are three types of commands: shell functions, built-in commands, and 506normal programs -- and the command is searched for (by name) in that order. 507They each are executed in a different way. 508.Pp 509When a shell function is executed, all of the shell positional parameters 510(except $0, which remains unchanged) are set to the arguments of the shell 511function. 512The variables which are explicitly placed in the environment of 513the command (by placing assignments to them before the function name) are 514made local to the function and are set to the values given. 515Then the command given in the function definition is executed. 516The positional parameters are restored to their original values 517when the command completes. 518This all occurs within the current shell. 519.Pp 520Shell built-ins are executed internally to the shell, without spawning a 521new process. 522.Pp 523Otherwise, if the command name doesn't match a function or built-in, the 524command is searched for as a normal program in the file system (as 525described in the next section). 526When a normal program is executed, the shell runs the program, 527passing the arguments and the environment to the program. 528If the program is not a normal executable file (i.e., if it does 529not begin with the "magic number" whose 530.Tn ASCII 531representation is "#!", so 532.Xr execve 2 533returns 534.Er ENOEXEC 535then) the shell will interpret the program in a subshell. 536The child shell will reinitialize itself in this case, 537so that the effect will be as if a 538new shell had been invoked to handle the ad-hoc shell script, except that 539the location of hashed commands located in the parent shell will be 540remembered by the child. 541.Pp 542Note that previous versions of this document and the source code itself 543misleadingly and sporadically refer to a shell script without a magic 544number as a "shell procedure". 545.Ss Path Search 546When locating a command, the shell first looks to see if it has a shell 547function by that name. 548Then it looks for a built-in command by that name. 549If a built-in command is not found, one of two things happen: 550.Bl -enum 551.It 552Command names containing a slash are simply executed without performing 553any searches. 554.It 555The shell searches each entry in 556.Ev PATH 557in turn for the command. 558The value of the 559.Ev PATH 560variable should be a series of entries separated by colons. 561Each entry consists of a directory name. 562The current directory may be indicated 563implicitly by an empty directory name, or explicitly by a single period. 564.El 565.Ss Command Exit Status 566Each command has an exit status that can influence the behavior 567of other shell commands. 568The paradigm is that a command exits 569with zero for normal or success, and non-zero for failure, 570error, or a false indication. 571The man page for each command 572should indicate the various exit codes and what they mean. 573Additionally, the built-in commands return exit codes, as does 574an executed shell function. 575.Pp 576If a command consists entirely of variable assignments then the 577exit status of the command is that of the last command substitution 578if any, otherwise 0. 579.Ss Complex Commands 580Complex commands are combinations of simple commands with control 581operators or reserved words, together creating a larger complex command. 582More generally, a command is one of the following: 583.Bl -bullet 584.It 585simple command 586.It 587pipeline 588.It 589list or compound-list 590.It 591compound command 592.It 593function definition 594.El 595.Pp 596Unless otherwise stated, the exit status of a command is that of the last 597simple command executed by the command. 598.Ss Pipelines 599A pipeline is a sequence of one or more commands separated 600by the control operator |. 601The standard output of all but 602the last command is connected to the standard input 603of the next command. 604The standard output of the last 605command is inherited from the shell, as usual. 606.Pp 607The format for a pipeline is: 608.Pp 609.Dl [!] command1 [ | command2 ...] 610.Pp 611The standard output of command1 is connected to the standard input of 612command2. 613The standard input, standard output, or both of a command is 614considered to be assigned by the pipeline before any redirection specified 615by redirection operators that are part of the command. 616.Pp 617If the pipeline is not in the background (discussed later), the shell 618waits for all commands to complete. 619.Pp 620If the reserved word ! does not precede the pipeline, the exit status is 621the exit status of the last command specified in the pipeline. 622Otherwise, the exit status is the logical NOT of the exit status of the 623last command. 624That is, if the last command returns zero, the exit status 625is 1; if the last command returns greater than zero, the exit status is 626zero. 627.Pp 628Because pipeline assignment of standard input or standard output or both 629takes place before redirection, it can be modified by redirection. 630For example: 631.Pp 632.Dl $ command1 2\*[Gt]\*[Am]1 | command2 633.Pp 634sends both the standard output and standard error of command1 635to the standard input of command2. 636.Pp 637A ; or 638.Aq newline 639terminator causes the preceding AND-OR-list (described 640next) to be executed sequentially; a \*[Am] causes asynchronous execution of 641the preceding AND-OR-list. 642.Pp 643Note that unlike some other shells, each process in the pipeline is a 644child of the invoking shell (unless it is a shell built-in, in which case 645it executes in the current shell -- but any effect it has on the 646environment is wiped). 647.Ss Background Commands -- \*[Am] 648If a command is terminated by the control operator ampersand (\*[Am]), the 649shell executes the command asynchronously -- that is, the shell does not 650wait for the command to finish before executing the next command. 651.Pp 652The format for running a command in background is: 653.Pp 654.Dl command1 \*[Am] [command2 \*[Am] ...] 655.Pp 656If the shell is not interactive, the standard input of an asynchronous 657command is set to 658.Pa /dev/null . 659.Ss Lists -- Generally Speaking 660A list is a sequence of zero or more commands separated by newlines, 661semicolons, or ampersands, and optionally terminated by one of these three 662characters. 663The commands in a list are executed in the order they are written. 664If command is followed by an ampersand, the shell starts the 665command and immediately proceed onto the next command; otherwise it waits 666for the command to terminate before proceeding to the next one. 667.Ss Short-Circuit List Operators 668.Dq \*[Am]\*[Am] 669and 670.Dq || 671are AND-OR list operators. 672.Dq \*[Am]\*[Am] 673executes the first command, and then executes the second command if and only 674if the exit status of the first command is zero. 675.Dq || 676is similar, but executes the second command if and only if the exit status 677of the first command is nonzero. 678.Dq \*[Am]\*[Am] 679and 680.Dq || 681both have the same priority. 682Note that these operators are left-associative, so 683.Dq true || echo bar \*[Am]\*[Am] echo baz 684writes 685.Dq baz 686and nothing else. 687This is not the way it works in C. 688Also, if you forget the left-hand side (for example when continuing lines but 689forgetting to use a backslash) it defaults to a true statement. 690This behavior is not useful and should not be relied upon. 691.Ss Flow-Control Constructs -- if, while, for, case 692The syntax of the if command is 693.Bd -literal -offset indent 694if list 695then list 696[ elif list 697then list ] ... 698[ else list ] 699fi 700.Ed 701.Pp 702The syntax of the while command is 703.Bd -literal -offset indent 704while list 705do list 706done 707.Ed 708.Pp 709The two lists are executed repeatedly while the exit status of the 710first list is zero. 711The until command is similar, but has the word 712until in place of while, which causes it to 713repeat until the exit status of the first list is zero. 714.Pp 715The syntax of the for command is 716.Bd -literal -offset indent 717for variable in word ... 718do list 719done 720.Ed 721.Pp 722The words are expanded, and then the list is executed repeatedly with the 723variable set to each word in turn. 724do and done may be replaced with 725.Dq { 726and 727.Dq } . 728.Pp 729The syntax of the break and continue command is 730.Bd -literal -offset indent 731break [ num ] 732continue [ num ] 733.Ed 734.Pp 735Break terminates the num innermost for or while loops. 736Continue continues with the next iteration of the innermost loop. 737These are implemented as built-in commands. 738.Pp 739The syntax of the case command is 740.Bd -literal -offset indent 741case word in 742pattern) list ;; 743\&... 744esac 745.Ed 746.Pp 747The pattern can actually be one or more patterns (see 748.Sx Shell Patterns 749described later), separated by 750.Dq \*(Ba 751characters. 752.Ss Grouping Commands Together 753Commands may be grouped by writing either 754.Pp 755.Dl (list) 756.Pp 757or 758.Pp 759.Dl { list; } 760.Pp 761The first of these executes the commands in a subshell. 762Built-in commands grouped into a (list) will not affect the current shell. 763The second form does not fork another shell so is slightly more efficient. 764Grouping commands together this way allows you to redirect 765their output as though they were one program: 766.Bd -literal -offset indent 767{ echo -n \*q hello \*q ; echo \*q world" ; } \*[Gt] greeting 768.Ed 769.Pp 770Note that 771.Dq } 772must follow a control operator (here, 773.Dq \&; ) 774so that it is recognized as a reserved word and not as another command argument. 775.Ss Functions 776The syntax of a function definition is 777.Pp 778.Dl name ( ) command 779.Pp 780A function definition is an executable statement; when executed it 781installs a function named name and returns an exit status of zero. 782The command is normally a list enclosed between 783.Dq { 784and 785.Dq } . 786.Pp 787Variables may be declared to be local to a function by using a local 788command. 789This should appear as the first statement of a function, and the syntax is 790.Pp 791.Dl local [ variable | - ] ... 792.Pp 793.Dq Local 794is implemented as a built-in command. 795.Pp 796When a variable is made local, it inherits the initial value and exported 797and read-only flags from the variable with the same name in the surrounding 798scope, if there is one. 799Otherwise, the variable is initially unset. 800The shell uses dynamic scoping, so that if you make the variable x local to 801function f, which then calls function g, references to the variable x made 802inside g will refer to the variable x declared inside f, not to the global 803variable named x. 804.Pp 805The only special parameter that can be made local is 806.Dq - . 807Making 808.Dq - 809local causes any shell options that are changed via the set command inside the 810function to be restored to their original values when the function 811returns. 812.Pp 813The syntax of the return command is 814.Pp 815.Dl return [ exitstatus ] 816.Pp 817It terminates the currently executing function. 818Return is implemented as a built-in command. 819.Ss Variables and Parameters 820The shell maintains a set of parameters. 821A parameter denoted by a name is called a variable. 822When starting up, the shell turns all the environment 823variables into shell variables. 824New variables can be set using the form 825.Pp 826.Dl name=value 827.Pp 828Variables set by the user must have a name consisting solely of 829alphabetics, numerics, and underscores - the first of which must not be 830numeric. 831A parameter can also be denoted by a number or a special 832character as explained below. 833.Ss Positional Parameters 834A positional parameter is a parameter denoted by a number (n \*[Gt] 0). 835The shell sets these initially to the values of its command line arguments 836that follow the name of the shell script. 837The 838.Ic set 839built-in can also be used to set or reset them. 840.Ss Special Parameters 841A special parameter is a parameter denoted by one of the following special 842characters. 843The value of the parameter is listed next to its character. 844.Bl -tag -width thinhyphena 845.It * 846Expands to the positional parameters, starting from one. 847When the 848expansion occurs within a double-quoted string it expands to a single 849field with the value of each parameter separated by the first character of 850the 851.Ev IFS 852variable, or by a 853.Aq space 854if 855.Ev IFS 856is unset. 857.It @ 858Expands to the positional parameters, starting from one. 859When the expansion occurs within double quotes, each positional 860parameter expands as a separate argument. 861If there are no positional parameters, the 862expansion of @ generates zero arguments, even when @ is 863double-quoted. 864What this basically means, for example, is 865if $1 is 866.Dq abc 867and $2 is 868.Dq def ghi , 869then 870.Qq $@ 871expands to 872the two arguments: 873.Pp 874.Sm off 875.Dl \*q abc \*q \ \*q def\ ghi \*q 876.Sm on 877.It # 878Expands to the number of positional parameters. 879.It \&? 880Expands to the exit status of the most recent pipeline. 881.It - (Hyphen.) 882Expands to the current option flags (the single-letter 883option names concatenated into a string) as specified on 884invocation, by the set built-in command, or implicitly 885by the shell. 886.It $ 887Expands to the process ID of the invoked shell. 888A subshell retains the same value of $ as its parent. 889.It \&! 890Expands to the process ID of the most recent background 891command executed from the current shell. 892For a pipeline, the process ID is that of the last command in the pipeline. 893.It 0 (Zero.) 894Expands to the name of the shell or shell script. 895.El 896.Ss Word Expansions 897This section describes the various expansions that are performed on words. 898Not all expansions are performed on every word, as explained later. 899.Pp 900Tilde expansions, parameter expansions, command substitutions, arithmetic 901expansions, and quote removals that occur within a single word expand to a 902single field. 903It is only field splitting or pathname expansion that can 904create multiple fields from a single word. 905The single exception to this 906rule is the expansion of the special parameter @ within double quotes, as 907was described above. 908.Pp 909The order of word expansion is: 910.Bl -enum 911.It 912Tilde Expansion, Parameter Expansion, Command Substitution, 913Arithmetic Expansion (these all occur at the same time). 914.It 915Field Splitting is performed on fields 916generated by step (1) unless the 917.Ev IFS 918variable is null. 919.It 920Pathname Expansion (unless set 921.Fl f 922is in effect). 923.It 924Quote Removal. 925.El 926.Pp 927The $ character is used to introduce parameter expansion, command 928substitution, or arithmetic evaluation. 929.Ss Tilde Expansion (substituting a user's home directory) 930A word beginning with an unquoted tilde character (~) is 931subjected to tilde expansion. 932All the characters up to 933a slash (/) or the end of the word are treated as a username 934and are replaced with the user's home directory. 935If the username is missing (as in 936.Pa ~/foobar ) , 937the tilde is replaced with the value of the 938.Va HOME 939variable (the current user's home directory). 940.Ss Parameter Expansion 941The format for parameter expansion is as follows: 942.Pp 943.Dl ${expression} 944.Pp 945where expression consists of all characters until the matching 946.Dq } . 947Any 948.Dq } 949escaped by a backslash or within a quoted string, and characters in 950embedded arithmetic expansions, command substitutions, and variable 951expansions, are not examined in determining the matching 952.Dq } . 953.Pp 954The simplest form for parameter expansion is: 955.Pp 956.Dl ${parameter} 957.Pp 958The value, if any, of parameter is substituted. 959.Pp 960The parameter name or symbol can be enclosed in braces, which are 961optional except for positional parameters with more than one digit or 962when parameter is followed by a character that could be interpreted as 963part of the name. 964If a parameter expansion occurs inside double quotes: 965.Bl -enum 966.It 967Pathname expansion is not performed on the results of the expansion. 968.It 969Field splitting is not performed on the results of the 970expansion, with the exception of the special rules for @. 971.El 972.Pp 973In addition, a parameter expansion can be modified by using one of the 974following formats. 975If the 976.Dq Dv \&: 977is omitted in the following modifiers, then the expansion is applied only 978to unset parameters, not null ones. 979.Bl -tag -width aaparameterwordaaaaa 980.It ${parameter:-word} 981Use Default Values. 982If parameter is unset or null, the expansion of word 983is substituted; otherwise, the value of parameter is substituted. 984.It ${parameter:=word} 985Assign Default Values. 986If parameter is unset or null, the expansion of 987word is assigned to parameter. 988In all cases, the final value of parameter is substituted. 989Only variables, not positional parameters or special 990parameters, can be assigned in this way. 991.It ${parameter:?[word]} 992Indicate Error if Null or Unset. 993If parameter is unset or null, the 994expansion of word (or a message indicating it is unset if word is omitted) 995is written to standard error and the shell exits with a nonzero exit status. 996Otherwise, the value of parameter is substituted. 997An interactive shell need not exit. 998.It ${parameter:+word} 999Use Alternative Value. 1000If parameter is unset or null, null is 1001substituted; otherwise, the expansion of word is substituted. 1002.It ${#parameter} 1003String Length. 1004The length in characters of the value of parameter. 1005.El 1006.Pp 1007The following four varieties of parameter expansion provide for substring 1008processing. 1009In each case, pattern matching notation (see 1010.Sx Shell Patterns ) , 1011rather than regular expression notation, is used to evaluate the patterns. 1012If parameter is * or @, the result of the expansion is unspecified. 1013Enclosing the full parameter expansion string in double quotes does not 1014cause the following four varieties of pattern characters to be quoted, 1015whereas quoting characters within the braces has this effect. 1016.Bl -tag -width aaparameterwordaaaaa 1017.It ${parameter%word} 1018Remove Smallest Suffix Pattern. 1019The word is expanded to produce a pattern. 1020The parameter expansion then results in parameter, with the 1021smallest portion of the suffix matched by the pattern deleted. 1022.It ${parameter%%word} 1023Remove Largest Suffix Pattern. 1024The word is expanded to produce a pattern. 1025The parameter expansion then results in parameter, with the largest 1026portion of the suffix matched by the pattern deleted. 1027.It ${parameter#word} 1028Remove Smallest Prefix Pattern. 1029The word is expanded to produce a pattern. 1030The parameter expansion then results in parameter, with the 1031smallest portion of the prefix matched by the pattern deleted. 1032.It ${parameter##word} 1033Remove Largest Prefix Pattern. 1034The word is expanded to produce a pattern. 1035The parameter expansion then results in parameter, with the largest 1036portion of the prefix matched by the pattern deleted. 1037.El 1038.Ss Command Substitution 1039Command substitution allows the output of a command to be substituted in 1040place of the command name itself. 1041Command substitution occurs when the command is enclosed as follows: 1042.Pp 1043.Dl $(command) 1044.Pp 1045or 1046.Po 1047.Dq backquoted 1048version 1049.Pc : 1050.Pp 1051.Dl `command` 1052.Pp 1053The shell expands the command substitution by executing command in a 1054subshell environment and replacing the command substitution with the 1055standard output of the command, removing sequences of one or more 1056.Ao newline Ac Ns s 1057at the end of the substitution. 1058(Embedded 1059.Ao newline Ac Ns s 1060before 1061the end of the output are not removed; however, during field splitting, 1062they may be translated into 1063.Ao space Ac Ns s , 1064depending on the value of 1065.Ev IFS 1066and quoting that is in effect.) 1067.Ss Arithmetic Expansion 1068Arithmetic expansion provides a mechanism for evaluating an arithmetic 1069expression and substituting its value. 1070The format for arithmetic expansion is as follows: 1071.Pp 1072.Dl $((expression)) 1073.Pp 1074The expression is treated as if it were in double quotes, except 1075that a double quote inside the expression is not treated specially. 1076The shell expands all tokens in the expression for parameter expansion, 1077command substitution, and quote removal. 1078.Pp 1079Next, the shell treats this as an arithmetic expression and 1080substitutes the value of the expression. 1081.Pp 1082Arithmetic expressions use a syntax similar to that 1083of the C language, and are evaluated using the 1084.Ql intmax_t 1085data type (this is an extension to 1086.Tn POSIX , 1087which requires only 1088.Ql long 1089arithmetic). 1090Shell variables may be referenced by name inside an arithmetic 1091expression, without needing a 1092.Dq \&$ 1093sign. 1094.Ss White Space Splitting (Field Splitting) 1095After parameter expansion, command substitution, and 1096arithmetic expansion the shell scans the results of 1097expansions and substitutions that did not occur in double quotes for 1098field splitting and multiple fields can result. 1099.Pp 1100The shell treats each character of the 1101.Ev IFS 1102as a delimiter and use the delimiters to split the results of parameter 1103expansion and command substitution into fields. 1104.Pp 1105Non-whitespace characters in 1106.Ev IFS 1107are treated strictly as parameter terminators. 1108So adjacent non-whitespace 1109.Ev IFS 1110characters will produce empty parameters. 1111.Pp 1112If 1113.Ev IFS 1114is unset it is assumed to contain space, tab, and newline. 1115.Ss Pathname Expansion (File Name Generation) 1116Unless the 1117.Fl f 1118flag is set, file name generation is performed after word splitting is 1119complete. 1120Each word is viewed as a series of patterns, separated by slashes. 1121The process of expansion replaces the word with the names of all 1122existing files whose names can be formed by replacing each pattern with a 1123string that matches the specified pattern. 1124There are two restrictions on 1125this: first, a pattern cannot match a string containing a slash, and 1126second, a pattern cannot match a string starting with a period unless the 1127first character of the pattern is a period. 1128The next section describes the 1129patterns used for both Pathname Expansion and the 1130.Ic case 1131command. 1132.Ss Shell Patterns 1133A pattern consists of normal characters, which match themselves, 1134and meta-characters. 1135The meta-characters are 1136.Dq \&! , 1137.Dq * , 1138.Dq \&? , 1139and 1140.Dq \&[ . 1141These characters lose their special meanings if they are quoted. 1142When command or variable substitution is performed 1143and the dollar sign or backquotes are not double-quoted, 1144the value of the variable or the output of 1145the command is scanned for these characters and they are turned into 1146meta-characters. 1147.Pp 1148An asterisk 1149.Pq Dq * 1150matches any string of characters. 1151A question mark 1152.Pq Dq \&? 1153matches any single character. 1154A left bracket 1155.Pq Dq \&[ 1156introduces a character class. 1157The end of the character class is indicated by a right bracket 1158.Pq Dq \&] ; 1159if this 1160.Dq \&] 1161is missing then the 1162.Dq \&[ 1163matches a 1164.Dq \&[ 1165rather than introducing a character class. 1166A character class matches any of the characters between the square brackets. 1167A named class of characters (see 1168.Xr wctype 3 ) 1169may be specified by surrounding the name with 1170.Pq Dq [: 1171and 1172.Pq Dq :] . 1173For example, 1174.Pq Dq [[:alpha:]] 1175is a shell pattern that matches a single letter. 1176A range of characters may be specified using a minus sign 1177.Pq Dq - . 1178The character class may be complemented 1179by making an exclamation mark 1180.Pq Dq \&! 1181the first character of the character class. 1182.Pp 1183To include a 1184.Dq \&] 1185in a character class, make it the first character listed (after the 1186.Dq \&! , 1187if any). 1188To include a 1189.Dq - , 1190make it the first or last character listed. 1191.Ss Built-ins 1192This section lists the built-in commands which are built-in because they 1193need to perform some operation that can't be performed by a separate 1194process. 1195In addition to these, there are several other commands that may 1196be built in for efficiency (e.g. 1197.Xr printf 1 , 1198.Xr echo 1 , 1199.Xr test 1 , 1200etc). 1201.Bl -tag -width 5n 1202.It : [ Ar arg ... ] 1203A null command that returns a 0 (true) exit value. 1204Any arguments are ignored. 1205.It \&. file 1206The dot command reads and executes the commands from the specified 1207.Ar file 1208in the current shell environment. 1209The file does not need to be executable and is looked up from the directories 1210listed in the 1211.Ev PATH 1212variable if it does not contain a directory separator 1213.Pq Sq / . 1214The return command can be used for a premature return from the sourced file. 1215.Pp 1216The POSIX standard is unclear on how loop control keywords (break 1217and continue) behave across a dot command boundary. 1218This implementation allows them to control loops surrounding the dot command, 1219but obviously such behavior should not be relied on. 1220.It alias Op Ar name Ns Op Ar "=string ..." 1221If 1222.Ar name=string 1223is specified, the shell defines the alias 1224.Ar name 1225with value 1226.Ar string . 1227If just 1228.Ar name 1229is specified, the value of the alias 1230.Ar name 1231is printed. 1232With no arguments, the 1233.Ic alias 1234built-in prints the 1235names and values of all defined aliases (see 1236.Ic unalias ) . 1237.It bg [ Ar job ] ... 1238Continue the specified jobs (or the current job if no 1239jobs are given) in the background. 1240.It command Oo Fl p Oc Oo Fl v Oc Oo Fl V Oc Ar command Oo Ar arg ... Oc 1241Execute the specified command but ignore shell functions when searching 1242for it. 1243(This is useful when you 1244have a shell function with the same name as a built-in command.) 1245.Bl -tag -width 5n 1246.It Fl p 1247search for command using a 1248.Ev PATH 1249that guarantees to find all the standard utilities. 1250.It Fl V 1251Do not execute the command but 1252search for the command and print the resolution of the 1253command search. 1254This is the same as the 1255.Ic type 1256built-in. 1257.It Fl v 1258Do not execute the command but 1259search for the command and print the absolute pathname 1260of utilities, the name for built-ins or the expansion of aliases. 1261.El 1262.It cd Oo Fl P Oc Op Ar directory Op Ar replace 1263Switch to the specified directory (default 1264.Ev $HOME ) . 1265If 1266.Ar replace 1267is specified, then the new directory name is generated by replacing 1268the first occurrence of 1269.Ar directory 1270in the current directory name with 1271.Ar replace . 1272If 1273.Ar directory 1274is 1275.Sq - , 1276then the current working directory is changed to the previous current 1277working directory as set in 1278.Ev OLDPWD . 1279Otherwise if an entry for 1280.Ev CDPATH 1281appears in the environment of the 1282.Ic cd 1283command or the shell variable 1284.Ev CDPATH 1285is set and the directory name does not begin with a slash, 1286or its first (or only) component isn't dot or dot dot, 1287then the directories listed in 1288.Ev CDPATH 1289will be searched for the specified directory. 1290The format of 1291.Ev CDPATH 1292is the same as that of 1293.Ev PATH . 1294.Pp 1295The 1296.Fl P 1297option instructs the shell to update 1298.Ev PWD 1299with the specified physical directory path and change to that directory. 1300This is the default. 1301.Pp 1302When the directory changes, the variable 1303.Ev OLDPWD 1304is set to the working directory before the change. 1305.Pp 1306Some shells also support a 1307.Fl L 1308option, which instructs the shell to update 1309.Ev PWD 1310with the logical path and to change the current directory 1311accordingly. 1312This is not supported. 1313.Pp 1314In an interactive shell, the 1315.Ic cd 1316command will print out the name of the 1317directory that it actually switched to if this is different from the name 1318that the user gave. 1319These may be different either because the 1320.Ev CDPATH 1321mechanism was used or because a symbolic link was crossed. 1322.It eval Ar string ... 1323Concatenate all the arguments with spaces. 1324Then re-parse and execute the command. 1325.It exec Op Ar command arg ... 1326Unless command is omitted, the shell process is replaced with the 1327specified program (which must be a real program, not a shell built-in or 1328function). 1329Any redirections on the 1330.Ic exec 1331command are marked as permanent, so that they are not undone when the 1332.Ic exec 1333command finishes. 1334.It exit Op Ar exitstatus 1335Terminate the shell process. 1336If 1337.Ar exitstatus 1338is given it is used as the exit status of the shell; otherwise the 1339exit status of the preceding command is used. 1340.It export Ar name ... 1341.It export Fl p 1342The specified names are exported so that they will appear in the 1343environment of subsequent commands. 1344The only way to un-export a variable is to unset it. 1345The shell allows the value of a variable to be set at the 1346same time it is exported by writing 1347.Pp 1348.Dl export name=value 1349.Pp 1350With no arguments the export command lists the names of all exported variables. 1351With the 1352.Fl p 1353option specified the output will be formatted suitably for non-interactive use. 1354.It fc Oo Fl e Ar editor Oc Oo Ar first Oo Ar last Oc Oc 1355.It fc Fl l Oo Fl nr Oc Oo Ar first Oo Ar last Oc Oc 1356.It fc Fl s Oo Ar old=new Oc Oo Ar first Oc 1357The 1358.Ic fc 1359built-in lists, or edits and re-executes, commands previously entered 1360to an interactive shell. 1361.Bl -tag -width 5n 1362.It Fl e No editor 1363Use the editor named by editor to edit the commands. 1364The editor string is a command name, subject to search via the 1365.Ev PATH 1366variable. 1367The value in the 1368.Ev FCEDIT 1369variable is used as a default when 1370.Fl e 1371is not specified. 1372If 1373.Ev FCEDIT 1374is null or unset, the value of the 1375.Ev EDITOR 1376variable is used. 1377If 1378.Ev EDITOR 1379is null or unset, 1380.Xr ed 1 1381is used as the editor. 1382.It Fl l No (ell) 1383List the commands rather than invoking an editor on them. 1384The commands are written in the sequence indicated by 1385the first and last operands, as affected by 1386.Fl r , 1387with each command preceded by the command number. 1388.It Fl n 1389Suppress command numbers when listing with -l. 1390.It Fl r 1391Reverse the order of the commands listed (with 1392.Fl l ) 1393or edited (with neither 1394.Fl l 1395nor 1396.Fl s ) . 1397.It Fl s 1398Re-execute the command without invoking an editor. 1399.It first 1400.It last 1401Select the commands to list or edit. 1402The number of previous commands that 1403can be accessed are determined by the value of the 1404.Ev HISTSIZE 1405variable. 1406The value of first or last or both are one of the following: 1407.Bl -tag -width 5n 1408.It [+]number 1409A positive number representing a command number; command numbers can be 1410displayed with the 1411.Fl l 1412option. 1413.It Fl number 1414A negative decimal number representing the command that was executed 1415number of commands previously. 1416For example, \-1 is the immediately previous command. 1417.El 1418.It string 1419A string indicating the most recently entered command that begins with 1420that string. 1421If the old=new operand is not also specified with 1422.Fl s , 1423the string form of the first operand cannot contain an embedded equal sign. 1424.El 1425.Pp 1426The following environment variables affect the execution of fc: 1427.Bl -tag -width HISTSIZE 1428.It Ev FCEDIT 1429Name of the editor to use. 1430.It Ev HISTSIZE 1431The number of previous commands that are accessible. 1432.El 1433.It fg Op Ar job 1434Move the specified job or the current job to the foreground. 1435.It getopts Ar optstring var 1436The 1437.Tn POSIX 1438.Ic getopts 1439command, not to be confused with the 1440.Em Bell Labs 1441-derived 1442.Xr getopt 1 . 1443.Pp 1444The first argument should be a series of letters, each of which may be 1445optionally followed by a colon to indicate that the option requires an 1446argument. 1447The variable specified is set to the parsed option. 1448.Pp 1449The 1450.Ic getopts 1451command deprecates the older 1452.Xr getopt 1 1453utility due to its handling of arguments containing whitespace. 1454.Pp 1455The 1456.Ic getopts 1457built-in may be used to obtain options and their arguments 1458from a list of parameters. 1459When invoked, 1460.Ic getopts 1461places the value of the next option from the option string in the list in 1462the shell variable specified by 1463.Va var 1464and its index in the shell variable 1465.Ev OPTIND . 1466When the shell is invoked, 1467.Ev OPTIND 1468is initialized to 1. 1469For each option that requires an argument, the 1470.Ic getopts 1471built-in will place it in the shell variable 1472.Ev OPTARG . 1473If an option is not allowed for in the 1474.Va optstring , 1475then 1476.Ev OPTARG 1477will be unset. 1478.Pp 1479.Va optstring 1480is a string of recognized option letters (see 1481.Xr getopt 3 ) . 1482If a letter is followed by a colon, the option is expected to have an 1483argument which may or may not be separated from it by whitespace. 1484If an option character is not found where expected, 1485.Ic getopts 1486will set the variable 1487.Va var 1488to a 1489.Dq \&? ; 1490.Ic getopts 1491will then unset 1492.Ev OPTARG 1493and write output to standard error. 1494By specifying a colon as the first character of 1495.Va optstring 1496all errors will be ignored. 1497.Pp 1498A nonzero value is returned when the last option is reached. 1499If there are no remaining arguments, 1500.Ic getopts 1501will set 1502.Va var 1503to the special option, 1504.Dq -- , 1505otherwise, it will set 1506.Va var 1507to 1508.Dq \&? . 1509.Pp 1510The following code fragment shows how one might process the arguments 1511for a command that can take the options 1512.Op a 1513and 1514.Op b , 1515and the option 1516.Op c , 1517which requires an argument. 1518.Bd -literal -offset indent 1519while getopts abc: f 1520do 1521 case $f in 1522 a | b) flag=$f;; 1523 c) carg=$OPTARG;; 1524 \e?) echo $USAGE; exit 1;; 1525 esac 1526done 1527shift $(expr $OPTIND - 1) 1528.Ed 1529.Pp 1530This code will accept any of the following as equivalent: 1531.Bd -literal -offset indent 1532cmd \-acarg file file 1533cmd \-a \-c arg file file 1534cmd \-carg -a file file 1535cmd \-a \-carg \-\- file file 1536.Ed 1537.It hash Fl rv Ar command ... 1538The shell maintains a hash table which remembers the 1539locations of commands. 1540With no arguments whatsoever, 1541the 1542.Ic hash 1543command prints out the contents of this table. 1544Entries which have not been looked at since the last 1545.Ic cd 1546command are marked with an asterisk; it is possible for these entries 1547to be invalid. 1548.Pp 1549With arguments, the 1550.Ic hash 1551command removes the specified commands from the hash table (unless 1552they are functions) and then locates them. 1553With the 1554.Fl v 1555option, hash prints the locations of the commands as it finds them. 1556The 1557.Fl r 1558option causes the hash command to delete all the entries in the hash table 1559except for functions. 1560.It inputrc Ar file 1561Read the 1562.Va file 1563to set keybindings as defined by 1564.Xr editrc 5 . 1565.It jobid Op Ar job 1566Print the process id's of the processes in the job. 1567If the 1568.Ar job 1569argument is omitted, the current job is used. 1570.It jobs 1571This command lists out all the background processes 1572which are children of the current shell process. 1573.It pwd Op Fl \&LP 1574Print the current directory. 1575If 1576.Fl L 1577is specified the cached value (initially set from 1578.Ev PWD ) 1579is checked to see if it refers to the current directory; if it does 1580the value is printed. 1581Otherwise the current directory name is found using 1582.Xr getcwd 3 . 1583The environment variable 1584.Ev PWD 1585is set to the printed value. 1586.Pp 1587The default is 1588.Ic pwd 1589.Fl L , 1590but note that the built-in 1591.Ic cd 1592command doesn't currently support the 1593.Fl L 1594option and will cache (almost) the absolute path. 1595If 1596.Ic cd 1597is changed, 1598.Ic pwd 1599may be changed to default to 1600.Ic pwd 1601.Fl P . 1602.Pp 1603If the current directory is renamed and replaced by a symlink to the 1604same directory, or the initial 1605.Ev PWD 1606value followed a symbolic link, then the cached value may not 1607be the absolute path. 1608.Pp 1609The built-in command may differ from the program of the same name because 1610the program will use 1611.Ev PWD 1612and the built-in uses a separately cached value. 1613.It read Oo Fl p Ar prompt Oc Oo Fl r Oc Ar variable Oo Ar ... Oc 1614The prompt is printed if the 1615.Fl p 1616option is specified and the standard input is a terminal. 1617Then a line is read from the standard input. 1618The trailing newline is deleted from the 1619line and the line is split as described in the 1620.Sx Word Expansions 1621section above, and the pieces are assigned to the variables in order. 1622If there are more pieces than variables, the remaining pieces 1623(along with the characters in 1624.Ev IFS 1625that separated them) are assigned to the last variable. 1626If there are more variables than pieces, 1627the remaining variables are assigned the null string. 1628The 1629.Ic read 1630built-in will indicate success unless EOF is encountered on input, in 1631which case failure is returned. 1632.Pp 1633By default, unless the 1634.Fl r 1635option is specified, the backslash 1636.Dq \e 1637acts as an escape character, causing the following character to be treated 1638literally. 1639If a backslash is followed by a newline, the backslash and the 1640newline will be deleted. 1641.It readonly Ar name ... 1642.It readonly Fl p 1643The specified names are marked as read only, so that they cannot be 1644subsequently modified or unset. 1645The shell allows the value of a variable 1646to be set at the same time it is marked read only by writing 1647.Pp 1648.Dl readonly name=value 1649.Pp 1650With no arguments the readonly command lists the names of all read only 1651variables. 1652With the 1653.Fl p 1654option specified the output will be formatted suitably for non-interactive use. 1655.Pp 1656.It return [ Ar n ] 1657Stop executing the current function or a dot command with return value of 1658.Ar n 1659or the value of the last executed command, if not specified. 1660For portability, 1661.Ar n 1662should be in the range from 0 to 255. 1663.Pp 1664The POSIX standard says that the results of 1665.Sq return 1666outside a function or a dot command are unspecified. 1667This implementation treats such a return as a no-op with a return value of 0 1668(success, true). 1669Use the exit command instead, if you want to return from a script or exit 1670your shell. 1671.It set Oo { Fl options | Cm +options | Cm \-- } Oc Ar arg ... 1672The 1673.Ic set 1674command performs three different functions. 1675.Pp 1676With no arguments, it lists the values of all shell variables. 1677.Pp 1678If options are given, it sets the specified option 1679flags, or clears them as described in the 1680.Sx Argument List Processing 1681section. 1682.Pp 1683The third use of the set command is to set the values of the shell's 1684positional parameters to the specified arguments. 1685To change the positional 1686parameters without changing any options, use 1687.Dq -- 1688as the first argument to set. 1689If no arguments are present, the set command 1690will clear all the positional parameters (equivalent to executing 1691.Dq shift $# . ) 1692.It setvar Ar variable Ar value 1693Assigns value to variable. 1694(In general it is better to write 1695variable=value rather than using 1696.Ic setvar . 1697.Ic setvar 1698is intended to be used in 1699functions that assign values to variables whose names are passed as 1700parameters.) 1701.It shift Op Ar n 1702Shift the positional parameters n times. 1703A 1704.Ic shift 1705sets the value of 1706.Va $1 1707to the value of 1708.Va $2 , 1709the value of 1710.Va $2 1711to the value of 1712.Va $3 , 1713and so on, decreasing 1714the value of 1715.Va $# 1716by one. 1717If there are zero positional parameters, 1718.Ic shift 1719does nothing. 1720.It trap Oo Fl l Oc 1721.It trap Oo Ar action Oc Ar signal ... 1722Cause the shell to parse and execute action when any of the specified 1723signals are received. 1724The signals are specified by signal number or as the name of the signal. 1725If 1726.Ar signal 1727is 1728.Li 0 1729or its equivalent, EXIT, 1730the action is executed when the shell exits. 1731.Ar action 1732may be null, which cause the specified signals to be ignored. 1733With 1734.Ar action 1735omitted or set to 1736.Sq - 1737the specified signals are set to their default action. 1738When the shell forks off a subshell, it resets trapped (but not ignored) 1739signals to the default action. 1740On non-interactive shells, the 1741.Ic trap 1742command has no effect on signals that were 1743ignored on entry to the shell. 1744On interactive shells, the 1745.Ic trap 1746command will catch or reset signals ignored on entry. 1747Issuing 1748.Ic trap 1749with option 1750.Ar -l 1751will print a list of valid signal names. 1752.Ic trap 1753without any arguments cause it to write a list of signals and their 1754associated action to the standard output in a format that is suitable 1755as an input to the shell that achieves the same trapping results. 1756.Pp 1757Examples: 1758.Pp 1759.Dl trap 1760.Pp 1761List trapped signals and their corresponding action 1762.Pp 1763.Dl trap -l 1764.Pp 1765Print a list of valid signals 1766.Pp 1767.Dl trap '' INT QUIT tstp 30 1768.Pp 1769Ignore signals INT QUIT TSTP USR1 1770.Pp 1771.Dl trap date INT 1772.Pp 1773Print date upon receiving signal INT 1774.It type Op Ar name ... 1775Interpret each name as a command and print the resolution of the command 1776search. 1777Possible resolutions are: 1778shell keyword, alias, shell built-in, 1779command, tracked alias and not found. 1780For aliases the alias expansion is 1781printed; for commands and tracked aliases the complete pathname of the 1782command is printed. 1783.It ulimit Oo Fl H \*(Ba Fl S Oc Oo Fl a \*(Ba Fl btfdscmlrpnv Oo Ar value Oc Oc 1784Inquire about or set the hard or soft limits on processes or set new 1785limits. 1786The choice between hard limit (which no process is allowed to 1787violate, and which may not be raised once it has been lowered) and soft 1788limit (which causes processes to be signaled but not necessarily killed, 1789and which may be raised) is made with these flags: 1790.Bl -tag -width Fl 1791.It Fl H 1792set or inquire about hard limits 1793.It Fl S 1794set or inquire about soft limits. 1795If neither 1796.Fl H 1797nor 1798.Fl S 1799is specified, the soft limit is displayed or both limits are set. 1800If both are specified, the last one wins. 1801.El 1802.Pp 1803The limit to be interrogated or set, then, is chosen by specifying 1804any one of these flags: 1805.Bl -tag -width Fl 1806.It Fl a 1807show all the current limits 1808.It Fl b 1809show or set the limit on the socket buffer size of a process (in bytes) 1810.It Fl t 1811show or set the limit on CPU time (in seconds) 1812.It Fl f 1813show or set the limit on the largest file that can be created 1814(in 512-byte blocks) 1815.It Fl d 1816show or set the limit on the data segment size of a process (in kilobytes) 1817.It Fl s 1818show or set the limit on the stack size of a process (in kilobytes) 1819.It Fl c 1820show or set the limit on the largest core dump size that can be produced 1821(in 512-byte blocks) 1822.It Fl m 1823show or set the limit on the total physical memory that can be 1824in use by a process (in kilobytes) 1825.It Fl l 1826show or set the limit on how much memory a process can lock with 1827.Xr mlock 2 1828(in kilobytes) 1829.It Fl r 1830show or set the limit on the number of threads this user can 1831have at one time 1832.It Fl p 1833show or set the limit on the number of processes this user can 1834have at one time 1835.It Fl n 1836show or set the limit on the number of files a process can have open at once 1837.It Fl v 1838show or set the limit on how large a process address space can be 1839.El 1840.Pp 1841If none of these is specified, it is the limit on file size that is shown 1842or set. 1843If value is specified, the limit is set to that number; otherwise 1844the current limit is displayed. 1845.Pp 1846Limits of an arbitrary process can be displayed or set using the 1847.Xr sysctl 8 1848utility. 1849.Pp 1850.It umask Op Ar mask 1851Set the value of umask (see 1852.Xr umask 2 ) 1853to the specified octal value. 1854If the argument is omitted, the umask value is printed. 1855.It unalias Oo Fl a Oc Oo Ar name Oc 1856If 1857.Ar name 1858is specified, the shell removes that alias. 1859If 1860.Fl a 1861is specified, all aliases are removed. 1862.It unset Ar name ... 1863The specified variables and functions are unset and unexported. 1864If a given name corresponds to both a variable and a function, both 1865the variable and the function are unset. 1866.It wait Op Ar job 1867Wait for the specified job to complete and return the exit status of the 1868last process in the job. 1869If the argument is omitted, wait for all jobs to 1870complete and then return an exit status of zero. 1871.El 1872.Ss Command Line Editing 1873When 1874.Nm 1875is being used interactively from a terminal, the current command 1876and the command history (see 1877.Ic fc 1878in the 1879.Sx Built-ins 1880section) 1881can be edited using emacs-mode or vi-mode command-line editing. 1882The command 1883.Ql set -o emacs 1884enables emacs-mode editing. 1885The command 1886.Ql set -o vi 1887enables vi-mode editing and places the current shell process into 1888.Ar vi 1889insert mode. 1890(See the 1891.Sx Argument List Processing 1892section above.) 1893.Pp 1894The 1895.Ar vi 1896mode uses commands similar to a subset of those described in the 1897.Xr vi 1 1898man page. 1899With vi-mode 1900enabled, 1901.Nm sh 1902can be switched between insert mode and command mode. 1903It's similar to 1904.Xr vi 1 : 1905pressing the 1906.Aq ESC 1907key will throw you into command VI command mode. 1908Pressing the 1909.Aq return 1910key while in command mode will pass the line to the shell. 1911.Pp 1912The 1913.Ar emacs 1914mode uses commands similar to a subset available in 1915the 1916.Xr emacs 1 1917editor. 1918With emacs-mode enabled, special keys can be used to modify the text 1919in the buffer using the control key. 1920.Pp 1921.Nm 1922uses the 1923.Xr editline 3 1924library. 1925.Sh ENVIRONMENT 1926.Bl -tag -width MAILCHECK 1927.It Ev HOME 1928Set automatically by 1929.Xr login 1 1930from the user's login directory in the password file 1931.Pq Xr passwd 5 . 1932This environment variable also functions as the default argument for the 1933.Ic cd 1934built-in. 1935.It Ev PATH 1936The default search path for executables. 1937See the 1938.Sx Path Search 1939section above. 1940.It Ev CDPATH 1941The search path used with the 1942.Ic cd 1943built-in. 1944.It Ev LINENO 1945The current line number in the script or function. 1946.It Ev LANG 1947The string used to specify localization information that allows users 1948to work with different culture-specific and language conventions. 1949See 1950.Xr nls 7 . 1951.It Ev MAIL 1952The name of a mail file, that will be checked for the arrival of new mail. 1953Overridden by 1954.Ev MAILPATH . 1955.It Ev MAILCHECK 1956The frequency in seconds that the shell checks for the arrival of mail 1957in the files specified by the 1958.Ev MAILPATH 1959or the 1960.Ev MAIL 1961file. 1962If set to 0, the check will occur at each prompt. 1963.It Ev MAILPATH 1964A colon 1965.Dq \&: 1966separated list of file names, for the shell to check for incoming mail. 1967This environment setting overrides the 1968.Ev MAIL 1969setting. 1970There is a maximum of 10 mailboxes that can be monitored at once. 1971.It Ev PS1 1972The primary prompt string, which defaults to 1973.Dq $ \ , 1974unless you are the superuser, in which case it defaults to 1975.Dq # \ . 1976.It Ev PS2 1977The secondary prompt string, which defaults to 1978.Dq \*[Gt] \ . 1979.It Ev PS4 1980Output before each line when execution trace (set -x) is enabled, 1981defaults to 1982.Dq + \ . 1983.It Ev IFS 1984Input Field Separators. 1985This is normally set to 1986.Aq space , 1987.Aq tab , 1988and 1989.Aq newline . 1990See the 1991.Sx White Space Splitting 1992section for more details. 1993.It Ev TERM 1994The default terminal setting for the shell. 1995This is inherited by 1996children of the shell, and is used in the history editing modes. 1997.It Ev HISTSIZE 1998The number of lines in the history buffer for the shell. 1999.El 2000.Sh FILES 2001.Bl -item 2002.It 2003.Pa $HOME/.profile 2004.It 2005.Pa /etc/profile 2006.El 2007.Sh EXIT STATUS 2008Errors that are detected by the shell, such as a syntax error, will cause the 2009shell to exit with a non-zero exit status. 2010If the shell is not an 2011interactive shell, the execution of the shell file will be aborted. 2012Otherwise 2013the shell will return the exit status of the last command executed, or 2014if the exit built-in is used with a numeric argument, it will return the 2015argument. 2016.Sh SEE ALSO 2017.Xr csh 1 , 2018.Xr echo 1 , 2019.Xr getopt 1 , 2020.Xr ksh 1 , 2021.Xr login 1 , 2022.Xr printf 1 , 2023.Xr test 1 , 2024.Xr editline 3 , 2025.Xr getopt 3 , 2026.\" .Xr profile 4 , 2027.Xr editrc 5 , 2028.Xr passwd 5 , 2029.Xr environ 7 , 2030.Xr nls 7 , 2031.Xr sysctl 8 2032.Sh HISTORY 2033A 2034.Nm 2035command appeared in 2036.At v1 . 2037It was, however, unmaintainable so we wrote this one. 2038.Sh BUGS 2039Setuid shell scripts should be avoided at all costs, as they are a 2040significant security risk. 2041.Pp 2042PS1, PS2, and PS4 should be subject to parameter expansion before 2043being displayed. 2044.Pp 2045The characters generated by filename completion should probably be quoted 2046to ensure that the filename is still valid after the input line has been 2047processed. 2048