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