1.\"- 2.\" SPDX-License-Identifier: BSD-3-Clause 3.\" 4.\" Copyright (c) 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" Kenneth Almquist. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" Portions of this text are reprinted and reproduced in electronic form 35.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 36.\" Portable Operating System Interface (POSIX), The Open Group Base 37.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 38.\" Electrical and Electronics Engineers, Inc and The Open Group. In the 39.\" event of any discrepancy between this version and the original IEEE and 40.\" The Open Group Standard, the original IEEE and The Open Group Standard is 41.\" the referee document. The original Standard can be obtained online at 42.\" http://www.opengroup.org/unix/online.html. 43.\" 44.Dd February 17, 2026 45.Dt SH 1 46.Os 47.Sh NAME 48.Nm sh 49.Nd command interpreter (shell) 50.Sh SYNOPSIS 51.Nm 52.Op Fl /+abCEefhIilmnPpTuVvx 53.Op Fl /+o Ar longname 54.Oo 55.Ar script 56.Op Ar arg ... 57.Oc 58.Nm 59.Op Fl /+abCEefhIilmnPpTuVvx 60.Op Fl /+o Ar longname 61.Fl c Ar string 62.Oo 63.Ar name 64.Op Ar arg ... 65.Oc 66.Nm 67.Op Fl /+abCEefhIilmnPpTuVvx 68.Op Fl /+o Ar longname 69.Fl s 70.Op Ar arg ... 71.Sh DESCRIPTION 72The 73.Nm 74utility is the standard command interpreter for the system. 75The current version of 76.Nm 77is close to the 78.St -p1003.1 79specification for the shell. 80It only supports features 81designated by POSIX, 82plus a few Berkeley extensions. 83This man page is not intended to be a tutorial nor a complete 84specification of the shell. 85.Ss Overview 86The shell is a command that reads lines from 87either a file or the terminal, interprets them, and 88generally executes other commands. 89It is the program that is started when a user logs into the system, 90although a user can select a different shell with the 91.Xr chsh 1 92command. 93The shell 94implements a language that has flow control constructs, 95a macro facility that provides a variety of features in 96addition to data storage, along with built-in history and line 97editing capabilities. 98It incorporates many features to 99aid interactive use and has the advantage that the interpretative 100language is common to both interactive and non-interactive 101use (shell scripts). 102That is, commands can be typed directly 103to the running shell or can be put into a file, 104which can be executed directly by the shell. 105.Ss Invocation 106.\" 107.\" XXX This next sentence is incredibly confusing. 108.\" 109If no arguments are present and if the standard input of the shell 110is connected to a terminal 111(or if the 112.Fl i 113option is set), 114the shell is considered an interactive shell. 115An interactive shell 116generally prompts before each command and handles programming 117and command errors differently (as described below). 118When first starting, the shell inspects argument 0, and 119if it begins with a dash 120.Pq Ql - , 121the shell is also considered a login shell. 122This is normally done automatically by the system 123when the user first logs in. 124A login shell first reads commands 125from the files 126.Pa /etc/profile 127and then 128.Pa .profile 129in a user's home directory, 130if they exist. 131If the environment variable 132.Ev ENV 133is set on entry to a shell, or is set in the 134.Pa .profile 135of a login shell, the shell then subjects its value to parameter expansion 136and arithmetic expansion and reads commands from the named file. 137Therefore, a user should place commands that are to be executed only 138at login time in the 139.Pa .profile 140file, and commands that are executed for every shell inside the 141.Ev ENV 142file. 143The user can set the 144.Ev ENV 145variable to some file by placing the following line in the file 146.Pa .profile 147in the home directory, 148substituting for 149.Pa .shrc 150the filename desired: 151.Pp 152.Dl "ENV=$HOME/.shrc; export ENV" 153.Pp 154The first non-option argument specified on the command line 155will be treated as the 156name of a file from which to read commands (a shell script), and 157the remaining arguments are set as the positional parameters 158of the shell 159.Li ( $1 , $2 , 160etc.). 161Otherwise, the shell reads commands 162from its standard input. 163.Pp 164Unlike older versions of 165.Nm 166the 167.Ev ENV 168script is only sourced on invocation of interactive shells. 169This 170closes a well-known, and sometimes easily exploitable security 171hole related to poorly thought out 172.Ev ENV 173scripts. 174.Ss Argument List Processing 175All of the single letter options to 176.Nm 177have a corresponding long name, 178with the exception of 179.Fl c 180and 181.Fl /+o . 182These long names are provided next to the single letter options 183in the descriptions below. 184The long name for an option may be specified as an argument to the 185.Fl /+o 186option of 187.Nm . 188Once the shell is running, 189the long name for an option may be specified as an argument to the 190.Fl /+o 191option of the 192.Ic set 193built-in command 194(described later in the section called 195.Sx Built-in Commands ) . 196Introducing an option with a dash 197.Pq Ql - 198enables the option, 199while using a plus 200.Pq Ql + 201disables the option. 202A 203.Dq Li -- 204or plain 205.Ql - 206will stop option processing and will force the remaining 207words on the command line to be treated as arguments. 208The 209.Fl /+o 210and 211.Fl c 212options do not have long names. 213They take arguments and are described after the single letter options. 214.Bl -tag -width indent 215.It Fl a Li allexport 216Flag variables for export when assignments are made to them. 217.It Fl b Li notify 218Enable asynchronous notification of background job 219completion. 220(UNIMPLEMENTED) 221.It Fl C Li noclobber 222Do not overwrite existing files with 223.Ql > . 224.It Fl E Li emacs 225Enable the built-in 226.Xr emacs 1 Pq Pa ports/editors/emacs 227command line editor (disables the 228.Fl V 229option if it has been set; 230set automatically when interactive on terminals). 231See 232.Sx Command Line Editing . 233.It Fl e Li errexit 234Exit immediately if any untested command fails in non-interactive mode. 235The exit status of a command is considered to be 236explicitly tested if the command is part of the list used to control 237an 238.Ic if , elif , while , 239or 240.Ic until ; 241if the command is the left 242hand operand of an 243.Dq Li && 244or 245.Dq Li || 246operator; or if the command is a pipeline preceded by the 247.Ic !\& 248keyword. 249If a shell function is executed and its exit status is explicitly 250tested, all commands of the function are considered to be tested as 251well. 252.Pp 253Note that many commands return non-zero values to convey information other 254than errors, which can cause unexpected program termination with 255.Fl e . 256.It Fl f Li noglob 257Disable pathname expansion. 258.It Fl h Li trackall 259A do-nothing option for POSIX compliance. 260.It Fl I Li ignoreeof 261Ignore 262.Dv EOF Ap s 263from input when in interactive mode. 264.It Fl i Li interactive 265Force the shell to behave interactively. 266.It Fl l 267Force the shell to act as if it has been invoked as a login shell. 268.It Fl m Li monitor 269Turn on job control (see 270.Sx Job Control ) . 271Set automatically when interactive. 272In a non-interactive shell, 273this option can be set even if no terminal is available 274and is useful to place processes in separate process groups. 275.It Fl n Li noexec 276If not interactive, read commands but do not 277execute them. 278This is useful for checking the 279syntax of shell scripts. 280.It Fl P Li physical 281Change the default for the 282.Ic cd 283and 284.Ic pwd 285commands from 286.Fl L 287(logical directory layout) 288to 289.Fl P 290(physical directory layout). 291.It Fl p Li privileged 292Turn on privileged mode. 293This mode is enabled on startup 294if either the effective user or group ID is not equal to the 295real user or group ID. 296Turning this mode off sets the 297effective user and group IDs to the real user and group IDs. 298When this mode is enabled for interactive shells, the file 299.Pa /etc/suid_profile 300is sourced instead of 301.Pa ~/.profile 302after 303.Pa /etc/profile 304is sourced, and the contents of the 305.Ev ENV 306variable are ignored. 307.It Fl s Li stdin 308Read commands from standard input (set automatically 309if no file arguments are present). 310This option has 311no effect when set after the shell has already started 312running (i.e., when set with the 313.Ic set 314command). 315.It Fl T Li trapsasync 316When waiting for a child, execute traps immediately. 317If this option is not set, 318traps are executed after the child exits, 319as specified in 320.St -p1003.2 . 321This nonstandard option is useful for putting guarding shells around 322children that block signals. 323The surrounding shell may kill the child 324or it may just return control to the tty and leave the child alone, 325like this: 326.Bd -literal -offset indent 327sh -T -c "trap 'exit 1' 2 ; some-blocking-program" 328.Ed 329.It Fl u Li nounset 330Write a message to standard error when attempting 331to expand a variable, a positional parameter or 332the special parameter 333.Va \&! 334that is not set, and if the 335shell is not interactive, exit immediately. 336.It Fl V Li vi 337Enable the built-in 338.Xr vi 1 339command line editor (disables 340.Fl E 341if it has been set). 342See 343.Sx Command Line Editing . 344.It Fl v Li verbose 345The shell writes its input to standard error 346as it is read. 347Useful for debugging. 348.It Fl x Li xtrace 349Write each command 350(preceded by the value of the 351.Va PS4 352variable subjected to parameter expansion and arithmetic expansion) 353to standard error before it is executed. 354Useful for debugging. 355.It Li nolog 356Another do-nothing option for POSIX compliance. 357It only has a long name. 358.It Li pipefail 359Change the exit status of a pipeline to the last non-zero exit status of 360any command in the pipeline, if any. 361Since an exit due to 362.Dv SIGPIPE 363counts as a non-zero exit status, 364this option may cause non-zero exit status for successful pipelines 365if a command such as 366.Xr head 1 367in the pipeline terminates with status 0 without reading its 368input completely. 369This option only has a long name. 370.It Li verify 371Set 372.Dv O_VERIFY 373when sourcing files or loading profiles. 374.\" See also 375.\" .Xr mac_veriexec 4 . TODO Does not exist; write it. 376.El 377.Pp 378The 379.Fl c 380option causes the commands to be read from the 381.Ar string 382operand instead of from the standard input. 383Keep in mind that this option only accepts a single string as its 384argument, hence multi-word strings must be quoted. 385.Pp 386The 387.Fl /+o 388option takes as its only argument the long name of an option 389to be enabled or disabled. 390For example, the following two invocations of 391.Nm 392both enable the built-in 393.Xr emacs 1 Pq Pa ports/editors/emacs 394command line editor: 395.Bd -literal -offset indent 396set -E 397set -o emacs 398.Ed 399.Pp 400If used without an argument, the 401.Fl o 402option displays the current option settings in a human-readable format. 403If 404.Cm +o 405is used without an argument, the current option settings are output 406in a format suitable for re-input into the shell. 407.Ss Lexical Structure 408The shell reads input in terms of lines from a file and breaks 409it up into words at whitespace (blanks and tabs), and at 410certain sequences of 411characters called 412.Dq operators , 413which are special to the shell. 414There are two types of operators: control operators and 415redirection operators (their meaning is discussed later). 416The following is a list of valid operators: 417.Bl -tag -width indent 418.It Control operators: 419.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact 420.It Li & Ta Li && Ta Li \&( Ta Li \&) Ta Li \en 421.It Li ;; Ta Li ;& Ta Li \&; Ta Li \&| Ta Li || 422.El 423.It Redirection operators: 424.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact 425.It Li < Ta Li > Ta Li << Ta Li >> Ta Li <> 426.It Li <& Ta Li >& Ta Li <<- Ta Li >| Ta \& 427.El 428.El 429.Pp 430The character 431.Ql # 432introduces a comment if used at the beginning of a word. 433The word starting with 434.Ql # 435and the rest of the line are ignored. 436.Pp 437ASCII 438.Dv NUL 439characters (character code 0) are not allowed in shell input. 440.Ss Quoting 441Quoting is used to remove the special meaning of certain characters 442or words to the shell, such as operators, whitespace, keywords, 443or alias names. 444.Pp 445There are four types of quoting: matched single quotes, 446dollar-single quotes, 447matched double quotes, and backslash. 448.Bl -tag -width indent 449.It Single Quotes 450Enclosing characters in single quotes preserves the literal 451meaning of all the characters (except single quotes, making 452it impossible to put single-quotes in a single-quoted string). 453.It Dollar-Single Quotes 454Enclosing characters between 455.Li $' 456and 457.Li ' 458preserves the literal meaning of all characters 459except backslashes and single quotes. 460A backslash introduces a C-style escape sequence: 461.Bl -tag -width xUnnnnnnnn 462.It \ea 463Alert (ring the terminal bell) 464.It \eb 465Backspace 466.It \ec Ns Ar c 467The control character denoted by 468.Li ^ Ns Ar c 469in 470.Xr stty 1 . 471If 472.Ar c 473is a backslash, it must be doubled. 474.It \ee 475The ESC character (ASCII 0x1b) 476.It \ef 477Formfeed 478.It \en 479Newline 480.It \er 481Carriage return 482.It \et 483Horizontal tab 484.It \ev 485Vertical tab 486.It \e\e 487Literal backslash 488.It \e\&' 489Literal single-quote 490.It \e\&" 491Literal double-quote 492.It \e Ns Ar nnn 493The byte whose octal value is 494.Ar nnn 495(one to three digits) 496.It \ex Ns Ar nn 497The byte whose hexadecimal value is 498.Ar nn 499(one or more digits only the last two of which are used) 500.It \eu Ns Ar nnnn 501The Unicode code point 502.Ar nnnn 503(four hexadecimal digits) 504.It \eU Ns Ar nnnnnnnn 505The Unicode code point 506.Ar nnnnnnnn 507(eight hexadecimal digits) 508.El 509.Pp 510The sequences for Unicode code points are currently only useful with 511UTF-8 locales. 512They reject code point 0 and UTF-16 surrogates. 513.Pp 514If an escape sequence would produce a byte with value 0, 515that byte and the rest of the string until the matching single-quote 516are ignored. 517.Pp 518Any other string starting with a backslash is an error. 519.It Double Quotes 520Enclosing characters within double quotes preserves the literal 521meaning of all characters except dollar sign 522.Pq Ql $ , 523backquote 524.Pq Ql ` , 525and backslash 526.Pq Ql \e . 527The backslash inside double quotes is historically weird. 528It remains literal unless it precedes the following characters, 529which it serves to quote: 530.Pp 531.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact 532.It Li $ Ta Li ` Ta Li \&" Ta Li \e Ta Li \en 533.El 534.It Backslash 535A backslash preserves the literal meaning of the following 536character, with the exception of the newline character 537.Pq Ql \en . 538A backslash preceding a newline is treated as a line continuation. 539.El 540.Ss Keywords 541Keywords or reserved words are words that have special meaning to the 542shell and are recognized at the beginning of a line and 543after a control operator. 544The following are keywords: 545.Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center 546.It Li \&! Ta { Ta } Ta Ic case Ta Ic do 547.It Ic done Ta Ic elif Ta Ic else Ta Ic esac Ta Ic fi 548.It Ic for Ta Ic if Ta Ic then Ta Ic until Ta Ic while 549.El 550.Ss Aliases 551An alias is a name and corresponding value set using the 552.Ic alias 553built-in command. 554Wherever the command word of a simple command may occur, 555and after checking for keywords if a keyword may occur, the shell 556checks the word to see if it matches an alias. 557If it does, it replaces it in the input stream with its value. 558For example, if there is an alias called 559.Dq Li lf 560with the value 561.Dq Li "ls -F" , 562then the input 563.Pp 564.Dl "lf foobar" 565.Pp 566would become 567.Pp 568.Dl "ls -F foobar" 569.Pp 570Aliases are also recognized after an alias 571whose value ends with a space or tab. 572For example, if there is also an alias called 573.Dq Li nohup 574with the value 575.Dq Li "nohup " , 576then the input 577.Pp 578.Dl "nohup lf foobar" 579.Pp 580would become 581.Pp 582.Dl "nohup ls -F foobar" 583.Pp 584Aliases provide a convenient way for naive users to 585create shorthands for commands without having to learn how 586to create functions with arguments. 587Using aliases in scripts is discouraged 588because the command that defines them must be executed 589before the code that uses them is parsed. 590This is fragile and not portable. 591.Pp 592An alias name may be escaped in a command line, so that it is not 593replaced by its alias value, by using quoting characters within or 594adjacent to the alias name. 595This is most often done by prefixing 596an alias name with a backslash to execute a function, built-in, or 597normal program with the same name. 598See the 599.Sx Quoting 600subsection. 601.Ss Commands 602The shell interprets the words it reads according to a 603language, the specification of which is outside the scope 604of this man page (refer to the BNF in the 605.St -p1003.2 606document). 607Essentially though, a line is read and if 608the first word of the line (or after a control operator) 609is not a keyword, then the shell has recognized a 610simple command. 611Otherwise, a complex command or some 612other special construct may have been recognized. 613.Ss Simple Commands 614If a simple command has been recognized, the shell performs 615the following actions: 616.Bl -enum 617.It 618Leading words of the form 619.Dq Li name=value 620are stripped off and assigned to the environment of 621the simple command 622(they do not affect expansions). 623Redirection operators and 624their arguments (as described below) are stripped 625off and saved for processing. 626.It 627The remaining words are expanded as described in 628the section called 629.Sx Word Expansions , 630and the first remaining word is considered the command 631name and the command is located. 632The remaining 633words are considered the arguments of the command. 634If no command name resulted, then the 635.Dq Li name=value 636variable assignments recognized in 1) affect the 637current shell. 638.It 639Redirections are performed as described in 640the next section. 641.El 642.Ss Redirections 643Redirections are used to change where a command reads its input 644or sends its output. 645In general, redirections open, close, or 646duplicate an existing reference to a file. 647The overall format 648used for redirection is: 649.Pp 650.D1 Oo Ar n Oc Ar redir-op file 651.Pp 652The 653.Ar redir-op 654is one of the redirection operators mentioned 655previously. 656The following gives some examples of how these 657operators can be used. 658Note that stdin and stdout are commonly used abbreviations 659for standard input and standard output respectively. 660.Bl -tag -width "1234567890XX" -offset indent 661.It Oo Ar n Oc Ns Li > Ar file 662redirect stdout (or file descriptor 663.Ar n ) 664to 665.Ar file 666.It Oo Ar n Oc Ns Li >| Ar file 667same as above, but override the 668.Fl C 669option 670.It Oo Ar n Oc Ns Li >> Ar file 671append stdout (or file descriptor 672.Ar n ) 673to 674.Ar file 675.It Oo Ar n Oc Ns Li < Ar file 676redirect stdin (or file descriptor 677.Ar n ) 678from 679.Ar file 680.It Oo Ar n Oc Ns Li <> Ar file 681redirect stdin (or file descriptor 682.Ar n ) 683to and from 684.Ar file 685.It Oo Ar n1 Oc Ns Li <& Ns Ar n2 686duplicate stdin (or file descriptor 687.Ar n1 ) 688from file descriptor 689.Ar n2 690.It Oo Ar n Oc Ns Li <&- 691close stdin (or file descriptor 692.Ar n ) 693.It Oo Ar n1 Oc Ns Li >& Ns Ar n2 694duplicate stdout (or file descriptor 695.Ar n1 ) 696to file descriptor 697.Ar n2 698.It Oo Ar n Oc Ns Li >&- 699close stdout (or file descriptor 700.Ar n ) 701.El 702.Pp 703The following redirection is often called a 704.Dq here-document . 705.Bd -unfilled -offset indent 706.Oo Ar n Oc Ns Li << Ar delimiter 707.Ar here-doc-text 708.Ar ... 709.Ar delimiter 710.Ed 711.Pp 712All the text on successive lines up to the delimiter is 713saved away and made available to the command on standard 714input, or file descriptor 715.Ar n 716if it is specified. 717If the 718.Ar delimiter 719as specified on the initial line is quoted, then the 720.Ar here-doc-text 721is treated literally, otherwise the text is subjected to 722parameter expansion, command substitution, and arithmetic 723expansion (as described in the section on 724.Sx Word Expansions ) . 725If the operator is 726.Dq Li <<- 727instead of 728.Dq Li << , 729then leading tabs 730in the 731.Ar here-doc-text 732are stripped. 733.Ss Search and Execution 734There are three types of commands: shell functions, 735built-in commands, and normal programs. 736The command is searched for (by name) in that order. 737The three types of commands are all executed in a different way. 738.Pp 739When a shell function is executed, all of the shell positional 740parameters (except 741.Li $0 , 742which remains unchanged) are 743set to the arguments of the shell function. 744The variables which are explicitly placed in the environment of 745the command (by placing assignments to them before the 746function name) are made local to the function and are set 747to the values given. 748Then the command given in the function definition is executed. 749The positional parameters are restored to their original values 750when the command completes. 751This all occurs within the current shell. 752.Pp 753Shell built-in commands are executed internally to the shell, without 754spawning a new process. 755There are two kinds of built-in commands: regular and special. 756Assignments before special builtins persist after they finish 757executing and assignment errors, redirection errors and certain 758operand errors cause a script to be aborted. 759Special builtins cannot be overridden with a function. 760Both regular and special builtins can affect the shell in ways 761normal programs cannot. 762.Pp 763Otherwise, if the command name does not match a function 764or built-in command, the command is searched for as a normal 765program in the file system (as described in the next section). 766When a normal program is executed, the shell runs the program, 767passing the arguments and the environment to the program. 768If the program is not a normal executable file 769(i.e., if it does not begin with the 770.Dq "magic number" 771whose ASCII representation is 772.Dq Li #! , 773resulting in an 774.Er ENOEXEC 775return value from 776.Xr execve 2 ) 777but appears to be a text file, 778the shell will run a new instance of 779.Nm 780to interpret it. 781.Pp 782Note that previous versions of this document 783and the source code itself misleadingly and sporadically 784refer to a shell script without a magic number 785as a 786.Dq "shell procedure" . 787.Ss Path Search 788When locating a command, the shell first looks to see if 789it has a shell function by that name. 790Then it looks for a 791built-in command by that name. 792If a built-in command is not found, 793one of two things happen: 794.Bl -enum 795.It 796Command names containing a slash are simply executed without 797performing any searches. 798.It 799The shell searches each entry in the 800.Va PATH 801variable 802in turn for the command. 803The value of the 804.Va PATH 805variable should be a series of 806entries separated by colons. 807Each entry consists of a 808directory name. 809The current directory 810may be indicated implicitly by an empty directory name, 811or explicitly by a single period. 812.El 813.Ss Command Exit Status 814Each command has an exit status that can influence the behavior 815of other shell commands. 816The paradigm is that a command exits 817with zero for normal or success, and non-zero for failure, 818error, or a false indication. 819The man page for each command 820should indicate the various exit codes and what they mean. 821Additionally, the built-in commands return exit codes, as does 822an executed shell function. 823.Pp 824If a command is terminated by a signal, its exit status is greater than 128. 825The signal name can be found by passing the exit status to 826.Li kill -l . 827.Pp 828If there is no command word, 829the exit status is the exit status of the last command substitution executed, 830or zero if the command does not contain any command substitutions. 831.Ss Complex Commands 832Complex commands are combinations of simple commands 833with control operators or keywords, together creating a larger complex 834command. 835More generally, a command is one of the following: 836.Bl -item -offset indent 837.It 838simple command 839.It 840pipeline 841.It 842list or compound-list 843.It 844compound command 845.It 846function definition 847.El 848.Pp 849Unless otherwise stated, the exit status of a command is 850that of the last simple command executed by the command, 851or zero if no simple command was executed. 852.Ss Pipelines 853A pipeline is a sequence of one or more commands separated 854by the control operator 855.Ql \&| . 856The standard output of all but 857the last command is connected to the standard input 858of the next command. 859The standard output of the last 860command is inherited from the shell, as usual. 861.Pp 862The format for a pipeline is: 863.Pp 864.D1 Oo Li \&! Oc Ar command1 Op Li \&| Ar command2 ... 865.Pp 866The standard output of 867.Ar command1 868is connected to the standard input of 869.Ar command2 . 870The standard input, standard output, or 871both of a command is considered to be assigned by the 872pipeline before any redirection specified by redirection 873operators that are part of the command. 874.Pp 875Note that unlike some other shells, 876.Nm 877executes each process in a pipeline with more than one command 878in a subshell environment and as a child of the 879.Nm 880process. 881.Pp 882If the pipeline is not in the background (discussed later), 883the shell waits for all commands to complete. 884.Pp 885If the keyword 886.Ic !\& 887does not precede the pipeline, the 888exit status is the exit status of the last command specified 889in the pipeline if the 890.Cm pipefail 891option is not set or all commands returned zero, 892or the last non-zero exit status of any command in the pipeline otherwise. 893Otherwise, the exit status is the logical 894NOT of that exit status. 895That is, if 896that status is zero, the exit status is 1; if 897that status is greater than zero, the exit status 898is zero. 899.Pp 900Because pipeline assignment of standard input or standard 901output or both takes place before redirection, it can be 902modified by redirection. 903For example: 904.Pp 905.Dl "command1 2>&1 | command2" 906.Pp 907sends both the standard output and standard error of 908.Ar command1 909to the standard input of 910.Ar command2 . 911.Pp 912A 913.Ql \&; 914or newline terminator causes the preceding 915AND-OR-list 916(described below in the section called 917.Sx Short-Circuit List Operators ) 918to be executed sequentially; 919an 920.Ql & 921causes asynchronous execution of the preceding AND-OR-list. 922.Ss Background Commands (&) 923If a command is terminated by the control operator ampersand 924.Pq Ql & , 925the shell executes the command in a subshell environment (see 926.Sx Grouping Commands Together 927below) and asynchronously; 928the shell does not wait for the command to finish 929before executing the next command. 930.Pp 931The format for running a command in background is: 932.Pp 933.D1 Ar command1 Li & Op Ar command2 Li & Ar ... 934.Pp 935If the shell is not interactive, the standard input of an 936asynchronous command is set to 937.Pa /dev/null . 938.Pp 939The exit status is zero. 940.Ss Lists (Generally Speaking) 941A list is a sequence of zero or more commands separated by 942newlines, semicolons, or ampersands, 943and optionally terminated by one of these three characters. 944The commands in a 945list are executed in the order they are written. 946If command is followed by an ampersand, the shell starts the 947command and immediately proceeds onto the next command; 948otherwise it waits for the command to terminate before 949proceeding to the next one. 950.Ss Short-Circuit List Operators 951.Dq Li && 952and 953.Dq Li || 954are AND-OR list operators. 955.Dq Li && 956executes the first command, and then executes the second command 957if the exit status of the first command is zero. 958.Dq Li || 959is similar, but executes the second command if the exit 960status of the first command is nonzero. 961.Dq Li && 962and 963.Dq Li || 964both have the same priority. 965.Ss Flow-Control Constructs (if, while, for, case) 966The syntax of the 967.Ic if 968command is: 969.Bd -unfilled -offset indent -compact 970.Ic if Ar list 971.Ic then Ar list 972.Oo Ic elif Ar list 973.Ic then Ar list Oc Ar ... 974.Op Ic else Ar list 975.Ic fi 976.Ed 977.Pp 978The exit status is that of selected 979.Ic then 980or 981.Ic else 982list, 983or zero if no list was selected. 984.Pp 985The syntax of the 986.Ic while 987command is: 988.Bd -unfilled -offset indent -compact 989.Ic while Ar list 990.Ic do Ar list 991.Ic done 992.Ed 993.Pp 994The two lists are executed repeatedly while the exit status of the 995first list is zero. 996The 997.Ic until 998command is similar, but has the word 999.Ic until 1000in place of 1001.Ic while , 1002which causes it to 1003repeat until the exit status of the first list is zero. 1004.Pp 1005The exit status is that of the last execution of the second list, 1006or zero if it was never executed. 1007.Pp 1008The syntax of the 1009.Ic for 1010command is: 1011.Bd -unfilled -offset indent -compact 1012.Ic for Ar variable Op Ic in Ar word ... 1013.Ic do Ar list 1014.Ic done 1015.Ed 1016.Pp 1017If 1018.Ic in 1019and the following words are omitted, 1020.Ic in Li \&"$@\&" 1021is used instead. 1022The words are expanded, and then the list is executed 1023repeatedly with the variable set to each word in turn. 1024The 1025.Ic do 1026and 1027.Ic done 1028commands may be replaced with 1029.Ql { 1030and 1031.Ql } . 1032.Pp 1033The syntax of the 1034.Ic break 1035and 1036.Ic continue 1037commands is: 1038.D1 Ic break Op Ar num 1039.D1 Ic continue Op Ar num 1040.Pp 1041The 1042.Ic break 1043command terminates the 1044.Ar num 1045innermost 1046.Ic for 1047or 1048.Ic while 1049loops. 1050The 1051.Ic continue 1052command continues with the next iteration of the innermost loop. 1053These are implemented as special built-in commands. 1054.Pp 1055The syntax of the 1056.Ic case 1057command is: 1058.Bd -unfilled -offset indent -compact 1059.Ic case Ar word Ic in 1060.Ar pattern ) Ar list Li ;; 1061.Ar ... 1062.Ic esac 1063.Ed 1064.Pp 1065The pattern can actually be one or more patterns 1066(see 1067.Sx Shell Patterns 1068described later), 1069separated by 1070.Ql \&| 1071characters. 1072Tilde expansion, parameter expansion, command substitution, 1073arithmetic expansion and quote removal are applied to the word. 1074Then, each pattern is expanded in turn using tilde expansion, 1075parameter expansion, command substitution and arithmetic expansion and 1076the expanded form of the word is checked against it. 1077If a match is found, the corresponding list is executed. 1078If the selected list is terminated by the control operator 1079.Ql ;& 1080instead of 1081.Ql ;; , 1082execution continues with the next list, 1083continuing until a list terminated with 1084.Ql ;; 1085or the end of the 1086.Ic case 1087command. 1088.Ss Grouping Commands Together 1089Commands may be grouped by writing either 1090.Sm off 1091.Bd -literal -offset indent 1092.Po Ar list Pc 1093.Ed 1094.Sm on 1095.Pp 1096or 1097.Bd -literal -offset indent 1098.No { Ar list ; } 1099.Ed 1100.Pp 1101The first form executes the commands in a subshell environment. 1102A subshell environment has its own copy of: 1103.Bl -enum 1104.It 1105The current working directory as set by 1106.Ic cd . 1107.It 1108The file creation mask as set by 1109.Ic umask . 1110.It 1111Resource limits as set by 1112.Ic ulimit . 1113.It 1114References to open files. 1115.It 1116Traps as set by 1117.Ic trap . 1118.It 1119Known jobs. 1120.It 1121Positional parameters and variables. 1122.It 1123Shell options. 1124.It 1125Shell functions. 1126.It 1127Shell aliases. 1128.El 1129.Pp 1130These are copied from the parent shell environment, 1131except that trapped (but not ignored) signals are reset to the default action 1132and known jobs are cleared. 1133Any changes do not affect the parent shell environment. 1134.Pp 1135A subshell environment may be implemented as a child process or differently. 1136If job control is enabled in an interactive shell 1137(see 1138.Sx Job Control ) , 1139commands grouped in parentheses can be suspended and continued as a unit. 1140.Pp 1141For compatibility with other shells, 1142two open parentheses in sequence should be separated by whitespace. 1143.Pp 1144The second form never forks another shell, 1145so it is slightly more efficient. 1146Grouping commands together this way allows the user to 1147redirect their output as though they were one program: 1148.Bd -literal -offset indent 1149{ echo -n "hello"; echo " world"; } > greeting 1150.Ed 1151.Ss Functions 1152The syntax of a function definition is 1153.Pp 1154.D1 Ar name Li \&( \&) Ar command 1155.Pp 1156A function definition is an executable statement; when 1157executed it installs a function named 1158.Ar name 1159and returns an 1160exit status of zero. 1161The 1162.Ar command 1163is normally a list 1164enclosed between 1165.Ql { 1166and 1167.Ql } . 1168.Pp 1169Variables may be declared to be local to a function by 1170using the 1171.Ic local 1172command. 1173This should appear as the first statement of a function, 1174and the syntax is: 1175.Pp 1176.D1 Ic local Oo Ar variable ... Oc Op Fl 1177.Pp 1178The 1179.Ic local 1180command is implemented as a built-in command. 1181The exit status is zero 1182unless the command is not in a function or a variable name is invalid. 1183.Pp 1184When a variable is made local, it inherits the initial 1185value and exported and readonly flags from the variable 1186with the same name in the surrounding scope, if there is 1187one. 1188Otherwise, the variable is initially unset. 1189The shell 1190uses dynamic scoping, so that if the variable 1191.Va x 1192is made local to function 1193.Em f , 1194which then calls function 1195.Em g , 1196references to the variable 1197.Va x 1198made inside 1199.Em g 1200will refer to the variable 1201.Va x 1202declared inside 1203.Em f , 1204not to the global variable named 1205.Va x . 1206.Pp 1207The only special parameter that can be made local is 1208.Ql - . 1209Making 1210.Ql - 1211local causes any shell options 1212(including those that only have long names) 1213that are 1214changed via the 1215.Ic set 1216command inside the function to be 1217restored to their original values when the function 1218returns. 1219.Pp 1220The syntax of the 1221.Ic return 1222command is 1223.Pp 1224.D1 Ic return Op Ar exitstatus 1225.Pp 1226It terminates the current executional scope, returning from the closest 1227nested function or sourced script; 1228if no function or sourced script is being executed, 1229it exits the shell instance. 1230If 1231.Ar exitstatus 1232is specified, the exit status is set to its value, 1233otherwise it is set to the exit status of the last executed command. 1234The 1235.Ic return 1236command is implemented as a special built-in command. 1237.Ss Variables and Parameters 1238The shell maintains a set of parameters. 1239A parameter 1240denoted by a name 1241(consisting solely 1242of alphabetics, numerics, and underscores, 1243and starting with an alphabetic or an underscore) 1244is called a variable. 1245When starting up, 1246the shell turns all environment variables with valid names into shell 1247variables. 1248New variables can be set using the form 1249.Pp 1250.D1 Ar name Ns = Ns Ar value 1251.Pp 1252A parameter can also be denoted by a number 1253or a special character as explained below. 1254.Pp 1255Assignments are expanded differently from other words: 1256tilde expansion is also performed after the equals sign and after any colon 1257and usernames are also terminated by colons, 1258and field splitting and pathname expansion are not performed. 1259.Pp 1260This special expansion applies not only to assignments that form a simple 1261command by themselves or precede a command word, 1262but also to words passed to the 1263.Ic export , 1264.Ic local 1265or 1266.Ic readonly 1267built-in commands that have this form. 1268For this, the builtin's name must be literal 1269(not the result of an expansion) 1270and may optionally be preceded by one or more literal instances of 1271.Ic command 1272without options. 1273.Ss Positional Parameters 1274A positional parameter is a parameter denoted by a number greater than zero. 1275The shell sets these initially to the values of its command line 1276arguments that follow the name of the shell script. 1277The 1278.Ic set 1279built-in command can also be used to set or reset them. 1280.Ss Special Parameters 1281Special parameters are parameters denoted by a single special character 1282or the digit zero. 1283They are shown in the following list, exactly as they would appear in input 1284typed by the user or in the source of a shell script. 1285.Bl -hang 1286.It Li $* 1287Expands to the positional parameters, starting from one. 1288When 1289the expansion occurs within a double-quoted string 1290it expands to a single field with the value of each parameter 1291separated by the first character of the 1292.Va IFS 1293variable, 1294or by a space if 1295.Va IFS 1296is unset. 1297.It Li $@ 1298Expands to the positional parameters, starting from one. 1299When 1300the expansion occurs within double-quotes, each positional 1301parameter expands as a separate argument. 1302If there are no positional parameters, the 1303expansion of 1304.Li @ 1305generates zero arguments, even when 1306.Li @ 1307is double-quoted. 1308What this basically means, for example, is 1309if 1310.Li $1 1311is 1312.Dq Li abc 1313and 1314.Li $2 1315is 1316.Dq Li "def ghi" , 1317then 1318.Li \&"$@\&" 1319expands to 1320the two arguments: 1321.Bd -literal -offset indent 1322"abc" "def ghi" 1323.Ed 1324.It Li $# 1325Expands to the number of positional parameters. 1326.It Li $? 1327Expands to the exit status of the most recent pipeline. 1328.It Li $- 1329(hyphen) Expands to the current option flags (the single-letter 1330option names concatenated into a string) as specified on 1331invocation, by the 1332.Ic set 1333built-in command, or implicitly 1334by the shell. 1335.It Li $$ 1336Expands to the process ID of the invoked shell. 1337A subshell 1338retains the same value of 1339.Va $ 1340as its parent. 1341.It Li $! 1342Expands to the process ID of the most recent background 1343command executed from the current shell. 1344For a 1345pipeline, the process ID is that of the last command in the 1346pipeline. 1347If this parameter is referenced, the shell will remember 1348the process ID and its exit status until the 1349.Ic wait 1350built-in command reports completion of the process. 1351.It Li $0 1352(zero) Expands to the name of the shell script if passed on the command line, 1353the 1354.Ar name 1355operand if given (with 1356.Fl c ) 1357or otherwise argument 0 passed to the shell. 1358.El 1359.Ss Special Variables 1360The following variables are set by the shell or 1361have special meaning to it: 1362.Bl -tag -width ".Va HISTSIZE" 1363.It Va CDPATH 1364The search path used with the 1365.Ic cd 1366built-in. 1367.It Va EDITOR 1368The fallback editor used with the 1369.Ic fc 1370built-in. 1371If not set, the default editor is 1372.Xr ed 1 . 1373.It Va FCEDIT 1374The default editor used with the 1375.Ic fc 1376built-in. 1377.It Va HISTFILE 1378File used for persistent history storage. 1379If unset 1380.Pa ~/.sh_history 1381will be used. 1382If set but empty or 1383.Va HISTSIZE 1384is set to 0 1385the shell will not load and save the history. 1386.It Va HISTSIZE 1387The number of previous commands that are accessible. 1388.It Va HOME 1389The user's home directory, 1390used in tilde expansion and as a default directory for the 1391.Ic cd 1392built-in. 1393.It Va IFS 1394Input Field Separators. 1395This is initialized at startup to 1396.Aq space , 1397.Aq tab , 1398and 1399.Aq newline 1400in that order. 1401This value also applies if 1402.Va IFS 1403is unset, but not if it is set to the empty string. 1404See the 1405.Sx White Space Splitting 1406section for more details. 1407.It Va LINENO 1408The current line number in the script or function. 1409.It Va MAIL 1410The name of a mail file, that will be checked for the arrival of new 1411mail. 1412Overridden by 1413.Va MAILPATH . 1414.It Va MAILPATH 1415A colon 1416.Pq Ql \&: 1417separated list of file names, for the shell to check for incoming 1418mail. 1419This variable overrides the 1420.Va MAIL 1421setting. 1422There is a maximum of 10 mailboxes that can be monitored at once. 1423.It Va OPTIND 1424The index of the next argument to be processed by 1425.Ic getopts . 1426This is initialized to 1 at startup. 1427.It Va PATH 1428The default search path for executables. 1429See the 1430.Sx Path Search 1431section for details. 1432.It Va PPID 1433The parent process ID of the invoked shell. 1434This is set at startup 1435unless this variable is in the environment. 1436A later change of parent process ID is not reflected. 1437A subshell retains the same value of 1438.Va PPID . 1439.It Va PS1 1440The primary prompt string, which defaults to 1441.Dq Li "$ " , 1442unless you are the superuser, in which case it defaults to 1443.Dq Li "# " . 1444.Va PS1 1445may include any of the following formatting sequences, 1446which are replaced by the given information: 1447.Bl -tag -width indent 1448.It Li \eD{format} 1449The current time in 1450.Xr strftime 3 1451.Ar format . 1452The braces are required. 1453Empty 1454.Ar format 1455is equivalent to 1456\&%X, 1457national representation of the time. 1458.It Li \eH 1459This system's fully-qualified hostname (FQDN). 1460.It Li \eh 1461This system's hostname. 1462.It Li \eu 1463User name. 1464.It Li \eW 1465The final component of the current working directory. 1466.It Li \ew 1467The entire path of the current working directory. 1468.It Li \e$ 1469Superuser status. 1470.Dq Li "$" 1471for normal users and 1472.Dq Li "#" 1473for superusers. 1474.It Li \e\e 1475A literal backslash. 1476.It Li \e[ 1477Start of a sequence of non-printing characters (used, for example, 1478to embed ANSI CSI sequences into the prompt). 1479.It Li \e] 1480End of a sequence of non-printing characters. 1481.El 1482.Pp 1483The following special and non-printing characters are supported 1484within the sequence of non-printing characters: 1485.Bl -tag -width indent 1486.It Li \ea 1487Emits ASCII BEL (0x07, 007) character. 1488.It Li \ee 1489Emits ASCII ESC (0x1b, 033) character. 1490.It Li \er 1491Emits ASCII CR (0x0d, 015) character. 1492.It Li \en 1493Emits CRLF sequence. 1494.El 1495.It Va PS2 1496The secondary prompt string, which defaults to 1497.Dq Li "> " . 1498.Va PS2 1499may include any of the formatting sequences from 1500.Va PS1 . 1501.It Va PS4 1502The prefix for the trace output (if 1503.Fl x 1504is active). 1505The default is 1506.Dq Li "+ " . 1507.El 1508.Ss Word Expansions 1509This clause describes the various expansions that are 1510performed on words. 1511Not all expansions are performed on 1512every word, as explained later. 1513.Pp 1514Tilde expansions, parameter expansions, command substitutions, 1515arithmetic expansions, and quote removals that occur within 1516a single word expand to a single field. 1517It is only field 1518splitting or pathname expansion that can create multiple 1519fields from a single word. 1520The single exception to this rule is 1521the expansion of the special parameter 1522.Va @ 1523within double-quotes, 1524as was described above. 1525.Pp 1526The order of word expansion is: 1527.Bl -enum 1528.It 1529Tilde Expansion, Parameter Expansion, Command Substitution, 1530Arithmetic Expansion (these all occur at the same time). 1531.It 1532Field Splitting is performed on fields generated by step (1) 1533unless the 1534.Va IFS 1535variable is null. 1536.It 1537Pathname Expansion (unless the 1538.Fl f 1539option is in effect). 1540.It 1541Quote Removal. 1542.El 1543.Pp 1544The 1545.Ql $ 1546character is used to introduce parameter expansion, command 1547substitution, or arithmetic expansion. 1548.Ss Tilde Expansion (substituting a user's home directory) 1549A word beginning with an unquoted tilde character 1550.Pq Ql ~ 1551is 1552subjected to tilde expansion. 1553All the characters up to a slash 1554.Pq Ql / 1555or the end of the word are treated as a username 1556and are replaced with the user's home directory. 1557If the 1558username is missing (as in 1559.Pa ~/foobar ) , 1560the tilde is replaced with the value of the 1561.Va HOME 1562variable (the current user's home directory). 1563.Ss Parameter Expansion 1564The format for parameter expansion is as follows: 1565.Pp 1566.D1 Li ${ Ns Ar expression Ns Li } 1567.Pp 1568where 1569.Ar expression 1570consists of all characters until the matching 1571.Ql } . 1572Any 1573.Ql } 1574escaped by a backslash or within a single-quoted or double-quoted 1575string, and characters in 1576embedded arithmetic expansions, command substitutions, and variable 1577expansions, are not examined in determining the matching 1578.Ql } . 1579If the variants with 1580.Ql + , 1581.Ql - , 1582.Ql = 1583or 1584.Ql ?\& 1585occur within a double-quoted string, 1586as an extension there may be unquoted parts 1587(via double-quotes inside the expansion); 1588.Ql } 1589within such parts are also not examined in determining the matching 1590.Ql } . 1591.Pp 1592The simplest form for parameter expansion is: 1593.Pp 1594.D1 Li ${ Ns Ar parameter Ns Li } 1595.Pp 1596The value, if any, of 1597.Ar parameter 1598is substituted. 1599.Pp 1600The parameter name or symbol can be enclosed in braces, which are 1601optional except for positional parameters with more than one digit or 1602when parameter is followed by a character that could be interpreted as 1603part of the name. 1604If a parameter expansion occurs inside double-quotes: 1605.Bl -enum 1606.It 1607Field splitting is not performed on the results of the 1608expansion, with the exception of the special parameter 1609.Va @ . 1610.It 1611Pathname expansion is not performed on the results of the 1612expansion. 1613.El 1614.Pp 1615In addition, a parameter expansion can be modified by using one of the 1616following formats. 1617.Bl -tag -width indent 1618.It Li ${ Ns Ar parameter Ns Li :- Ns Ar word Ns Li } 1619Use Default Values. 1620If 1621.Ar parameter 1622is unset or null, the expansion of 1623.Ar word 1624is substituted; otherwise, the value of 1625.Ar parameter 1626is substituted. 1627.It Li ${ Ns Ar parameter Ns Li := Ns Ar word Ns Li } 1628Assign Default Values. 1629If 1630.Ar parameter 1631is unset or null, the expansion of 1632.Ar word 1633is assigned to 1634.Ar parameter . 1635In all cases, the 1636final value of 1637.Ar parameter 1638is substituted. 1639Quoting inside 1640.Ar word 1641does not prevent field splitting or pathname expansion. 1642Only variables, not positional 1643parameters or special parameters, can be 1644assigned in this way. 1645.It Li ${ Ns Ar parameter Ns Li :? Ns Oo Ar word Oc Ns Li } 1646Indicate Error if Null or Unset. 1647If 1648.Ar parameter 1649is unset or null, the expansion of 1650.Ar word 1651(or a message indicating it is unset if 1652.Ar word 1653is omitted) is written to standard 1654error and the shell exits with a nonzero 1655exit status. 1656Otherwise, the value of 1657.Ar parameter 1658is substituted. 1659An 1660interactive shell need not exit. 1661.It Li ${ Ns Ar parameter Ns Li :+ Ns Ar word Ns Li } 1662Use Alternate Value. 1663If 1664.Ar parameter 1665is unset or null, null is substituted; 1666otherwise, the expansion of 1667.Ar word 1668is substituted. 1669.El 1670.Pp 1671In the parameter expansions shown previously, use of the colon in the 1672format results in a test for a parameter that is unset or null; omission 1673of the colon results in a test for a parameter that is only unset. 1674.Pp 1675The 1676.Ar word 1677inherits the type of quoting 1678(unquoted, double-quoted or here-document) 1679from the surroundings, 1680with the exception that a backslash that quotes a closing brace is removed 1681during quote removal. 1682.Bl -tag -width indent 1683.It Li ${# Ns Ar parameter Ns Li } 1684String Length. 1685The length in characters of 1686the value of 1687.Ar parameter . 1688.El 1689.Pp 1690The following four varieties of parameter expansion provide for substring 1691processing. 1692In each case, pattern matching notation 1693(see 1694.Sx Shell Patterns ) , 1695rather than regular expression notation, 1696is used to evaluate the patterns. 1697If parameter is one of the special parameters 1698.Va * 1699or 1700.Va @ , 1701the result of the expansion is unspecified. 1702Enclosing the full parameter expansion string in double-quotes does not 1703cause the following four varieties of pattern characters to be quoted, 1704whereas quoting characters within the braces has this effect. 1705.Bl -tag -width indent 1706.It Li ${ Ns Ar parameter Ns Li % Ns Ar word Ns Li } 1707Remove Smallest Suffix Pattern. 1708The 1709.Ar word 1710is expanded to produce a pattern. 1711The 1712parameter expansion then results in 1713.Ar parameter , 1714with the smallest portion of the 1715suffix matched by the pattern deleted. 1716.It Li ${ Ns Ar parameter Ns Li %% Ns Ar word Ns Li } 1717Remove Largest Suffix Pattern. 1718The 1719.Ar word 1720is expanded to produce a pattern. 1721The 1722parameter expansion then results in 1723.Ar parameter , 1724with the largest portion of the 1725suffix matched by the pattern deleted. 1726.It Li ${ Ns Ar parameter Ns Li # Ns Ar word Ns Li } 1727Remove Smallest Prefix Pattern. 1728The 1729.Ar word 1730is expanded to produce a pattern. 1731The 1732parameter expansion then results in 1733.Ar parameter , 1734with the smallest portion of the 1735prefix matched by the pattern deleted. 1736.It Li ${ Ns Ar parameter Ns Li ## Ns Ar word Ns Li } 1737Remove Largest Prefix Pattern. 1738The 1739.Ar word 1740is expanded to produce a pattern. 1741The 1742parameter expansion then results in 1743.Ar parameter , 1744with the largest portion of the 1745prefix matched by the pattern deleted. 1746.El 1747.Ss Command Substitution 1748Command substitution allows the output of a command to be substituted in 1749place of the command name itself. 1750Command substitution occurs when 1751the command is enclosed as follows: 1752.Pp 1753.D1 Li $( Ns Ar command Ns Li )\& 1754.Pp 1755or the backquoted version: 1756.Pp 1757.D1 Li ` Ns Ar command Ns Li ` 1758.Pp 1759The shell expands the command substitution by executing command 1760and replacing the command substitution 1761with the standard output of the command, 1762removing sequences of one or more newlines at the end of the substitution. 1763Embedded newlines before the end of the output are not removed; 1764however, during field splitting, they may be translated into spaces 1765depending on the value of 1766.Va IFS 1767and the quoting that is in effect. 1768The command is executed in a subshell environment, 1769except that the built-in commands 1770.Ic jobid , 1771.Ic jobs , 1772and 1773.Ic trap 1774return information about the parent shell environment 1775and 1776.Ic times 1777returns information about the same process 1778if they are the only command in a command substitution. 1779.Pp 1780If a command substitution of the 1781.Li $( 1782form begins with a subshell, 1783the 1784.Li $( 1785and 1786.Li (\& 1787must be separated by whitespace 1788to avoid ambiguity with arithmetic expansion. 1789.Ss Arithmetic Expansion 1790Arithmetic expansion provides a mechanism for evaluating an arithmetic 1791expression and substituting its value. 1792The format for arithmetic expansion is as follows: 1793.Pp 1794.D1 Li $(( Ns Ar expression Ns Li )) 1795.Pp 1796The 1797.Ar expression 1798is treated as if it were in double-quotes, except 1799that a double-quote inside the expression is not treated specially. 1800The 1801shell expands all tokens in the 1802.Ar expression 1803for parameter expansion, 1804command substitution, 1805arithmetic expansion 1806and quote removal. 1807.Pp 1808The allowed expressions are a subset of C expressions, 1809summarized below. 1810.Bl -tag -width "Variables" -offset indent 1811.It Values 1812All values are of type 1813.Ft intmax_t . 1814.It Constants 1815Decimal, octal (starting with 1816.Li 0 ) 1817and hexadecimal (starting with 1818.Li 0x ) 1819integer constants. 1820.It Variables 1821Shell variables can be read and written 1822and contain integer constants. 1823.It Unary operators 1824.Li "! ~ + -" 1825.It Binary operators 1826.Li "* / % + - << >> < <= > >= == != & ^ | && ||"\& 1827.It Assignment operators 1828.Li "= += -= *= /= %= <<= >>= &= ^= |=" 1829.It Conditional operator 1830.Li "? :"\& 1831.El 1832.Pp 1833The result of the expression is substituted in decimal. 1834.Ss White Space Splitting (Field Splitting) 1835In certain contexts, 1836after parameter expansion, command substitution, and 1837arithmetic expansion the shell scans the results of 1838expansions and substitutions that did not occur in double-quotes for 1839field splitting and multiple fields can result. 1840.Pp 1841Characters in 1842.Va IFS 1843that are whitespace 1844.Po 1845.Aq space , 1846.Aq tab , 1847and 1848.Aq newline 1849.Pc 1850are treated differently from other characters in 1851.Va IFS . 1852.Pp 1853Whitespace in 1854.Va IFS 1855at the beginning or end of a word is discarded. 1856.Pp 1857Subsequently, a field is delimited by either 1858.Bl -enum 1859.It 1860a non-whitespace character in 1861.Va IFS 1862with any whitespace in 1863.Va IFS 1864surrounding it, or 1865.It 1866one or more whitespace characters in 1867.Va IFS . 1868.El 1869.Pp 1870If a word ends with a non-whitespace character in 1871.Va IFS , 1872there is no empty field after this character. 1873.Pp 1874If no field is delimited, the word is discarded. 1875In particular, if a word consists solely of an unquoted substitution 1876and the result of the substitution is null, 1877it is removed by field splitting even if 1878.Va IFS 1879is null. 1880.Ss Pathname Expansion (File Name Generation) 1881Unless the 1882.Fl f 1883option is set, 1884file name generation is performed 1885after word splitting is complete. 1886Each word is 1887viewed as a series of patterns, separated by slashes. 1888The 1889process of expansion replaces the word with the names of 1890all existing files whose names can be formed by replacing 1891each pattern with a string that matches the specified pattern. 1892There are two restrictions on this: first, a pattern cannot match 1893a string containing a slash, and second, 1894a pattern cannot match a string starting with a period 1895unless the first character of the pattern is a period. 1896The next section describes the patterns used for 1897Pathname Expansion, 1898the four varieties of parameter expansion for substring processing and the 1899.Ic case 1900command. 1901.Ss Shell Patterns 1902A pattern consists of normal characters, which match themselves, 1903and meta-characters. 1904The meta-characters are 1905.Ql * , 1906.Ql \&? , 1907and 1908.Ql \&[ . 1909These characters lose their special meanings if they are quoted. 1910When command or variable substitution is performed and the dollar sign 1911or back quotes are not double-quoted, the value of the 1912variable or the output of the command is scanned for these 1913characters and they are turned into meta-characters. 1914.Pp 1915An asterisk 1916.Pq Ql * 1917matches any string of characters. 1918A question mark 1919.Pq Ql \&? 1920matches any single character. 1921A left bracket 1922.Pq Ql \&[ 1923introduces a character class. 1924The end of the character class is indicated by a 1925.Ql \&] ; 1926if the 1927.Ql \&] 1928is missing then the 1929.Ql \&[ 1930matches a 1931.Ql \&[ 1932rather than introducing a character class. 1933A character class matches any of the characters between the square brackets. 1934A locale-dependent range of characters may be specified using a minus sign. 1935A named class of characters (see 1936.Xr wctype 3 ) 1937may be specified by surrounding the name with 1938.Ql \&[:\& 1939and 1940.Ql :\&] . 1941For example, 1942.Ql \&[\&[:alpha:\&]\&] 1943is a shell pattern that matches a single letter. 1944The character class may be complemented by making an exclamation point 1945.Pq Ql !\& 1946the first character of the character class. 1947A caret 1948.Pq Ql ^ 1949has the same effect but is non-standard. 1950.Pp 1951To include a 1952.Ql \&] 1953in a character class, make it the first character listed 1954(after the 1955.Ql \&! 1956or 1957.Ql ^ , 1958if any). 1959To include a 1960.Ql - , 1961make it the first or last character listed. 1962.Ss Job Control 1963A job is a set of processes, comprising a shell pipeline 1964(see 1965.Sx Pipelines ) , 1966and any processes descended from it, that are all 1967in the same process group. 1968.Pp 1969The job control facility allows users to 1970selectively suspend the execution of processes (by pressing 1971.Sq Ctrl-Z , 1972if not adjusted using 1973.Xr stty 1 ) , 1974continue their execution at a later point, 1975and run them in the foreground or in the background (using builtins 1976.Ic fg 1977and 1978.Ic bg ) . 1979.Pp 1980A job ID is a handle that is used to refer to a job. 1981It can take any of the following forms: 1982.Bl -tag -width "%?string" 1983.It Cm %% 1984Current job. 1985.It Cm %+ 1986Current job. 1987.It Cm %- 1988Previous job. 1989.It Cm % Ns Ar n 1990Job number 1991.Ar n . 1992.It Cm % Ns Ar string 1993Job whose command begins with 1994.Ar string . 1995.It Cm %? Ns Ar string 1996Job whose command contains 1997.Ar string . 1998.El 1999.Pp 2000The job control built-in commands 2001are: 2002.Ic bg , 2003.Ic fg , 2004.Ic jobid 2005and 2006.Ic jobs . 2007Additionally, the following built-in commands accept a job ID 2008as an argument: 2009.Ic kill , 2010.Ic wait . 2011See 2012.Sx Built-in Commands 2013below. 2014.Ss Built-in Commands 2015This section lists the built-in commands. 2016.Bl -tag -width indent 2017.It Ic \&: Op Ar arg Ar ... 2018A null command that returns a 0 (true) exit value. 2019Any arguments are discarded. 2020.It Ic \&. Ar file 2021The commands in the specified file are read and executed by the shell. 2022The 2023.Ic return 2024command may be used to return to the 2025.Ic \&. 2026command's caller. 2027If 2028.Ar file 2029contains any 2030.Ql / 2031characters, it is used as is. 2032Otherwise, the shell searches the 2033.Va PATH 2034for the file. 2035If it is not found in the 2036.Va PATH , 2037it is sought in the current working directory. 2038.It Ic \&[ 2039A built-in equivalent of 2040.Xr test 1 . 2041.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc Ar ... Oc 2042If 2043.Ar name Ns = Ns Ar string 2044is specified, the shell defines the alias 2045.Ar name 2046with value 2047.Ar string . 2048If just 2049.Ar name 2050is specified, the value of the alias 2051.Ar name 2052is printed. 2053With no arguments, the 2054.Ic alias 2055built-in command prints the names and values of all defined aliases 2056(see 2057.Ic unalias ) . 2058Alias values are written with appropriate quoting so that they are 2059suitable for re-input to the shell. 2060Also see the 2061.Sx Aliases 2062subsection. 2063.It Ic bg Op Ar job ... 2064Continue the specified jobs 2065(or the current job if no jobs are given) 2066in the background. 2067See 2068.Sx Job Control 2069for a list of job ID forms. 2070.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc 2071List or alter key bindings for the line editor, 2072.Xr editline 7 . 2073This command is documented in 2074.Xr editrc 5 . 2075.It Ic break Op Ar num 2076See the 2077.Sx Flow-Control Constructs 2078subsection. 2079.It Ic builtin Ar cmd Op Ar arg ... 2080Execute the specified built-in command, 2081.Ar cmd . 2082This is useful when the user wishes to override a shell function 2083with the same name as a built-in command. 2084.It Ic cd Oo Fl L | P Oc Oo Fl e Oc Op Ar directory 2085.It Ic cd Fl 2086Switch to the specified 2087.Ar directory , 2088to the directory specified in the 2089.Va HOME 2090environment variable if no 2091.Ar directory 2092is specified or 2093to the directory specified in the 2094.Va OLDPWD 2095environment variable if 2096.Ar directory 2097is 2098.Fl . 2099If 2100.Ar directory 2101does not begin with 2102.Pa / , \&. , 2103or 2104.Pa .. , 2105then the directories listed in the 2106.Va CDPATH 2107variable will be 2108searched for the specified 2109.Ar directory . 2110If 2111.Va CDPATH 2112is unset, the current directory is searched. 2113The format of 2114.Va CDPATH 2115is the same as that of 2116.Va PATH . 2117In an interactive shell, 2118the 2119.Ic cd 2120command will print out the name of the directory 2121that it actually switched to 2122if the 2123.Va CDPATH 2124mechanism was used or if 2125.Ar directory 2126was 2127.Fl . 2128.Pp 2129If the 2130.Fl P 2131option is specified, 2132.Pa .. 2133is handled physically and symbolic links are resolved before 2134.Pa .. 2135components are processed. 2136If the 2137.Fl L 2138option is specified, 2139.Pa .. 2140is handled logically. 2141This is the default. 2142.Pp 2143The 2144.Fl e 2145option causes 2146.Ic cd 2147to return exit status 1 if the full pathname of the new directory 2148cannot be determined reliably or at all. 2149Normally this is not considered an error, 2150although a warning is printed. 2151.Pp 2152If changing the directory fails, the exit status is greater than 1. 2153If the directory is changed, the exit status is 0, or also 1 if 2154.Fl e 2155was given. 2156.It Ic chdir 2157A synonym for the 2158.Ic cd 2159built-in command. 2160.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... 2161.It Ic command Oo Fl p Oc Fl v Ar utility 2162.It Ic command Oo Fl p Oc Fl V Ar utility 2163The first form of invocation executes the specified 2164.Ar utility , 2165ignoring shell functions in the search. 2166If 2167.Ar utility 2168is a special builtin, 2169it is executed as if it were a regular builtin. 2170.Pp 2171If the 2172.Fl p 2173option is specified, the command search is performed using a 2174default value of 2175.Va PATH 2176that is guaranteed to find all of the standard utilities. 2177.Pp 2178If the 2179.Fl v 2180option is specified, 2181.Ar utility 2182is not executed but a description of its interpretation by the shell is 2183printed. 2184For ordinary commands the output is the path name; for shell built-in 2185commands, shell functions and keywords only the name is written. 2186Aliases are printed as 2187.Dq Ic alias Ar name Ns = Ns Ar value . 2188.Pp 2189The 2190.Fl V 2191option is identical to 2192.Fl v 2193except for the output. 2194It prints 2195.Dq Ar utility Ic is Ar description 2196where 2197.Ar description 2198is either 2199the path name to 2200.Ar utility , 2201a special shell builtin, 2202a shell builtin, 2203a shell function, 2204a shell keyword 2205or 2206an alias for 2207.Ar value . 2208.It Ic continue Op Ar num 2209See the 2210.Sx Flow-Control Constructs 2211subsection. 2212.It Ic echo Oo Fl e | n Oc Op Ar string ... 2213Print a space-separated list of the arguments to the standard output 2214and append a newline character. 2215.Bl -tag -width indent 2216.It Fl n 2217Suppress the output of the trailing newline. 2218.It Fl e 2219Process C-style backslash escape sequences. 2220The 2221.Ic echo 2222command understands the following character escapes: 2223.Bl -tag -width indent 2224.It \ea 2225Alert (ring the terminal bell) 2226.It \eb 2227Backspace 2228.It \ec 2229Suppress the trailing newline (this has the side-effect of truncating the 2230line if it is not the last character) 2231.It \ee 2232The ESC character (ASCII 0x1b) 2233.It \ef 2234Formfeed 2235.It \en 2236Newline 2237.It \er 2238Carriage return 2239.It \et 2240Horizontal tab 2241.It \ev 2242Vertical tab 2243.It \e\e 2244Literal backslash 2245.It \e0nnn 2246(Zero) The character whose octal value is 2247.Ar nnn 2248.El 2249.Pp 2250If 2251.Ar string 2252is not enclosed in quotes then the backslash itself must be escaped 2253with a backslash to protect it from the shell. 2254For example 2255.Bd -literal -offset indent 2256$ echo -e "a\evb" 2257a 2258 b 2259$ echo -e a\e\evb 2260a 2261 b 2262$ echo -e "a\e\eb" 2263a\eb 2264$ echo -e a\e\e\e\eb 2265a\eb 2266.Ed 2267.El 2268.Pp 2269Only one of the 2270.Fl e 2271and 2272.Fl n 2273options may be specified. 2274.It Ic eval Ar string ... 2275Concatenate all the arguments with spaces. 2276Then re-parse and execute the command. 2277.It Ic exec Op Ar command Op arg ... 2278Unless 2279.Ar command 2280is omitted, 2281the shell process is replaced with the specified program 2282(which must be a real program, not a shell built-in command or function). 2283Any redirections on the 2284.Ic exec 2285command are marked as permanent, 2286so that they are not undone when the 2287.Ic exec 2288command finishes. 2289.It Ic exit Op Ar exitstatus 2290Terminate the shell process. 2291If 2292.Ar exitstatus 2293is given 2294it is used as the exit status of the shell. 2295Otherwise, if the shell is executing an 2296.Cm EXIT 2297trap, the exit status of the last command before the trap is used; 2298if the shell is executing a trap for a signal, 2299the shell exits by resending the signal to itself. 2300Otherwise, the exit status of the preceding command is used. 2301The exit status should be an integer between 0 and 255. 2302.It Ic export Ar name ... 2303.It Ic export Op Fl p 2304The specified names are exported so that they will 2305appear in the environment of subsequent commands. 2306The only way to un-export a variable is to 2307.Ic unset 2308it. 2309The shell allows the value of a variable to be set 2310at the same time as it is exported by writing 2311.Pp 2312.D1 Ic export Ar name Ns = Ns Ar value 2313.Pp 2314With no arguments the 2315.Ic export 2316command lists the names 2317of all exported variables. 2318If the 2319.Fl p 2320option is specified, the exported variables are printed as 2321.Dq Ic export Ar name Ns = Ns Ar value 2322lines, suitable for re-input to the shell. 2323.It Ic false 2324A null command that returns a non-zero (false) exit value. 2325.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last 2326.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last 2327.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first 2328The 2329.Ic fc 2330built-in command lists, or edits and re-executes, 2331commands previously entered to an interactive shell. 2332.Bl -tag -width indent 2333.It Fl e Ar editor 2334Use the editor named by 2335.Ar editor 2336to edit the commands. 2337The 2338.Ar editor 2339string is a command name, 2340subject to search via the 2341.Va PATH 2342variable. 2343The value in the 2344.Va FCEDIT 2345variable is used as a default when 2346.Fl e 2347is not specified. 2348If 2349.Va FCEDIT 2350is null or unset, the value of the 2351.Va EDITOR 2352variable is used. 2353If 2354.Va EDITOR 2355is null or unset, 2356.Xr ed 1 2357is used as the editor. 2358.It Fl l No (ell) 2359List the commands rather than invoking 2360an editor on them. 2361The commands are written in the 2362sequence indicated by the 2363.Ar first 2364and 2365.Ar last 2366operands, as affected by 2367.Fl r , 2368with each command preceded by the command number. 2369.It Fl n 2370Suppress command numbers when listing with 2371.Fl l . 2372.It Fl r 2373Reverse the order of the commands listed 2374(with 2375.Fl l ) 2376or edited 2377(with neither 2378.Fl l 2379nor 2380.Fl s ) . 2381.It Fl s 2382Re-execute the command without invoking an editor. 2383.It Ar first 2384.It Ar last 2385Select the commands to list or edit. 2386The number of previous commands that can be accessed 2387are determined by the value of the 2388.Va HISTSIZE 2389variable. 2390The value of 2391.Ar first 2392or 2393.Ar last 2394or both are one of the following: 2395.Bl -tag -width indent 2396.It Oo Cm + Oc Ns Ar num 2397A positive number representing a command number; 2398command numbers can be displayed with the 2399.Fl l 2400option. 2401.It Fl Ar num 2402A negative decimal number representing the 2403command that was executed 2404.Ar num 2405of 2406commands previously. 2407For example, \-1 is the immediately previous command. 2408.It Ar string 2409A string indicating the most recently entered command 2410that begins with that string. 2411If the 2412.Ar old Ns = Ns Ar new 2413operand is not also specified with 2414.Fl s , 2415the string form of the first operand cannot contain an embedded equal sign. 2416.El 2417.El 2418.Pp 2419The following variables affect the execution of 2420.Ic fc : 2421.Bl -tag -width ".Va HISTSIZE" 2422.It Va FCEDIT 2423Name of the editor to use for history editing. 2424.It Va HISTSIZE 2425The number of previous commands that are accessible. 2426.El 2427.It Ic fg Op Ar job 2428Move the specified 2429.Ar job 2430or the current job to the foreground. 2431See 2432.Sx Job Control 2433for a list of job ID forms. 2434.It Ic getopts Ar optstring var 2435Parse command-line options and arguments. 2436The first argument 2437.Va optstring 2438should be a series of letters, each possibly 2439followed by a colon which indicates that the option takes an argument. 2440The specified variable 2441.Va var 2442is set to the parsed option. 2443The index of 2444the next argument is placed into the shell variable 2445.Va OPTIND . 2446If an option takes an argument, it is placed into the shell variable 2447.Va OPTARG . 2448.Pp 2449If the found character 2450is not specified by 2451.Va optstring 2452or if it is missing a required argument, 2453the option is considered invalid and: 2454.Bl -enum 2455.It 2456If the first character of 2457.Va optstring 2458is not a colon then 2459.Va OPTARG 2460is unset, 2461.Ar var 2462is set to 2463.Ql \&? 2464and a diagnostic message is written to stderr. 2465.It 2466If the first character of 2467.Va optstring 2468is a colon then 2469.Va OPTARG 2470is set to the option character found, 2471.Ar var 2472is set to 2473.Ql \&: 2474when a required argument is missing or to 2475.Ql \&? 2476when the option was not specified by 2477.Va optstring , 2478and no diagnostic message is written to stderr. 2479.El 2480.Pp 2481.Ic getopts 2482returns a false value (1) when it encounters the end of the options. 2483A new set of arguments may be parsed by assigning 2484.Li OPTIND=1 . 2485The POSIX 2486.Ic getopts 2487command deprecates the older 2488.Xr getopt 1 2489command. 2490.It Ic hash Oo Fl rv Oc Op Ar command ... 2491The shell maintains a hash table which remembers the locations of commands. 2492With no arguments whatsoever, the 2493.Ic hash 2494command prints out the contents of this table. 2495.Pp 2496With arguments, the 2497.Ic hash 2498command removes each specified 2499.Ar command 2500from the hash table (unless they are functions) and then locates it. 2501With the 2502.Fl v 2503option, 2504.Ic hash 2505prints the locations of the commands as it finds them. 2506The 2507.Fl r 2508option causes the 2509.Ic hash 2510command to delete all the entries in the hash table except for functions. 2511.It Ic jobid Op Ar job 2512Print the process IDs of the processes in the specified 2513.Ar job . 2514If the 2515.Ar job 2516argument is omitted, use the current job. 2517See 2518.Sx Job Control 2519for a list of job ID forms. 2520.It Ic jobs Oo Fl lps Oc Op Ar job ... 2521Print information about the specified jobs, or all jobs if no 2522.Ar job 2523argument is given. 2524See 2525.Sx Job Control 2526for a list of job ID forms. 2527.Pp 2528If the 2529.Fl l 2530option is not specified, the output line is the following 2531for each job: 2532.Dl Oo Ar job_number Oc Ar current Ar state Ar command 2533where: 2534.Bl -tag -width "job_number" 2535.It Ar job_number 2536A number that can be used to identify the process group to the 2537.Ic bg , 2538.Ic fg , 2539.Ic kill 2540and 2541.Ic wait 2542commands. 2543Using these commands, the job can be identified by prefixing 2544the 2545.Ar job_number 2546with 2547.Cm % . 2548See also 2549.Sx Job Control . 2550.It Ar current 2551One of the following characters: 2552.Bl -tag -width "<space>" 2553.It Cm + 2554Identifies the job that would be used as a default for the 2555.Ic fg 2556or 2557.Ic bg 2558commands. 2559.It Cm - 2560Identifies the job that would become the default if the 2561current default job were to exit. 2562.It Aq Cm space 2563For all other jobs that are neither marked with 2564.Cm + 2565nor 2566.Cm - . 2567.El 2568.It Ar state 2569One of the following strings, describing the current job state: 2570.Bl -tag -width "Stopped (tty output)" 2571.It Running 2572Indicates that the job has not been suspended by a signal and 2573has not exited. 2574.It Done 2575Indicates that the job completed and returned exit status zero. 2576.It Done Ns Pq Ar code 2577Indicates that the job completed normally and that it exited 2578with the specified non-zero exit status, 2579.Ar code . 2580.It Suspended 2581Indicates that the job was interrupted by the 2582.Dv SIGTSTP 2583signal. 2584This is typically because 2585.Sq Ctrl-Z 2586was pressed. 2587.It Suspended Pq signal 2588Indicates that the job was interrupted by the 2589.Dv SIGSTOP 2590signal. 2591.It Stopped Pq tty input 2592Indicates that the job was interrupted by the 2593.Dv SIGTTIN 2594signal. 2595This is typically because the command attempted to read from the 2596terminal while in the background. 2597.It Stopped Pq tty output 2598Indicates that the job was interrupted by the 2599.Dv SIGTTOU 2600signal. 2601This is typically because the command attempted to change terminal 2602settings or (if 2603.Ic stty tostop 2604is in effect; see 2605.Xr stty 1 ) 2606write to the terminal while in the background. 2607.El 2608.Pp 2609See 2610.Xr signal 3 2611for additional information on the meanings of the aforementioned signals. 2612.It Ar command 2613The associated command that was given to the shell. 2614.El 2615.Pp 2616If the 2617.Fl l 2618option is specified, the PID of the job is 2619inserted before the 2620.Ar state 2621field. 2622.Pp 2623If the 2624.Fl p 2625option is specified, only the process IDs for the process group leaders 2626are printed, one per line. 2627.Pp 2628If the 2629.Fl s 2630option is specified, only the PIDs of the job commands are printed, one per 2631line. 2632.It Ic kill 2633A built-in equivalent of 2634.Xr kill 1 2635that additionally supports sending signals to jobs, 2636by means of specifying their job IDs as arguments. 2637See 2638.Sx Job Control 2639for a list of job ID forms. 2640.It Ic local Oo Ar variable ... Oc Op Fl 2641See the 2642.Sx Functions 2643subsection. 2644.It Ic printf 2645A built-in equivalent of 2646.Xr printf 1 . 2647.It Ic pwd Op Fl L | P 2648Print the path of the current directory. 2649The built-in command may 2650differ from the program of the same name because the 2651built-in command remembers what the current directory 2652is rather than recomputing it each time. 2653This makes 2654it faster. 2655However, if the current directory is 2656renamed, 2657the built-in version of 2658.Xr pwd 1 2659will continue to print the old name for the directory. 2660.Pp 2661If the 2662.Fl P 2663option is specified, symbolic links are resolved. 2664If the 2665.Fl L 2666option is specified, the shell's notion of the current directory 2667is printed (symbolic links are not resolved). 2668This is the default. 2669.It Ic read Oo Fl p Ar prompt Oc Oo 2670.Fl t Ar timeout Oc Oo Fl er Oc Ar variable ... 2671The 2672.Ar prompt 2673is printed if the 2674.Fl p 2675option is specified 2676and the standard input is a terminal. 2677Then a line is 2678read from the standard input. 2679The trailing newline 2680is deleted from the line and the line is split as 2681described in the section on 2682.Sx White Space Splitting (Field Splitting)\& 2683above, and 2684the pieces are assigned to the variables in order. 2685If there are more pieces than variables, the remaining 2686pieces (along with the characters in 2687.Va IFS 2688that separated them) 2689are assigned to the last variable. 2690If there are more variables than pieces, the remaining 2691variables are assigned the null string. 2692.Pp 2693Backslashes are treated specially, unless the 2694.Fl r 2695option is 2696specified. 2697If a backslash is followed by 2698a newline, the backslash and the newline will be 2699deleted. 2700If a backslash is followed by any other 2701character, the backslash will be deleted and the following 2702character will be treated as though it were not in 2703.Va IFS , 2704even if it is. 2705.Pp 2706If the 2707.Fl t 2708option is specified and the 2709.Ar timeout 2710elapses before a complete line of input is supplied, 2711the 2712.Ic read 2713command will return an exit status as if terminated by 2714.Dv SIGALRM 2715without assigning any values. 2716The 2717.Ar timeout 2718value may optionally be followed by one of 2719.Ql s , 2720.Ql m 2721or 2722.Ql h 2723to explicitly specify seconds, minutes or hours. 2724If none is supplied, 2725.Ql s 2726is assumed. 2727Multiple value-unit groups may be stringed together, in which case 2728they are added up, e.g.\& 2729.Ql 1h30m15s 2730which adds up to 5,415 seconds. 2731.Pp 2732The 2733.Fl e 2734option exists only for backward compatibility with older scripts. 2735.Pp 2736The exit status is 0 on success, 1 on end of file, 2737between 2 and 128 if an error occurs 2738and greater than 128 if a trapped signal interrupts 2739.Ic read . 2740.It Ic readonly Oo Fl p Oc Op Ar name ... 2741Each specified 2742.Ar name 2743is marked as read only, 2744so that it cannot be subsequently modified or unset. 2745The shell allows the value of a variable to be set 2746at the same time as it is marked read only 2747by using the following form: 2748.Pp 2749.D1 Ic readonly Ar name Ns = Ns Ar value 2750.Pp 2751With no arguments the 2752.Ic readonly 2753command lists the names of all read only variables. 2754If the 2755.Fl p 2756option is specified, the read-only variables are printed as 2757.Dq Ic readonly Ar name Ns = Ns Ar value 2758lines, suitable for re-input to the shell. 2759.It Ic return Op Ar exitstatus 2760See the 2761.Sx Functions 2762subsection. 2763.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname 2764.Oc Op Fl - Ar arg ... 2765The 2766.Ic set 2767command performs three different functions: 2768.Bl -item 2769.It 2770With no arguments, it lists the values of all shell variables. 2771.It 2772If options are given, 2773either in short form or using the long 2774.Dq Fl /+o Ar longname 2775form, 2776it sets or clears the specified options as described in the section called 2777.Sx Argument List Processing . 2778.It 2779If the 2780.Dq Fl - 2781option is specified, 2782.Ic set 2783will replace the shell's positional parameters with the subsequent 2784arguments. 2785If no arguments follow the 2786.Dq Fl - 2787option, 2788all the positional parameters will be cleared, 2789which is equivalent to executing the command 2790.Dq Li "shift $#" . 2791The 2792.Dq Fl - 2793flag may be omitted when specifying arguments to be used 2794as positional replacement parameters. 2795This is not recommended, 2796because the first argument may begin with a dash 2797.Pq Ql - 2798or a plus 2799.Pq Ql + , 2800which the 2801.Ic set 2802command will interpret as a request to enable or disable options. 2803.El 2804.It Ic setvar Ar variable value 2805Assigns the specified 2806.Ar value 2807to the specified 2808.Ar variable . 2809The 2810.Ic setvar 2811command is intended to be used in functions that 2812assign values to variables whose names are passed as parameters. 2813In general it is better to write 2814.Dq Ar variable Ns = Ns Ar value 2815rather than using 2816.Ic setvar . 2817.It Ic shift Op Ar n 2818Shift the positional parameters 2819.Ar n 2820times, or once if 2821.Ar n 2822is not specified. 2823A shift sets the value of 2824.Li $1 2825to the value of 2826.Li $2 , 2827the value of 2828.Li $2 2829to the value of 2830.Li $3 , 2831and so on, 2832decreasing the value of 2833.Li $# 2834by one. 2835For portability, shifting if there are zero positional parameters 2836should be avoided, since the shell may abort. 2837.It Ic test 2838A built-in equivalent of 2839.Xr test 1 . 2840.It Ic times 2841Print the amount of time spent executing the shell process and its children. 2842The first output line shows the user and system times for the shell process 2843itself, the second one contains the user and system times for the 2844children. 2845.It Ic trap Oo Ar action Oc Ar signal ... 2846.It Ic trap Fl l 2847Cause the shell to parse and execute 2848.Ar action 2849when any specified 2850.Ar signal 2851is received. 2852The signals are specified by name or number. 2853In addition, the pseudo-signal 2854.Cm EXIT 2855may be used to specify an 2856.Ar action 2857that is performed when the shell terminates. 2858The 2859.Ar action 2860may be an empty string or a dash 2861.Pq Ql - ; 2862the former causes the specified signal to be ignored 2863and the latter causes the default action to be taken. 2864Omitting the 2865.Ar action 2866and using only signal numbers is another way to request the default action. 2867In a subshell or utility environment, 2868the shell resets trapped (but not ignored) signals to the default action. 2869The 2870.Ic trap 2871command has no effect on signals that were ignored on entry to the shell. 2872.Pp 2873Option 2874.Fl l 2875causes the 2876.Ic trap 2877command to display a list of valid signal names. 2878.It Ic true 2879A null command that returns a 0 (true) exit value. 2880.It Ic type Op Ar name ... 2881Interpret each 2882.Ar name 2883as a command and print the resolution of the command search. 2884Possible resolutions are: 2885shell keyword, alias, special shell builtin, shell builtin, command, 2886tracked alias 2887and not found. 2888For aliases the alias expansion is printed; 2889for commands and tracked aliases 2890the complete pathname of the command is printed. 2891.It Ic ulimit Oo Fl HSabcdfklmnopstuvw Oc Op Ar limit 2892Set or display resource limits (see 2893.Xr getrlimit 2 ) . 2894If 2895.Ar limit 2896is specified, the named resource will be set; 2897otherwise the current resource value will be displayed. 2898.Pp 2899If 2900.Fl H 2901is specified, the hard limits will be set or displayed. 2902While everybody is allowed to reduce a hard limit, 2903only the superuser can increase it. 2904The 2905.Fl S 2906option 2907specifies the soft limits instead. 2908When displaying limits, 2909only one of 2910.Fl S 2911or 2912.Fl H 2913can be given. 2914The default is to display the soft limits, 2915and to set both the hard and the soft limits. 2916.Pp 2917Option 2918.Fl a 2919causes the 2920.Ic ulimit 2921command to display all resources. 2922The parameter 2923.Ar limit 2924is not acceptable in this mode. 2925.Pp 2926The remaining options specify which resource value is to be 2927displayed or modified. 2928They are mutually exclusive. 2929.Bl -tag -width indent 2930.It Fl b Ar sbsize 2931The maximum size of socket buffer usage, in bytes. 2932.It Fl c Ar coredumpsize 2933The maximal size of core dump files, in 512-byte blocks. 2934Setting 2935.Ar coredumpsize 2936to 0 prevents core dump files from being created. 2937.It Fl d Ar datasize 2938The maximal size of the data segment of a process, in kilobytes. 2939.It Fl f Ar filesize 2940The maximal size of a file, in 512-byte blocks. 2941.It Fl k Ar kqueues 2942The maximal number of kqueues 2943(see 2944.Xr kqueue 2 ) 2945for this user ID. 2946.It Fl l Ar lockedmem 2947The maximal size of memory that can be locked by a process, in 2948kilobytes. 2949.It Fl m Ar memoryuse 2950The maximal resident set size of a process, in kilobytes. 2951.It Fl n Ar nofiles 2952The maximal number of descriptors that could be opened by a process. 2953.It Fl o Ar umtxp 2954The maximal number of process-shared locks 2955(see 2956.Xr pthread 3 ) 2957for this user ID. 2958.It Fl p Ar pseudoterminals 2959The maximal number of pseudo-terminals for this user ID. 2960.It Fl s Ar stacksize 2961The maximal size of the stack segment, in kilobytes. 2962.It Fl t Ar time 2963The maximal amount of CPU time to be used by each process, in seconds. 2964.It Fl u Ar userproc 2965The maximal number of simultaneous processes for this user ID. 2966.It Fl v Ar virtualmem 2967The maximal virtual size of a process, in kilobytes. 2968.It Fl w Ar swapuse 2969The maximum amount of swap space reserved or used for this user ID, 2970in kilobytes. 2971.El 2972.It Ic umask Oo Fl S Oc Op Ar mask 2973Set the file creation mask (see 2974.Xr umask 2 ) 2975to the octal or symbolic (see 2976.Xr chmod 1 ) 2977value specified by 2978.Ar mask . 2979If the argument is omitted, the current mask value is printed. 2980If the 2981.Fl S 2982option is specified, the output is symbolic, otherwise the output is octal. 2983.It Ic unalias Oo Fl a Oc Op Ar name ... 2984The specified alias names are removed. 2985If 2986.Fl a 2987is specified, all aliases are removed. 2988.It Ic unset Oo Fl fv Oc Ar name ... 2989The specified variables or functions are unset and unexported. 2990If the 2991.Fl v 2992option is specified or no options are given, the 2993.Ar name 2994arguments are treated as variable names. 2995If the 2996.Fl f 2997option is specified, the 2998.Ar name 2999arguments are treated as function names. 3000.It Ic wait Op Ar job ... 3001Wait for each specified 3002.Ar job 3003to complete and return the exit status of the last process in the 3004last specified 3005.Ar job . 3006If any 3007.Ar job 3008specified is unknown to the shell, it is treated as if it 3009were a known job that exited with exit status 127. 3010If no operands are given, wait for all jobs to complete 3011and return an exit status of zero. 3012.El 3013.Ss Command Line Editing 3014When 3015.Nm 3016is being used interactively from a terminal, the current command 3017and the command history 3018(see 3019.Ic fc 3020in 3021.Sx Built-in Commands ) 3022can be edited using 3023.Nm vi Ns -mode 3024command line editing. 3025This mode uses commands similar 3026to a subset of those described in the 3027.Xr vi 1 3028man page. 3029The command 3030.Dq Li "set -o vi" 3031(or 3032.Dq Li "set -V" ) 3033enables 3034.Nm vi Ns -mode 3035editing and places 3036.Nm 3037into 3038.Nm vi 3039insert mode. 3040With 3041.Nm vi Ns -mode 3042enabled, 3043.Nm 3044can be switched between insert mode and command mode by typing 3045.Aq ESC . 3046Hitting 3047.Aq return 3048while in command mode will pass the line to the shell. 3049.Pp 3050Similarly, the 3051.Dq Li "set -o emacs" 3052(or 3053.Dq Li "set -E" ) 3054command can be used to enable a subset of 3055.Nm emacs Ns -style 3056command line editing features. 3057.Pp 3058Command line editing in 3059.Nm 3060is handled by the 3061.Xr editline 7 . 3062.Sh ENVIRONMENT 3063The following environment variables affect the execution of 3064.Nm : 3065.Bl -tag -width ".Ev LANGXXXXXX" 3066.It Ev ENV 3067Initialization file for interactive shells. 3068.It Ev LANG , Ev LC_* 3069Locale settings. 3070These are inherited by children of the shell, 3071and is used in a limited manner by the shell itself. 3072.It Ev OLDPWD 3073The previous current directory. 3074This is used and updated by 3075.Ic cd . 3076.It Ev PWD 3077An absolute pathname for the current directory, 3078possibly containing symbolic links. 3079This is used and updated by the shell. 3080.It Ev TERM 3081The default terminal setting for the shell. 3082This is inherited by children of the shell, and is used in the history 3083editing modes. 3084.El 3085.Pp 3086Additionally, environment variables are turned into shell variables 3087at startup, 3088which may affect the shell as described under 3089.Sx Special Variables . 3090.Sh FILES 3091.Bl -tag -width "/etc/suid_profileXX" -compact 3092.It Pa ~/.profile 3093User's login profile. 3094.It Pa ~/.sh_history 3095Default shell history. 3096.It Pa ~/.shrc 3097Default shell resources. 3098.It Pa /etc/profile 3099System login profile. 3100.It Pa /etc/shells 3101Shell database. 3102.It Pa /etc/suid_profile 3103Privileged shell profile. 3104.El 3105.Sh EXIT STATUS 3106If the 3107.Ar script 3108cannot be found, the exit status will be 127; 3109if it cannot be opened for another reason, the exit status will be 126. 3110Other errors that are detected by the shell, such as a syntax error, will 3111cause the shell to exit with a non-zero exit status. 3112If the shell is not an interactive shell, the execution of the shell 3113file will be aborted. 3114Otherwise the shell will return the exit status of the last command 3115executed, or if the 3116.Ic exit 3117builtin is used with a numeric argument, it 3118will return the argument. 3119.Sh SEE ALSO 3120.Xr builtin 1 , 3121.Xr chsh 1 , 3122.Xr echo 1 , 3123.Xr ed 1 , 3124.Xr emacs 1 Pq Pa ports/editors/emacs , 3125.Xr kill 1 , 3126.Xr printf 1 , 3127.Xr pwd 1 , 3128.Xr test 1 , 3129.Xr vi 1 , 3130.Xr execve 2 , 3131.Xr getrlimit 2 , 3132.Xr umask 2 , 3133.Xr signal 3 , 3134.Xr wctype 3 , 3135.Xr editrc 5 , 3136.Xr shells 5 , 3137.Xr editline 7 3138.Sh HISTORY 3139A 3140.Nm 3141command, the Thompson shell, appeared in 3142.At v1 . 3143It was superseded in 3144.At v7 3145by the Bourne shell, which inherited the name 3146.Nm . 3147.Pp 3148This version of 3149.Nm 3150was rewritten in 1989 under the 3151.Bx 3152license after the Bourne shell from 3153.At V.4 3154and first appeared in 3155.Bx 4.3 Net/2 . 3156.Sh AUTHORS 3157This version of 3158.Nm 3159was originally written by 3160.An Kenneth Almquist . 3161.Sh BUGS 3162The 3163.Nm 3164utility does not recognize multibyte characters other than UTF-8. 3165Splitting using 3166.Va IFS 3167does not recognize multibyte characters. 3168