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