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