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