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