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